diff --git a/.circleci/config.yml b/.circleci/config.yml index 801ee5bf5082..fab2fb290918 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -4,13 +4,13 @@ jobs: lint: working_directory: /work - docker: [{image: 'docker:19.03-git'}] + docker: [{image: 'docker:20.10-git'}] environment: DOCKER_BUILDKIT: 1 steps: - checkout - setup_remote_docker: - version: 19.03.12 + version: 20.10.6 reusable: true exclusive: false - run: @@ -39,14 +39,15 @@ jobs: cross: working_directory: /work - docker: [{image: 'docker:19.03-git'}] + docker: [{image: 'docker:20.10-git'}] environment: DOCKER_BUILDKIT: 1 + BUILDX_VERSION: "v0.5.1" parallelism: 3 steps: - checkout - setup_remote_docker: - version: 19.03.12 + version: 20.10.6 reusable: true exclusive: false - run: @@ -55,33 +56,26 @@ jobs: - run: name: "Docker info" command: docker info - - run: - name: "Cross - build image" - command: | - docker build --progress=plain -f dockerfiles/Dockerfile.cross --tag cli-builder:$CIRCLE_BUILD_NUM . - - run: - name: "Cross" - command: | - name=cross-$CIRCLE_BUILD_NUM-$CIRCLE_NODE_INDEX - docker run \ - -e CROSS_GROUP=$CIRCLE_NODE_INDEX \ - --name $name cli-builder:$CIRCLE_BUILD_NUM \ - make cross - docker cp \ - $name:/go/src/github.com/docker/cli/build \ - /work/build + - run: apk add make curl + - run: mkdir -vp ~/.docker/cli-plugins/ + - run: curl -fsSL --output ~/.docker/cli-plugins/docker-buildx https://github.com/docker/buildx/releases/download/${BUILDX_VERSION}/buildx-${BUILDX_VERSION}.linux-amd64 + - run: chmod a+x ~/.docker/cli-plugins/docker-buildx + - run: docker buildx version + - run: docker context create buildctx + - run: docker buildx create --use buildctx && docker buildx inspect --bootstrap + - run: GROUP_INDEX=$CIRCLE_NODE_INDEX GROUP_TOTAL=$CIRCLE_NODE_TOTAL docker buildx bake cross --progress=plain - store_artifacts: path: /work/build test: working_directory: /work - docker: [{image: 'docker:19.03-git'}] + docker: [{image: 'docker:20.10-git'}] environment: DOCKER_BUILDKIT: 1 steps: - checkout - setup_remote_docker: - version: 19.03.12 + version: 20.10.6 reusable: true exclusive: false - run: @@ -122,13 +116,13 @@ jobs: validate: working_directory: /work - docker: [{image: 'docker:19.03-git'}] + docker: [{image: 'docker:20.10-git'}] environment: DOCKER_BUILDKIT: 1 steps: - checkout - setup_remote_docker: - version: 19.03.12 + version: 20.10.6 reusable: true exclusive: false - run: diff --git a/.dockerignore b/.dockerignore index 80d9bd96ddda..1718dd67c28f 100644 --- a/.dockerignore +++ b/.dockerignore @@ -1,6 +1,5 @@ .circleci .dockerignore -.git .github .gitignore appveyor.yml diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 000000000000..74c506971ebe --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,120 @@ +name: CI + +on: + push: + branches: + - master + - 'release/**' + pull_request: + branches: + - master + - 'release/**' + +env: + PLATFORM: Docker Engine - WAGO (Community) + DEFAULT_PRODUCT_LICENSE: Community Engine + DOCKER_GITCOMMIT: ${{ github.sha }} + DOCKER_EXPERIMENTAL: 1 + DOCKER_GRAPHDRIVER: overlay2 + BUILDKIT_PROGRESS: plain + BASE_DEBIAN_DISTRO: buster + GO_VERSION: 1.16.7 + APT_MIRROR: cdn-fastly.deb.debian.org + CHECK_CONFIG_COMMIT: 78405559cfe5987174aa2cb6463b9b2c1b917255 + TESTDEBUG: 0 + TIMEOUT: 120m + BUILD_OUTPUT: build + VERSION: '20.10-dev' + +jobs: + build-static-binary: + + strategy: + fail-fast: false + matrix: + include: + - arch: amd64 + platform: linux/amd64 + - arch: arm32v7 + platform: linux/arm/v7 + + runs-on: ubuntu-latest + + steps: + - name: Checkout code + uses: actions/checkout@v2 + + - name: Set up node for Docker make + id: setup-docker-make + uses: WAGO/docker-actions/setup-docker-make@release/v1.0 + with: + golang-version: ${{ env.GO_VERSION }} + base-debian-distro: ${{ env.BASE_DEBIAN_DISTRO }} + host-arch: ${{ matrix.arch }} + target-platform: ${{ matrix.platform }} + check-config-commit: ${{ env.CHECK_CONFIG_COMMIT }} + project-version: ${{ env.VERSION }} + + - name: Set bundle meta information + id: set-bundle-info + run: | + input_path="${BUILD_OUTPUT}/docker-cli" + echo "::set-output name=input-path::${input_path}" + + - name: Build binary + uses: docker/build-push-action@v2 + with: + target: binary + context: . + push: false + outputs: | + type=local,dest=${{ steps.set-bundle-info.outputs.input-path }} + cache-from: type=local,src=${{ steps.setup-docker-make.outputs.buildx-cache }} + cache-to: type=local,dest=/tmp/.buildx-cache-new,mode=max + platforms: | + ${{ matrix.platform }} + build-args: | + APT_MIRROR + PLATFORM + DEFAULT_PRODUCT_LICENSE + DOCKER_GITCOMMIT + VERSION=${{ steps.setup-docker-make.outputs.version }} + CGO_ENABLED=1 + BASE_VARIANT=${{ env.BASE_DEBIAN_DISTRO }} + GO_VERSION=${{ env.GO_VERSION }} + load: false + + # Temp fix + # https://github.com/docker/build-push-action/issues/252 + # https://github.com/moby/buildkit/issues/1896 + - name: Move cache + env: + BUILDX_CACHE: ${{ steps.setup-docker-make.outputs.buildx-cache }} + run: | + rm -rf "${BUILDX_CACHE}" + mv /tmp/.buildx-cache-new "${BUILDX_CACHE}" + + - name: Create bundle + id: create-bundle + env: + BUNDLE_PLATFORM: ${{ steps.setup-docker-make.outputs.target-platform-id }} + BUNDLE_INPUT_PATH: ${{ steps.set-bundle-info.outputs.input-path }} + run: | + bundle_archive_name="docker-cli-static-${BUNDLE_PLATFORM}.tar" + bundle_archive="${BUILD_OUTPUT}/${bundle_archive_name}" + tar -C "${BUNDLE_INPUT_PATH}" -cvf "${bundle_archive}" . + echo "::set-output name=archive::${bundle_archive}" + echo "::set-output name=archive-name::${bundle_archive_name}" + + - name: Upload bundle + uses: actions/upload-artifact@v2 + with: + name: ${{ steps.create-bundle.outputs.archive-name }} + path: ${{ steps.create-bundle.outputs.archive }} + retention-days: 7 + + - name: Print artifact version informations + env: + BUNDLE_INPUT_PATH: ${{ steps.set-bundle-info.outputs.input-path }} + run: | + "${BUNDLE_INPUT_PATH}/docker" version diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml new file mode 100644 index 000000000000..b61c3e053eff --- /dev/null +++ b/.github/workflows/release.yml @@ -0,0 +1,266 @@ +name: Release + +on: + push: + tags: + - 'v*' # Push events to matching v*, i.e. v1.0, v20.15.10 + +env: + PLATFORM: Docker Engine - WAGO (Community) + DEFAULT_PRODUCT_LICENSE: Community Engine + DOCKER_GITCOMMIT: ${{ github.sha }} + DOCKER_EXPERIMENTAL: 1 + DOCKER_GRAPHDRIVER: overlay2 + BUILDKIT_PROGRESS: plain + BASE_DEBIAN_DISTRO: buster + GO_VERSION: 1.16.7 + APT_MIRROR: cdn-fastly.deb.debian.org + CHECK_CONFIG_COMMIT: 78405559cfe5987174aa2cb6463b9b2c1b917255 + TESTDEBUG: 0 + TIMEOUT: 120m + BUILD_OUTPUT: build + VERSION: '20.10-dev' + +jobs: + check: + runs-on: ubuntu-18.04 + + outputs: + stringver: ${{ steps.contentrel.outputs.stringver }} + + steps: + - name: Checkout code + uses: actions/checkout@v2 + with: + ref: ${{ github.ref }} + + - name: Check signature + run: | + releasever=${{ github.ref }} + releasever="${releasever#refs/tags/}" + tagcheck=$(git tag -v ${releasever} 2>&1 >/dev/null) || + echo "${tagcheck}" | grep -q "error" && { + echo "::error::tag ${releasever} is not a signed tag. Failing release process." + exit 1 + } || { + echo "Tag ${releasever} is signed." + exit 0 + } + + - name: Release content + id: contentrel + run: | + releasever=${{ github.ref }} + echo "::set-output name=stringver::${releasever#refs/tags/v}" + + file_path="${BUILD_OUTPUT}"/release-notes.md + echo "::set-output name=path::${file_path}" + + mkdir -p "${BUILD_OUTPUT}" + git tag -l ${releasever#refs/tags/} -n20000 | tail -n +3 | cut -c 5- > "${file_path}" + + - name: Save release notes + uses: actions/upload-artifact@v2 + with: + name: docker-cli-release-notes + path: ${{ steps.contentrel.outputs.path }} + + build-static-binary: + + strategy: + matrix: + include: + - arch: amd64 + platform: linux/amd64 + - arch: arm32v7 + platform: linux/arm/v7 + + runs-on: ubuntu-18.04 + needs: + - check + + env: + VERSION: ${{ needs.check.outputs.stringver }} + + steps: + - name: Checkout code + uses: actions/checkout@v2 + + - name: Set up node for Docker make + id: setup-docker-make + uses: WAGO/docker-actions/setup-docker-make@release/v1.0 + with: + golang-version: ${{ env.GO_VERSION }} + base-debian-distro: ${{ env.BASE_DEBIAN_DISTRO }} + host-arch: ${{ matrix.arch }} + target-platform: ${{ matrix.platform }} + check-config-commit: ${{ env.CHECK_CONFIG_COMMIT }} + project-version: ${{ env.VERSION }} + + - name: Set bundle meta information + id: set-bundle-info + run: | + input_path="${BUILD_OUTPUT}/docker-cli" + echo "::set-output name=input-path::${input_path}" + + - name: Build binary + uses: docker/build-push-action@v2 + with: + target: binary + context: . + push: false + outputs: | + type=local,dest=${{ steps.set-bundle-info.outputs.input-path }} + cache-from: type=local,src=${{ steps.setup-docker-make.outputs.buildx-cache }} + cache-to: type=local,dest=/tmp/.buildx-cache-new,mode=max + platforms: | + ${{ matrix.platform }} + build-args: | + SOURCE_DATE_EPOCH + BUILDTIME + APT_MIRROR + PLATFORM + DEFAULT_PRODUCT_LICENSE + DOCKER_GITCOMMIT + VERSION=${{ steps.setup-docker-make.outputs.version }} + CGO_ENABLED=1 + BASE_VARIANT=${{ env.BASE_DEBIAN_DISTRO }} + GO_VERSION=${{ env.GO_VERSION }} + load: false + + # Temp fix + # https://github.com/docker/build-push-action/issues/252 + # https://github.com/moby/buildkit/issues/1896 + - name: Move cache + env: + BUILDX_CACHE: ${{ steps.setup-docker-make.outputs.buildx-cache }} + run: | + rm -rf "${BUILDX_CACHE}" + mv /tmp/.buildx-cache-new "${BUILDX_CACHE}" + + - name: Create bundle + id: create-bundle + env: + BUNDLE_PLATFORM: ${{ steps.setup-docker-make.outputs.target-platform-id }} + BUNDLE_INPUT_PATH: ${{ steps.set-bundle-info.outputs.input-path }} + VERSION: ${{ steps.setup-docker-make.outputs.version }} + run: | + bundle_archive_name="docker-cli-${VERSION//\./_}_static-${BUNDLE_PLATFORM}.tar" + bundle_archive_base="${BUILD_OUTPUT}/${bundle_archive_name}" + bundle_archive="${bundle_archive_base}.gz" + tar -C "${BUNDLE_INPUT_PATH}" -czvf "${bundle_archive}" . + (cd "$(dirname "${bundle_archive}")"; sha256sum "$(basename "${bundle_archive}")") > "${bundle_archive}".sha256sum + echo "::set-output name=archive-base::${bundle_archive_base}" + + - name: Upload bundle + uses: actions/upload-artifact@v2 + with: + name: docker-cli-bundles + path: ${{ steps.create-bundle.outputs.archive-base }}.* + retention-days: 7 + + - name: Print artifact version informations + env: + BUNDLE_INPUT_PATH: ${{ steps.set-bundle-info.outputs.input-path }} + run: | + "${BUNDLE_INPUT_PATH}/docker" version + + release: + runs-on: ubuntu-18.04 + + needs: + - build-static-binary + - check + + outputs: + upload_url: ${{ steps.create-release.outputs.upload_url }} + + steps: + - name: Release notes + uses: actions/download-artifact@v2 + with: + name: docker-cli-release-notes + path: ${{ env.BUILD_OUTPUT }} + + - name: Create Release + id: create-release + uses: actions/create-release@v1.1.2 + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + with: + tag_name: ${{ github.ref }} + release_name: docker cli ${{ needs.check.outputs.stringver }} + body_path: ${{ env.BUILD_OUTPUT }}/release-notes.md + draft: false + prerelease: ${{ contains(github.ref, 'beta') || contains(github.ref, 'rc') }} + + release-upload: + runs-on: ubuntu-18.04 + + needs: + - release + + steps: + - name: Checkout code + uses: actions/checkout@v2 + + - name: Set artifact information + id: set-artifact-info + uses: WAGO/docker-actions/artifact-info@release/v1.0 + with: + version: ${{ env.VERSION }} + platform: ${{ matrix.platform }} + + - name: Download bundles + uses: actions/download-artifact@v2 + with: + name: docker-cli-bundles + path: ${{ env.BUILD_OUTPUT }} + + - name: Create catalog + id: catalog + run: | + _filenum=1 + for f in $(ls "docker-cli-"*); do + echo "::set-output name=file${_filenum}::${f}" + let _filenum+=1 + done + working-directory: ${{ env.BUILD_OUTPUT }} + + - name: 1st Upload tarball + uses: actions/upload-release-asset@v1 + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + with: + upload_url: ${{ needs.release.outputs.upload_url }} + asset_path: ${{ env.BUILD_OUTPUT }}/${{ steps.catalog.outputs.file1 }} + asset_name: ${{ steps.catalog.outputs.file1 }} + asset_content_type: application/gzip + - name: 1st Upload sha256 sum + uses: actions/upload-release-asset@v1 + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + with: + upload_url: ${{ needs.release.outputs.upload_url }} + asset_path: ${{ env.BUILD_OUTPUT }}/${{ steps.catalog.outputs.file2 }} + asset_name: ${{ steps.catalog.outputs.file2 }} + asset_content_type: text/plain + + - name: 2nd Upload tarball + uses: actions/upload-release-asset@v1 + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + with: + upload_url: ${{ needs.release.outputs.upload_url }} + asset_path: ${{ env.BUILD_OUTPUT }}/${{ steps.catalog.outputs.file3 }} + asset_name: ${{ steps.catalog.outputs.file3 }} + asset_content_type: application/gzip + - name: 2nd Upload sha256 sum + uses: actions/upload-release-asset@v1 + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + with: + upload_url: ${{ needs.release.outputs.upload_url }} + asset_path: ${{ env.BUILD_OUTPUT }}/${{ steps.catalog.outputs.file4 }} + asset_name: ${{ steps.catalog.outputs.file4 }} + asset_content_type: text/plain diff --git a/.gitignore b/.gitignore index a1f1bc9dafe5..c479555c8809 100644 --- a/.gitignore +++ b/.gitignore @@ -8,8 +8,7 @@ Thumbs.db .editorconfig /build/ -cli/winresources/rsrc_386.syso -cli/winresources/rsrc_amd64.syso +cli/winresources/rsrc_*.syso /man/man1/ /man/man5/ /man/man8/ diff --git a/Dockerfile b/Dockerfile new file mode 100644 index 000000000000..955c280e9d6a --- /dev/null +++ b/Dockerfile @@ -0,0 +1,62 @@ +# syntax=docker/dockerfile:1.3 + +ARG BASE_VARIANT=alpine +ARG GO_VERSION=1.16.15 +ARG XX_VERSION=1.0.0-rc.2 + +FROM --platform=$BUILDPLATFORM golang:${GO_VERSION}-${BASE_VARIANT} AS gostable +FROM --platform=$BUILDPLATFORM golang:1.17rc1-${BASE_VARIANT} AS golatest + +FROM gostable AS go-linux +FROM gostable AS go-darwin +FROM gostable AS go-windows-amd64 +FROM gostable AS go-windows-386 +FROM gostable AS go-windows-arm +FROM golatest AS go-windows-arm64 +FROM go-windows-${TARGETARCH} AS go-windows + +FROM --platform=$BUILDPLATFORM tonistiigi/xx:${XX_VERSION} AS xx + +FROM go-${TARGETOS} AS build-base-alpine +COPY --from=xx / / +RUN apk add --no-cache clang lld llvm file git +WORKDIR /go/src/github.com/docker/cli + +FROM build-base-alpine AS build-alpine +ARG TARGETPLATFORM +# gcc is installed for libgcc only +RUN xx-apk add --no-cache musl-dev gcc + +FROM go-${TARGETOS} AS build-base-buster +COPY --from=xx / / +RUN apt-get update && apt-get install --no-install-recommends -y clang lld file +WORKDIR /go/src/github.com/docker/cli + +FROM build-base-buster AS build-buster +ARG TARGETPLATFORM +RUN xx-apt install --no-install-recommends -y libc6-dev libgcc-8-dev + +FROM build-${BASE_VARIANT} AS build +# GO_LINKMODE defines if static or dynamic binary should be produced +ARG GO_LINKMODE=static +# GO_BUILDTAGS defines additional build tags +ARG GO_BUILDTAGS +# GO_STRIP strips debugging symbols if set +ARG GO_STRIP +# CGO_ENABLED manually sets if cgo is used +ARG CGO_ENABLED +# VERSION sets the version for the produced binary +ARG VERSION +RUN --mount=ro --mount=type=cache,target=/root/.cache \ + --mount=from=dockercore/golang-cross:xx-sdk-extras,target=/xx-sdk,src=/xx-sdk \ + --mount=type=tmpfs,target=cli/winresources \ + xx-go --wrap && \ + # export GOCACHE=$(go env GOCACHE)/$(xx-info)$([ -f /etc/alpine-release ] && echo "alpine") && \ + TARGET=/out ./scripts/build/binary && \ + xx-verify $([ "$GO_LINKMODE" = "static" ] && echo "--static") /out/docker + +FROM build-base-${BASE_VARIANT} AS dev +COPY . . + +FROM scratch AS binary +COPY --from=build /out . diff --git a/Jenkinsfile b/Jenkinsfile index d5028c921bbe..1e0850257b9b 100644 --- a/Jenkinsfile +++ b/Jenkinsfile @@ -1,6 +1,6 @@ pipeline { agent { - label "linux && x86_64" + label "amd64 && ubuntu-1804 && overlay2" } options { @@ -21,9 +21,9 @@ pipeline { make -f docker.Makefile test-e2e-non-experimental" } } - stage("e2e (non-experimental) - 18.09 engine") { + stage("e2e (non-experimental) - 19.03 engine") { steps { - sh "E2E_ENGINE_VERSION=18.09-dind \ + sh "E2E_ENGINE_VERSION=19.03-dind \ E2E_UNIQUE_ID=clie2e${BUILD_NUMBER} \ IMAGE_TAG=clie2e${BUILD_NUMBER} \ make -f docker.Makefile test-e2e-non-experimental" diff --git a/Makefile b/Makefile index 96c6379c9383..47f43eff8089 100644 --- a/Makefile +++ b/Makefile @@ -30,8 +30,7 @@ lint: ## run all the lint tools gometalinter --config gometalinter.json ./... .PHONY: binary -binary: ## build executable for Linux - @echo "WARNING: binary creates a Linux executable. Use cross for macOS or Windows." +binary: ./scripts/build/binary .PHONY: plugins @@ -39,28 +38,20 @@ plugins: ## build example CLI plugins ./scripts/build/plugins .PHONY: cross -cross: ## build executable for macOS and Windows - ./scripts/build/cross - -.PHONY: binary-windows -binary-windows: ## build executable for Windows - ./scripts/build/windows +cross: + ./scripts/build/binary .PHONY: plugins-windows plugins-windows: ## build example CLI plugins for Windows ./scripts/build/plugins-windows -.PHONY: binary-osx -binary-osx: ## build executable for macOS - ./scripts/build/osx - .PHONY: plugins-osx plugins-osx: ## build example CLI plugins for macOS ./scripts/build/plugins-osx .PHONY: dynbinary dynbinary: ## build dynamically linked binary - ./scripts/build/dynbinary + GO_LINKMODE=dynamic ./scripts/build/binary vendor: vendor.conf ## check that vendor matches vendor.conf rm -rf vendor diff --git a/README.md b/README.md index e21bccec0c04..770d68c1db8f 100644 --- a/README.md +++ b/README.md @@ -12,18 +12,31 @@ Development `docker/cli` is developed using Docker. -Build a linux binary: +Build CLI from source: ``` -$ make -f docker.Makefile binary +$ docker buildx bake ``` Build binaries for all supported platforms: ``` -$ make -f docker.Makefile cross +$ docker buildx bake cross ``` +Build for a specific platform: + +``` +$ docker buildx bake --set binary.platform=linux/arm64 +``` + +Build dynamic binary for glibc or musl: + +``` +$ USE_GLIBC=1 docker buildx bake dynbinary +``` + + Run all linting: ``` @@ -44,12 +57,6 @@ Start an interactive development environment: $ make -f docker.Makefile shell ``` -In the development environment you can run many tasks, including build binaries: - -``` -$ make binary -``` - Legal ===== *Brought to you courtesy of our legal counsel. For more context, diff --git a/appveyor.yml b/appveyor.yml index f019485c75ef..af219dc3587e 100644 --- a/appveyor.yml +++ b/appveyor.yml @@ -4,7 +4,7 @@ clone_folder: c:\gopath\src\github.com\docker\cli environment: GOPATH: c:\gopath - GOVERSION: 1.13.15 + GOVERSION: 1.16.15 DEPVERSION: v0.4.1 install: diff --git a/cli-plugins/manager/candidate.go b/cli-plugins/manager/candidate.go index 2000e5b142f6..752b1cb0ef8f 100644 --- a/cli-plugins/manager/candidate.go +++ b/cli-plugins/manager/candidate.go @@ -1,7 +1,7 @@ package manager import ( - "os/exec" + exec "golang.org/x/sys/execabs" ) // Candidate represents a possible plugin candidate, for mocking purposes diff --git a/cli-plugins/manager/manager.go b/cli-plugins/manager/manager.go index eaac4826221f..50f7208ea334 100644 --- a/cli-plugins/manager/manager.go +++ b/cli-plugins/manager/manager.go @@ -3,7 +3,6 @@ package manager import ( "io/ioutil" "os" - "os/exec" "path/filepath" "sort" "strings" @@ -12,6 +11,7 @@ import ( "github.com/docker/cli/cli/config" "github.com/fvbommel/sortorder" "github.com/spf13/cobra" + exec "golang.org/x/sys/execabs" ) // ReexecEnvvar is the name of an ennvar which is set to the command diff --git a/cli/command/cli.go b/cli/command/cli.go index 65ba4e82161c..fe6444f42f8d 100644 --- a/cli/command/cli.go +++ b/cli/command/cli.go @@ -255,7 +255,7 @@ func (cli *DockerCli) Initialize(opts *cliflags.ClientOptions, ops ...Initialize if tlsconfig.IsErrEncryptedKey(err) { passRetriever := passphrase.PromptRetrieverWithInOut(cli.In(), cli.Out(), nil) newClient := func(password string) (client.APIClient, error) { - cli.dockerEndpoint.TLSPassword = password + cli.dockerEndpoint.TLSPassword = password //nolint: staticcheck // SA1019: cli.dockerEndpoint.TLSPassword is deprecated return newAPIClientFromEndpoint(cli.dockerEndpoint, cli.configFile) } cli.client, err = getClientWithPassword(passRetriever, newClient) diff --git a/cli/command/cli_test.go b/cli/command/cli_test.go index 65cacdc61d27..370ecec803b9 100644 --- a/cli/command/cli_test.go +++ b/cli/command/cli_test.go @@ -6,7 +6,6 @@ import ( "crypto/x509" "fmt" "io/ioutil" - "net/http" "os" "runtime" "testing" @@ -80,24 +79,6 @@ func TestNewAPIClientFromFlagsWithAPIVersionFromEnv(t *testing.T) { assert.Check(t, is.Equal(customVersion, apiclient.ClientVersion())) } -func TestNewAPIClientFromFlagsWithHttpProxyEnv(t *testing.T) { - defer env.Patch(t, "HTTP_PROXY", "http://proxy.acme.com:1234")() - defer env.Patch(t, "DOCKER_HOST", "tcp://docker.acme.com:2376")() - - opts := &flags.CommonOptions{} - configFile := &configfile.ConfigFile{} - apiclient, err := NewAPIClientFromFlags(opts, configFile) - assert.NilError(t, err) - transport, ok := apiclient.HTTPClient().Transport.(*http.Transport) - assert.Assert(t, ok) - assert.Assert(t, transport.Proxy != nil) - request, err := http.NewRequest(http.MethodGet, "tcp://docker.acme.com:2376", nil) - assert.NilError(t, err) - url, err := transport.Proxy(request) - assert.NilError(t, err) - assert.Check(t, is.Equal("http://proxy.acme.com:1234", url.String())) -} - type fakeClient struct { client.Client pingFunc func() (types.Ping, error) diff --git a/cli/command/container/attach.go b/cli/command/container/attach.go index 854aa7395224..8470855992c8 100644 --- a/cli/command/container/attach.go +++ b/cli/command/container/attach.go @@ -97,7 +97,8 @@ func runAttach(dockerCli command.Cli, opts *attachOptions) error { } if opts.proxy && !c.Config.Tty { - sigc := ForwardAllSignals(ctx, dockerCli, opts.container) + sigc := notfiyAllSignals() + go ForwardAllSignals(ctx, dockerCli, opts.container, sigc) defer signal.StopCatch(sigc) } diff --git a/cli/command/container/client_test.go b/cli/command/container/client_test.go index 3643550b92c8..6aa7d9991e34 100644 --- a/cli/command/container/client_test.go +++ b/cli/command/container/client_test.go @@ -32,6 +32,7 @@ type fakeClient struct { containerExportFunc func(string) (io.ReadCloser, error) containerExecResizeFunc func(id string, options types.ResizeOptions) error containerRemoveFunc func(ctx context.Context, container string, options types.ContainerRemoveOptions) error + containerKillFunc func(ctx context.Context, container, signal string) error Version string } @@ -154,3 +155,10 @@ func (f *fakeClient) ContainerExecResize(_ context.Context, id string, options t } return nil } + +func (f *fakeClient) ContainerKill(ctx context.Context, container, signal string) error { + if f.containerKillFunc != nil { + return f.containerKillFunc(ctx, container, signal) + } + return nil +} diff --git a/cli/command/container/create_test.go b/cli/command/container/create_test.go index 15a9c4174915..54a83ce75d44 100644 --- a/cli/command/container/create_test.go +++ b/cli/command/container/create_test.go @@ -133,7 +133,7 @@ func TestCreateContainerImagePullPolicy(t *testing.T) { return ioutil.NopCloser(strings.NewReader("")), nil }, infoFunc: func() (types.Info, error) { - return types.Info{IndexServerAddress: "http://indexserver"}, nil + return types.Info{IndexServerAddress: "https://indexserver.example.com"}, nil }, } cli := test.NewFakeCli(client) diff --git a/cli/command/container/run.go b/cli/command/container/run.go index 74bee8cd12e1..fec9995841f8 100644 --- a/cli/command/container/run.go +++ b/cli/command/container/run.go @@ -131,7 +131,8 @@ func runContainer(dockerCli command.Cli, opts *runOptions, copts *containerOptio return runStartContainerErr(err) } if opts.sigProxy { - sigc := ForwardAllSignals(ctx, dockerCli, createResponse.ID) + sigc := notfiyAllSignals() + go ForwardAllSignals(ctx, dockerCli, createResponse.ID, sigc) defer signal.StopCatch(sigc) } diff --git a/cli/command/container/signals.go b/cli/command/container/signals.go new file mode 100644 index 000000000000..1929a9b19132 --- /dev/null +++ b/cli/command/container/signals.go @@ -0,0 +1,61 @@ +package container + +import ( + "context" + "os" + gosignal "os/signal" + + "github.com/docker/cli/cli/command" + "github.com/docker/docker/pkg/signal" + "github.com/sirupsen/logrus" +) + +// ForwardAllSignals forwards signals to the container +// +// The channel you pass in must already be setup to receive any signals you want to forward. +func ForwardAllSignals(ctx context.Context, cli command.Cli, cid string, sigc <-chan os.Signal) { + var ( + s os.Signal + ok bool + ) + for { + select { + case s, ok = <-sigc: + if !ok { + return + } + case <-ctx.Done(): + return + } + + if s == signal.SIGCHLD || s == signal.SIGPIPE { + continue + } + + // In go1.14+, the go runtime issues SIGURG as an interrupt to support pre-emptable system calls on Linux. + // Since we can't forward that along we'll check that here. + if isRuntimeSig(s) { + continue + } + var sig string + for sigStr, sigN := range signal.SignalMap { + if sigN == s { + sig = sigStr + break + } + } + if sig == "" { + continue + } + + if err := cli.Client().ContainerKill(ctx, cid, sig); err != nil { + logrus.Debugf("Error sending signal: %s", err) + } + } +} + +func notfiyAllSignals() chan os.Signal { + sigc := make(chan os.Signal, 128) + gosignal.Notify(sigc) + return sigc +} diff --git a/cli/command/container/signals_test.go b/cli/command/container/signals_test.go new file mode 100644 index 000000000000..39eaab1c5da8 --- /dev/null +++ b/cli/command/container/signals_test.go @@ -0,0 +1,48 @@ +package container + +import ( + "context" + "os" + "testing" + "time" + + "github.com/docker/cli/internal/test" + "github.com/docker/docker/pkg/signal" +) + +func TestForwardSignals(t *testing.T) { + ctx, cancel := context.WithCancel(context.Background()) + defer cancel() + + called := make(chan struct{}) + client := &fakeClient{containerKillFunc: func(ctx context.Context, container, signal string) error { + close(called) + return nil + }} + + cli := test.NewFakeCli(client) + sigc := make(chan os.Signal) + defer close(sigc) + + go ForwardAllSignals(ctx, cli, t.Name(), sigc) + + timer := time.NewTimer(30 * time.Second) + defer timer.Stop() + + select { + case <-timer.C: + t.Fatal("timeout waiting to send signal") + case sigc <- signal.SignalMap["TERM"]: + } + if !timer.Stop() { + <-timer.C + } + timer.Reset(30 * time.Second) + + select { + case <-called: + case <-timer.C: + t.Fatal("timeout waiting for signal to be processed") + } + +} diff --git a/cli/command/container/signals_unix.go b/cli/command/container/signals_unix.go new file mode 100644 index 000000000000..8db4cfe8353d --- /dev/null +++ b/cli/command/container/signals_unix.go @@ -0,0 +1,13 @@ +// +build !windows + +package container + +import ( + "os" + + "golang.org/x/sys/unix" +) + +func isRuntimeSig(s os.Signal) bool { + return s == unix.SIGURG +} diff --git a/cli/command/container/signals_unix_test.go b/cli/command/container/signals_unix_test.go new file mode 100644 index 000000000000..61ffe64a1cac --- /dev/null +++ b/cli/command/container/signals_unix_test.go @@ -0,0 +1,59 @@ +// +build !windows + +package container + +import ( + "context" + "os" + "syscall" + "testing" + "time" + + "github.com/docker/cli/internal/test" + "golang.org/x/sys/unix" + "gotest.tools/v3/assert" +) + +func TestIgnoredSignals(t *testing.T) { + ignoredSignals := []syscall.Signal{unix.SIGPIPE, unix.SIGCHLD, unix.SIGURG} + + for _, s := range ignoredSignals { + t.Run(unix.SignalName(s), func(t *testing.T) { + ctx, cancel := context.WithCancel(context.Background()) + defer cancel() + + var called bool + client := &fakeClient{containerKillFunc: func(ctx context.Context, container, signal string) error { + called = true + return nil + }} + + cli := test.NewFakeCli(client) + sigc := make(chan os.Signal) + defer close(sigc) + + done := make(chan struct{}) + go func() { + ForwardAllSignals(ctx, cli, t.Name(), sigc) + close(done) + }() + + timer := time.NewTimer(30 * time.Second) + defer timer.Stop() + + select { + case <-timer.C: + t.Fatal("timeout waiting to send signal") + case sigc <- s: + case <-done: + } + + // cancel the context so ForwardAllSignals will exit after it has processed the signal we sent. + // This is how we know the signal was actually processed and are not introducing a flakey test. + cancel() + <-done + + assert.Assert(t, !called, "kill was called") + }) + } +} diff --git a/cli/command/container/signals_windows.go b/cli/command/container/signals_windows.go new file mode 100644 index 000000000000..1e51b952fa74 --- /dev/null +++ b/cli/command/container/signals_windows.go @@ -0,0 +1,7 @@ +package container + +import "os" + +func isRuntimeSig(_ os.Signal) bool { + return false +} diff --git a/cli/command/container/start.go b/cli/command/container/start.go index 5ab05ae68b2e..bec948225f3f 100644 --- a/cli/command/container/start.go +++ b/cli/command/container/start.go @@ -74,7 +74,8 @@ func runStart(dockerCli command.Cli, opts *startOptions) error { // We always use c.ID instead of container to maintain consistency during `docker start` if !c.Config.Tty { - sigc := ForwardAllSignals(ctx, dockerCli, c.ID) + sigc := notfiyAllSignals() + go ForwardAllSignals(ctx, dockerCli, c.ID, sigc) defer signal.StopCatch(sigc) } diff --git a/cli/command/container/tty.go b/cli/command/container/tty.go index b7003f1a04df..4060c0a19f9a 100644 --- a/cli/command/container/tty.go +++ b/cli/command/container/tty.go @@ -95,32 +95,3 @@ func MonitorTtySize(ctx context.Context, cli command.Cli, id string, isExec bool } return nil } - -// ForwardAllSignals forwards signals to the container -func ForwardAllSignals(ctx context.Context, cli command.Cli, cid string) chan os.Signal { - sigc := make(chan os.Signal, 128) - signal.CatchAll(sigc) - go func() { - for s := range sigc { - if s == signal.SIGCHLD || s == signal.SIGPIPE { - continue - } - var sig string - for sigStr, sigN := range signal.SignalMap { - if sigN == s { - sig = sigStr - break - } - } - if sig == "" { - fmt.Fprintf(cli.Err(), "Unsupported signal: %v. Discarding.\n", s) - continue - } - - if err := cli.Client().ContainerKill(ctx, cid, sig); err != nil { - logrus.Debugf("Error sending signal: %s", err) - } - } - }() - return sigc -} diff --git a/cli/command/context/cmd.go b/cli/command/context/cmd.go index 1b6898456d04..6dce68aeaaa9 100644 --- a/cli/command/context/cmd.go +++ b/cli/command/context/cmd.go @@ -1,10 +1,6 @@ package context import ( - "errors" - "fmt" - "regexp" - "github.com/docker/cli/cli" "github.com/docker/cli/cli/command" "github.com/spf13/cobra" @@ -30,20 +26,3 @@ func NewContextCommand(dockerCli command.Cli) *cobra.Command { ) return cmd } - -const restrictedNamePattern = "^[a-zA-Z0-9][a-zA-Z0-9_.+-]+$" - -var restrictedNameRegEx = regexp.MustCompile(restrictedNamePattern) - -func validateContextName(name string) error { - if name == "" { - return errors.New("context name cannot be empty") - } - if name == "default" { - return errors.New(`"default" is a reserved context name`) - } - if !restrictedNameRegEx.MatchString(name) { - return fmt.Errorf("context name %q is invalid, names are validated against regexp %q", name, restrictedNamePattern) - } - return nil -} diff --git a/cli/command/context/create.go b/cli/command/context/create.go index 9d5865a70a7d..776d29fa10d7 100644 --- a/cli/command/context/create.go +++ b/cli/command/context/create.go @@ -62,8 +62,11 @@ func newCreateCommand(dockerCli command.Cli) *cobra.Command { &opts.DefaultStackOrchestrator, "default-stack-orchestrator", "", "Default orchestrator for stack operations to use with this context (swarm|kubernetes|all)") + flags.SetAnnotation("default-stack-orchestrator", "deprecated", nil) flags.StringToStringVar(&opts.Docker, "docker", nil, "set the docker endpoint") flags.StringToStringVar(&opts.Kubernetes, "kubernetes", nil, "set the kubernetes endpoint") + flags.SetAnnotation("kubernetes", "kubernetes", nil) + flags.SetAnnotation("kubernetes", "deprecated", nil) flags.StringVar(&opts.From, "from", "", "create context from a named context") return cmd } @@ -137,7 +140,7 @@ func createNewContext(o *CreateOptions, stackOrchestrator command.Orchestrator, } func checkContextNameForCreation(s store.Reader, name string) error { - if err := validateContextName(name); err != nil { + if err := store.ValidateContextName(name); err != nil { return err } if _, err := s.GetMetadata(name); !store.IsErrContextDoesNotExist(err) { diff --git a/cli/command/context/create_test.go b/cli/command/context/create_test.go index 916672daee6a..afdd8bef3f23 100644 --- a/cli/command/context/create_test.go +++ b/cli/command/context/create_test.go @@ -169,7 +169,7 @@ func validateTestKubeEndpoint(t *testing.T, s store.Reader, name string) { kubeMeta := ctxMetadata.Endpoints[kubernetes.KubernetesEndpoint].(kubernetes.EndpointMeta) kubeEP, err := kubeMeta.WithTLSData(s, name) assert.NilError(t, err) - assert.Equal(t, "https://someserver", kubeEP.Host) + assert.Equal(t, "https://someserver.example.com", kubeEP.Host) assert.Equal(t, "the-ca", string(kubeEP.TLSData.CA)) assert.Equal(t, "the-cert", string(kubeEP.TLSData.Cert)) assert.Equal(t, "the-key", string(kubeEP.TLSData.Key)) @@ -287,7 +287,7 @@ func TestCreateFromContext(t *testing.T) { assert.Equal(t, newContextTyped.Description, c.expectedDescription) assert.Equal(t, newContextTyped.StackOrchestrator, c.expectedOrchestrator) assert.Equal(t, dockerEndpoint.Host, "tcp://42.42.42.42:2375") - assert.Equal(t, kubeEndpoint.Host, "https://someserver") + assert.Equal(t, kubeEndpoint.Host, "https://someserver.example.com") }) } } @@ -361,7 +361,7 @@ func TestCreateFromCurrent(t *testing.T) { assert.Equal(t, newContextTyped.Description, c.expectedDescription) assert.Equal(t, newContextTyped.StackOrchestrator, c.expectedOrchestrator) assert.Equal(t, dockerEndpoint.Host, "tcp://42.42.42.42:2375") - assert.Equal(t, kubeEndpoint.Host, "https://someserver") + assert.Equal(t, kubeEndpoint.Host, "https://someserver.example.com") }) } } diff --git a/cli/command/context/export.go b/cli/command/context/export.go index fd66a5d490d0..c7cc94ff3e0f 100644 --- a/cli/command/context/export.go +++ b/cli/command/context/export.go @@ -46,6 +46,8 @@ func newExportCommand(dockerCli command.Cli) *cobra.Command { flags := cmd.Flags() flags.BoolVar(&opts.Kubeconfig, "kubeconfig", false, "Export as a kubeconfig file") + flags.SetAnnotation("kubeconfig", "kubernetes", nil) + flags.SetAnnotation("kubeconfig", "deprecated", nil) return cmd } @@ -77,7 +79,7 @@ func writeTo(dockerCli command.Cli, reader io.Reader, dest string) error { // RunExport exports a Docker context func RunExport(dockerCli command.Cli, opts *ExportOptions) error { - if err := validateContextName(opts.ContextName); err != nil && opts.ContextName != command.DefaultContextName { + if err := store.ValidateContextName(opts.ContextName); err != nil && opts.ContextName != command.DefaultContextName { return err } ctxMeta, err := dockerCli.ContextStore().GetMetadata(opts.ContextName) diff --git a/cli/command/context/list_test.go b/cli/command/context/list_test.go index d628493fc31b..b71a78b5a98c 100644 --- a/cli/command/context/list_test.go +++ b/cli/command/context/list_test.go @@ -18,7 +18,7 @@ func createTestContextWithKubeAndSwarm(t *testing.T, cli command.Cli, name strin DefaultStackOrchestrator: orchestrator, Description: "description of " + name, Kubernetes: map[string]string{keyFrom: "default"}, - Docker: map[string]string{keyHost: "https://someswarmserver"}, + Docker: map[string]string{keyHost: "https://someswarmserver.example.com"}, }) assert.NilError(t, err) } diff --git a/cli/command/context/testdata/inspect.golden b/cli/command/context/testdata/inspect.golden index d520b4f93ca3..5578411950ab 100644 --- a/cli/command/context/testdata/inspect.golden +++ b/cli/command/context/testdata/inspect.golden @@ -7,11 +7,11 @@ }, "Endpoints": { "docker": { - "Host": "https://someswarmserver", + "Host": "https://someswarmserver.example.com", "SkipTLSVerify": false }, "kubernetes": { - "Host": "https://someserver", + "Host": "https://someserver.example.com", "SkipTLSVerify": false, "DefaultNamespace": "default" } diff --git a/cli/command/context/testdata/list.golden b/cli/command/context/testdata/list.golden index 6909a8d7f5bf..b1a2ec7c240d 100644 --- a/cli/command/context/testdata/list.golden +++ b/cli/command/context/testdata/list.golden @@ -1,5 +1,5 @@ -NAME DESCRIPTION DOCKER ENDPOINT KUBERNETES ENDPOINT ORCHESTRATOR -current * description of current https://someswarmserver https://someserver (default) all -default Current DOCKER_HOST based configuration unix:///var/run/docker.sock swarm -other description of other https://someswarmserver https://someserver (default) all -unset description of unset https://someswarmserver https://someserver (default) +NAME DESCRIPTION DOCKER ENDPOINT KUBERNETES ENDPOINT ORCHESTRATOR +current * description of current https://someswarmserver.example.com https://someserver.example.com (default) all +default Current DOCKER_HOST based configuration unix:///var/run/docker.sock swarm +other description of other https://someswarmserver.example.com https://someserver.example.com (default) all +unset description of unset https://someswarmserver.example.com https://someserver.example.com (default) diff --git a/cli/command/context/testdata/test-kubeconfig b/cli/command/context/testdata/test-kubeconfig index f6baf8e843de..5d5c858ed8f2 100644 --- a/cli/command/context/testdata/test-kubeconfig +++ b/cli/command/context/testdata/test-kubeconfig @@ -2,7 +2,7 @@ apiVersion: v1 clusters: - cluster: certificate-authority-data: dGhlLWNh - server: https://someserver + server: https://someserver.example.com name: test-cluster contexts: - context: diff --git a/cli/command/context/update.go b/cli/command/context/update.go index 9165bb301969..cfd4d76bc880 100644 --- a/cli/command/context/update.go +++ b/cli/command/context/update.go @@ -61,14 +61,17 @@ func newUpdateCommand(dockerCli command.Cli) *cobra.Command { &opts.DefaultStackOrchestrator, "default-stack-orchestrator", "", "Default orchestrator for stack operations to use with this context (swarm|kubernetes|all)") + flags.SetAnnotation("default-stack-orchestrator", "deprecated", nil) flags.StringToStringVar(&opts.Docker, "docker", nil, "set the docker endpoint") flags.StringToStringVar(&opts.Kubernetes, "kubernetes", nil, "set the kubernetes endpoint") + flags.SetAnnotation("kubernetes", "kubernetes", nil) + flags.SetAnnotation("kubernetes", "deprecated", nil) return cmd } // RunUpdate updates a Docker context func RunUpdate(cli command.Cli, o *UpdateOptions) error { - if err := validateContextName(o.Name); err != nil { + if err := store.ValidateContextName(o.Name); err != nil { return err } s := cli.ContextStore() diff --git a/cli/command/context/use.go b/cli/command/context/use.go index 97e3a9705615..a3998da69dd6 100644 --- a/cli/command/context/use.go +++ b/cli/command/context/use.go @@ -5,6 +5,7 @@ import ( "os" "github.com/docker/cli/cli/command" + "github.com/docker/cli/cli/context/store" "github.com/spf13/cobra" ) @@ -23,7 +24,7 @@ func newUseCommand(dockerCli command.Cli) *cobra.Command { // RunUse set the current Docker context func RunUse(dockerCli command.Cli, name string) error { - if err := validateContextName(name); err != nil && name != "default" { + if err := store.ValidateContextName(name); err != nil && name != "default" { return err } if _, err := dockerCli.ContextStore().GetMetadata(name); err != nil && name != "default" { diff --git a/cli/command/image/build/context.go b/cli/command/image/build/context.go index 24a9d525b5fb..2509f66de4a4 100644 --- a/cli/command/image/build/context.go +++ b/cli/command/image/build/context.go @@ -9,7 +9,6 @@ import ( "io/ioutil" "net/http" "os" - "os/exec" "path/filepath" "runtime" "strings" @@ -24,6 +23,7 @@ import ( "github.com/docker/docker/pkg/streamformatter" "github.com/docker/docker/pkg/stringid" "github.com/pkg/errors" + exec "golang.org/x/sys/execabs" ) const ( diff --git a/cli/command/image/build_buildkit.go b/cli/command/image/build_buildkit.go index e377fc2886b4..b40d53cdbd21 100644 --- a/cli/command/image/build_buildkit.go +++ b/cli/command/image/build_buildkit.go @@ -78,7 +78,7 @@ func runBuildBuildKit(dockerCli command.Cli, options buildOptions) error { if options.dockerfileFromStdin() { return errStdinConflict } - rc, isArchive, err := build.DetectArchiveReader(os.Stdin) + rc, isArchive, err := build.DetectArchiveReader(dockerCli.In()) if err != nil { return err } @@ -98,7 +98,7 @@ func runBuildBuildKit(dockerCli command.Cli, options buildOptions) error { case isLocalDir(options.context): contextDir = options.context if options.dockerfileFromStdin() { - dockerfileReader = os.Stdin + dockerfileReader = dockerCli.In() } else if options.dockerfileName != "" { dockerfileName = filepath.Base(options.dockerfileName) dockerfileDir = filepath.Dir(options.dockerfileName) diff --git a/cli/command/image/trust_test.go b/cli/command/image/trust_test.go index 11b3e1b170fa..b7279dc330b7 100644 --- a/cli/command/image/trust_test.go +++ b/cli/command/image/trust_test.go @@ -15,17 +15,17 @@ import ( ) func TestENVTrustServer(t *testing.T) { - defer env.PatchAll(t, map[string]string{"DOCKER_CONTENT_TRUST_SERVER": "https://notary-test.com:5000"})() + defer env.PatchAll(t, map[string]string{"DOCKER_CONTENT_TRUST_SERVER": "https://notary-test.example.com:5000"})() indexInfo := ®istrytypes.IndexInfo{Name: "testserver"} output, err := trust.Server(indexInfo) - expectedStr := "https://notary-test.com:5000" + expectedStr := "https://notary-test.example.com:5000" if err != nil || output != expectedStr { t.Fatalf("Expected server to be %s, got %s", expectedStr, output) } } func TestHTTPENVTrustServer(t *testing.T) { - defer env.PatchAll(t, map[string]string{"DOCKER_CONTENT_TRUST_SERVER": "http://notary-test.com:5000"})() + defer env.PatchAll(t, map[string]string{"DOCKER_CONTENT_TRUST_SERVER": "http://notary-test.example.com:5000"})() indexInfo := ®istrytypes.IndexInfo{Name: "testserver"} _, err := trust.Server(indexInfo) if err == nil { diff --git a/cli/command/registry.go b/cli/command/registry.go index 68cb43144db6..68e3dd36ed71 100644 --- a/cli/command/registry.go +++ b/cli/command/registry.go @@ -66,11 +66,11 @@ func RegistryAuthenticationPrivilegedFunc(cli Cli, index *registrytypes.IndexInf if err != nil { fmt.Fprintf(cli.Err(), "Unable to retrieve stored credentials for %s, error: %s.\n", indexServer, err) } - err = ConfigureAuth(cli, "", "", authConfig, isDefaultRegistry) + err = ConfigureAuth(cli, "", "", &authConfig, isDefaultRegistry) if err != nil { return "", err } - return EncodeAuthToBase64(*authConfig) + return EncodeAuthToBase64(authConfig) } } @@ -89,7 +89,7 @@ func ResolveAuthConfig(ctx context.Context, cli Cli, index *registrytypes.IndexI // GetDefaultAuthConfig gets the default auth config given a serverAddress // If credentials for given serverAddress exists in the credential store, the configuration will be populated with values in it -func GetDefaultAuthConfig(cli Cli, checkCredStore bool, serverAddress string, isDefaultRegistry bool) (*types.AuthConfig, error) { +func GetDefaultAuthConfig(cli Cli, checkCredStore bool, serverAddress string, isDefaultRegistry bool) (types.AuthConfig, error) { if !isDefaultRegistry { serverAddress = registry.ConvertToHostname(serverAddress) } @@ -98,13 +98,15 @@ func GetDefaultAuthConfig(cli Cli, checkCredStore bool, serverAddress string, is if checkCredStore { authconfig, err = cli.ConfigFile().GetAuthConfig(serverAddress) if err != nil { - return nil, err + return types.AuthConfig{ + ServerAddress: serverAddress, + }, err } } authconfig.ServerAddress = serverAddress authconfig.IdentityToken = "" res := types.AuthConfig(authconfig) - return &res, nil + return res, nil } // ConfigureAuth handles prompting of user's username and password if needed diff --git a/cli/command/registry/login.go b/cli/command/registry/login.go index f6cb579e7556..3820c414b124 100644 --- a/cli/command/registry/login.go +++ b/cli/command/registry/login.go @@ -111,24 +111,22 @@ func runLogin(dockerCli command.Cli, opts loginOptions) error { //nolint: gocycl serverAddress = authServer } - var err error - var authConfig *types.AuthConfig var response registrytypes.AuthenticateOKBody isDefaultRegistry := serverAddress == authServer - authConfig, err = command.GetDefaultAuthConfig(dockerCli, opts.user == "" && opts.password == "", serverAddress, isDefaultRegistry) + authConfig, err := command.GetDefaultAuthConfig(dockerCli, opts.user == "" && opts.password == "", serverAddress, isDefaultRegistry) if err == nil && authConfig.Username != "" && authConfig.Password != "" { - response, err = loginWithCredStoreCreds(ctx, dockerCli, authConfig) + response, err = loginWithCredStoreCreds(ctx, dockerCli, &authConfig) } if err != nil || authConfig.Username == "" || authConfig.Password == "" { - err = command.ConfigureAuth(dockerCli, opts.user, opts.password, authConfig, isDefaultRegistry) + err = command.ConfigureAuth(dockerCli, opts.user, opts.password, &authConfig, isDefaultRegistry) if err != nil { return err } - response, err = clnt.RegistryLogin(ctx, *authConfig) + response, err = clnt.RegistryLogin(ctx, authConfig) if err != nil && client.IsErrConnectionFailed(err) { // If the server isn't responding (yet) attempt to login purely client side - response, err = loginClientSide(ctx, *authConfig) + response, err = loginClientSide(ctx, authConfig) } // If we (still) have an error, give up if err != nil { @@ -151,7 +149,7 @@ func runLogin(dockerCli command.Cli, opts loginOptions) error { //nolint: gocycl } } - if err := creds.Store(configtypes.AuthConfig(*authConfig)); err != nil { + if err := creds.Store(configtypes.AuthConfig(authConfig)); err != nil { return errors.Errorf("Error saving credentials: %v", err) } diff --git a/cli/command/registry_test.go b/cli/command/registry_test.go index ae7c3ac052f0..bd9e5edbdb5a 100644 --- a/cli/command/registry_test.go +++ b/cli/command/registry_test.go @@ -66,10 +66,10 @@ func TestElectAuthServer(t *testing.T) { }, }, { - expectedAuthServer: "https://foo.bar", + expectedAuthServer: "https://foo.example.com", expectedWarning: "", infoFunc: func() (types.Info, error) { - return types.Info{IndexServerAddress: "https://foo.bar"}, nil + return types.Info{IndexServerAddress: "https://foo.example.com"}, nil }, }, { @@ -145,7 +145,21 @@ func TestGetDefaultAuthConfig(t *testing.T) { assert.Check(t, is.Equal(tc.expectedErr, err.Error())) } else { assert.NilError(t, err) - assert.Check(t, is.DeepEqual(tc.expectedAuthConfig, *authconfig)) + assert.Check(t, is.DeepEqual(tc.expectedAuthConfig, authconfig)) } } } + +func TestGetDefaultAuthConfig_HelperError(t *testing.T) { + cli := test.NewFakeCli(&fakeClient{}) + errBuf := new(bytes.Buffer) + cli.SetErr(errBuf) + cli.ConfigFile().CredentialsStore = "fake-does-not-exist" + serverAddress := "test-server-address" + expectedAuthConfig := types.AuthConfig{ + ServerAddress: serverAddress, + } + authconfig, err := GetDefaultAuthConfig(cli, true, serverAddress, serverAddress == "https://index.docker.io/v1/") + assert.Check(t, is.DeepEqual(expectedAuthConfig, authconfig)) + assert.Check(t, is.ErrorContains(err, "docker-credential-fake-does-not-exist")) +} diff --git a/cli/command/service/opts.go b/cli/command/service/opts.go index b8b6873a0b3c..020e9dd01561 100644 --- a/cli/command/service/opts.go +++ b/cli/command/service/opts.go @@ -165,7 +165,7 @@ func updateConfigFromDefaults(defaultUpdateConfig *api.UpdateConfig) *swarm.Upda } func (opts updateOptions) updateConfig(flags *pflag.FlagSet) *swarm.UpdateConfig { - if !anyChanged(flags, flagUpdateParallelism, flagUpdateDelay, flagUpdateMonitor, flagUpdateFailureAction, flagUpdateMaxFailureRatio) { + if !anyChanged(flags, flagUpdateParallelism, flagUpdateDelay, flagUpdateMonitor, flagUpdateFailureAction, flagUpdateMaxFailureRatio, flagUpdateOrder) { return nil } @@ -194,7 +194,7 @@ func (opts updateOptions) updateConfig(flags *pflag.FlagSet) *swarm.UpdateConfig } func (opts updateOptions) rollbackConfig(flags *pflag.FlagSet) *swarm.UpdateConfig { - if !anyChanged(flags, flagRollbackParallelism, flagRollbackDelay, flagRollbackMonitor, flagRollbackFailureAction, flagRollbackMaxFailureRatio) { + if !anyChanged(flags, flagRollbackParallelism, flagRollbackDelay, flagRollbackMonitor, flagRollbackFailureAction, flagRollbackMaxFailureRatio, flagRollbackOrder) { return nil } diff --git a/cli/command/service/opts_test.go b/cli/command/service/opts_test.go index c89948ad39e1..7d014a02e64a 100644 --- a/cli/command/service/opts_test.go +++ b/cli/command/service/opts_test.go @@ -289,6 +289,22 @@ func TestToServiceUpdateRollback(t *testing.T) { assert.Check(t, is.DeepEqual(service.RollbackConfig, expected.RollbackConfig)) } +func TestToServiceUpdateRollbackOrder(t *testing.T) { + flags := newCreateCommand(nil).Flags() + flags.Set("update-order", "start-first") + flags.Set("rollback-order", "start-first") + + o := newServiceOptions() + o.mode = "replicated" + o.update = updateOptions{order: "start-first"} + o.rollback = updateOptions{order: "start-first"} + + service, err := o.ToService(context.Background(), &fakeClient{}, flags) + assert.NilError(t, err) + assert.Check(t, is.Equal(service.UpdateConfig.Order, o.update.order)) + assert.Check(t, is.Equal(service.RollbackConfig.Order, o.rollback.order)) +} + func TestToServiceMaxReplicasGlobalModeConflict(t *testing.T) { opt := serviceOptions{ mode: "global", diff --git a/cli/command/service/progress/progress.go b/cli/command/service/progress/progress.go index 3f118d81a485..3ed41cb9e44a 100644 --- a/cli/command/service/progress/progress.go +++ b/cli/command/service/progress/progress.go @@ -99,6 +99,7 @@ func ServiceProgress(ctx context.Context, client client.APIClient, serviceID str convergedAt time.Time monitor = 5 * time.Second rollback bool + message *progress.Progress ) for { @@ -140,8 +141,9 @@ func ServiceProgress(ctx context.Context, client client.APIClient, serviceID str return fmt.Errorf("service rollback paused: %s", service.UpdateStatus.Message) case swarm.UpdateStateRollbackCompleted: if !converged { - return fmt.Errorf("service rolled back: %s", service.UpdateStatus.Message) + message = &progress.Progress{ID: "rollback", Message: service.UpdateStatus.Message} } + rollback = true } } if converged && time.Since(convergedAt) >= monitor { @@ -149,7 +151,9 @@ func ServiceProgress(ctx context.Context, client client.APIClient, serviceID str ID: "verify", Action: "Service converged", }) - + if message != nil { + progressOut.WriteProgress(*message) + } return nil } diff --git a/cli/command/stack/cmd.go b/cli/command/stack/cmd.go index f4ded7716934..8248ad240d6e 100644 --- a/cli/command/stack/cmd.go +++ b/cli/command/stack/cmd.go @@ -69,7 +69,9 @@ func NewStackCommand(dockerCli command.Cli) *cobra.Command { flags := cmd.PersistentFlags() flags.String("kubeconfig", "", "Kubernetes config file") flags.SetAnnotation("kubeconfig", "kubernetes", nil) + flags.SetAnnotation("kubeconfig", "deprecated", nil) flags.String("orchestrator", "", "Orchestrator to use (swarm|kubernetes|all)") + flags.SetAnnotation("orchestrator", "deprecated", nil) return cmd } diff --git a/cli/command/stack/kubernetes/cli.go b/cli/command/stack/kubernetes/cli.go index a531846809cc..9b6d50473b37 100644 --- a/cli/command/stack/kubernetes/cli.go +++ b/cli/command/stack/kubernetes/cli.go @@ -50,6 +50,7 @@ func NewOptions(flags *flag.FlagSet, orchestrator command.Orchestrator) Options func AddNamespaceFlag(flags *flag.FlagSet) { flags.String("namespace", "", "Kubernetes namespace to use") flags.SetAnnotation("namespace", "kubernetes", nil) + flags.SetAnnotation("namespace", "deprecated", nil) } // WrapCli wraps command.Cli with kubernetes specifics diff --git a/cli/command/stack/list.go b/cli/command/stack/list.go index 5175ea371c8f..412cc2e5ee86 100644 --- a/cli/command/stack/list.go +++ b/cli/command/stack/list.go @@ -30,8 +30,10 @@ func newListCommand(dockerCli command.Cli, common *commonOptions) *cobra.Command flags.StringVar(&opts.Format, "format", "", "Pretty-print stacks using a Go template") flags.StringSliceVar(&opts.Namespaces, "namespace", []string{}, "Kubernetes namespaces to use") flags.SetAnnotation("namespace", "kubernetes", nil) + flags.SetAnnotation("namespace", "deprecated", nil) flags.BoolVarP(&opts.AllNamespaces, "all-namespaces", "", false, "List stacks from all Kubernetes namespaces") flags.SetAnnotation("all-namespaces", "kubernetes", nil) + flags.SetAnnotation("all-namespaces", "deprecated", nil) return cmd } diff --git a/cli/command/swarm/ca_test.go b/cli/command/swarm/ca_test.go index e9fafcaf71f0..1f65647c5880 100644 --- a/cli/command/swarm/ca_test.go +++ b/cli/command/swarm/ca_test.go @@ -104,20 +104,20 @@ func TestDisplayTrustRootInvalidFlags(t *testing.T) { errorMsg: "flag requires the `--rotate` flag to update the CA", }, { - args: []string{"--external-ca=protocol=cfssl,url=https://some.com/https/url"}, + args: []string{"--external-ca=protocol=cfssl,url=https://some.example.com/https/url"}, errorMsg: "flag requires the `--rotate` flag to update the CA", }, { // to make sure we're not erroring because we didn't provide a CA cert and external CA args: []string{ "--ca-cert=" + tmpfile, - "--external-ca=protocol=cfssl,url=https://some.com/https/url", + "--external-ca=protocol=cfssl,url=https://some.example.com/https/url", }, errorMsg: "flag requires the `--rotate` flag to update the CA", }, { args: []string{ "--rotate", - "--external-ca=protocol=cfssl,url=https://some.com/https/url", + "--external-ca=protocol=cfssl,url=https://some.example.com/https/url", }, errorMsg: "rotating to an external CA requires the `--ca-cert` flag to specify the external CA's cert - " + "to add an external CA with the current root CA certificate, use the `update` command instead", @@ -243,7 +243,7 @@ func TestUpdateSwarmSpecCertAndExternalCA(t *testing.T) { "--rotate", "--detach", "--ca-cert=" + certfile, - "--external-ca=protocol=cfssl,url=https://some.external.ca"}) + "--external-ca=protocol=cfssl,url=https://some.external.ca.example.com"}) cmd.SetOut(cli.OutBuffer()) assert.NilError(t, cmd.Execute()) @@ -253,7 +253,7 @@ func TestUpdateSwarmSpecCertAndExternalCA(t *testing.T) { expected.CAConfig.ExternalCAs = []*swarm.ExternalCA{ { Protocol: swarm.ExternalCAProtocolCFSSL, - URL: "https://some.external.ca", + URL: "https://some.external.ca.example.com", CACert: cert, Options: make(map[string]string), }, @@ -281,7 +281,7 @@ func TestUpdateSwarmSpecCertAndKeyAndExternalCA(t *testing.T) { "--detach", "--ca-cert=" + certfile, "--ca-key=" + keyfile, - "--external-ca=protocol=cfssl,url=https://some.external.ca"}) + "--external-ca=protocol=cfssl,url=https://some.external.ca.example.com"}) cmd.SetOut(cli.OutBuffer()) assert.NilError(t, cmd.Execute()) @@ -291,7 +291,7 @@ func TestUpdateSwarmSpecCertAndKeyAndExternalCA(t *testing.T) { expected.CAConfig.ExternalCAs = []*swarm.ExternalCA{ { Protocol: swarm.ExternalCAProtocolCFSSL, - URL: "https://some.external.ca", + URL: "https://some.external.ca.example.com", CACert: cert, Options: make(map[string]string), }, diff --git a/cli/command/system/info.go b/cli/command/system/info.go index 0e9bd0db42ce..6c4dc01d9c36 100644 --- a/cli/command/system/info.go +++ b/cli/command/system/info.go @@ -14,6 +14,7 @@ import ( "github.com/docker/cli/templates" "github.com/docker/docker/api/types" "github.com/docker/docker/api/types/swarm" + "github.com/docker/docker/api/types/versions" "github.com/docker/go-units" "github.com/spf13/cobra" ) @@ -211,9 +212,6 @@ func prettyPrintServerInfo(dockerCli command.Cli, info types.Info) []error { for _, o := range so.Options { switch o.Key { case "profile": - if o.Value != "default" { - fmt.Fprintln(dockerCli.Err(), " WARNING: You're not using the default seccomp profile") - } fmt.Fprintln(dockerCli.Out(), " Profile:", o.Value) } } @@ -378,6 +376,9 @@ func printSwarmInfo(dockerCli command.Cli, info types.Info) { } func printServerWarnings(dockerCli command.Cli, info types.Info) { + if versions.LessThan(dockerCli.Client().ClientVersion(), "1.42") { + printSecurityOptionsWarnings(dockerCli, info) + } if len(info.Warnings) > 0 { fmt.Fprintln(dockerCli.Err(), strings.Join(info.Warnings, "\n")) return @@ -387,6 +388,29 @@ func printServerWarnings(dockerCli command.Cli, info types.Info) { printServerWarningsLegacy(dockerCli, info) } +// printSecurityOptionsWarnings prints warnings based on the security options +// returned by the daemon. +// DEPRECATED: warnings are now generated by the daemon, and returned in +// info.Warnings. This function is used to provide backward compatibility with +// daemons that do not provide these warnings. No new warnings should be added +// here. +func printSecurityOptionsWarnings(dockerCli command.Cli, info types.Info) { + if info.OSType == "windows" { + return + } + kvs, _ := types.DecodeSecurityOptions(info.SecurityOptions) + for _, so := range kvs { + if so.Name != "seccomp" { + continue + } + for _, o := range so.Options { + if o.Key == "profile" && o.Value != "default" && o.Value != "builtin" { + _, _ = fmt.Fprintln(dockerCli.Err(), "WARNING: You're not using the default seccomp profile") + } + } + } +} + // printServerWarningsLegacy generates warnings based on information returned by the daemon. // DEPRECATED: warnings are now generated by the daemon, and returned in // info.Warnings. This function is used to provide backward compatibility with @@ -402,10 +426,7 @@ func printServerWarningsLegacy(dockerCli command.Cli, info types.Info) { if !info.SwapLimit { fmt.Fprintln(dockerCli.Err(), "WARNING: No swap limit support") } - if !info.KernelMemory { - fmt.Fprintln(dockerCli.Err(), "WARNING: No kernel memory limit support") - } - if !info.OomKillDisable { + if !info.OomKillDisable && info.CgroupVersion != "2" { fmt.Fprintln(dockerCli.Err(), "WARNING: No oom kill disable support") } if !info.CPUCfsQuota { diff --git a/cli/command/system/info_test.go b/cli/command/system/info_test.go index 04e52450b77b..d3762ea783dc 100644 --- a/cli/command/system/info_test.go +++ b/cli/command/system/info_test.go @@ -248,7 +248,6 @@ func TestPrettyPrintInfo(t *testing.T) { sampleInfoDaemonWarnings.Warnings = []string{ "WARNING: No memory limit support", "WARNING: No swap limit support", - "WARNING: No kernel memory limit support", "WARNING: No oom kill disable support", "WARNING: No cpu cfs quota support", "WARNING: No cpu cfs period support", diff --git a/cli/command/system/testdata/docker-info-daemon-warnings.json.golden b/cli/command/system/testdata/docker-info-daemon-warnings.json.golden index 5b7b23124fdd..09e1ebd9c54f 100644 --- a/cli/command/system/testdata/docker-info-daemon-warnings.json.golden +++ b/cli/command/system/testdata/docker-info-daemon-warnings.json.golden @@ -1 +1 @@ -{"ID":"EKHL:QDUU:QZ7U:MKGD:VDXK:S27Q:GIPU:24B7:R7VT:DGN6:QCSF:2UBX","Containers":0,"ContainersRunning":0,"ContainersPaused":0,"ContainersStopped":0,"Images":0,"Driver":"aufs","DriverStatus":[["Root Dir","/var/lib/docker/aufs"],["Backing Filesystem","extfs"],["Dirs","0"],["Dirperm1 Supported","true"]],"Plugins":{"Volume":["local"],"Network":["bridge","host","macvlan","null","overlay"],"Authorization":null,"Log":["awslogs","fluentd","gcplogs","gelf","journald","json-file","logentries","splunk","syslog"]},"MemoryLimit":true,"SwapLimit":true,"KernelMemory":true,"KernelMemoryTCP":false,"CpuCfsPeriod":true,"CpuCfsQuota":true,"CPUShares":true,"CPUSet":true,"PidsLimit":false,"IPv4Forwarding":true,"BridgeNfIptables":true,"BridgeNfIp6tables":true,"Debug":true,"NFd":33,"OomKillDisable":true,"NGoroutines":135,"SystemTime":"2017-08-24T17:44:34.077811894Z","LoggingDriver":"json-file","CgroupDriver":"cgroupfs","NEventsListener":0,"KernelVersion":"4.4.0-87-generic","OperatingSystem":"Ubuntu 16.04.3 LTS","OSVersion":"","OSType":"linux","Architecture":"x86_64","IndexServerAddress":"https://index.docker.io/v1/","RegistryConfig":{"AllowNondistributableArtifactsCIDRs":null,"AllowNondistributableArtifactsHostnames":null,"InsecureRegistryCIDRs":["127.0.0.0/8"],"IndexConfigs":{"docker.io":{"Name":"docker.io","Mirrors":null,"Secure":true,"Official":true}},"Mirrors":null},"NCPU":2,"MemTotal":2097356800,"GenericResources":null,"DockerRootDir":"/var/lib/docker","HttpProxy":"","HttpsProxy":"","NoProxy":"","Name":"system-sample","Labels":["provider=digitalocean"],"ExperimentalBuild":false,"ServerVersion":"17.06.1-ce","Runtimes":{"runc":{"path":"docker-runc"}},"DefaultRuntime":"runc","Swarm":{"NodeID":"","NodeAddr":"","LocalNodeState":"inactive","ControlAvailable":false,"Error":"","RemoteManagers":null},"LiveRestoreEnabled":false,"Isolation":"","InitBinary":"docker-init","ContainerdCommit":{"ID":"6e23458c129b551d5c9871e5174f6b1b7f6d1170","Expected":"6e23458c129b551d5c9871e5174f6b1b7f6d1170"},"RuncCommit":{"ID":"810190ceaa507aa2727d7ae6f4790c76ec150bd2","Expected":"810190ceaa507aa2727d7ae6f4790c76ec150bd2"},"InitCommit":{"ID":"949e6fa","Expected":"949e6fa"},"SecurityOptions":["name=apparmor","name=seccomp,profile=default"],"DefaultAddressPools":[{"Base":"10.123.0.0/16","Size":24}],"Warnings":["WARNING: No memory limit support","WARNING: No swap limit support","WARNING: No kernel memory limit support","WARNING: No oom kill disable support","WARNING: No cpu cfs quota support","WARNING: No cpu cfs period support","WARNING: No cpu shares support","WARNING: No cpuset support","WARNING: IPv4 forwarding is disabled","WARNING: bridge-nf-call-iptables is disabled","WARNING: bridge-nf-call-ip6tables is disabled"],"ClientInfo":{"Debug":true,"Context":"default","Plugins":[],"Warnings":null}} +{"ID":"EKHL:QDUU:QZ7U:MKGD:VDXK:S27Q:GIPU:24B7:R7VT:DGN6:QCSF:2UBX","Containers":0,"ContainersRunning":0,"ContainersPaused":0,"ContainersStopped":0,"Images":0,"Driver":"aufs","DriverStatus":[["Root Dir","/var/lib/docker/aufs"],["Backing Filesystem","extfs"],["Dirs","0"],["Dirperm1 Supported","true"]],"Plugins":{"Volume":["local"],"Network":["bridge","host","macvlan","null","overlay"],"Authorization":null,"Log":["awslogs","fluentd","gcplogs","gelf","journald","json-file","logentries","splunk","syslog"]},"MemoryLimit":true,"SwapLimit":true,"KernelMemory":true,"KernelMemoryTCP":false,"CpuCfsPeriod":true,"CpuCfsQuota":true,"CPUShares":true,"CPUSet":true,"PidsLimit":false,"IPv4Forwarding":true,"BridgeNfIptables":true,"BridgeNfIp6tables":true,"Debug":true,"NFd":33,"OomKillDisable":true,"NGoroutines":135,"SystemTime":"2017-08-24T17:44:34.077811894Z","LoggingDriver":"json-file","CgroupDriver":"cgroupfs","NEventsListener":0,"KernelVersion":"4.4.0-87-generic","OperatingSystem":"Ubuntu 16.04.3 LTS","OSVersion":"","OSType":"linux","Architecture":"x86_64","IndexServerAddress":"https://index.docker.io/v1/","RegistryConfig":{"AllowNondistributableArtifactsCIDRs":null,"AllowNondistributableArtifactsHostnames":null,"InsecureRegistryCIDRs":["127.0.0.0/8"],"IndexConfigs":{"docker.io":{"Name":"docker.io","Mirrors":null,"Secure":true,"Official":true}},"Mirrors":null},"NCPU":2,"MemTotal":2097356800,"GenericResources":null,"DockerRootDir":"/var/lib/docker","HttpProxy":"","HttpsProxy":"","NoProxy":"","Name":"system-sample","Labels":["provider=digitalocean"],"ExperimentalBuild":false,"ServerVersion":"17.06.1-ce","Runtimes":{"runc":{"path":"docker-runc"}},"DefaultRuntime":"runc","Swarm":{"NodeID":"","NodeAddr":"","LocalNodeState":"inactive","ControlAvailable":false,"Error":"","RemoteManagers":null},"LiveRestoreEnabled":false,"Isolation":"","InitBinary":"docker-init","ContainerdCommit":{"ID":"6e23458c129b551d5c9871e5174f6b1b7f6d1170","Expected":"6e23458c129b551d5c9871e5174f6b1b7f6d1170"},"RuncCommit":{"ID":"810190ceaa507aa2727d7ae6f4790c76ec150bd2","Expected":"810190ceaa507aa2727d7ae6f4790c76ec150bd2"},"InitCommit":{"ID":"949e6fa","Expected":"949e6fa"},"SecurityOptions":["name=apparmor","name=seccomp,profile=default"],"DefaultAddressPools":[{"Base":"10.123.0.0/16","Size":24}],"Warnings":["WARNING: No memory limit support","WARNING: No swap limit support","WARNING: No oom kill disable support","WARNING: No cpu cfs quota support","WARNING: No cpu cfs period support","WARNING: No cpu shares support","WARNING: No cpuset support","WARNING: IPv4 forwarding is disabled","WARNING: bridge-nf-call-iptables is disabled","WARNING: bridge-nf-call-ip6tables is disabled"],"ClientInfo":{"Debug":true,"Context":"default","Plugins":[],"Warnings":null}} diff --git a/cli/command/system/testdata/docker-info-warnings.golden b/cli/command/system/testdata/docker-info-warnings.golden index a7a4d792b0b6..579a8d422a9f 100644 --- a/cli/command/system/testdata/docker-info-warnings.golden +++ b/cli/command/system/testdata/docker-info-warnings.golden @@ -1,6 +1,5 @@ WARNING: No memory limit support WARNING: No swap limit support -WARNING: No kernel memory limit support WARNING: No oom kill disable support WARNING: No cpu cfs quota support WARNING: No cpu cfs period support diff --git a/cli/command/system/version.go b/cli/command/system/version.go index c086822c88ab..418ce651c0ca 100644 --- a/cli/command/system/version.go +++ b/cli/command/system/version.go @@ -114,6 +114,7 @@ func NewVersionCommand(dockerCli command.Cli) *cobra.Command { flags.StringVarP(&opts.format, "format", "f", "", "Format the output using the given Go template") flags.StringVar(&opts.kubeConfig, "kubeconfig", "", "Kubernetes config file") flags.SetAnnotation("kubeconfig", "kubernetes", nil) + flags.SetAnnotation("kubeconfig", "deprecated", nil) return cmd } diff --git a/cli/config/config.go b/cli/config/config.go index 703fa30f48f4..31ad117d4159 100644 --- a/cli/config/config.go +++ b/cli/config/config.go @@ -24,17 +24,38 @@ const ( ) var ( - initConfigDir sync.Once + initConfigDir = new(sync.Once) configDir string + homeDir string ) +// resetHomeDir is used in testing to reset the "homeDir" package variable to +// force re-lookup of the home directory between tests. +func resetHomeDir() { + homeDir = "" +} + +func getHomeDir() string { + if homeDir == "" { + homeDir = homedir.Get() + } + return homeDir +} + +// resetConfigDir is used in testing to reset the "configDir" package variable +// and its sync.Once to force re-lookup between tests. +func resetConfigDir() { + configDir = "" + initConfigDir = new(sync.Once) +} + func setConfigDir() { if configDir != "" { return } configDir = os.Getenv("DOCKER_CONFIG") if configDir == "" { - configDir = filepath.Join(homedir.Get(), configFileDir) + configDir = filepath.Join(getHomeDir(), configFileDir) } } @@ -87,6 +108,15 @@ func LoadFromReader(configData io.Reader) (*configfile.ConfigFile, error) { // the auth config information and returns values. // FIXME: use the internal golang config parser func Load(configDir string) (*configfile.ConfigFile, error) { + cfg, _, err := load(configDir) + return cfg, err +} + +// TODO remove this temporary hack, which is used to warn about the deprecated ~/.dockercfg file +// so we can remove the bool return value and collapse this back into `Load` +func load(configDir string) (*configfile.ConfigFile, bool, error) { + printLegacyFileWarning := false + if configDir == "" { configDir = Dir() } @@ -101,35 +131,35 @@ func Load(configDir string) (*configfile.ConfigFile, error) { if err != nil { err = errors.Wrap(err, filename) } - return configFile, err + return configFile, printLegacyFileWarning, err } else if !os.IsNotExist(err) { // if file is there but we can't stat it for any reason other // than it doesn't exist then stop - return configFile, errors.Wrap(err, filename) + return configFile, printLegacyFileWarning, errors.Wrap(err, filename) } // Can't find latest config file so check for the old one - home, err := os.UserHomeDir() - if err != nil { - return configFile, errors.Wrap(err, oldConfigfile) - } - filename = filepath.Join(home, oldConfigfile) + filename = filepath.Join(getHomeDir(), oldConfigfile) if file, err := os.Open(filename); err == nil { + printLegacyFileWarning = true defer file.Close() if err := configFile.LegacyLoadFromReader(file); err != nil { - return configFile, errors.Wrap(err, filename) + return configFile, printLegacyFileWarning, errors.Wrap(err, filename) } } - return configFile, nil + return configFile, printLegacyFileWarning, nil } // LoadDefaultConfigFile attempts to load the default config file and returns // an initialized ConfigFile struct if none is found. func LoadDefaultConfigFile(stderr io.Writer) *configfile.ConfigFile { - configFile, err := Load(Dir()) + configFile, printLegacyFileWarning, err := load(Dir()) if err != nil { fmt.Fprintf(stderr, "WARNING: Error loading config file: %v\n", err) } + if printLegacyFileWarning { + _, _ = fmt.Fprintln(stderr, "WARNING: Support for the legacy ~/.dockercfg configuration file and file-format is deprecated and will be removed in an upcoming release") + } if !configFile.ContainsAuth() { configFile.CredentialsStore = credentials.DetectDefaultStore(configFile.CredentialsStore) } diff --git a/cli/config/config_test.go b/cli/config/config_test.go index a861d4da1ec8..26197454e6ee 100644 --- a/cli/config/config_test.go +++ b/cli/config/config_test.go @@ -12,9 +12,11 @@ import ( "github.com/docker/cli/cli/config/configfile" "github.com/docker/cli/cli/config/credentials" + "github.com/docker/cli/cli/config/types" "gotest.tools/v3/assert" is "gotest.tools/v3/assert/cmp" "gotest.tools/v3/env" + "gotest.tools/v3/fs" ) var homeKey = "HOME" @@ -115,6 +117,7 @@ password`: "Invalid Auth config file", email`: "Invalid auth configuration file", } + resetHomeDir() tmpHome, err := ioutil.TempDir("", "config-test") assert.NilError(t, err) defer os.RemoveAll(tmpHome) @@ -131,6 +134,7 @@ email`: "Invalid auth configuration file", } func TestOldValidAuth(t *testing.T) { + resetHomeDir() tmpHome, err := ioutil.TempDir("", "config-test") assert.NilError(t, err) defer os.RemoveAll(tmpHome) @@ -165,6 +169,7 @@ func TestOldValidAuth(t *testing.T) { } func TestOldJSONInvalid(t *testing.T) { + resetHomeDir() tmpHome, err := ioutil.TempDir("", "config-test") assert.NilError(t, err) defer os.RemoveAll(tmpHome) @@ -184,6 +189,7 @@ func TestOldJSONInvalid(t *testing.T) { } func TestOldJSON(t *testing.T) { + resetHomeDir() tmpHome, err := ioutil.TempDir("", "config-test") assert.NilError(t, err) defer os.RemoveAll(tmpHome) @@ -219,6 +225,31 @@ func TestOldJSON(t *testing.T) { } } +func TestOldJSONFallbackDeprecationWarning(t *testing.T) { + js := `{"https://index.docker.io/v1/":{"auth":"am9lam9lOmhlbGxv","email":"user@example.com"}}` + tmpHome := fs.NewDir(t, t.Name(), fs.WithFile(oldConfigfile, js)) + defer tmpHome.Remove() + defer env.PatchAll(t, map[string]string{homeKey: tmpHome.Path(), "DOCKER_CONFIG": ""})() + + // reset the homeDir, configDir, and its sync.Once, to force them being resolved again + resetHomeDir() + resetConfigDir() + + buffer := new(bytes.Buffer) + configFile := LoadDefaultConfigFile(buffer) + expected := configfile.New(tmpHome.Join(configFileDir, ConfigFileName)) + expected.AuthConfigs = map[string]types.AuthConfig{ + "https://index.docker.io/v1/": { + Username: "joejoe", + Password: "hello", + Email: "user@example.com", + ServerAddress: "https://index.docker.io/v1/", + }, + } + assert.Assert(t, strings.Contains(buffer.String(), "WARNING: Support for the legacy ~/.dockercfg configuration file and file-format is deprecated and will be removed in an upcoming release")) + assert.Check(t, is.DeepEqual(expected, configFile)) +} + func TestNewJSON(t *testing.T) { tmpHome, err := ioutil.TempDir("", "config-test") assert.NilError(t, err) diff --git a/cli/config/configfile/file_test.go b/cli/config/configfile/file_test.go index 0ed7b73fdd04..fbab2930f776 100644 --- a/cli/config/configfile/file_test.go +++ b/cli/config/configfile/file_test.go @@ -27,16 +27,19 @@ func TestEncodeAuth(t *testing.T) { } func TestProxyConfig(t *testing.T) { - httpProxy := "http://proxy.mycorp.com:3128" - httpsProxy := "https://user:password@proxy.mycorp.com:3129" - ftpProxy := "http://ftpproxy.mycorp.com:21" - noProxy := "*.intra.mycorp.com" - defaultProxyConfig := ProxyConfig{ - HTTPProxy: httpProxy, - HTTPSProxy: httpsProxy, - FTPProxy: ftpProxy, - NoProxy: noProxy, - } + var ( + httpProxy = "http://proxy.mycorp.example.com:3128" + httpsProxy = "https://user:password@proxy.mycorp.example.com:3129" + ftpProxy = "http://ftpproxy.mycorp.example.com:21" + noProxy = "*.intra.mycorp.example.com" + + defaultProxyConfig = ProxyConfig{ + HTTPProxy: httpProxy, + HTTPSProxy: httpsProxy, + FTPProxy: ftpProxy, + NoProxy: noProxy, + } + ) cfg := ConfigFile{ Proxies: map[string]ProxyConfig{ @@ -59,18 +62,21 @@ func TestProxyConfig(t *testing.T) { } func TestProxyConfigOverride(t *testing.T) { - httpProxy := "http://proxy.mycorp.com:3128" - overrideHTTPProxy := "http://proxy.example.com:3128" - overrideNoProxy := "" - httpsProxy := "https://user:password@proxy.mycorp.com:3129" - ftpProxy := "http://ftpproxy.mycorp.com:21" - noProxy := "*.intra.mycorp.com" - defaultProxyConfig := ProxyConfig{ - HTTPProxy: httpProxy, - HTTPSProxy: httpsProxy, - FTPProxy: ftpProxy, - NoProxy: noProxy, - } + var ( + httpProxy = "http://proxy.mycorp.example.com:3128" + httpProxyOverride = "http://proxy.example.com:3128" + httpsProxy = "https://user:password@proxy.mycorp.example.com:3129" + ftpProxy = "http://ftpproxy.mycorp.example.com:21" + noProxy = "*.intra.mycorp.example.com" + noProxyOverride = "" + + defaultProxyConfig = ProxyConfig{ + HTTPProxy: httpProxy, + HTTPSProxy: httpsProxy, + FTPProxy: ftpProxy, + NoProxy: noProxy, + } + ) cfg := ConfigFile{ Proxies: map[string]ProxyConfig{ @@ -84,46 +90,49 @@ func TestProxyConfigOverride(t *testing.T) { } ropts := map[string]*string{ - "HTTP_PROXY": clone(overrideHTTPProxy), - "NO_PROXY": clone(overrideNoProxy), + "HTTP_PROXY": clone(httpProxyOverride), + "NO_PROXY": clone(noProxyOverride), } proxyConfig := cfg.ParseProxyConfig("/var/run/docker.sock", ropts) expected := map[string]*string{ - "HTTP_PROXY": &overrideHTTPProxy, + "HTTP_PROXY": &httpProxyOverride, "http_proxy": &httpProxy, "HTTPS_PROXY": &httpsProxy, "https_proxy": &httpsProxy, "FTP_PROXY": &ftpProxy, "ftp_proxy": &ftpProxy, - "NO_PROXY": &overrideNoProxy, + "NO_PROXY": &noProxyOverride, "no_proxy": &noProxy, } assert.Check(t, is.DeepEqual(expected, proxyConfig)) } func TestProxyConfigPerHost(t *testing.T) { - httpProxy := "http://proxy.mycorp.com:3128" - httpsProxy := "https://user:password@proxy.mycorp.com:3129" - ftpProxy := "http://ftpproxy.mycorp.com:21" - noProxy := "*.intra.mycorp.com" - - extHTTPProxy := "http://proxy.example.com:3128" - extHTTPSProxy := "https://user:password@proxy.example.com:3129" - extFTPProxy := "http://ftpproxy.example.com:21" - extNoProxy := "*.intra.example.com" - - defaultProxyConfig := ProxyConfig{ - HTTPProxy: httpProxy, - HTTPSProxy: httpsProxy, - FTPProxy: ftpProxy, - NoProxy: noProxy, - } - externalProxyConfig := ProxyConfig{ - HTTPProxy: extHTTPProxy, - HTTPSProxy: extHTTPSProxy, - FTPProxy: extFTPProxy, - NoProxy: extNoProxy, - } + var ( + httpProxy = "http://proxy.mycorp.example.com:3128" + httpsProxy = "https://user:password@proxy.mycorp.example.com:3129" + ftpProxy = "http://ftpproxy.mycorp.example.com:21" + noProxy = "*.intra.mycorp.example.com" + + extHTTPProxy = "http://proxy.example.com:3128" + extHTTPSProxy = "https://user:password@proxy.example.com:3129" + extFTPProxy = "http://ftpproxy.example.com:21" + extNoProxy = "*.intra.example.com" + + defaultProxyConfig = ProxyConfig{ + HTTPProxy: httpProxy, + HTTPSProxy: httpsProxy, + FTPProxy: ftpProxy, + NoProxy: noProxy, + } + + externalProxyConfig = ProxyConfig{ + HTTPProxy: extHTTPProxy, + HTTPSProxy: extHTTPSProxy, + FTPProxy: extFTPProxy, + NoProxy: extNoProxy, + } + ) cfg := ConfigFile{ Proxies: map[string]ProxyConfig{ @@ -226,9 +235,11 @@ func TestGetAllCredentialsCredsStore(t *testing.T) { } func TestGetAllCredentialsCredHelper(t *testing.T) { - testCredHelperSuffix := "test_cred_helper" - testCredHelperRegistryHostname := "credhelper.com" - testExtraCredHelperRegistryHostname := "somethingweird.com" + const ( + testCredHelperSuffix = "test_cred_helper" + testCredHelperRegistryHostname = "credhelper.com" + testExtraCredHelperRegistryHostname = "somethingweird.com" + ) unexpectedCredHelperAuth := types.AuthConfig{ Username: "file_store_user", @@ -265,9 +276,11 @@ func TestGetAllCredentialsCredHelper(t *testing.T) { } func TestGetAllCredentialsFileStoreAndCredHelper(t *testing.T) { - testFileStoreRegistryHostname := "example.com" - testCredHelperSuffix := "test_cred_helper" - testCredHelperRegistryHostname := "credhelper.com" + const ( + testFileStoreRegistryHostname = "example.com" + testCredHelperSuffix = "test_cred_helper" + testCredHelperRegistryHostname = "credhelper.com" + ) expectedFileStoreAuth := types.AuthConfig{ Username: "file_store_user", @@ -301,10 +314,12 @@ func TestGetAllCredentialsFileStoreAndCredHelper(t *testing.T) { } func TestGetAllCredentialsCredStoreAndCredHelper(t *testing.T) { - testCredStoreSuffix := "test_creds_store" - testCredStoreRegistryHostname := "credstore.com" - testCredHelperSuffix := "test_cred_helper" - testCredHelperRegistryHostname := "credhelper.com" + const ( + testCredStoreSuffix = "test_creds_store" + testCredStoreRegistryHostname = "credstore.com" + testCredHelperSuffix = "test_cred_helper" + testCredHelperRegistryHostname = "credhelper.com" + ) configFile := New("filename") configFile.CredentialsStore = testCredStoreSuffix @@ -343,9 +358,11 @@ func TestGetAllCredentialsCredStoreAndCredHelper(t *testing.T) { } func TestGetAllCredentialsCredHelperOverridesDefaultStore(t *testing.T) { - testCredStoreSuffix := "test_creds_store" - testCredHelperSuffix := "test_cred_helper" - testRegistryHostname := "example.com" + const ( + testCredStoreSuffix = "test_creds_store" + testCredHelperSuffix = "test_cred_helper" + testRegistryHostname = "example.com" + ) configFile := New("filename") configFile.CredentialsStore = testCredStoreSuffix @@ -424,38 +441,36 @@ func TestCheckKubernetesConfigurationRaiseAnErrorOnInvalidValue(t *testing.T) { expectError bool }{ { - "no kubernetes config is valid", - nil, - false, + name: "no kubernetes config is valid", }, { - "enabled is valid", - &KubernetesConfig{AllNamespaces: "enabled"}, - false, + name: "enabled is valid", + config: &KubernetesConfig{AllNamespaces: "enabled"}, }, { - "disabled is valid", - &KubernetesConfig{AllNamespaces: "disabled"}, - false, + name: "disabled is valid", + config: &KubernetesConfig{AllNamespaces: "disabled"}, }, { - "empty string is valid", - &KubernetesConfig{AllNamespaces: ""}, - false, + name: "empty string is valid", + config: &KubernetesConfig{AllNamespaces: ""}, }, { - "other value is invalid", - &KubernetesConfig{AllNamespaces: "unknown"}, - true, + name: "other value is invalid", + config: &KubernetesConfig{AllNamespaces: "unknown"}, + expectError: true, }, } - for _, test := range testCases { - err := checkKubernetesConfiguration(test.config) - if test.expectError { - assert.Assert(t, err != nil, test.name) - } else { - assert.NilError(t, err, test.name) - } + for _, tc := range testCases { + test := tc + t.Run(test.name, func(t *testing.T) { + err := checkKubernetesConfiguration(test.config) + if test.expectError { + assert.Assert(t, err != nil, test.name) + } else { + assert.NilError(t, err, test.name) + } + }) } } diff --git a/cli/config/credentials/default_store.go b/cli/config/credentials/default_store.go index 7a760f1a979c..402235bff025 100644 --- a/cli/config/credentials/default_store.go +++ b/cli/config/credentials/default_store.go @@ -1,7 +1,7 @@ package credentials import ( - "os/exec" + exec "golang.org/x/sys/execabs" ) // DetectDefaultStore return the default credentials store for the platform if diff --git a/cli/config/credentials/file_store_test.go b/cli/config/credentials/file_store_test.go index 3a95f2be207b..f04fe22e1ca0 100644 --- a/cli/config/credentials/file_store_test.go +++ b/cli/config/credentials/file_store_test.go @@ -70,7 +70,7 @@ func TestFileStoreGet(t *testing.T) { func TestFileStoreGetAll(t *testing.T) { s1 := "https://example.com" - s2 := "https://example2.com" + s2 := "https://example2.example.com" f := newStore(map[string]types.AuthConfig{ s1: { Auth: "super_secret_token", @@ -80,7 +80,7 @@ func TestFileStoreGetAll(t *testing.T) { s2: { Auth: "super_secret_token2", Email: "foo@example2.com", - ServerAddress: "https://example2.com", + ServerAddress: "https://example2.example.com", }, }) diff --git a/cli/connhelper/commandconn/commandconn.go b/cli/connhelper/commandconn/commandconn.go index 4c5783fb3bc2..128da447b5f6 100644 --- a/cli/connhelper/commandconn/commandconn.go +++ b/cli/connhelper/commandconn/commandconn.go @@ -20,7 +20,6 @@ import ( "io" "net" "os" - "os/exec" "runtime" "strings" "sync" @@ -29,6 +28,7 @@ import ( "github.com/pkg/errors" "github.com/sirupsen/logrus" + exec "golang.org/x/sys/execabs" ) // New returns net.Conn diff --git a/cli/connhelper/connhelper.go b/cli/connhelper/connhelper.go index e349b3eaefc3..9ac9d6744d45 100644 --- a/cli/connhelper/connhelper.go +++ b/cli/connhelper/connhelper.go @@ -49,7 +49,7 @@ func getConnectionHelper(daemonURL string, sshFlags []string) (*ConnectionHelper Dialer: func(ctx context.Context, network, addr string) (net.Conn, error) { return commandconn.New(ctx, "ssh", append(sshFlags, sp.Args("docker", "system", "dial-stdio")...)...) }, - Host: "http://docker", + Host: "http://docker.example.com", }, nil } // Future version may support plugins via ~/.docker/config.json. e.g. "dind" @@ -63,6 +63,6 @@ func GetCommandConnectionHelper(cmd string, flags ...string) (*ConnectionHelper, Dialer: func(ctx context.Context, network, addr string) (net.Conn, error) { return commandconn.New(ctx, cmd, flags...) }, - Host: "http://docker", + Host: "http://docker.example.com", }, nil } diff --git a/cli/context/docker/load.go b/cli/context/docker/load.go index c85d4b6d36ab..ccfee02d1c17 100644 --- a/cli/context/docker/load.go +++ b/cli/context/docker/load.go @@ -26,7 +26,12 @@ type EndpointMeta = context.EndpointMetaBase // a Docker Engine endpoint, with its tls data type Endpoint struct { EndpointMeta - TLSData *context.TLSData + TLSData *context.TLSData + + // Deprecated: Use of encrypted TLS private keys has been deprecated, and + // will be removed in a future release. Golang has deprecated support for + // legacy PEM encryption (as specified in RFC 1423), as it is insecure by + // design (see https://go-review.googlesource.com/c/go/+/264159). TLSPassword string } @@ -66,8 +71,9 @@ func (c *Endpoint) tlsConfig() (*tls.Config, error) { } var err error - if x509.IsEncryptedPEMBlock(pemBlock) { - keyBytes, err = x509.DecryptPEMBlock(pemBlock, []byte(c.TLSPassword)) + // TODO should we follow Golang, and deprecate RFC 1423 encryption, and produce a warning (or just error)? see https://github.com/docker/cli/issues/3212 + if x509.IsEncryptedPEMBlock(pemBlock) { //nolint: staticcheck // SA1019: x509.IsEncryptedPEMBlock is deprecated, and insecure by design + keyBytes, err = x509.DecryptPEMBlock(pemBlock, []byte(c.TLSPassword)) //nolint: staticcheck // SA1019: x509.IsEncryptedPEMBlock is deprecated, and insecure by design if err != nil { return nil, errors.Wrap(err, "private key is encrypted, but could not decrypt it") } diff --git a/cli/context/store/store.go b/cli/context/store/store.go index b3cd4c54edf3..71220e9ac0f6 100644 --- a/cli/context/store/store.go +++ b/cli/context/store/store.go @@ -7,19 +7,24 @@ import ( "bytes" _ "crypto/sha256" // ensure ids can be computed "encoding/json" - "errors" "fmt" "io" "io/ioutil" "net/http" "path" "path/filepath" + "regexp" "strings" "github.com/docker/docker/errdefs" digest "github.com/opencontainers/go-digest" + "github.com/pkg/errors" ) +const restrictedNamePattern = "^[a-zA-Z0-9][a-zA-Z0-9_.+-]+$" + +var restrictedNameRegEx = regexp.MustCompile(restrictedNamePattern) + // Store provides a context store for easily remembering endpoints configuration type Store interface { Reader @@ -184,6 +189,20 @@ func (s *store) GetStorageInfo(contextName string) StorageInfo { } } +// ValidateContextName checks a context name is valid. +func ValidateContextName(name string) error { + if name == "" { + return errors.New("context name cannot be empty") + } + if name == "default" { + return errors.New(`"default" is a reserved context name`) + } + if !restrictedNameRegEx.MatchString(name) { + return fmt.Errorf("context name %q is invalid, names are validated against regexp %q", name, restrictedNamePattern) + } + return nil +} + // Export exports an existing namespace into an opaque data stream // This stream is actually a tarball containing context metadata and TLS materials, but it does // not map 1:1 the layout of the context store (don't try to restore it manually without calling store.Import) @@ -295,6 +314,19 @@ func Import(name string, s Writer, reader io.Reader) error { } } +func isValidFilePath(p string) error { + if p != metaFile && !strings.HasPrefix(p, "tls/") { + return errors.New("unexpected context file") + } + if path.Clean(p) != p { + return errors.New("unexpected path format") + } + if strings.Contains(p, `\`) { + return errors.New(`unexpected '\' in path`) + } + return nil +} + func importTar(name string, s Writer, reader io.Reader) error { tr := tar.NewReader(&LimitedReader{R: reader, N: maxAllowedFileSizeToImport}) tlsData := ContextTLSData{ @@ -309,10 +341,13 @@ func importTar(name string, s Writer, reader io.Reader) error { if err != nil { return err } - if hdr.Typeflag == tar.TypeDir { + if hdr.Typeflag != tar.TypeReg { // skip this entry, only taking files into account continue } + if err := isValidFilePath(hdr.Name); err != nil { + return errors.Wrap(err, hdr.Name) + } if hdr.Name == metaFile { data, err := ioutil.ReadAll(tr) if err != nil { @@ -358,10 +393,13 @@ func importZip(name string, s Writer, reader io.Reader) error { var importedMetaFile bool for _, zf := range zr.File { fi := zf.FileInfo() - if fi.IsDir() { - // skip this entry, only taking files into account + if !fi.Mode().IsRegular() { + // skip this entry, only taking regular files into account continue } + if err := isValidFilePath(zf.Name); err != nil { + return errors.Wrap(err, zf.Name) + } if zf.Name == metaFile { f, err := zf.Open() if err != nil { @@ -408,6 +446,9 @@ func parseMetadata(data []byte, name string) (Metadata, error) { if err := json.Unmarshal(data, &meta); err != nil { return meta, err } + if err := ValidateContextName(name); err != nil { + return Metadata{}, err + } meta.Name = name return meta, nil } diff --git a/cli/context/store/store_test.go b/cli/context/store/store_test.go index df506061e52a..4b412652de01 100644 --- a/cli/context/store/store_test.go +++ b/cli/context/store/store_test.go @@ -175,7 +175,7 @@ func TestImportTarInvalid(t *testing.T) { var r io.Reader = source s := New(testDir, testCfg) err = Import("tarInvalid", s, r) - assert.ErrorContains(t, err, "invalid context: no metadata found") + assert.ErrorContains(t, err, "unexpected context file") } func TestImportZip(t *testing.T) { @@ -254,5 +254,5 @@ func TestImportZipInvalid(t *testing.T) { var r io.Reader = source s := New(testDir, testCfg) err = Import("zipInvalid", s, r) - assert.ErrorContains(t, err, "invalid context: no metadata found") + assert.ErrorContains(t, err, "unexpected context file") } diff --git a/cli/context/store/storeconfig_test.go b/cli/context/store/storeconfig_test.go index 7f59e3f015b6..4d9a3b63fb49 100644 --- a/cli/context/store/storeconfig_test.go +++ b/cli/context/store/storeconfig_test.go @@ -29,3 +29,32 @@ func TestConfigModification(t *testing.T) { assert.Equal(t, &testEP2{}, cfgCopy.endpointTypes["ep1"]()) assert.Equal(t, &testEP3{}, cfgCopy.endpointTypes["ep2"]()) } + +func TestValidFilePaths(t *testing.T) { + paths := map[string]bool{ + "tls/_/../../something": false, + "tls/../../something": false, + "../../something": false, + "/tls/absolute/unix/path": false, + `C:\tls\absolute\windows\path`: false, + "C:/tls/absolute/windows/path": false, + "tls/kubernetes/key.pem": true, + } + for p, expectedValid := range paths { + err := isValidFilePath(p) + assert.Equal(t, err == nil, expectedValid, "%q should report valid as: %v", p, expectedValid) + } +} + +func TestValidateContextName(t *testing.T) { + names := map[string]bool{ + "../../invalid/escape": false, + "/invalid/absolute": false, + `\invalid\windows`: false, + "validname": true, + } + for n, expectedValid := range names { + err := ValidateContextName(n) + assert.Equal(t, err == nil, expectedValid, "%q should report valid as: %v", n, expectedValid) + } +} diff --git a/cli/winresources/res_windows.go b/cli/winresources/res_windows.go index 3f755cc4bdbf..033995d0bcec 100644 --- a/cli/winresources/res_windows.go +++ b/cli/winresources/res_windows.go @@ -5,7 +5,7 @@ These resources are used to provide * An icon * A Windows manifest declaring Windows version support -The resource object files are generated with go generate. +The resource object files are generated when building with scripts/build/binary . The resource source files are located in scripts/winresources. This occurs automatically when you run scripts/build/windows. @@ -14,5 +14,3 @@ is included. */ package winresources - -//go:generate ../../scripts/gen/windows-resources diff --git a/cmd/docker/docker_test.go b/cmd/docker/docker_test.go index 388eb2af85e5..0acca1b6b138 100644 --- a/cmd/docker/docker_test.go +++ b/cmd/docker/docker_test.go @@ -17,7 +17,9 @@ import ( func TestClientDebugEnabled(t *testing.T) { defer debug.Disable() - tcmd := newDockerCommand(&command.DockerCli{}) + cli, err := command.NewDockerCli() + assert.NilError(t, err) + tcmd := newDockerCommand(cli) tcmd.SetFlag("debug", "true") cmd, _, err := tcmd.HandleGlobalFlags() assert.NilError(t, err) diff --git a/contrib/completion/bash/docker b/contrib/completion/bash/docker index 6baf68211822..347165e0101f 100644 --- a/contrib/completion/bash/docker +++ b/contrib/completion/bash/docker @@ -935,7 +935,7 @@ __docker_complete_log_options() { # awslogs does not implement the $common_options2. local awslogs_options="$common_options1 awslogs-create-group awslogs-credentials-endpoint awslogs-datetime-format awslogs-group awslogs-multiline-pattern awslogs-region awslogs-stream tag" - local fluentd_options="$common_options1 $common_options2 fluentd-address fluentd-async-connect fluentd-buffer-limit fluentd-retry-wait fluentd-max-retries fluentd-sub-second-precision tag" + local fluentd_options="$common_options1 $common_options2 fluentd-address fluentd-async fluentd-buffer-limit fluentd-request-ack fluentd-retry-wait fluentd-max-retries fluentd-sub-second-precision tag" local gcplogs_options="$common_options1 $common_options2 gcp-log-cmd gcp-meta-id gcp-meta-name gcp-meta-zone gcp-project" local gelf_options="$common_options1 $common_options2 gelf-address gelf-compression-level gelf-compression-type gelf-tcp-max-reconnect gelf-tcp-reconnect-delay tag" local journald_options="$common_options1 $common_options2 tag" @@ -1955,6 +1955,7 @@ _docker_container_run_and_create() { --pid --pids-limit --publish -p + --pull --restart --runtime --security-opt @@ -2153,6 +2154,10 @@ _docker_container_run_and_create() { esac return ;; + --pull) + COMPREPLY=( $( compgen -W 'always missing never' -- "$cur" ) ) + return + ;; --runtime) __docker_complete_runtimes return @@ -2548,6 +2553,7 @@ _docker_daemon() { --ip-forward=false --ip-masq=false --iptables=false + --ip6tables --ipv6 --live-restore --no-new-privileges @@ -3601,7 +3607,7 @@ _docker_service_ls() { return ;; mode) - COMPREPLY=( $( compgen -W "global replicated" -- "${cur##*=}" ) ) + COMPREPLY=( $( compgen -W "global global-job replicated replicated-job" -- "${cur##*=}" ) ) return ;; name) @@ -3731,6 +3737,7 @@ _docker_service_update_and_create() { --limit-pids --log-driver --log-opt + --max-replicas --replicas --replicas-max-per-node --reserve-cpu @@ -3804,7 +3811,7 @@ _docker_service_update_and_create() { return ;; --mode) - COMPREPLY=( $( compgen -W "global replicated" -- "$cur" ) ) + COMPREPLY=( $( compgen -W "global global-job replicated replicated-job" -- "$cur" ) ) return ;; esac @@ -4348,6 +4355,9 @@ _docker_node_ls() { __docker_complete_nodes --cur "${cur##*=}" --id return ;; + label|node.label) + return + ;; membership) COMPREPLY=( $( compgen -W "accepted pending" -- "${cur##*=}" ) ) return @@ -4364,7 +4374,7 @@ _docker_node_ls() { case "$prev" in --filter|-f) - COMPREPLY=( $( compgen -W "id label membership name role" -S = -- "$cur" ) ) + COMPREPLY=( $( compgen -W "id label membership name node.label role" -S = -- "$cur" ) ) __docker_nospace return ;; diff --git a/contrib/completion/zsh/_docker b/contrib/completion/zsh/_docker index 7fe2043132b6..5a4ad4b6c25e 100644 --- a/contrib/completion/zsh/_docker +++ b/contrib/completion/zsh/_docker @@ -1343,7 +1343,7 @@ __docker_node_complete_ls_filters() { ;; esac else - opts=('id' 'label' 'membership' 'name' 'role') + opts=('id' 'label' 'membership' 'name' 'node.label' 'role') _describe -t filter-opts "filter options" opts -qS "=" && ret=0 fi @@ -2544,6 +2544,82 @@ __docker_volume_subcommand() { # EO volume +# BO context + +__docker_complete_contexts() { + [[ $PREFIX = -* ]] && return 1 + integer ret=1 + declare -a contexts + + contexts=(${(f)${:-"$(_call_program commands docker $docker_options context ls -q)"$'\n'}}) + + _describe -t context-list "context" contexts && ret=0 + return ret +} + +__docker_context_commands() { + local -a _docker_context_subcommands + _docker_context_subcommands=( + "create:Create new context" + "inspect:Display detailed information on one or more contexts" + "list:List available contexts" + "rm:Remove one or more contexts" + "show:Print the current context" + "update:Update a context" + "use:Set the default context" + ) + _describe -t docker-context-commands "docker context command" _docker_context_subcommands +} + +__docker_context_subcommand() { + local -a _command_args opts_help + local expl help="--help" + integer ret=1 + + opts_help=("(: -)--help[Print usage]") + + case "$words[1]" in + (create) + _arguments $(__docker_arguments) \ + $opts_help \ + "($help)--default-stack-orchestrator=[Default orchestrator for stack operations to use with this context]:default-stack-orchestrator:(swarm kubernetes all)" \ + "($help)--description=[Description of the context]:description:" \ + "($help)--docker=[Set the docker endpoint]:docker:" \ + "($help)--kubernetes=[Set the kubernetes endpoint]:kubernetes:" \ + "($help)--from=[Create context from a named context]:from:__docker_complete_contexts" \ + "($help -):name: " && ret=0 + ;; + (use) + _arguments $(__docker_arguments) \ + $opts_help \ + "($help -)1:context:__docker_complete_contexts" && ret=0 + ;; + (inspect) + _arguments $(__docker_arguments) \ + $opts_help \ + "($help -)1:context:__docker_complete_contexts" && ret=0 + ;; + (rm) + _arguments $(__docker_arguments) \ + $opts_help \ + "($help -)1:context:__docker_complete_contexts" && ret=0 + ;; + (update) + _arguments $(__docker_arguments) \ + $opts_help \ + "($help)--default-stack-orchestrator=[Default orchestrator for stack operations to use with this context]:default-stack-orchestrator:(swarm kubernetes all)" \ + "($help)--description=[Description of the context]:description:" \ + "($help)--docker=[Set the docker endpoint]:docker:" \ + "($help)--kubernetes=[Set the kubernetes endpoint]:kubernetes:" \ + "($help -):name:" && ret=0 + ;; + esac + + return ret +} + +# EO context + __docker_caching_policy() { oldp=( "$1"(Nmh+1) ) # 1 hour (( $#oldp )) @@ -2631,6 +2707,23 @@ __docker_subcommand() { ;; esac ;; + (context) + local curcontext="$curcontext" state + _arguments $(__docker_arguments) \ + $opts_help \ + "($help -): :->command" \ + "($help -)*:: :->option-or-argument" && ret=0 + + case $state in + (command) + __docker_context_commands && ret=0 + ;; + (option-or-argument) + curcontext=${curcontext%:*:*}:docker-${words[-1]}: + __docker_context_subcommand && ret=0 + ;; + esac + ;; (daemon) _arguments $(__docker_arguments) \ $opts_help \ diff --git a/docker-bake.hcl b/docker-bake.hcl new file mode 100644 index 000000000000..909dd4fc189e --- /dev/null +++ b/docker-bake.hcl @@ -0,0 +1,63 @@ +variable "VERSION" { + default = "" +} + +variable "USE_GLIBC" { + default = "" +} + +variable "STRIP_TARGET" { + default = "" +} + +group "default" { + targets = ["binary"] +} + +target "binary" { + target = "binary" + platforms = ["local"] + output = ["build"] + args = { + BASE_VARIANT = USE_GLIBC != "" ? "buster" : "alpine" + VERSION = VERSION + GO_STRIP = STRIP_TARGET + } +} + +target "dynbinary" { + inherits = ["binary"] + args = { + GO_LINKMODE = "dynamic" + } +} + +variable "GROUP_TOTAL" { + default = "1" +} + +variable "GROUP_INDEX" { + default = "0" +} + +function "platforms" { + params = [] + result = ["linux/amd64", "linux/386", "linux/arm64", "linux/arm", "linux/ppc64le", "linux/s390x", "darwin/amd64", "darwin/arm64", "windows/amd64"] +} + +function "glen" { + params = [platforms, GROUP_TOTAL] + result = ceil(length(platforms)/GROUP_TOTAL) +} + +target "_all_platforms" { + platforms = slice(platforms(), GROUP_INDEX*glen(platforms(), GROUP_TOTAL),min(length(platforms()), (GROUP_INDEX+1)*glen(platforms(), GROUP_TOTAL))) +} + +target "cross" { + inherits = ["binary", "_all_platforms"] +} + +target "dynbinary-cross" { + inherits = ["dynbinary", "_all_platforms"] +} diff --git a/docker.Makefile b/docker.Makefile index 804133b2fb5f..4f582b7fb7c3 100644 --- a/docker.Makefile +++ b/docker.Makefile @@ -38,11 +38,6 @@ build_linter_image: # build dockerfile from stdin so that we don't send the build-context; source is bind-mounted in the development environment cat ./dockerfiles/Dockerfile.lint | docker build ${DOCKER_BUILD_ARGS} --build-arg=GO_VERSION -t $(LINTER_IMAGE_NAME) - -.PHONY: build_cross_image -build_cross_image: - # build dockerfile from stdin so that we don't send the build-context; source is bind-mounted in the development environment - cat ./dockerfiles/Dockerfile.cross | docker build ${DOCKER_BUILD_ARGS} --build-arg=GO_VERSION -t $(CROSS_IMAGE_NAME) - - .PHONY: build_shell_validate_image build_shell_validate_image: # build dockerfile from stdin so that we don't send the build-context; source is bind-mounted in the development environment @@ -80,22 +75,10 @@ test-unit: build_docker_image ## run unit tests (using go test) .PHONY: test ## run unit and e2e tests test: test-unit test-e2e -.PHONY: cross -cross: build_cross_image ## build the CLI for macOS and Windows - $(DOCKER_RUN) $(CROSS_IMAGE_NAME) make cross - -.PHONY: binary-windows -binary-windows: build_cross_image ## build the CLI for Windows - $(DOCKER_RUN) $(CROSS_IMAGE_NAME) make $@ - .PHONY: plugins-windows plugins-windows: build_cross_image ## build the example CLI plugins for Windows $(DOCKER_RUN) $(CROSS_IMAGE_NAME) make $@ -.PHONY: binary-osx -binary-osx: build_cross_image ## build the CLI for macOS - $(DOCKER_RUN) $(CROSS_IMAGE_NAME) make $@ - .PHONY: plugins-osx plugins-osx: build_cross_image ## build the example CLI plugins for macOS $(DOCKER_RUN) $(CROSS_IMAGE_NAME) make $@ @@ -120,9 +103,6 @@ fmt: ## run gofmt vendor: build_docker_image vendor.conf ## download dependencies (vendor/) listed in vendor.conf $(DOCKER_RUN) -it $(DEV_DOCKER_IMAGE_NAME) make vendor -dynbinary: build_cross_image ## build the CLI dynamically linked - $(DOCKER_RUN) -it $(CROSS_IMAGE_NAME) make dynbinary - .PHONY: authors authors: ## generate AUTHORS file from git history $(DOCKER_RUN) -it $(DEV_DOCKER_IMAGE_NAME) make authors diff --git a/dockerfiles/Dockerfile.binary-native b/dockerfiles/Dockerfile.binary-native index 37c1c64fe8d3..9d47a9110276 100644 --- a/dockerfiles/Dockerfile.binary-native +++ b/dockerfiles/Dockerfile.binary-native @@ -1,4 +1,4 @@ -ARG GO_VERSION=1.13.15 +ARG GO_VERSION=1.16.10 FROM golang:${GO_VERSION}-alpine diff --git a/dockerfiles/Dockerfile.dev b/dockerfiles/Dockerfile.dev index ddd1b6b72be2..cf8ab33c4864 100644 --- a/dockerfiles/Dockerfile.dev +++ b/dockerfiles/Dockerfile.dev @@ -1,5 +1,6 @@ -# syntax=docker/dockerfile:1.1.7-experimental -ARG GO_VERSION=1.13.15 +# syntax=docker/dockerfile:1.3 + +ARG GO_VERSION=1.16.15 FROM golang:${GO_VERSION}-alpine AS golang ENV CGO_ENABLED=0 @@ -9,21 +10,21 @@ ARG ESC_VERSION=v0.2.0 RUN --mount=type=cache,target=/root/.cache/go-build \ --mount=type=cache,target=/go/pkg/mod \ --mount=type=tmpfs,target=/go/src/ \ - GO111MODULE=on go get github.com/mjibson/esc@${ESC_VERSION} + GO111MODULE=on go install github.com/mjibson/esc@${ESC_VERSION} FROM golang AS gotestsum ARG GOTESTSUM_VERSION=v0.4.0 RUN --mount=type=cache,target=/root/.cache/go-build \ --mount=type=cache,target=/go/pkg/mod \ --mount=type=tmpfs,target=/go/src/ \ - GO111MODULE=on go get gotest.tools/gotestsum@${GOTESTSUM_VERSION} + GO111MODULE=on go install gotest.tools/gotestsum@${GOTESTSUM_VERSION} FROM golang AS vndr ARG VNDR_VERSION=v0.1.2 RUN --mount=type=cache,target=/root/.cache/go-build \ --mount=type=cache,target=/go/pkg/mod \ --mount=type=tmpfs,target=/go/src/ \ - GO111MODULE=on go get github.com/LK4D4/vndr@${VNDR_VERSION} + GO111MODULE=on go install github.com/LK4D4/vndr@${VNDR_VERSION} FROM golang AS dev RUN apk add --no-cache \ @@ -43,4 +44,5 @@ COPY --from=vndr /go/bin/* /go/bin/ COPY --from=gotestsum /go/bin/* /go/bin/ WORKDIR /go/src/github.com/docker/cli +ENV GO111MODULE=auto COPY . . diff --git a/dockerfiles/Dockerfile.e2e b/dockerfiles/Dockerfile.e2e index afd4e47b6012..b9a7b3624b86 100644 --- a/dockerfiles/Dockerfile.e2e +++ b/dockerfiles/Dockerfile.e2e @@ -1,4 +1,4 @@ -ARG GO_VERSION=1.13.15 +ARG GO_VERSION=1.16.10 # Use Debian based image as docker-compose requires glibc. FROM golang:${GO_VERSION}-buster diff --git a/dockerfiles/Dockerfile.lint b/dockerfiles/Dockerfile.lint index 7b180f51e364..e48fd23d788f 100644 --- a/dockerfiles/Dockerfile.lint +++ b/dockerfiles/Dockerfile.lint @@ -1,6 +1,6 @@ -# syntax=docker/dockerfile:1.1.3-experimental +# syntax=docker/dockerfile:1.3 -ARG GO_VERSION=1.13.15 +ARG GO_VERSION=1.16.15 ARG GOLANGCI_LINTER_SHA="v1.21.0" FROM golang:${GO_VERSION}-alpine AS build @@ -13,6 +13,7 @@ RUN --mount=type=cache,target=/root/.cache/go-build \ go get github.com/golangci/golangci-lint/cmd/golangci-lint@${GOLANGCI_LINTER_SHA} FROM golang:${GO_VERSION}-alpine AS lint +ENV GO111MODULE=off ENV CGO_ENABLED=0 ENV DISABLE_WARN_OUTSIDE_CONTAINER=1 COPY --from=build /go/bin/golangci-lint /usr/local/bin diff --git a/docs/deprecated.md b/docs/deprecated.md index 267f8eef871d..e17450507da4 100644 --- a/docs/deprecated.md +++ b/docs/deprecated.md @@ -50,8 +50,11 @@ The table below provides an overview of the current status of deprecated feature Status | Feature | Deprecated | Remove -----------|------------------------------------------------------------------------------------------------------------------------------------|------------|------------ +Deprecated | [Support for encrypted TLS private keys](#support-for-encrypted-tls-private-keys) | v20.10 | - +Deprecated | [Kubernetes stack and context support](#kubernetes-stack-and-context-support) | v20.10 | - Deprecated | [Pulling images from non-compliant image registries](#pulling-images-from-non-compliant-image-registries) | v20.10 | - Deprecated | [Linux containers on Windows (LCOW)](#linux-containers-on-windows-lcow-experimental) | v20.10 | - +Deprecated | [BLKIO weight options with cgroups v1](#blkio-weight-options-with-cgroups-v1) | v20.10 | - Deprecated | [Kernel memory limit](#kernel-memory-limit) | v20.10 | - Deprecated | [Classic Swarm and overlay networks using external key/value stores](#classic-swarm-and-overlay-networks-using-cluster-store) | v20.10 | - Deprecated | [Support for the legacy `~/.dockercfg` configuration file for authentication](#support-for-legacy-dockercfg-configuration-files) | v20.10 | - @@ -96,6 +99,22 @@ Removed | [`--api-enable-cors` flag on `dockerd`](#--api-enable-cors-flag-on- Removed | [`--run` flag on `docker commit`](#--run-flag-on-docker-commit) | v0.10 | v1.13 Removed | [Three arguments form in `docker import`](#three-arguments-form-in-docker-import) | v0.6.7 | v1.12 +### Support for encrypted TLS private keys + +**Deprecated in Release: v20.10** + +Use of encrypted TLS private keys has been deprecated, and will be removed in a +future release. Golang has deprecated support for legacy PEM encryption (as +specified in [RFC 1423](https://datatracker.ietf.org/doc/html/rfc1423)), as it +is insecure by design (see [https://go-review.googlesource.com/c/go/+/264159](https://go-review.googlesource.com/c/go/+/264159)). + +### Kubernetes stack and context support + +**Deprecated in Release: v20.10** + +Following the deprecation of [Compose on Kubernetes](https://github.com/docker/compose-on-kubernetes), support for +Kubernetes in the `stack` and `context` commands in the docker CLI is now marked as deprecated as well. + ### Pulling images from non-compliant image registries **Deprecated in Release: v20.10** @@ -140,6 +159,16 @@ now stopped in favor of running docker natively on Linux in WSL2. Developers who want to run Linux workloads on a Windows host are encouraged to use [Docker Desktop with WSL2](https://docs.docker.com/docker-for-windows/wsl/) instead. +### BLKIO weight options with cgroups v1 + +**Deprecated in Release: v20.10** + +Specifying blkio weight (`docker run --blkio-weight` and `docker run --blkio-weight-device`) +is now marked as deprecated when using cgroups v1 because the corresponding features +were [removed in Linux kernel v5.0 and up](https://github.com/torvalds/linux/commit/f382fb0bcef4c37dc049e9f6963e3baf204d815c). +When using cgroups v2, the `--blkio-weight` options are implemented using +[`io.weight](https://github.com/torvalds/linux/blob/v5.0/Documentation/admin-guide/cgroup-v2.rst#io). + ### Kernel memory limit **Deprecated in Release: v20.10** @@ -559,9 +588,9 @@ Log tags are now generated in a standard way across different logging drivers. Because of which, the driver specific log tag options `syslog-tag`, `gelf-tag` and `fluentd-tag` have been deprecated in favor of the generic `tag` option. -```bash +```console {% raw %} -docker --log-driver=syslog --log-opt tag="{{.ImageName}}/{{.Name}}/{{.ID}}" +$ docker --log-driver=syslog --log-opt tag="{{.ImageName}}/{{.Name}}/{{.ID}}" {% endraw %} ``` diff --git a/docs/extend/index.md b/docs/extend/index.md index ecdf00b8f876..2608d0590baf 100644 --- a/docs/extend/index.md +++ b/docs/extend/index.md @@ -55,7 +55,7 @@ enabled, and use it to create a volume. 1. Install the `sshfs` plugin. - ```bash + ```console $ docker plugin install vieux/sshfs Plugin "vieux/sshfs" is requesting the following privileges: @@ -74,7 +74,7 @@ enabled, and use it to create a volume. 2. Check that the plugin is enabled in the output of `docker plugin ls`. - ```bash + ```console $ docker plugin ls ID NAME TAG DESCRIPTION ENABLED @@ -87,7 +87,7 @@ enabled, and use it to create a volume. This volume can now be mounted into containers. - ```bash + ```console $ docker volume create \ -d vieux/sshfs \ --name sshvolume \ @@ -96,9 +96,10 @@ enabled, and use it to create a volume. sshvolume ``` + 4. Verify that the volume was created successfully. - ```bash + ```console $ docker volume ls DRIVER NAME @@ -107,22 +108,23 @@ enabled, and use it to create a volume. 5. Start a container that uses the volume `sshvolume`. - ```bash + ```console $ docker run --rm -v sshvolume:/data busybox ls /data ``` 6. Remove the volume `sshvolume` - ```bash - docker volume rm sshvolume + ```console + $ docker volume rm sshvolume sshvolume ``` + To disable a plugin, use the `docker plugin disable` command. To completely remove it, use the `docker plugin remove` command. For other available commands and options, see the -[command line reference](../reference/commandline/index.md). +[command line reference](https://docs.docker.com/engine/reference/commandline/cli/). ## Developing a plugin @@ -134,7 +136,7 @@ example, it was created from a Dockerfile: >**Note:** The `/run/docker/plugins` directory is mandatory inside of the plugin's filesystem for docker to communicate with the plugin. -```bash +```console $ git clone https://github.com/vieux/docker-volume-sshfs $ cd docker-volume-sshfs $ docker build -t rootfsimage . @@ -193,13 +195,13 @@ Stdout of a plugin is redirected to dockerd logs. Such entries have a `f52a3df433b9aceee436eaada0752f5797aab1de47e5485f1690a073b860ff62` and their corresponding log entries in the docker daemon logs. -```bash +```console $ docker plugin install tiborvass/sample-volume-plugin INFO[0036] Starting... Found 0 volumes on startup plugin=f52a3df433b9aceee436eaada0752f5797aab1de47e5485f1690a073b860ff62 ``` -```bash +```console $ docker volume create -d tiborvass/sample-volume-plugin samplevol INFO[0193] Create Called... Ensuring directory /data/samplevol exists on host... plugin=f52a3df433b9aceee436eaada0752f5797aab1de47e5485f1690a073b860ff62 @@ -208,7 +210,7 @@ INFO[0193] Created volume samplevol with mountpoint /data/samp INFO[0193] Path Called... Returned path /data/samplevol plugin=f52a3df433b9aceee436eaada0752f5797aab1de47e5485f1690a073b860ff62 ``` -```bash +```console $ docker run -v samplevol:/tmp busybox sh INFO[0421] Get Called... Found samplevol plugin=f52a3df433b9aceee436eaada0752f5797aab1de47e5485f1690a073b860ff62 @@ -223,7 +225,7 @@ INFO[0421] Unmount Called... Unmounted samplevol plugin=f52a3df433b9a plugins. This is specifically useful to collect plugin logs if they are redirected to a file. -```bash +```console $ sudo docker-runc --root /var/run/docker/plugins/runtime-root/moby-plugins list ID PID STATUS BUNDLE CREATED OWNER @@ -232,13 +234,14 @@ ID PID S c5bb4b90941efcaccca999439ed06d6a6affdde7081bb34dc84126b57b3e793d 14984 running /run/docker/containerd/daemon/io.containerd.runtime.v1.linux/moby-plugins/c5bb4b90941efcaccca999439ed06d6a6affdde7081bb34dc84126b57b3e793d 2018-02-08T21:35:12.321288966Z root ``` -```bash +```console $ sudo docker-runc --root /var/run/docker/plugins/runtime-root/moby-plugins exec 93f1e7dbfe11c938782c2993628c895cf28e2274072c4a346a6002446c949b25 cat /var/log/plugin.log ``` If the plugin has a built-in shell, then exec into the plugin can be done as follows: -```bash + +```console $ sudo docker-runc --root /var/run/docker/plugins/runtime-root/moby-plugins exec -t 93f1e7dbfe11c938782c2993628c895cf28e2274072c4a346a6002446c949b25 sh ``` @@ -251,17 +254,18 @@ the plugin is listening on the said socket. For a well functioning plugin, these basic requests should work. Note that plugin sockets are available on the host under `/var/run/docker/plugins/` -```bash -curl -H "Content-Type: application/json" -XPOST -d '{}' --unix-socket /var/run/docker/plugins/e8a37ba56fc879c991f7d7921901723c64df6b42b87e6a0b055771ecf8477a6d/plugin.sock http:/VolumeDriver.List +```console +$ curl -H "Content-Type: application/json" -XPOST -d '{}' --unix-socket /var/run/docker/plugins/e8a37ba56fc879c991f7d7921901723c64df6b42b87e6a0b055771ecf8477a6d/plugin.sock http:/VolumeDriver.List {"Mountpoint":"","Err":"","Volumes":[{"Name":"myvol1","Mountpoint":"/data/myvol1"},{"Name":"myvol2","Mountpoint":"/data/myvol2"}],"Volume":null} ``` -```bash -curl -H "Content-Type: application/json" -XPOST -d '{}' --unix-socket /var/run/docker/plugins/45e00a7ce6185d6e365904c8bcf62eb724b1fe307e0d4e7ecc9f6c1eb7bcdb70/plugin.sock http:/NetworkDriver.GetCapabilities +```console +$ curl -H "Content-Type: application/json" -XPOST -d '{}' --unix-socket /var/run/docker/plugins/45e00a7ce6185d6e365904c8bcf62eb724b1fe307e0d4e7ecc9f6c1eb7bcdb70/plugin.sock http:/NetworkDriver.GetCapabilities {"Scope":"local"} ``` + When using curl 7.5 and above, the URL should be of the form `http://hostname/APICall`, where `hostname` is the valid hostname where the plugin is installed and `APICall` is the call to the plugin API. diff --git a/docs/extend/legacy_plugins.md b/docs/extend/legacy_plugins.md index 0fd6d11655d8..586c4d6082a3 100644 --- a/docs/extend/legacy_plugins.md +++ b/docs/extend/legacy_plugins.md @@ -72,7 +72,7 @@ The sections below provide an inexhaustive overview of available plugins. | [Horcrux Volume Plugin](https://github.com/muthu-r/horcrux) | A volume plugin that allows on-demand, version controlled access to your data. Horcrux is an open-source plugin, written in Go, and supports SCP, [Minio](https://www.minio.io) and Amazon S3. | | [HPE 3Par Volume Plugin](https://github.com/hpe-storage/python-hpedockerplugin/) | A volume plugin that supports HPE 3Par and StoreVirtual iSCSI storage arrays. | | [Infinit volume plugin](https://infinit.sh/documentation/docker/volume-plugin) | A volume plugin that makes it easy to mount and manage Infinit volumes using Docker. | -| [IPFS Volume Plugin](http://github.com/vdemeester/docker-volume-ipfs) | An open source volume plugin that allows using an [ipfs](https://ipfs.io/) filesystem as a volume. | +| [IPFS Volume Plugin](https://github.com/vdemeester/docker-volume-ipfs) | An open source volume plugin that allows using an [ipfs](https://ipfs.io/) filesystem as a volume. | | [Keywhiz plugin](https://github.com/calavera/docker-volume-keywhiz) | A plugin that provides credentials and secret management using Keywhiz as a central repository. | | [Local Persist Plugin](https://github.com/CWSpear/local-persist) | A volume plugin that extends the default `local` driver's functionality by allowing you specify a mountpoint anywhere on the host, which enables the files to *always persist*, even if the volume is removed via `docker volume rm`. | | [NetApp Plugin](https://github.com/NetApp/netappdvp) (nDVP) | A volume plugin that provides direct integration with the Docker ecosystem for the NetApp storage portfolio. The nDVP package supports the provisioning and management of storage resources from the storage platform to Docker hosts, with a robust framework for adding additional platforms in the future. | @@ -80,7 +80,7 @@ The sections below provide an inexhaustive overview of available plugins. | [Nimble Storage Volume Plugin](https://connect.nimblestorage.com/community/app-integration/docker) | A volume plug-in that integrates with Nimble Storage Unified Flash Fabric arrays. The plug-in abstracts array volume capabilities to the Docker administrator to allow self-provisioning of secure multi-tenant volumes and clones. | | [OpenStorage Plugin](https://github.com/libopenstorage/openstorage) | A cluster-aware volume plugin that provides volume management for file and block storage solutions. It implements a vendor neutral specification for implementing extensions such as CoS, encryption, and snapshots. It has example drivers based on FUSE, NFS, NBD and EBS to name a few. | | [Portworx Volume Plugin](https://github.com/portworx/px-dev) | A volume plugin that turns any server into a scale-out converged compute/storage node, providing container granular storage and highly available volumes across any node, using a shared-nothing storage backend that works with any docker scheduler. | -| [Quobyte Volume Plugin](https://github.com/quobyte/docker-volume) | A volume plugin that connects Docker to [Quobyte](http://www.quobyte.com/containers)'s data center file system, a general-purpose scalable and fault-tolerant storage platform. | +| [Quobyte Volume Plugin](https://github.com/quobyte/docker-volume) | A volume plugin that connects Docker to [Quobyte](https://www.quobyte.com/containers)'s data center file system, a general-purpose scalable and fault-tolerant storage platform. | | [REX-Ray plugin](https://github.com/emccode/rexray) | A volume plugin which is written in Go and provides advanced storage functionality for many platforms including VirtualBox, EC2, Google Compute Engine, OpenStack, and EMC. | | [Virtuozzo Storage and Ploop plugin](https://github.com/virtuozzo/docker-volume-ploop) | A volume plugin with support for Virtuozzo Storage distributed cloud file system as well as ploop devices. | | [VMware vSphere Storage Plugin](https://github.com/vmware/docker-volume-vsphere) | Docker Volume Driver for vSphere enables customers to address persistent storage requirements for Docker containers in vSphere environments. | diff --git a/docs/extend/plugin_api.md b/docs/extend/plugin_api.md index 2a317f953aa2..812b465085bf 100644 --- a/docs/extend/plugin_api.md +++ b/docs/extend/plugin_api.md @@ -90,7 +90,7 @@ The `TLSConfig` field is optional and TLS will only be verified if this configur Plugins should be started before Docker, and stopped after Docker. For example, when packaging a plugin for a platform which supports `systemd`, you might use [`systemd` dependencies]( -http://www.freedesktop.org/software/systemd/man/systemd.unit.html#Before=) to +https://www.freedesktop.org/software/systemd/man/systemd.unit.html#Before=) to manage startup and shutdown order. When upgrading a plugin, you should first stop the Docker daemon, upgrade the @@ -114,7 +114,7 @@ a `service` file and a `socket` file. The `service` file (for example `/lib/systemd/system/your-plugin.service`): -``` +```systemd [Unit] Description=Your plugin Before=docker.service @@ -127,9 +127,10 @@ ExecStart=/usr/lib/docker/your-plugin [Install] WantedBy=multi-user.target ``` + The `socket` file (for example `/lib/systemd/system/your-plugin.socket`): -``` +```systemd [Unit] Description=Your plugin @@ -166,7 +167,8 @@ Plugins are activated via the following "handshake" API call. **Request:** empty body **Response:** -``` + +```json { "Implements": ["VolumeDriver"] } diff --git a/docs/extend/plugins_authorization.md b/docs/extend/plugins_authorization.md index d62c795862d8..2fc444e1017d 100644 --- a/docs/extend/plugins_authorization.md +++ b/docs/extend/plugins_authorization.md @@ -114,9 +114,9 @@ Enable the authorization plugin with a dedicated command line flag in the `--authorization-plugin=PLUGIN_ID` format. The flag supplies a `PLUGIN_ID` value. This value can be the plugin’s socket or a path to a specification file. Authorization plugins can be loaded without restarting the daemon. Refer -to the [`dockerd` documentation](../reference/commandline/dockerd.md#configuration-reloading) for more information. +to the [`dockerd` documentation](../reference/commandline/dockerd.md#configuration-reload-behavior) for more information. -```bash +```console $ dockerd --authorization-plugin=plugin1 --authorization-plugin=plugin2,... ``` @@ -124,26 +124,26 @@ Docker's authorization subsystem supports multiple `--authorization-plugin` para ### Calling authorized command (allow) -```bash +```console $ docker pull centos -... +<...> f1b10cd84249: Pull complete -... +<...> ``` ### Calling unauthorized command (deny) -```bash +```console $ docker pull centos -... +<...> docker: Error response from daemon: authorization denied by plugin PLUGIN_NAME: volumes are not allowed. ``` ### Error from plugins -```bash +```console $ docker pull centos -... +<...> docker: Error response from daemon: plugin PLUGIN_NAME failed with error: AuthZPlugin.AuthZReq: Cannot connect to the Docker daemon. Is the docker daemon running on this host?. ``` @@ -180,6 +180,7 @@ should implement the following two methods: "Err": "The error message if things go wrong" } ``` + #### /AuthZPlugin.AuthZRes **Request**: diff --git a/docs/extend/plugins_graphdriver.md b/docs/extend/plugins_graphdriver.md index d8d4531d8cf2..da7ab68ea2f0 100644 --- a/docs/extend/plugins_graphdriver.md +++ b/docs/extend/plugins_graphdriver.md @@ -31,7 +31,7 @@ You need to install and enable the plugin and then restart the Docker daemon before using the plugin. See the following example for the correct ordering of steps. -``` +```console $ docker plugin install cpuguy83/docker-overlay2-graphdriver-plugin # this command also enables the driver $ pkill dockerd @@ -309,6 +309,7 @@ Get an archive of the changes between the filesystem layers specified by the `ID and `Parent`. `Parent` may be an empty string, in which case there is no parent. **Response**: + ``` {% raw %} {{ TAR STREAM }} @@ -354,6 +355,7 @@ Respond with a non-empty string error if an error occurred. ### /GraphDriver.ApplyDiff **Request**: + ``` {% raw %} {{ TAR STREAM }} diff --git a/docs/extend/plugins_logging.md b/docs/extend/plugins_logging.md index fbfd2197c14a..6405dd26cf37 100644 --- a/docs/extend/plugins_logging.md +++ b/docs/extend/plugins_logging.md @@ -211,6 +211,7 @@ as they come in once the existing logs have been read. to determine what set of logs to read. **Response**: + ``` {% raw %}{{ log stream }}{% endraw %} ``` diff --git a/docs/extend/plugins_network.md b/docs/extend/plugins_network.md index 93aea4bd0f9d..1e218bb4d4b1 100644 --- a/docs/extend/plugins_network.md +++ b/docs/extend/plugins_network.md @@ -42,7 +42,7 @@ Once running however, network driver plugins are used just like the built-in network drivers: by being mentioned as a driver in network-oriented Docker commands. For example, -```bash +```console $ docker network create --driver weave mynet ``` @@ -51,7 +51,7 @@ Some network driver plugins are listed in [plugins](legacy_plugins.md) The `mynet` network is now owned by `weave`, so subsequent commands referring to that network will be sent to the plugin, -```bash +```console $ docker run --network=mynet busybox top ``` diff --git a/docs/extend/plugins_services.md b/docs/extend/plugins_services.md index cd94d11cb5e6..20889dd976ca 100644 --- a/docs/extend/plugins_services.md +++ b/docs/extend/plugins_services.md @@ -29,20 +29,20 @@ node1 is the manager and node2 is the worker. 1. Prepare manager. In node 1: - ```bash + ```console $ docker swarm init Swarm initialized: current node (dxn1zf6l61qsb1josjja83ngz) is now a manager. ``` 2. Join swarm, install plugin and create volume on worker. In node 2: - ```bash + ```console $ docker swarm join \ - --token SWMTKN-1-49nj1cmql0jkz5s954yi3oex3nedyz0fb0xx14ie39trti4wxv-8vxv8rssmk743ojnwacrr2e7c \ - 192.168.99.100:2377 + --token SWMTKN-1-49nj1cmql0jkz5s954yi3oex3nedyz0fb0xx14ie39trti4wxv-8vxv8rssmk743ojnwacrr2e7c \ + 192.168.99.100:2377 ``` - ```bash + ```console $ docker plugin install tiborvass/sample-volume-plugin latest: Pulling from tiborvass/sample-volume-plugin eb9c16fbdc53: Download complete @@ -51,23 +51,24 @@ node1 is the manager and node2 is the worker. Installed plugin tiborvass/sample-volume-plugin ``` - ```bash + ```console $ docker volume create -d tiborvass/sample-volume-plugin --name pluginVol ``` 3. Create a service using the plugin and volume. In node1: - ```bash + ```console $ docker service create --name my-service --mount type=volume,volume-driver=tiborvass/sample-volume-plugin,source=pluginVol,destination=/tmp busybox top $ docker service ls z1sj8bb8jnfn my-service replicated 1/1 busybox:latest ``` - docker service ls shows service 1 instance of service running. + + `docker service ls` shows service 1 instance of service running. 4. Observe the task getting scheduled in node 2: - ```bash + ```console {% raw %} $ docker ps --format '{{.ID}}\t {{.Status}} {{.Names}} {{.Command}}' 83fc1e842599 Up 2 days my-service.1.9jn59qzn7nbc3m0zt1hij12xs "top" @@ -87,7 +88,7 @@ Note that node1 is the manager and node2 is the worker. 1. Install a global scoped network plugin on both manager and worker. On node1 and node2: - ```bash + ```console $ docker plugin install bboreham/weave2 Plugin "bboreham/weave2" is requesting the following privileges: - network: [host] @@ -102,7 +103,7 @@ Note that node1 is the manager and node2 is the worker. 2. Create a network using plugin on manager. On node1: - ```bash + ```console $ docker network create --driver=bboreham/weave2:latest globalnet $ docker network ls @@ -115,12 +116,12 @@ containers get scheduled on both manager and worker. On node 1: - ```bash + ```console $ docker service create --network globalnet --name myservice --replicas=8 mrjana/simpleweb simpleweb w90drnfzw85nygbie9kb89vpa ``` - ```bash + ```console $ docker ps CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 87520965206a mrjana/simpleweb@sha256:317d7f221d68c86d503119b0ea12c29de42af0a22ca087d522646ad1069a47a4 "simpleweb" 5 seconds ago Up 4 seconds myservice.4.ytdzpktmwor82zjxkh118uf1v @@ -131,7 +132,7 @@ w90drnfzw85nygbie9kb89vpa On node 2: - ```bash + ```console $ docker ps CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 53c0ae7c1dae mrjana/simpleweb@sha256:317d7f221d68c86d503119b0ea12c29de42af0a22ca087d522646ad1069a47a4 "simpleweb" 2 seconds ago Up Less than a second myservice.7.x44tvvdm3iwkt9kif35f7ykz1 @@ -142,14 +143,14 @@ w90drnfzw85nygbie9kb89vpa 4. Scale down the number of instances. On node1: - ```bash + ```console $ docker service scale myservice=0 myservice scaled to 0 ``` 5. Disable and uninstall the plugin on the worker. On node2: - ```bash + ```console $ docker plugin rm -f bboreham/weave2 bboreham/weave2 ``` @@ -159,12 +160,12 @@ scheduled on the master and not on the worker, because the plugin is not availab On node 1: - ```bash + ```console $ docker service scale myservice=8 myservice scaled to 8 ``` - ```bash + ```console $ docker ps CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES cf4b0ec2415e mrjana/simpleweb@sha256:317d7f221d68c86d503119b0ea12c29de42af0a22ca087d522646ad1069a47a4 "simpleweb" 39 seconds ago Up 36 seconds myservice.3.r7p5o208jmlzpcbm2ytl3q6n1 @@ -179,7 +180,7 @@ scheduled on the master and not on the worker, because the plugin is not availab On node 2: - ```bash + ```console $ docker ps CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES ``` diff --git a/docs/extend/plugins_volume.md b/docs/extend/plugins_volume.md index 74abfd1bff21..23e7cddf9e94 100644 --- a/docs/extend/plugins_volume.md +++ b/docs/extend/plugins_volume.md @@ -54,7 +54,7 @@ flags on the `docker container run` command. The `--volume` (or `-v`) flag accepts a volume name and path on the host, and the `--volume-driver` flag accepts a driver type. -```bash +```console $ docker volume create --driver=flocker volumename $ docker container run -it --volume volumename:/data busybox sh diff --git a/docs/reference/builder.md b/docs/reference/builder.md index 4ebe6ae6dec0..7e73282a7c00 100644 --- a/docs/reference/builder.md +++ b/docs/reference/builder.md @@ -33,11 +33,11 @@ a `Dockerfile` and a *context*. The build's context is the set of files at a specified location `PATH` or `URL`. The `PATH` is a directory on your local filesystem. The `URL` is a Git repository location. -A context is processed recursively. So, a `PATH` includes any subdirectories and -the `URL` includes the repository and its submodules. This example shows a -build command that uses the current directory as context: +The build context is processed recursively. So, a `PATH` includes any subdirectories +and the `URL` includes the repository and its submodules. This example shows a +build command that uses the current directory (`.`) as build context: -```bash +```console $ docker build . Sending build context to Docker daemon 6.51 MB @@ -52,8 +52,9 @@ Dockerfile. > **Warning** > -> Do not use your root directory, `/`, as the `PATH` as it causes the build to -> transfer the entire contents of your hard drive to the Docker daemon. +> Do not use your root directory, `/`, as the `PATH` for your build context, as +> it causes the build to transfer the entire contents of your hard drive to the +> Docker daemon. {:.warning} To use a file in the build context, the `Dockerfile` refers to the file specified @@ -66,32 +67,37 @@ Traditionally, the `Dockerfile` is called `Dockerfile` and located in the root of the context. You use the `-f` flag with `docker build` to point to a Dockerfile anywhere in your file system. -```bash +```console $ docker build -f /path/to/a/Dockerfile . ``` You can specify a repository and tag at which to save the new image if the build succeeds: -```bash +```console $ docker build -t shykes/myapp . ``` To tag the image into multiple repositories after the build, add multiple `-t` parameters when you run the `build` command: -```bash +```console $ docker build -t shykes/myapp:1.0.2 -t shykes/myapp:latest . ``` Before the Docker daemon runs the instructions in the `Dockerfile`, it performs a preliminary validation of the `Dockerfile` and returns an error if the syntax is incorrect: -```bash +```console $ docker build -t test/myapp . -Sending build context to Docker daemon 2.048 kB -Error response from daemon: Unknown instruction: RUNCMD +[+] Building 0.3s (2/2) FINISHED + => [internal] load build definition from Dockerfile 0.1s + => => transferring dockerfile: 60B 0.0s + => [internal] load .dockerignore 0.1s + => => transferring context: 2B 0.0s +error: failed to solve: rpc error: code = Unknown desc = failed to solve with frontend dockerfile.v0: failed to create LLB definition: +dockerfile parse error line 2: unknown instruction: RUNCMD ``` The Docker daemon runs the instructions in the `Dockerfile` one-by-one, @@ -104,38 +110,35 @@ Note that each instruction is run independently, and causes a new image to be created - so `RUN cd /tmp` will not have any effect on the next instructions. -Whenever possible, Docker will re-use the intermediate images (cache), -to accelerate the `docker build` process significantly. This is indicated by -the `Using cache` message in the console output. -(For more information, see the [`Dockerfile` best practices guide](https://docs.docker.com/engine/userguide/eng-image/dockerfile_best-practices/): +Whenever possible, Docker uses a build-cache to accelerate the `docker build` +process significantly. This is indicated by the `CACHED` message in the console +output. (For more information, see the [`Dockerfile` best practices guide](https://docs.docker.com/engine/userguide/eng-image/dockerfile_best-practices/)): -```bash +```console $ docker build -t svendowideit/ambassador . -Sending build context to Docker daemon 15.36 kB -Step 1/4 : FROM alpine:3.2 - ---> 31f630c65071 -Step 2/4 : MAINTAINER SvenDowideit@home.org.au - ---> Using cache - ---> 2a1c91448f5f -Step 3/4 : RUN apk update && apk add socat && rm -r /var/cache/ - ---> Using cache - ---> 21ed6e7fbb73 -Step 4/4 : CMD env | grep _TCP= | (sed 's/.*_PORT_\([0-9]*\)_TCP=tcp:\/\/\(.*\):\(.*\)/socat -t 100000000 TCP4-LISTEN:\1,fork,reuseaddr TCP4:\2:\3 \&/' && echo wait) | sh - ---> Using cache - ---> 7ea8aef582cc -Successfully built 7ea8aef582cc +[+] Building 0.7s (6/6) FINISHED + => [internal] load build definition from Dockerfile 0.1s + => => transferring dockerfile: 286B 0.0s + => [internal] load .dockerignore 0.1s + => => transferring context: 2B 0.0s + => [internal] load metadata for docker.io/library/alpine:3.2 0.4s + => CACHED [1/2] FROM docker.io/library/alpine:3.2@sha256:e9a2035f9d0d7ce 0.0s + => CACHED [2/2] RUN apk add --no-cache socat 0.0s + => exporting to image 0.0s + => => exporting layers 0.0s + => => writing image sha256:1affb80ca37018ac12067fa2af38cc5bcc2a8f09963de 0.0s + => => naming to docker.io/svendowideit/ambassador 0.0s ``` -Build cache is only used from images that have a local parent chain. This means -that these images were created by previous builds or the whole chain of images -was loaded with `docker load`. If you wish to use build cache of a specific -image you can specify it with `--cache-from` option. Images specified with -`--cache-from` do not need to have a parent chain and may be pulled from other -registries. +By default, the build cache is based on results from previous builds on the machine +on which you are building. The `--cache-from` option also allows you to use a +build-cache that's distributed through an image registry refer to the +[specifying external cache sources](commandline/build.md#specifying-external-cache-sources) +section in the `docker build` command reference. -When you're done with your build, you're ready to look into [*Pushing a -repository to its registry*](https://docs.docker.com/engine/tutorials/dockerrepos/#/contributing-to-docker-hub). +When you're done with your build, you're ready to look into [scanning your image with `docker scan`](https://docs.docker.com/engine/scan/), +and [pushing your image to Docker Hub](https://docs.docker.com/docker-hub/repos/). ## BuildKit @@ -156,8 +159,8 @@ implementation. For example, BuildKit can: To use the BuildKit backend, you need to set an environment variable `DOCKER_BUILDKIT=1` on the CLI before invoking `docker build`. -To learn about the experimental Dockerfile syntax available to BuildKit-based -builds [refer to the documentation in the BuildKit repository](https://github.com/moby/buildkit/blob/master/frontend/dockerfile/docs/experimental.md). +To learn about the Dockerfile syntax available to BuildKit-based +builds [refer to the documentation in the BuildKit repository](https://github.com/moby/buildkit/blob/master/frontend/dockerfile/docs/syntax.md). ## Format @@ -176,7 +179,7 @@ Docker runs instructions in a `Dockerfile` in order. A `Dockerfile` **must begin with a `FROM` instruction**. This may be after [parser directives](#parser-directives), [comments](#format), and globally scoped [ARGs](#arg). The `FROM` instruction specifies the [*Parent -Image*](https://docs.docker.com/glossary/#parent_image) from which you are +Image*](https://docs.docker.com/glossary/#parent-image) from which you are building. `FROM` may only be preceded by one or more `ARG` instructions, which declare arguments that are used in `FROM` lines in the `Dockerfile`. @@ -315,6 +318,8 @@ The following parser directives are supported: ## syntax + + ```dockerfile # syntax=[remote image reference] ``` @@ -322,55 +327,73 @@ The following parser directives are supported: For example: ```dockerfile -# syntax=docker/dockerfile -# syntax=docker/dockerfile:1.0 +# syntax=docker/dockerfile:1 # syntax=docker.io/docker/dockerfile:1 -# syntax=docker/dockerfile:1.0.0-experimental # syntax=example.com/user/repo:tag@sha256:abcdef... ``` -This feature is only enabled if the [BuildKit](#buildkit) backend is used. +This feature is only available when using the [BuildKit](#buildkit) backend, and +is ignored when using the classic builder backend. -The syntax directive defines the location of the Dockerfile builder that is used for -building the current Dockerfile. The BuildKit backend allows to seamlessly use -external implementations of builders that are distributed as Docker images and -execute inside a container sandbox environment. +The syntax directive defines the location of the Dockerfile syntax that is used +to build the Dockerfile. The BuildKit backend allows to seamlessly use external +implementations that are distributed as Docker images and execute inside a +container sandbox environment. -Custom Dockerfile implementation allows you to: +Custom Dockerfile implementations allows you to: - - Automatically get bugfixes without updating the daemon + - Automatically get bugfixes without updating the Docker daemon - Make sure all users are using the same implementation to build your Dockerfile - - Use the latest features without updating the daemon - - Try out new experimental or third-party features + - Use the latest features without updating the Docker daemon + - Try out new features or third-party features before they are integrated in the Docker daemon + - Use [alternative build definitions, or create your own](https://github.com/moby/buildkit#exploring-llb) ### Official releases Docker distributes official versions of the images that can be used for building Dockerfiles under `docker/dockerfile` repository on Docker Hub. There are two -channels where new images are released: stable and experimental. +channels where new images are released: `stable` and `labs`. + +Stable channel follows [semantic versioning](https://semver.org). For example: + + - `docker/dockerfile:1` - kept updated with the latest `1.x.x` minor _and_ patch release + - `docker/dockerfile:1.2` - kept updated with the latest `1.2.x` patch release, + and stops receiving updates once version `1.3.0` is released. + - `docker/dockerfile:1.2.1` - immutable: never updated -Stable channel follows semantic versioning. For example: +We recommend using `docker/dockerfile:1`, which always points to the latest stable +release of the version 1 syntax, and receives both "minor" and "patch" updates +for the version 1 release cycle. BuildKit automatically checks for updates of the +syntax when performing a build, making sure you are using the most current version. - - `docker/dockerfile:1.0.0` - only allow immutable version `1.0.0` - - `docker/dockerfile:1.0` - allow versions `1.0.*` - - `docker/dockerfile:1` - allow versions `1.*.*` - - `docker/dockerfile:latest` - latest release on stable channel +If a specific version is used, such as `1.2` or `1.2.1`, the Dockerfile needs to +be updated manually to continue receiving bugfixes and new features. Old versions +of the Dockerfile remain compatible with the new versions of the builder. -The experimental channel uses incremental versioning with the major and minor -component from the stable channel on the time of the release. For example: +**labs channel** - - `docker/dockerfile:1.0.1-experimental` - only allow immutable version `1.0.1-experimental` - - `docker/dockerfile:1.0-experimental` - latest experimental releases after `1.0` - - `docker/dockerfile:experimental` - latest release on experimental channel +The "labs" channel provides early access to Dockerfile features that are not yet +available in the stable channel. Labs channel images are released in conjunction +with the stable releases, and follow the same versioning with the `-labs` suffix, +for example: -You should choose a channel that best fits your needs. If you only want -bugfixes, you should use `docker/dockerfile:1.0`. If you want to benefit from -experimental features, you should use the experimental channel. If you are using -the experimental channel, newer releases may not be backwards compatible, so it + - `docker/dockerfile:labs` - latest release on labs channel + - `docker/dockerfile:1-labs` - same as `dockerfile:1` in the stable channel, with labs features enabled + - `docker/dockerfile:1.2-labs` - same as `dockerfile:1.2` in the stable channel, with labs features enabled + - `docker/dockerfile:1.2.1-labs` - immutable: never updated. Same as `dockerfile:1.2.1` in the stable channel, with labs features enabled + +Choose a channel that best fits your needs; if you want to benefit from +new features, use the labs channel. Images in the labs channel provide a superset +of the features in the stable channel; note that `stable` features in the labs +channel images follow [semantic versioning](https://semver.org), but "labs" +features do not, and newer releases may not be backwards compatible, so it is recommended to use an immutable full version variant. -For master builds and nightly feature releases refer to the description in -[the source repository](https://github.com/moby/buildkit/blob/master/README.md). +For documentation on "labs" features, master builds, and nightly feature releases, +refer to the description in [the BuildKit source repository on GitHub](https://github.com/moby/buildkit/blob/master/README.md). +For a full list of available images, visit the [image repository on Docker Hub](https://hub.docker.com/r/docker/dockerfile), +and the [docker/dockerfile-upstream image repository](https://hub.docker.com/r/docker/dockerfile-upstream) +for development builds. ## escape @@ -413,14 +436,15 @@ RUN dir c:\ Results in: -```powershell -PS C:\John> docker build -t cmd . +```console +PS E:\myproject> docker build -t cmd . + Sending build context to Docker daemon 3.072 kB Step 1/2 : FROM microsoft/nanoserver ---> 22738ff49c6d Step 2/2 : COPY testfile.txt c:\RUN dir c: GetFileAttributesEx c:RUN: The system cannot find the file specified. -PS C:\John> +PS E:\myproject> ``` One solution to the above would be to use `/` as the target of both the `COPY` @@ -441,8 +465,9 @@ RUN dir c:\ Results in: -```powershell -PS C:\John> docker build -t succeeds --no-cache=true . +```console +PS E:\myproject> docker build -t succeeds --no-cache=true . + Sending build context to Docker daemon 3.072 kB Step 1/3 : FROM microsoft/nanoserver ---> 22738ff49c6d @@ -467,7 +492,7 @@ Step 3/3 : RUN dir c:\ ---> 01c7f3bef04f Removing intermediate container a2c157f842f5 Successfully built 01c7f3bef04f -PS C:\John> +PS E:\myproject> ``` ## Environment replacement @@ -574,10 +599,10 @@ This file causes the following build behavior: Matching is done using Go's -[filepath.Match](http://golang.org/pkg/path/filepath#Match) rules. A +[filepath.Match](https://golang.org/pkg/path/filepath#Match) rules. A preprocessing step removes leading and trailing whitespace and eliminates `.` and `..` elements using Go's -[filepath.Clean](http://golang.org/pkg/path/filepath/#Clean). Lines +[filepath.Clean](https://golang.org/pkg/path/filepath/#Clean). Lines that are blank after preprocessing are ignored. Beyond Go's filepath.Match rules, Docker also supports a special @@ -652,7 +677,7 @@ FROM [--platform=] [@] [AS ] ``` The `FROM` instruction initializes a new build stage and sets the -[*Base Image*](https://docs.docker.com/glossary/#base_image) for subsequent instructions. As such, a +[*Base Image*](https://docs.docker.com/glossary/#base-image) for subsequent instructions. As such, a valid `Dockerfile` must start with a `FROM` instruction. The image can be any valid image – it is especially easy to start by **pulling an image** from the [*Public Repositories*](https://docs.docker.com/docker-hub/repos/). @@ -734,6 +759,7 @@ RUN instruction onto the next line. For example, consider these two lines: RUN /bin/bash -c 'source $HOME/.bashrc; \ echo $HOME' ``` + Together they are equivalent to this single line: ```dockerfile @@ -910,9 +936,10 @@ the most-recently-applied value overrides any previously-set value. To view an image's labels, use the `docker image inspect` command. You can use the `--format` option to show just the labels; -```bash -docker image inspect --format='{{json .Config.Labels}}' myimage +```console +$ docker image inspect --format='{{json .Config.Labels}}' myimage ``` + ```json { "com.example.vendor": "ACME Incorporated", @@ -938,7 +965,7 @@ easily, for example with `docker inspect`. To set a label corresponding to the `MAINTAINER` field you could use: ```dockerfile -LABEL maintainer="SvenDowideit@home.org.au" +LABEL org.opencontainers.image.authors="SvenDowideit@home.org.au" ``` This will then be visible from `docker inspect` with the other labels. @@ -980,8 +1007,8 @@ port on the host, so the port will not be the same for TCP and UDP. Regardless of the `EXPOSE` settings, you can override them at runtime by using the `-p` flag. For example -```bash -docker run -p 80:80/tcp -p 80:80/udp ... +```console +$ docker run -p 80:80/tcp -p 80:80/udp ... ``` To set up port redirection on the host system, see [using the -P flag](run.md#expose-incoming-ports). @@ -1090,7 +1117,7 @@ directories, their paths are interpreted as relative to the source of the context of the build. Each `` may contain wildcards and matching will be done using Go's -[filepath.Match](http://golang.org/pkg/path/filepath#Match) rules. For example: +[filepath.Match](https://golang.org/pkg/path/filepath#Match) rules. For example: To add all files starting with "hom": @@ -1266,7 +1293,7 @@ directories will be interpreted as relative to the source of the context of the build. Each `` may contain wildcards and matching will be done using Go's -[filepath.Match](http://golang.org/pkg/path/filepath#Match) rules. For example: +[filepath.Match](https://golang.org/pkg/path/filepath#Match) rules. For example: To add all files starting with "hom": @@ -1397,7 +1424,7 @@ An `ENTRYPOINT` allows you to configure a container that will run as an executab For example, the following starts nginx with its default content, listening on port 80: -```bash +```console $ docker run -i -t --rm -p 80:80 nginx ``` @@ -1432,7 +1459,7 @@ CMD ["-c"] When you run the container, you can see that `top` is the only process: -```bash +```console $ docker run -it --rm --name test top -H top - 08:25:00 up 7:27, 0 users, load average: 0.00, 0.01, 0.05 @@ -1447,7 +1474,7 @@ KiB Swap: 1441840 total, 0 used, 1441840 free. 1324440 cached Mem To examine the result further, you can use `docker exec`: -```bash +```console $ docker exec -it test ps aux USER PID %CPU %MEM VSZ RSS TTY STAT START TIME COMMAND @@ -1519,7 +1546,7 @@ If you run this image with `docker run -it --rm -p 80:80 --name test apache`, you can then examine the container's processes with `docker exec`, or `docker top`, and then ask the script to stop Apache: -```bash +```console $ docker exec -it test ps aux USER PID %CPU %MEM VSZ RSS TTY STAT START TIME COMMAND @@ -1579,7 +1606,7 @@ ENTRYPOINT exec top -b When you run this image, you'll see the single `PID 1` process: -```bash +```console $ docker run -it --rm --name test top Mem: 1704520K used, 352148K free, 0K shrd, 0K buff, 140368121167873K cached @@ -1591,7 +1618,7 @@ Load average: 0.08 0.03 0.05 2/98 6 Which exits cleanly on `docker stop`: -```bash +```console $ /usr/bin/time docker stop test test @@ -1610,7 +1637,7 @@ CMD --ignored-param1 You can then run it (giving it a name for the next step): -```bash +```console $ docker run -it --name test top --ignored-param2 Mem: 1704184K used, 352484K free, 0K shrd, 0K buff, 140621524238337K cached @@ -1626,7 +1653,7 @@ You can see from the output of `top` that the specified `ENTRYPOINT` is not `PID If you then run `docker stop test`, the container will not exit cleanly - the `stop` command will be forced to send a `SIGKILL` after the timeout: -```bash +```console $ docker exec -it test ps aux PID USER COMMAND @@ -1797,6 +1824,11 @@ RUN pwd The output of the final `pwd` command in this `Dockerfile` would be `/path/$DIRNAME` +If not specified, the default working directory is `/`. In practice, if you aren't building a Dockerfile from scratch (`FROM scratch`), +the `WORKDIR` may likely be set by the base image you're using. + +Therefore, to avoid unintended operations in unknown directories, it is best practice to set your `WORKDIR` explicitly. + ## ARG ```dockerfile @@ -1859,9 +1891,10 @@ ARG user USER $user # ... ``` + A user builds this file by calling: -```bash +```console $ docker build --build-arg user=what_user . ``` @@ -1900,7 +1933,7 @@ RUN echo $CONT_IMG_VER Then, assume this image is built with this command: -```bash +```console $ docker build --build-arg CONT_IMG_VER=v2.0.1 . ``` @@ -1922,7 +1955,7 @@ RUN echo $CONT_IMG_VER Unlike an `ARG` instruction, `ENV` values are always persisted in the built image. Consider a docker build without the `--build-arg` flag: -```bash +```console $ docker build . ``` @@ -1948,10 +1981,11 @@ corresponding `ARG` instruction in the Dockerfile. - `NO_PROXY` - `no_proxy` -To use these, simply pass them on the command line using the flag: +To use these, pass them on the command line using the `--build-arg` flag, for +example: -```bash ---build-arg = +```console +$ docker build --build-arg HTTPS_PROXY=https://my-proxy.example.com . ``` By default, these pre-defined variables are excluded from the output of @@ -2144,9 +2178,14 @@ ONBUILD RUN /usr/local/bin/python-build --dir /app/src STOPSIGNAL signal ``` -The `STOPSIGNAL` instruction sets the system call signal that will be sent to the container to exit. -This signal can be a valid unsigned number that matches a position in the kernel's syscall table, for instance 9, -or a signal name in the format SIGNAME, for instance SIGKILL. +The `STOPSIGNAL` instruction 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 default is `SIGTERM` if not +defined. + +The image's default stopsignal can be overridden per container, using the +`--stop-signal` flag on `docker run` and `docker create`. ## HEALTHCHECK @@ -2298,8 +2337,9 @@ RUN c:\example\Execute-MyCmdlet -sample 'hello world' Resulting in: -```powershell -PS E:\docker\build\shell> docker build -t shell . +```console +PS E:\myproject> docker build -t shell . + Sending build context to Docker daemon 4.096 kB Step 1/5 : FROM microsoft/nanoserver ---> 22738ff49c6d @@ -2314,9 +2354,9 @@ Step 3/5 : RUN New-Item -ItemType Directory C:\Example Directory: C:\ -Mode LastWriteTime Length Name ----- ------------- ------ ---- -d----- 10/28/2016 11:26 AM Example +Mode LastWriteTime Length Name +---- ------------- ------ ---- +d----- 10/28/2016 11:26 AM Example ---> 3f2fbf1395d9 @@ -2330,7 +2370,7 @@ hello world ---> 8e559e9bf424 Removing intermediate container be6d8e63fe75 Successfully built 8e559e9bf424 -PS E:\docker\build\shell> +PS E:\myproject> ``` The `SHELL` instruction could also be used to modify the way in which @@ -2340,61 +2380,10 @@ environment variable expansion semantics could be modified. The `SHELL` instruction can also be used on Linux should an alternate shell be required such as `zsh`, `csh`, `tcsh` and others. -## External implementation features - -This feature is only available when using the [BuildKit](#buildkit) backend. - -Docker build supports experimental features like cache mounts, build secrets and -ssh forwarding that are enabled by using an external implementation of the -builder with a syntax directive. To learn about these features, -[refer to the documentation in BuildKit repository](https://github.com/moby/buildkit/blob/master/frontend/dockerfile/docs/experimental.md). - ## Dockerfile examples -Below you can see some examples of Dockerfile syntax. - -```dockerfile -# Nginx -# -# VERSION 0.0.1 - -FROM ubuntu -LABEL Description="This image is used to start the foobar executable" Vendor="ACME Products" Version="1.0" -RUN apt-get update && apt-get install -y inotify-tools nginx apache2 openssh-server -``` - -```dockerfile -# Firefox over VNC -# -# VERSION 0.3 - -FROM ubuntu - -# Install vnc, xvfb in order to create a 'fake' display and firefox -RUN apt-get update && apt-get install -y x11vnc xvfb firefox -RUN mkdir ~/.vnc -# Setup a password -RUN x11vnc -storepasswd 1234 ~/.vnc/passwd -# Autostart firefox (might not be the best way, but it does the trick) -RUN bash -c 'echo "firefox" >> /.bashrc' - -EXPOSE 5900 -CMD ["x11vnc", "-forever", "-usepw", "-create"] -``` - -```dockerfile -# Multiple images example -# -# VERSION 0.1 - -FROM ubuntu -RUN echo foo > bar -# Will output something like ===> 907ad6c2736f +For examples of Dockerfiles, refer to: -FROM ubuntu -RUN echo moo > oink -# Will output something like ===> 695d7793cbe4 - -# You'll now have two images, 907ad6c2736f with /bar, and 695d7793cbe4 with -# /oink. -``` +- The ["build images" section](https://docs.docker.com/develop/develop-images/dockerfile_best-practices/) +- The ["get started](https://docs.docker.com/get-started/) +- The [language-specific getting started guides](https://docs.docker.com/language/) diff --git a/docs/reference/commandline/attach.md b/docs/reference/commandline/attach.md index dcd8a91fa2ea..4418f7b054d3 100644 --- a/docs/reference/commandline/attach.md +++ b/docs/reference/commandline/attach.md @@ -84,7 +84,7 @@ containers, see [**Configuration file** section](cli.md#configuration-files). ### Attach to and detach from a running container -```bash +```console $ docker run -d --name topdemo ubuntu /usr/bin/top -b $ docker attach topdemo @@ -130,22 +130,19 @@ $ docker ps -a | grep topdemo 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: -```bash - $ docker run --name test -d -it debian +```console +$ docker run --name test -d -it debian +275c44472aebd77c926d4527885bb09f2f6db21d878c75f0a1c212c03d3bcfab - 275c44472aebd77c926d4527885bb09f2f6db21d878c75f0a1c212c03d3bcfab +$ docker attach test +root@f38c87f2a42d:/# exit 13 - $ docker attach test +exit - root@f38c87f2a42d:/# exit 13 - - exit - - $ echo $? - - 13 +$ echo $? +13 - $ docker ps -a | grep test +$ docker ps -a | grep test - 275c44472aeb debian:7 "/bin/bash" 26 seconds ago Exited (13) 17 seconds ago test +275c44472aeb debian:7 "/bin/bash" 26 seconds ago Exited (13) 17 seconds ago test ``` diff --git a/docs/reference/commandline/build.md b/docs/reference/commandline/build.md index c4c36a2b6a4c..1a45bba73b4e 100644 --- a/docs/reference/commandline/build.md +++ b/docs/reference/commandline/build.md @@ -92,7 +92,7 @@ context. For example, run this command to use a directory called `docker` in the branch `container`: -```bash +```console $ docker build https://github.com/docker/rootfs.git#container:docker ``` @@ -120,7 +120,7 @@ Build Syntax Suffix | Commit Used | Build Context Used If you pass an URL to a remote tarball, the URL itself is sent to the daemon: -```bash +```console $ docker build http://server/context.tar.gz ``` @@ -136,7 +136,7 @@ build context. Tarball contexts must be tar archives conforming to the standard 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`: -```bash +```console $ docker build - < Dockerfile ``` @@ -176,7 +176,7 @@ build fails, a non-zero failure code will be returned. There should be informational output of the reason for failure output to `STDERR`: -```bash +```console $ docker build -t fail . Sending build context to Docker daemon 2.048 kB @@ -198,7 +198,7 @@ See also: ### Build with PATH -```bash +```console $ docker build . Uploading context 10240 bytes @@ -243,7 +243,7 @@ you must use `--rm=false`. This does not affect the build cache. ### Build with URL -```bash +```console $ docker build github.com/creack/docker-firefox ``` @@ -251,7 +251,7 @@ 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. -```bash +```console $ docker build -f ctx/Dockerfile http://server/ctx.tar.gz Downloading context: http://server/ctx.tar.gz [===================>] 240 B/240 B @@ -277,7 +277,7 @@ ctx/container.cfg /` operation works as expected. ### Build with - -```bash +```console $ docker build - < Dockerfile ``` @@ -286,7 +286,7 @@ 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. -```bash +```console $ docker build - < context.tar.gz ``` @@ -295,7 +295,7 @@ formats are: bzip2, gzip and xz. ### Use a .dockerignore file -```bash +```console $ docker build . Uploading context 18.829 MB @@ -334,7 +334,7 @@ files. ### Tag an image (-t) -```bash +```console $ docker build -t vieux/apache:2.0 . ``` @@ -348,27 +348,27 @@ version. For example, to tag an image both as `whenry/fedora-jboss:latest` and `whenry/fedora-jboss:v2.1`, use the following: -```bash +```console $ docker build -t whenry/fedora-jboss:latest -t whenry/fedora-jboss:v2.1 . ``` ### Specify a Dockerfile (-f) -```bash +```console $ docker build -f Dockerfile.debug . ``` This will use a file called `Dockerfile.debug` for the build instructions instead of `Dockerfile`. -```bash +```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. -```bash +```console $ docker build -f dockerfiles/Dockerfile.debug -t myapp_debug . $ docker build -f dockerfiles/Dockerfile.prod -t myapp_prod . ``` @@ -377,7 +377,7 @@ 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. -```bash +```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 @@ -420,7 +420,7 @@ 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: -```bash +```console $ docker build --build-arg HTTP_PROXY=http://10.20.30.2:1234 --build-arg FTP_PROXY=http://40.50.60.5:4567 . ``` @@ -439,7 +439,7 @@ 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: -```bash +```console $ export HTTP_PROXY=http://10.20.30.2:1234 $ docker build --build-arg HTTP_PROXY . ``` @@ -491,7 +491,7 @@ FROM alpine AS production-env ... ``` -```bash +```console $ docker build -t mybuildimage --target build-env . ``` @@ -516,7 +516,7 @@ 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: -```bash +```console $ docker build -o out . ``` @@ -525,13 +525,13 @@ 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): -```bash +```console $ docker build --output type=local,dest=out . ``` Use the `tar` type to export the files as a `.tar` archive: -```bash +```console $ docker build --output type=tar,dest=out.tar . ``` @@ -540,8 +540,8 @@ case, `-` is specified as destination, which automatically selects the `tar` typ and writes the output tarball to standard output, which is then redirected to the `out.tar` file: -```bash -docker build -o - . > out.tar +```console +$ docker build -o - . > out.tar ``` The `--output` option exports all files from the target stage. A common pattern @@ -562,7 +562,7 @@ 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: -```bash +```console $ docker build -o out . [+] Building 2.3s (7/7) FINISHED @@ -610,7 +610,7 @@ 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: -```bash +```console $ docker build -t myname/myapp --build-arg BUILDKIT_INLINE_CACHE=1 . $ docker push myname/myapp ``` @@ -618,8 +618,9 @@ $ 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. -```bash -# on another machine +On another machine: + +```console $ docker build --cache-from myname/myapp . ``` @@ -666,7 +667,7 @@ The `--squash` option has a number of known limitations: 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 in tact, and one for the squashed version. + 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. @@ -725,7 +726,7 @@ To enable experimental features, you need to start the Docker daemon with Then make sure the experimental flag is enabled: -```bash +```console $ docker version -f '{{.Server.Experimental}}' true ``` @@ -745,15 +746,15 @@ RUN rm /remove_me An image named `test` is built with `--squash` argument. -```bash +```console $ docker build --squash -t test . -[...] +<...> ``` If everything is right, the history looks like this: -```bash +```console $ docker history test IMAGE CREATED CREATED BY SIZE COMMENT diff --git a/docs/reference/commandline/checkpoint.md b/docs/reference/commandline/checkpoint.md new file mode 100644 index 000000000000..56b0a5978b63 --- /dev/null +++ b/docs/reference/commandline/checkpoint.md @@ -0,0 +1,102 @@ +--- +title: docker checkpoint +description: "The checkpoint command description and usage" +keywords: experimental, checkpoint, restore, criu +experimental: true +--- + +## Description + +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/). + +### 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). + +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. + +### Use cases for checkpoint and restore + +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 + +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 + +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) + +Additionally, a `--checkpoint` flag is added to the `docker container start` command. + +The options for `docker checkpoint create`: + +```console +Usage: docker checkpoint create [OPTIONS] CONTAINER CHECKPOINT + +Create a checkpoint from a running container + + --leave-running=false Leave the container running after checkpoint + --checkpoint-dir Use a custom checkpoint storage directory +``` + +And to restore a container: + +```console +Usage: docker start --checkpoint CHECKPOINT_ID [OTHER OPTIONS] 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 + +$ docker checkpoint create cr checkpoint1 + +# +$ 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. + +### Known limitations + +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: + +```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 +``` diff --git a/docs/reference/commandline/cli.md b/docs/reference/commandline/cli.md index f82d2deb8836..9a7566547b3b 100644 --- a/docs/reference/commandline/cli.md +++ b/docs/reference/commandline/cli.md @@ -1,9 +1,9 @@ --- title: "Use the Docker command line" description: "Docker's CLI command description and usage" -keywords: "Docker, Docker documentation, CLI, command line" +keywords: "Docker, Docker documentation, CLI, command line, config.json, CLI configuration file" redirect_from: - - /go/experimental/ + - /reference/commandline/cli/ - /engine/reference/commandline/engine/ - /engine/reference/commandline/engine_activate/ - /engine/reference/commandline/engine_check/ @@ -24,7 +24,7 @@ redirect_from: To list available commands, either run `docker` with no parameters or execute `docker help`: -```bash +```console $ docker Usage: docker [OPTIONS] COMMAND [ARG...] docker [ --help | -v | --version ] @@ -62,30 +62,23 @@ the [installation](https://docs.docker.com/install/) instructions for your opera ## Environment variables -For easy reference, the following list of environment variables are supported -by the `docker` command line: - -* `DOCKER_API_VERSION` The API version to use (e.g. `1.19`) -* `DOCKER_CONFIG` The location of your client configuration files. -* `DOCKER_HOST` Daemon socket to connect to. -* `DOCKER_STACK_ORCHESTRATOR` Configure the default orchestrator to use when using `docker stack` management commands. -* `DOCKER_CONTENT_TRUST` When set Docker uses notary to sign and verify images. - Equates to `--disable-content-trust=false` for build, create, pull, push, run. -* `DOCKER_CONTENT_TRUST_SERVER` The URL of the Notary server to use. This defaults - to the same URL as the registry. -* `DOCKER_HIDE_LEGACY_COMMANDS` When set, Docker hides "legacy" top-level commands (such as `docker rm`, and - `docker pull`) in `docker help` output, and only `Management commands` per object-type (e.g., `docker container`) are - printed. This may become the default in a future release, at which point this environment-variable is removed. -* `DOCKER_CONTEXT` Specify the context to use (overrides DOCKER_HOST env var and default context set with "docker context use") -* `DOCKER_DEFAULT_PLATFORM` Specify the default platform for the commands that take the `--platform` flag. - -#### Shared Environment variables - -These environment variables can be used both with the `docker` command line and -`dockerd` command line: - -* `DOCKER_CERT_PATH` The location of your authentication keys. -* `DOCKER_TLS_VERIFY` When set Docker uses TLS and verifies the remote. +The following list of environment variables are supported by the `docker` command +line: + +| Variable | Description | +|:------------------------------|:--------------------------------------------------------------------------------------------------------------------------------------| +| `DOCKER_API_VERSION` | Override the negotiated API version to use for debugging (e.g. `1.19`) | +| `DOCKER_CERT_PATH` | Location of your authentication keys. This variable is used both by the `docker` CLI and the [`dockerd` daemon](dockerd.md) | +| `DOCKER_CONFIG` | The location of your client configuration files. | +| `DOCKER_CONTENT_TRUST_SERVER` | The URL of the Notary server to use. Defaults to the same URL as the registry. | +| `DOCKER_CONTENT_TRUST` | When set Docker uses notary to sign and verify images. Equates to `--disable-content-trust=false` for build, create, pull, push, run. | +| `DOCKER_CONTEXT` | Name of the `docker context` to use (overrides `DOCKER_HOST` env var and default context set with `docker context use`) | +| `DOCKER_DEFAULT_PLATFORM` | Default platform for commands that take the `--platform` flag. | +| `DOCKER_HIDE_LEGACY_COMMANDS` | When set, Docker hides "legacy" top-level commands (such as `docker rm`, and `docker pull`) in `docker help` output, and only `Management commands` per object-type (e.g., `docker container`) are printed. This may become the default in a future release, at which point this environment-variable is removed. | +| `DOCKER_HOST` | Daemon socket to connect to. | +| `DOCKER_STACK_ORCHESTRATOR` | Configure the default orchestrator to use when using `docker stack` management commands. | +| `DOCKER_TLS_VERIFY` | When set Docker uses TLS and verifies the remote. This variable is used both by the `docker` CLI and the [`dockerd` daemon](dockerd.md) | +| `BUILDKIT_PROGRESS` | Set type of progress output (`auto`, `plain`, `tty`) when [building](build.md) with [BuildKit backend](../builder.md#buildkit). Use plain to show container output (default `auto`). | Because Docker is developed using Go, you can also use any environment variables used by the Go runtime. In particular, you may find these useful: @@ -95,10 +88,10 @@ variables used by the Go runtime. In particular, you may find these useful: * `NO_PROXY` These Go environment variables are case-insensitive. See the -[Go specification](http://golang.org/pkg/net/http/) for details on these +[Go specification](https://golang.org/pkg/net/http/) for details on these variables. -### Configuration files +## Configuration files By default, the Docker command line stores its configuration files in a directory called `.docker` within your `$HOME` directory. @@ -124,7 +117,7 @@ specified, then the `--config` option overrides the `DOCKER_CONFIG` environment variable. The example below overrides the `docker ps` command using a `config.json` file located in the `~/testconfigs/` directory. -```bash +```console $ docker --config ~/testconfigs/ ps ``` @@ -133,79 +126,56 @@ configuration, you can set the `DOCKER_CONFIG` environment variable in your shell (e.g. `~/.profile` or `~/.bashrc`). The example below sets the new directory to be `HOME/newdir/.docker`. -```bash -echo export DOCKER_CONFIG=$HOME/newdir/.docker > ~/.profile +```console +$ echo export DOCKER_CONFIG=$HOME/newdir/.docker > ~/.profile ``` -### `config.json` properties +## Docker CLI configuration file (`config.json`) properties + + + +Use the Docker CLI configuration to customize settings for the `docker` CLI. The +configuration file uses JSON formatting, and properties: + +By default, configuration file is stored in `~/.docker/config.json`. Refer to the +[change the `.docker` directory](#change-the-docker-directory) section to use a +different location. -The `config.json` file stores a JSON encoding of several properties: +> **Warning** +> +> The configuration file and other files inside the `~/.docker` configuration +> directory may contain sensitive information, such as authentication information +> for proxies or, depending on your credential store, credentials for your image +> registries. Review your configuration file's content before sharing with others, +> and prevent committing the file to version control. + +### Customize the default output format for commands + +These fields allow you to customize the default output format for some commands +if no `--format` flag is provided. + +| Property | Description | +|:-----------------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `configFormat` | Custom default format for `docker config ls` output. Refer to the [**format the output** section in the `docker config ls` documentation](config_ls.md#format-the-output) for a list of supported formatting directives. | +| `imagesFormat` | Custom default format for `docker images` / `docker image ls` output. Refer to the [**format the output** section in the `docker images` documentation](images.md#format-the-output) for a list of supported formatting directives. | +| `nodesFormat` | Custom default format for `docker node ls` output. Refer to the [**formatting** section in the `docker node ls` documentation](node_ls.md#formatting) for a list of supported formatting directives. | +| `pluginsFormat` | Custom default format for `docker plugin ls` output. Refer to the [**formatting** section in the `docker plugin ls` documentation](plugin_ls.md#formatting) for a list of supported formatting directives. | +| `psFormat` | Custom default format for `docker ps` / `docker container ps` output. Refer to the [**formatting** section in the `docker ps` documentation](ps.md#formatting) for a list of supported formatting directives. | +| `secretFormat` | Custom default format for `docker secret ls` output. Refer to the [**format the output** section in the `docker secret ls` documentation](secret_ls.md#format-the-output) for a list of supported formatting directives. | +| `serviceInspectFormat` | Custom default format for `docker service inspect` output. Refer to the [**formatting** section in the `docker service inspect` documentation](service_inspect.md#formatting) for a list of supported formatting directives. | +| `servicesFormat` | Custom default format for `docker service ls` output. Refer to the [**formatting** section in the `docker service ls` documentation](service_ls.md#formatting) for a list of supported formatting directives. | +| `statsFormat` | Custom default format for `docker stats` output. Refer to the [**formatting** section in the `docker stats` documentation](stats.md#formatting) for a list of supported formatting directives. | + + +### Custom HTTP headers The property `HttpHeaders` specifies a set of headers to include in all messages sent from the Docker client to the daemon. Docker does not try to interpret or -understand these header; it simply puts them into the messages. Docker does +understand these headers; it simply puts them into the messages. Docker does not allow these headers to change any headers it sets for itself. -The property `psFormat` specifies the default format for `docker ps` output. -When the `--format` flag is not provided with the `docker ps` command, -Docker's client uses this property. If this property is not set, the client -falls back to the default table format. For a list of supported formatting -directives, see the -[**Formatting** section in the `docker ps` documentation](ps.md) - -The property `imagesFormat` specifies the default format for `docker images` output. -When the `--format` flag is not provided with the `docker images` command, -Docker's client uses this property. If this property is not set, the client -falls back to the default table format. For a list of supported formatting -directives, see the [**Formatting** section in the `docker images` documentation](images.md) - -The property `pluginsFormat` specifies the default format for `docker plugin ls` output. -When the `--format` flag is not provided with the `docker plugin ls` command, -Docker's client uses this property. If this property is not set, the client -falls back to the default table format. For a list of supported formatting -directives, see the [**Formatting** section in the `docker plugin ls` documentation](plugin_ls.md) - -The property `servicesFormat` specifies the default format for `docker -service ls` output. When the `--format` flag is not provided with the -`docker service ls` command, Docker's client uses this property. If this -property is not set, the client falls back to the default json format. For a -list of supported formatting directives, see the -[**Formatting** section in the `docker service ls` documentation](service_ls.md) - -The property `serviceInspectFormat` specifies the default format for `docker -service inspect` output. When the `--format` flag is not provided with the -`docker service inspect` command, Docker's client uses this property. If this -property is not set, the client falls back to the default json format. For a -list of supported formatting directives, see the -[**Formatting** section in the `docker service inspect` documentation](service_inspect.md) - -The property `statsFormat` specifies the default format for `docker -stats` output. When the `--format` flag is not provided with the -`docker stats` command, Docker's client uses this property. If this -property is not set, the client falls back to the default table -format. For a list of supported formatting directives, see -[**Formatting** section in the `docker stats` documentation](stats.md) - -The property `secretFormat` specifies the default format for `docker -secret ls` output. When the `--format` flag is not provided with the -`docker secret ls` command, Docker's client uses this property. If this -property is not set, the client falls back to the default table -format. For a list of supported formatting directives, see -[**Formatting** section in the `docker secret ls` documentation](secret_ls.md) - - -The property `nodesFormat` specifies the default format for `docker node ls` output. -When the `--format` flag is not provided with the `docker node ls` command, -Docker's client uses the value of `nodesFormat`. If the value of `nodesFormat` is not set, -the client uses the default table format. For a list of supported formatting -directives, see the [**Formatting** section in the `docker node ls` documentation](node_ls.md) - -The property `configFormat` specifies the default format for `docker -config ls` output. When the `--format` flag is not provided with the -`docker config ls` command, Docker's client uses this property. If this -property is not set, the client falls back to the default table -format. For a list of supported formatting directives, see -[**Formatting** section in the `docker config ls` documentation](config_ls.md) + +### Credential store options The property `credsStore` specifies an external binary to serve as the default credential store. When this property is set, `docker login` will attempt to @@ -221,11 +191,17 @@ credentials for specific registries. If this property is set, the binary for a specific registry. For more information, see the [**Credential helpers** section in the `docker login` documentation](login.md#credential-helpers) + +### Orchestrator options for docker stacks + The property `stackOrchestrator` specifies the default orchestrator to use when running `docker stack` management commands. Valid values are `"swarm"`, `"kubernetes"`, and `"all"`. This property can be overridden with the `DOCKER_STACK_ORCHESTRATOR` environment variable, or the `--orchestrator` flag. + +### Automatic proxy configuration for containers + The property `proxies` specifies proxy environment variables to be automatically set on containers, and set as `--build-arg` on containers used during `docker build`. A `"default"` set of proxies can be configured, and will be used for any docker @@ -233,15 +209,26 @@ daemon that the client connects to, or a configuration per host (docker daemon), for example, "https://docker-daemon1.example.com". The following properties can be set for each environment: -* `httpProxy` (sets the value of `HTTP_PROXY` and `http_proxy`) -* `httpsProxy` (sets the value of `HTTPS_PROXY` and `https_proxy`) -* `ftpProxy` (sets the value of `FTP_PROXY` and `ftp_proxy`) -* `noProxy` (sets the value of `NO_PROXY` and `no_proxy`) +| Property | Description | +|:---------------|:--------------------------------------------------------------------------------------------------------| +| `httpProxy` | Default value of `HTTP_PROXY` and `http_proxy` for containers, and as `--build-arg` on `docker build` | +| `httpsProxy` | Default value of `HTTPS_PROXY` and `https_proxy` for containers, and as `--build-arg` on `docker build` | +| `ftpProxy` | Default value of `FTP_PROXY` and `ftp_proxy` for containers, and as `--build-arg` on `docker build` | +| `noProxy` | Default value of `NO_PROXY` and `no_proxy` for containers, and as `--build-arg` on `docker build` | + +These settings are used to configure proxy settings for containers only, and not +used as proxy settings for the `docker` CLI or the `dockerd` daemon. Refer to the +[environment variables](#environment-variables) and [HTTP/HTTPS proxy](https://docs.docker.com/config/daemon/systemd/#httphttps-proxy) +sections for configuring proxy settings for the cli and daemon. -> **Warning**: Proxy settings may contain sensitive information (for example, -> if the proxy requires authentication). Environment variables are stored as -> plain text in the container's configuration, and as such can be inspected -> through the remote API or committed to an image when using `docker commit`. +> **Warning** +> +> Proxy settings may contain sensitive information (for example, if the proxy +> requires authentication). Environment variables are stored as plain text in +> the container's configuration, and as such can be inspected through the remote +> API or committed to an image when using `docker commit`. + +### Default key-sequence to detach from containers Once attached to a container, users detach from it and leave it running using the using `CTRL-p CTRL-q` key sequence. This detach key sequence is customizable @@ -261,11 +248,17 @@ Users can override your custom or the default key sequence on a per-container basis. To do this, the user specifies the `--detach-keys` flag with the `docker attach`, `docker exec`, `docker run` or `docker start` command. +### CLI Plugin options + The property `plugins` contains settings specific to CLI plugins. The key is the plugin name, while the value is a further map of options, which are specific to that plugin. -Following is a sample `config.json` file: + +### Sample configuration file + +Following is a sample `config.json` file to illustrate the format used for +various fields: ```json {% raw %} @@ -301,14 +294,14 @@ Following is a sample `config.json` file: "proxies": { "default": { "httpProxy": "http://user:pass@example.com:3128", - "httpsProxy": "http://user:pass@example.com:3128", - "noProxy": "http://user:pass@example.com:3128", + "httpsProxy": "https://my-proxy.example.com:3129", + "noProxy": "intra.mycorp.example.com", "ftpProxy": "http://user:pass@example.com:3128" }, "https://manager1.mycorp.example.com:2377": { "httpProxy": "http://user:pass@example.com:3128", - "httpsProxy": "http://user:pass@example.com:3128" - }, + "httpsProxy": "https://my-proxy.example.com:3129" + } } } {% endraw %} @@ -320,6 +313,9 @@ Experimental features provide early access to future product functionality. These features are intended for testing and feedback, and they may change between releases without warning or can be removed from a future release. +Starting with Docker 20.10, experimental CLI features are enabled by default, +and require no configuration to enable them. + ### Notary If using your own notary server and a self-signed certificate or an internal @@ -336,16 +332,18 @@ list of root Certificate Authorities. To list the help on any command just execute the command, followed by the `--help` option. - $ docker run --help +```console +$ docker run --help - Usage: docker run [OPTIONS] IMAGE [COMMAND] [ARG...] +Usage: docker run [OPTIONS] IMAGE [COMMAND] [ARG...] - Run a command in a new container +Run a command in a new container - Options: - --add-host value Add a custom host-to-IP mapping (host:ip) (default []) - -a, --attach value Attach to STDIN, STDOUT or STDERR (default []) - ... +Options: + --add-host value Add a custom host-to-IP mapping (host:ip) (default []) + -a, --attach value Attach to STDIN, STDOUT or STDERR (default []) +<...> +``` ### Option types @@ -366,7 +364,7 @@ container **will** run in "detached" mode, in the background. Options which default to `true` (e.g., `docker build --rm=true`) can only be set to the non-default value by explicitly setting them to `false`: -```bash +```console $ docker build --rm=false . ``` @@ -375,7 +373,7 @@ $ docker build --rm=false . You can specify options like `-a=[]` multiple times in a single command line, for example in these commands: -```bash +```console $ docker run -a stdin -a stdout -i -t ubuntu /bin/bash $ docker run -a stdin -a stdout -a stderr ubuntu /bin/ls @@ -384,7 +382,7 @@ $ docker run -a stdin -a stdout -a stderr ubuntu /bin/ls Sometimes, multiple options can call for a more complex value string as for `-v`: -```bash +```console $ docker run -v /host:/container example/mysql ``` diff --git a/docs/reference/commandline/commit.md b/docs/reference/commandline/commit.md index 4af081440b2d..9fb49c3b66f6 100644 --- a/docs/reference/commandline/commit.md +++ b/docs/reference/commandline/commit.md @@ -43,7 +43,7 @@ created. Supported `Dockerfile` instructions: ### Commit a container -```bash +```console $ docker ps CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES @@ -62,7 +62,7 @@ svendowideit/testimage version3 f5283438590d 16 sec ### Commit a container with new configurations -```bash +```console $ docker ps CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES @@ -84,7 +84,7 @@ $ docker inspect -f "{{ .Config.Env }}" f5283438590d ### Commit a container with new `CMD` and `EXPOSE` instructions -```bash +```console $ docker ps CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES diff --git a/docs/reference/commandline/config.md b/docs/reference/commandline/config.md new file mode 100644 index 000000000000..67329bd94075 --- /dev/null +++ b/docs/reference/commandline/config.md @@ -0,0 +1,35 @@ +--- +title: "config" +description: "The config command description and usage" +keywords: "config" +--- + +# config + +```markdown +Usage: docker config COMMAND + +Manage Docker configs + +Options: + --help Print usage + +Commands: + create Create a config from a file or STDIN + inspect Display detailed information on one or more configs + ls List configs + rm Remove one or more configs + +Run 'docker config COMMAND --help' for more information on a command. +``` + +## Description + +Manage configs. + +## Related commands + +* [config create](config_create.md) +* [config inspect](config_inspect.md) +* [config list](config_ls.md) +* [config rm](config_rm.md) diff --git a/docs/reference/commandline/config_create.md b/docs/reference/commandline/config_create.md new file mode 100644 index 000000000000..eca320a84fb9 --- /dev/null +++ b/docs/reference/commandline/config_create.md @@ -0,0 +1,99 @@ +--- +title: "config create" +description: "The config create command description and usage" +keywords: ["config, create"] +--- + +# config create + +```Markdown +Usage: docker config create [OPTIONS] CONFIG [file|-] + +Create a config from a file or STDIN as content + +Options: + -l, --label list Config labels + --template-driver string Template driver +``` + +## Description + +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/). + +> **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. + +## Examples + +### Create a config + +```console +$ printf | docker config create my_config - + +onakdyv307se2tl7nl20anokv + +$ docker config ls + +ID NAME CREATED UPDATED +onakdyv307se2tl7nl20anokv my_config 6 seconds ago 6 seconds ago +``` + +### Create a config with a file + +```console +$ docker config create my_config ./config.json + +dg426haahpi5ezmkkj5kyl3sn + +$ docker config ls + +ID NAME CREATED UPDATED +dg426haahpi5ezmkkj5kyl3sn my_config 7 seconds ago 7 seconds ago +``` + +### Create a config with labels + +```console +$ docker config create \ + --label env=dev \ + --label rev=20170324 \ + my_config ./config.json + +eo7jnzguqgtpdah3cm5srfb97 +``` + +```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" + } + } +] +``` + + +## Related commands + +* [config inspect](config_inspect.md) +* [config ls](config_ls.md) +* [config rm](config_rm.md) diff --git a/docs/reference/commandline/config_inspect.md b/docs/reference/commandline/config_inspect.md new file mode 100644 index 000000000000..a2cf767ec5a3 --- /dev/null +++ b/docs/reference/commandline/config_inspect.md @@ -0,0 +1,97 @@ +--- +title: "config inspect" +description: "The config inspect command description and usage" +keywords: ["config, inspect"] +--- + +# config inspect + +```Markdown +Usage: docker config inspect [OPTIONS] CONFIG [CONFIG...] + +Display detailed information on one or more configs + +Options: + -f, --format string Format the output using the given Go template + --help Print usage +``` + +## Description + +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. + +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/). + +> **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. + +## Examples + +### Inspect a config by name or ID + +You can inspect a config, either by its *name*, or *ID* + +For example, given the following config: + +```console +$ docker config ls + +ID NAME CREATED UPDATED +eo7jnzguqgtpdah3cm5srfb97 my_config 3 minutes ago 3 minutes ago +``` + +```console +$ docker config inspect config.json +``` + +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" + }, + "Data": "aGVsbG8K" + } + } +] +``` + +### Formatting + +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 + +2017-03-24 08:15:09.735271783 +0000 UTC +``` + + +## Related commands + +* [config create](config_create.md) +* [config ls](config_ls.md) +* [config rm](config_rm.md) diff --git a/docs/reference/commandline/config_ls.md b/docs/reference/commandline/config_ls.md new file mode 100644 index 000000000000..196203422c39 --- /dev/null +++ b/docs/reference/commandline/config_ls.md @@ -0,0 +1,155 @@ +--- +title: "config ls" +description: "The config ls command description and usage" +keywords: ["config, ls"] +--- + +# config ls + +```Markdown +Usage: docker config ls [OPTIONS] + +List configs + +Aliases: + ls, list + +Options: + -f, --filter filter Filter output based on conditions provided + --format string Pretty-print configs using a Go template + --help Print usage + -q, --quiet Only display IDs +``` + +## Description + +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/). + +> **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. + +## Examples + +```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 +``` + +### Filtering + +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: + +- [id](#id) (config's ID) +- [label](#label) (`label=` or `label==`) +- [name](#name) (config's name) + +#### id + +The `id` filter matches all or prefix of a config's id. + +```console +$ docker config ls -f "id=6697bflskwj1998km1gnnjr38" + +ID NAME CREATED UPDATED +6697bflskwj1998km1gnnjr38 q5s5570vtvnimefos1fyeo2u2 6 weeks ago 6 weeks ago +``` + +#### label + +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: + +```console +$ docker config ls --filter label=project + +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. + +```console +$ docker service ls --filter label=project=test + +ID NAME CREATED UPDATED +mem02h8n73mybpgqjf0kfi1n0 test_config About an hour ago About an hour ago +``` + +#### 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`. + +```console +$ docker config ls --filter name=test_config + +ID NAME CREATED UPDATED +mem02h8n73mybpgqjf0kfi1n0 test_config About an hour ago About an hour ago +``` + +### Format the output + +The formatting option (`--format`) pretty prints configs output +using a Go template. + +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"}}` | + +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: + +```console +$ docker config ls --format "{{.ID}}: {{.Name}}" + +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: + +```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 +``` + +## Related commands + +* [config create](config_create.md) +* [config inspect](config_inspect.md) +* [config rm](config_rm.md) diff --git a/docs/reference/commandline/config_rm.md b/docs/reference/commandline/config_rm.md new file mode 100644 index 000000000000..03b7413ce139 --- /dev/null +++ b/docs/reference/commandline/config_rm.md @@ -0,0 +1,53 @@ +--- +title: "config rm" +description: "The config rm command description and usage" +keywords: ["config, rm"] +--- + +# config rm + +```Markdown +Usage: docker config rm CONFIG [CONFIG...] + +Remove one or more configs + +Aliases: + rm, remove + +Options: + --help Print usage +``` + +## Description + +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/). + +> **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. + +## Examples + +This example removes a config: + +```console +$ docker config rm my_config +sapth4csdo5b6wz2p5uimh5xg +``` + +> **Warning** +> +> Unlike `docker rm`, this command does not ask for confirmation before removing +> a config. + + +## Related commands + +* [config create](config_create.md) +* [config inspect](config_inspect.md) +* [config ls](config_ls.md) diff --git a/docs/reference/commandline/container_prune.md b/docs/reference/commandline/container_prune.md index 9426939ee94a..c1101e25ce8e 100644 --- a/docs/reference/commandline/container_prune.md +++ b/docs/reference/commandline/container_prune.md @@ -26,7 +26,7 @@ Removes all stopped containers. ### Prune containers -```bash +```console $ docker container prune WARNING! This will remove all stopped containers. Are you sure you want to continue? [y/N] y @@ -66,7 +66,7 @@ containers without the specified labels. The following removes containers created more than 5 minutes ago: -```bash +```console $ docker ps -a --format 'table {{.ID}}\t{{.Image}}\t{{.Command}}\t{{.CreatedAt}}\t{{.Status}}' CONTAINER ID IMAGE COMMAND CREATED AT STATUS @@ -88,7 +88,7 @@ CONTAINER ID IMAGE COMMAND CREATED AT The following removes containers created before `2017-01-04T13:10:00`: -```bash +```console $ docker ps -a --format 'table {{.ID}}\t{{.Image}}\t{{.Command}}\t{{.CreatedAt}}\t{{.Status}}' CONTAINER ID IMAGE COMMAND CREATED AT STATUS diff --git a/docs/reference/commandline/context_create.md b/docs/reference/commandline/context_create.md index ac5fb7550070..c6e2d4303347 100644 --- a/docs/reference/commandline/context_create.md +++ b/docs/reference/commandline/context_create.md @@ -62,7 +62,7 @@ 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`: -```bash +```console $ docker context create \ --docker host=unix:///var/run/docker.sock \ --kubernetes config-file=/home/me/my-kube-config \ @@ -75,19 +75,19 @@ 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`: -```bash +```console $ docker context create --from existing-context my-context ``` If the `--from` option is not set, the `context` is created from the current context: -```bash +```console $ docker context create my-context ``` This can be used to create a context out of an existing `DOCKER_HOST` based script: -```bash +```console $ source my-setup-script.sh $ docker context create my-context ``` @@ -98,7 +98,7 @@ 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`: -```bash +```console $ docker context create \ --docker from=existing-context \ --kubernetes config-file=/home/me/my-kube-config \ @@ -110,7 +110,7 @@ To source only the `kubernetes` configuration from an existing context use the context named `my-context` using the kuberentes configuration from the existing context `existing-context` and a docker endpoint of `/var/run/docker.sock`: -```bash +```console $ docker context create \ --docker host=unix:///var/run/docker.sock \ --kubernetes from=existing-context \ diff --git a/docs/reference/commandline/context_inspect.md b/docs/reference/commandline/context_inspect.md index 562259651619..10e3bd8a7c63 100644 --- a/docs/reference/commandline/context_inspect.md +++ b/docs/reference/commandline/context_inspect.md @@ -23,7 +23,7 @@ Inspects one or more contexts. ### Inspect a context by name -```bash +```console $ docker context inspect "local+aks" [ diff --git a/docs/reference/commandline/context_ls.md b/docs/reference/commandline/context_ls.md index 181940e27221..5d0a3c875485 100644 --- a/docs/reference/commandline/context_ls.md +++ b/docs/reference/commandline/context_ls.md @@ -25,7 +25,9 @@ Options: Use `docker context ls` to print all contexts. The currently active context is indicated with an `*`: -```bash +```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 diff --git a/docs/reference/commandline/context_update.md b/docs/reference/commandline/context_update.md index 959a42e49ab6..8b1721df6437 100644 --- a/docs/reference/commandline/context_update.md +++ b/docs/reference/commandline/context_update.md @@ -54,7 +54,7 @@ See [context create](context_create.md). ### Update an existing context -```bash +```console $ docker context update \ --description "some description" \ --docker "host=tcp://myserver:2376,ca=~/ca-file,cert=~/cert-file,key=~/key-file" \ diff --git a/docs/reference/commandline/cp.md b/docs/reference/commandline/cp.md index 839ce0022f3f..397d6eadc23a 100644 --- a/docs/reference/commandline/cp.md +++ b/docs/reference/commandline/cp.md @@ -95,11 +95,11 @@ 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): -```bash +```console $ docker exec CONTAINER tar Ccf $(dirname SRC_PATH) - $(basename SRC_PATH) | tar Cxf DEST_PATH - ``` -```bash +```console $ tar Ccf $(dirname SRC_PATH) - $(basename SRC_PATH) | docker exec -i CONTAINER tar Cxf DEST_PATH - ``` diff --git a/docs/reference/commandline/create.md b/docs/reference/commandline/create.md index 0c9a96ee26d1..d24caf7b721c 100644 --- a/docs/reference/commandline/create.md +++ b/docs/reference/commandline/create.md @@ -109,7 +109,7 @@ Options: Unit is optional and can be `b` (bytes), `k` (kilobytes), `m` (megabytes), or `g` (gigabytes). If you omit the unit, the system uses bytes. --stop-signal string Signal to stop a container (default "SIGTERM") - --stop-timeout=10 Timeout (in seconds) to stop a container + --stop-timeout int Timeout (in seconds) to stop a container --storage-opt value Storage driver options for the container (default []) --sysctl value Sysctl options (default map[]) --tmpfs value Mount a tmpfs directory (default []) @@ -131,6 +131,7 @@ Options: --volumes-from value Mount volumes from the specified container(s) (default []) -w, --workdir string Working directory inside the container ``` + ## Description The `docker create` command creates a writeable container layer over the @@ -149,7 +150,7 @@ Please see the [run command](run.md) section and the [Docker run reference](../r ### Create and start a container -```bash +```console $ docker create -t -i fedora bash 6d8af538ec541dd581ebc2a24153a28329acb5268abe5ef868c1f1a261221752 @@ -165,7 +166,7 @@ As of v1.4.0 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: -```bash +```console $ docker create -v /data --name data ubuntu 240633dfbb98128fa77473d3d9018f6123b99c454b3251427ae190a7d951ad57 @@ -180,7 +181,7 @@ 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: -```bash +```console $ docker create -v /home/docker:/docker --name docker ubuntu 9aa88c08f319cd1e4515c3c46b0de7cc9aa75e878357b1e96f91e2c773029f03 @@ -202,7 +203,7 @@ drwxr-xr-x 32 1000 staff 1140 Dec 5 04:01 docker Set storage driver options per container. -```bash +```console $ docker create -it --storage-opt size=120G fedora /bin/bash ``` @@ -223,12 +224,11 @@ 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 if the -daemon is running on Windows server, or `hyperv` if running on Windows client. | -| `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 if the daemon is running on Windows server, or `hyperv` if running on Windows client. | +| `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"`. @@ -239,14 +239,14 @@ 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 solution is to add a more permissive rule to a 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: -``` -docker create --device-cgroup-rule='c 42:* rmw' -name my-container my-image +```console +$ docker create --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 ` diff --git a/docs/reference/commandline/diff.md b/docs/reference/commandline/diff.md index 51eab8d440fc..cc9c1c41333d 100644 --- a/docs/reference/commandline/diff.md +++ b/docs/reference/commandline/diff.md @@ -33,7 +33,7 @@ You can use the full or shortened container ID or the container name set using Inspect the changes to an `nginx` container: -```bash +```console $ docker diff 1fdfd1f54c1b C /dev diff --git a/docs/reference/commandline/dockerd.md b/docs/reference/commandline/dockerd.md index a482577fb776..c016da6081e7 100644 --- a/docs/reference/commandline/dockerd.md +++ b/docs/reference/commandline/dockerd.md @@ -115,8 +115,8 @@ Options with [] may be specified multiple times. uses different binaries for the daemon and client. To run the daemon you type `dockerd`. -To run the daemon with debug output, use `dockerd -D` or add `"debug": true` to -the `daemon.json` file. +To run the daemon with debug output, use `dockerd --debug` or add `"debug": true` +to [the `daemon.json` file](#daemon-configuration-file). > **Enabling experimental features** > @@ -164,7 +164,7 @@ communication with the daemon. > supported anymore for security reasons. On Systemd based systems, you can communicate with the daemon via -[Systemd socket activation](http://0pointer.de/blog/projects/socket-activation.html), +[Systemd socket activation](https://0pointer.de/blog/projects/socket-activation.html), use `dockerd -H fd://`. Using `fd://` will work perfectly for most setups but you can also specify individual sockets: `dockerd -H fd://3`. If the specified socket activated files aren't found, then Docker will exit. You can @@ -174,20 +174,21 @@ find examples of using Systemd socket activation with Docker and Systemd in the You can configure the Docker daemon to listen to multiple sockets at the same time using multiple `-H` options: -```bash -# listen using the default unix socket, and on 2 specific IP addresses on this host. +The example below runs the daemon listenin on the default unix socket, and +on 2 specific IP addresses on this host: +```console $ sudo dockerd -H unix:///var/run/docker.sock -H tcp://192.168.59.106 -H tcp://10.10.10.2 ``` The Docker client will honor the `DOCKER_HOST` environment variable to set the `-H` flag for the client. Use **one** of the following commands: -```bash +```console $ docker -H tcp://0.0.0.0:2375 ps ``` -```bash +```console $ export DOCKER_HOST="tcp://0.0.0.0:2375" $ docker ps @@ -197,7 +198,7 @@ Setting the `DOCKER_TLS_VERIFY` environment variable to any value other than the empty string is equivalent to setting the `--tlsverify` flag. The following are equivalent: -```bash +```console $ docker --tlsverify ps # or $ export DOCKER_TLS_VERIFY=1 @@ -210,7 +211,7 @@ precedence over `HTTP_PROXY`. The Docker client supports connecting to a remote daemon via SSH: -``` +```console $ docker -H ssh://me@example.com:22 ps $ docker -H ssh://me@example.com ps $ docker -H ssh://example.com ps @@ -267,22 +268,21 @@ when no `-H` was passed in. Run Docker in daemon mode: -```bash +```console $ sudo /dockerd -H 0.0.0.0:5555 & ``` Download an `ubuntu` image: -```bash +```console $ docker -H :5555 pull ubuntu ``` You can use multiple `-H`, for example, if you want to listen on both TCP and a Unix socket -```bash -# Run docker in daemon mode -$ sudo /dockerd -H tcp://127.0.0.1:2375 -H unix:///var/run/docker.sock & +```console +$ sudo dockerd -H tcp://127.0.0.1:2375 -H unix:///var/run/docker.sock & # Download an ubuntu image, use default Unix socket $ docker pull ubuntu # OR use the TCP port @@ -307,12 +307,12 @@ devices, one for data and one for metadata. By default, these block devices are created automatically by using loopback mounts of automatically created sparse files. Refer to [Devicemapper options](#devicemapper-options) below for a way how to customize this setup. -[~jpetazzo/Resizing Docker containers with the Device Mapper plugin](http://jpetazzo.github.io/2014/01/29/docker-device-mapper-resize/) +[~jpetazzo/Resizing Docker containers with the Device Mapper plugin](https://jpetazzo.github.io/2014/01/29/docker-device-mapper-resize/) article explains how to tune your existing setup without the use of options. The `btrfs` driver is very fast for `docker build` - but like `devicemapper` does not share executable memory between devices. Use -`dockerd -s btrfs -g /mnt/btrfs_partition`. +`dockerd --storage-driver btrfs --data-root /mnt/btrfs_partition`. The `zfs` driver is probably not as fast as `btrfs` but has a longer track record on stability. Thanks to `Single Copy ARC` shared blocks between clones will be @@ -395,7 +395,7 @@ not use loopback in production. Ensure your Engine daemon has a ###### Example: -```bash +```console $ sudo dockerd --storage-opt dm.thinpooldev=/dev/mapper/thin-pool ``` @@ -406,7 +406,7 @@ device for you. ###### Example: -```bash +```console $ sudo dockerd --storage-opt dm.directlvm_device=/dev/xvdf ``` @@ -416,7 +416,7 @@ Sets the percentage of passed in block device to use for storage. ###### Example: -```bash +```console $ sudo dockerd --storage-opt dm.thinp_percent=95 ``` @@ -426,7 +426,7 @@ Sets the percentage of the passed in block device to use for metadata storage. ###### Example: -```bash +```console $ sudo dockerd --storage-opt dm.thinp_metapercent=1 ``` @@ -437,7 +437,7 @@ autoextend the available space [100 = disabled] ###### Example: -```bash +```console $ sudo dockerd --storage-opt dm.thinp_autoextend_threshold=80 ``` @@ -448,7 +448,7 @@ attempts to autoextend the available space [100 = disabled] ###### Example: -```bash +```console $ sudo dockerd --storage-opt dm.thinp_autoextend_percent=20 ``` @@ -467,7 +467,7 @@ new base device size. ###### Examples -```bash +```console $ sudo dockerd --storage-opt dm.basesize=50G ``` @@ -479,7 +479,7 @@ This value affects the system-wide "base" empty filesystem that may already be initialized and inherited by pulled images. Typically, a change to this value requires additional steps to take effect: - ```bash +```console $ sudo service docker stop $ sudo rm -rf /var/lib/docker @@ -502,7 +502,7 @@ much space. ###### Example -```bash +```console $ sudo dockerd --storage-opt dm.loopdatasize=200G ``` @@ -520,7 +520,7 @@ this much space. ###### Example -```bash +```console $ sudo dockerd --storage-opt dm.loopmetadatasize=4G ``` @@ -531,7 +531,7 @@ options are "ext4" and "xfs". The default is "xfs" ###### Example -```bash +```console $ sudo dockerd --storage-opt dm.fs=ext4 ``` @@ -541,7 +541,7 @@ Specifies extra mkfs arguments to be used when creating the base device. ###### Example -```bash +```console $ sudo dockerd --storage-opt "dm.mkfsarg=-O ^has_journal" ``` @@ -551,7 +551,7 @@ Specifies extra mount options used when mounting the thin devices. ###### Example -```bash +```console $ sudo dockerd --storage-opt dm.mountopt=nodiscard ``` @@ -567,7 +567,7 @@ device. ###### Example -```bash +```console $ sudo dockerd \ --storage-opt dm.datadev=/dev/sdb1 \ --storage-opt dm.metadatadev=/dev/sdc1 @@ -585,13 +585,13 @@ data, or even better on an SSD. If setting up a new metadata pool it is required to be valid. This can be achieved by zeroing the first 4k to indicate empty metadata, like this: -```bash +```console $ dd if=/dev/zero of=$metadata_dev bs=4096 count=1 ``` ###### Example -```bash +```console $ sudo dockerd \ --storage-opt dm.datadev=/dev/sdb1 \ --storage-opt dm.metadatadev=/dev/sdc1 @@ -604,7 +604,7 @@ blocksize is 64K. ###### Example -```bash +```console $ sudo dockerd --storage-opt dm.blocksize=512K ``` @@ -620,7 +620,7 @@ returned to the system for other use when containers are removed. ###### Examples -```bash +```console $ sudo dockerd --storage-opt dm.blkdiscard=false ``` @@ -632,11 +632,11 @@ Overrides the `udev` synchronization checks between `devicemapper` and `udev`. To view the `udev` sync support of a Docker daemon that is using the `devicemapper` driver, run: -```bash +```console $ docker info -[...] +<...> Udev Sync Supported: true -[...] +<...> ``` When `udev` sync support is `true`, then `devicemapper` and udev can @@ -650,7 +650,7 @@ results in errors and failures. (For information on these failures, see To allow the `docker` daemon to start, regardless of `udev` sync not being supported, set `dm.override_udev_sync_check` to true: -```bash +```console $ sudo dockerd --storage-opt dm.override_udev_sync_check=true ``` @@ -683,7 +683,7 @@ loop trying to remove a busy device. ###### Example -```bash +```console $ sudo dockerd --storage-opt dm.use_deferred_removal=true ``` @@ -701,7 +701,7 @@ Error deleting container: Error response from daemon: Cannot destroy container To avoid this failure, enable both deferred device deletion and deferred device removal on the daemon. -```bash +```console $ sudo dockerd \ --storage-opt dm.use_deferred_deletion=true \ --storage-opt dm.use_deferred_removal=true @@ -741,7 +741,7 @@ the issue. ###### Example -```bash +```console $ sudo dockerd --storage-opt dm.min_free_space=10% ``` @@ -757,7 +757,7 @@ ENOSPC and will shutdown filesystem. ###### Example -```bash +```console $ sudo dockerd --storage-opt dm.xfs_nospace_max_retries=0 ``` @@ -783,7 +783,7 @@ their corresponding levels when output by `dockerd`. ###### Example -```bash +```console $ sudo dockerd \ --log-level debug \ --storage-opt dm.libdm_log_level=7 @@ -799,7 +799,7 @@ By default docker will pick up the zfs filesystem where docker graph ###### Example -```bash +```console $ sudo dockerd -s zfs --storage-opt zfs.fsname=zroot/docker ``` @@ -814,7 +814,7 @@ a container with **--storage-opt size** option, docker should ensure the ###### Example -```bash +```console $ sudo dockerd -s btrfs --storage-opt btrfs.min_space=10G ``` @@ -837,7 +837,7 @@ conditions the user can pass any size less then the backing fs size. ###### Example -```bash +```console $ sudo dockerd -s overlay2 --storage-opt overlay2.size=1G ``` @@ -959,7 +959,7 @@ By default, the Docker daemon automatically starts `containerd`. If you want to control `containerd` startup, manually start `containerd` and pass the path to the `containerd` socket using the `--containerd` flag. For example: -```bash +```console $ sudo dockerd --containerd /var/run/dev/docker-containerd.sock ``` @@ -987,7 +987,7 @@ The following is an example adding 2 runtimes via the configuration: This is the same example via the command line: -```bash +```console $ sudo dockerd --add-runtime runc=runc --add-runtime custom=/usr/local/bin/my-runc-replacement ``` @@ -1009,7 +1009,7 @@ is used on cgroup v2 hosts with systemd available. This example sets the `cgroupdriver` to `systemd`: -```bash +```console $ sudo dockerd --exec-opt native.cgroupdriver=systemd ``` @@ -1030,13 +1030,13 @@ value is specified on daemon start, on Windows client, the default is To set the DNS server for all Docker containers, use: -```bash +```console $ sudo dockerd --dns 8.8.8.8 ``` To set the DNS search domain for all Docker containers, use: -```bash +```console $ sudo dockerd --dns-search example.com ``` @@ -1162,7 +1162,7 @@ TLS. To configure the client TLS settings used by the daemon can be configured using the `--cluster-store-opt` flag, specifying the paths to PEM encoded files. For example: -```bash +```console $ sudo dockerd \ --cluster-advertise 192.168.1.2:2376 \ --cluster-store etcd://192.168.1.2:2379 \ @@ -1189,7 +1189,7 @@ organization can purchase or build themselves. You can install one or more authorization plugins when you start the Docker `daemon` using the `--authorization-plugin=PLUGIN_ID` option. -```bash +```console $ sudo dockerd --authorization-plugin=plugin1 --authorization-plugin=plugin2,... ``` @@ -1203,14 +1203,14 @@ command line or Docker's Engine API are allowed or denied by the plugin. If you have multiple plugins installed, each plugin, in order, must allow the request for it to complete. -For information about how to create an authorization plugin, see [authorization -plugin](../../extend/plugins_authorization.md) section in the Docker extend section of this documentation. +For information about how to create an authorization plugin, refer to the +[authorization plugin](../../extend/plugins_authorization.md) section. ### Daemon user namespace options The Linux kernel -[user namespace support](http://man7.org/linux/man-pages/man7/user_namespaces.7.html) +[user namespace support](https://man7.org/linux/man-pages/man7/user_namespaces.7.html) provides additional security by enabling a process, and therefore a container, to have a unique range of user and group IDs which are outside the traditional user and group range utilized by the host system. Potentially the most important @@ -1232,10 +1232,16 @@ Docker supports softlinks for the Docker data directory (`/var/lib/docker`) and for `/var/lib/docker/tmp`. The `DOCKER_TMPDIR` and the data directory can be set like this: - DOCKER_TMPDIR=/mnt/disk2/tmp /usr/local/bin/dockerd -D -g /var/lib/docker -H unix:// > /var/lib/docker-machine/docker.log 2>&1 - # or - export DOCKER_TMPDIR=/mnt/disk2/tmp - /usr/local/bin/dockerd -D -g /var/lib/docker -H unix:// > /var/lib/docker-machine/docker.log 2>&1 +```console +$ DOCKER_TMPDIR=/mnt/disk2/tmp /usr/local/bin/dockerd --data-root /var/lib/docker -H unix:// > /var/lib/docker-machine/docker.log 2>&1 +``` + +or + +```console +$ export DOCKER_TMPDIR=/mnt/disk2/tmp +$ /usr/local/bin/dockerd --data-root /var/lib/docker -H unix:// > /var/lib/docker-machine/docker.log 2>&1 +```` #### Default cgroup parent @@ -1354,11 +1360,11 @@ This is a full example of the allowed configuration options on Linux: "debug": true, "default-address-pools": [ { - "base": "172.80.0.0/16", + "base": "172.30.0.0/16", "size": 24 }, { - "base": "172.90.0.0/16", + "base": "172.31.0.0/16", "size": 24 } ], @@ -1400,6 +1406,10 @@ This is a full example of the allowed configuration options on Linux: "log-driver": "json-file", "log-level": "", "log-opts": { + "cache-disabled": "false", + "cache-max-file": "5", + "cache-max-size": "20m", + "cache-compress": "true", "env": "os,customer", "labels": "somelabel", "max-file": "5", @@ -1544,7 +1554,7 @@ The list of currently supported options that can be reconfigured is this: be used to run containers. - `authorization-plugin`: it specifies the authorization plugins to use. - `allow-nondistributable-artifacts`: Replaces the set of registries to which the daemon will push nondistributable artifacts with a new set of registries. -- `insecure-registries`: it replaces the daemon insecure registries with a new set of insecure registries. If some existing insecure registries in daemon's configuration are not in newly reloaded insecure resgitries, these existing ones will be removed from daemon's config. +- `insecure-registries`: it replaces the daemon insecure registries with a new set of insecure registries. If some existing insecure registries in daemon's configuration are not in newly reloaded insecure registries, these existing ones will be removed from daemon's config. - `registry-mirrors`: it replaces the daemon registry mirrors with a new set of registry mirrors. If some existing registry mirrors in daemon's configuration are not in newly reloaded registry mirrors, these existing ones will be removed from daemon's config. - `shutdown-timeout`: it replaces the daemon's existing configuration timeout with a new timeout for shutting down all containers. - `features`: it explicitly enables or disables specific features. @@ -1560,7 +1570,9 @@ previously configured cluster configurations. ### Run multiple daemons -> **Note:** Running multiple daemons on a single host is considered as "experimental". The user should be aware of +> **Note:** +> +> Running multiple daemons on a single host is considered as "experimental". The user should be aware of > unsolved problems. This solution may not work properly in some cases. Solutions are currently under development > and will be delivered in the near future. @@ -1612,7 +1624,7 @@ The `--tls*` options enable use of specific certificates for individual daemons. Example script for a separate “bootstrap” instance of the Docker daemon without network: -```bash +```console $ sudo dockerd \ -H unix:///var/run/docker-bootstrap.sock \ -p /var/run/docker-bootstrap.pid \ diff --git a/docs/reference/commandline/events.md b/docs/reference/commandline/events.md index d4ccec316314..5f88ba72307d 100644 --- a/docs/reference/commandline/events.md +++ b/docs/reference/commandline/events.md @@ -194,11 +194,11 @@ The currently supported filters are: If a format (`--format`) is specified, the given template will be executed instead of the default -format. Go's [text/template](http://golang.org/pkg/text/template/) package +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 http://jsonlines.org/. +Lines. For information about JSON Lines, please refer to https://jsonlines.org/. ## Examples @@ -208,13 +208,13 @@ You'll need two shells for this example. **Shell 1: Listening for events:** -```bash +```console $ docker events ``` **Shell 2: Start and Stop containers:** -```bash +```console $ docker create --name test alpine:latest top $ docker start test $ docker stop test @@ -239,7 +239,7 @@ To exit the `docker events` command, use `CTRL+C`. You can filter the output by an absolute timestamp or relative time on the host machine, using the following different time syntaxes: -```bash +```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) @@ -292,7 +292,7 @@ $ docker events --since '2017-01-05T00:35:30' --until '2017-01-05T00:36:05' The following commands show several different ways to filter the `docker event` output. -```bash +```console $ docker events --filter 'event=stop' 2017-01-05T00:40:22.880175420+08:00 container stop 0fdb...ff37 (image=alpine:latest, name=test) @@ -388,7 +388,7 @@ $ docker events --filter 'scope=swarm' ### Format the output -```bash +```console $ docker events --filter 'type=container' --format 'Type={{.Type}} Status={{.Status}} ID={{.ID}}' Type=container Status=create ID=2ee349dac409e97974ce8d01b70d250b85e0ba8189299c126a87812311951e26 @@ -401,7 +401,7 @@ Type=container Status=destroy ID=2ee349dac409e97974ce8d01b70d250b85e0ba8189299 #### Format as JSON -```bash +```console $ docker events --format '{{json .}}' {"status":"create","id":"196016a57679bf42424484918746a9474cd905dd993c4d0f4.. diff --git a/docs/reference/commandline/exec.md b/docs/reference/commandline/exec.md index adfc6f7ea607..15a2eb5809b1 100644 --- a/docs/reference/commandline/exec.md +++ b/docs/reference/commandline/exec.md @@ -46,7 +46,7 @@ not work, but `docker exec -ti my_container sh -c "echo a && echo b"` will. First, start a container. -```bash +```console $ docker run --name ubuntu_bash --rm -i -t ubuntu bash ``` @@ -54,7 +54,7 @@ This will create a container named `ubuntu_bash` and start a Bash session. Next, execute a command on the container. -```bash +```console $ docker exec -d ubuntu_bash touch /tmp/execWorks ``` @@ -63,7 +63,7 @@ This will create a new file `/tmp/execWorks` inside the running container Next, execute an interactive `bash` shell on the container. -```bash +```console $ docker exec -it ubuntu_bash bash ``` @@ -71,7 +71,7 @@ This will create a new Bash session in the container `ubuntu_bash`. Next, set an environment variable in the current bash session. -```bash +```console $ docker exec -it -e VAR=1 ubuntu_bash bash ``` @@ -81,14 +81,14 @@ on the current Bash session. By default `docker exec` command runs in the same working directory set when container was created. -```bash +```console $ docker exec -it ubuntu_bash pwd / ``` You can select working directory for the command to execute into -```bash +```console $ docker exec -it -w /root ubuntu_bash pwd /root ``` @@ -98,7 +98,7 @@ $ docker exec -it -w /root ubuntu_bash pwd If the container is paused, then the `docker exec` command will fail with an error: -```bash +```console $ docker pause test test diff --git a/docs/reference/commandline/export.md b/docs/reference/commandline/export.md index 7f85fd27b4db..1eac5391619c 100644 --- a/docs/reference/commandline/export.md +++ b/docs/reference/commandline/export.md @@ -30,10 +30,10 @@ in the user guide for examples on exporting data in a volume. Each of these commands has the same result. -```bash +```console $ docker export red_panda > latest.tar ``` -```bash +```console $ docker export --output="latest.tar" red_panda ``` diff --git a/docs/reference/commandline/history.md b/docs/reference/commandline/history.md index c6cfdd1f7ba2..bbff26df3b85 100644 --- a/docs/reference/commandline/history.md +++ b/docs/reference/commandline/history.md @@ -24,7 +24,7 @@ Options: To see how the `docker:latest` image was built: -```bash +```console $ docker history docker IMAGE CREATED CREATED BY SIZE COMMENT @@ -38,7 +38,7 @@ be51b77efb42 8 days ago /bin/sh -c apt-get update && apt-get ins To see how the `docker:apache` image was added to a container's base image: -```bash +```console $ docker history docker:scm IMAGE CREATED CREATED BY SIZE COMMENT 2ac9d1098bf1 3 months ago /bin/bash 241.4 MB Added Apache to Fedora base image @@ -71,7 +71,7 @@ The following example uses a template without headers and outputs the `ID` and `CreatedSince` entries separated by a colon (`:`) for the `busybox` image: -```bash +```console $ docker history --format "{{.ID}}: {{.CreatedSince}}" busybox f6e427c148a7: 4 weeks ago diff --git a/docs/reference/commandline/image_prune.md b/docs/reference/commandline/image_prune.md index ac750517912c..7b3f968488db 100644 --- a/docs/reference/commandline/image_prune.md +++ b/docs/reference/commandline/image_prune.md @@ -26,7 +26,7 @@ Remove all dangling images. If `-a` is specified, will also remove all images no Example output: -```bash +```console $ docker image prune -a WARNING! This will remove all images without at least one container associated to them. @@ -101,7 +101,7 @@ images without the specified labels. The following removes images created before `2017-01-04T00:00:00`: -```bash +```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 @@ -128,7 +128,7 @@ foo latest 2f287ac753da 2017-01-04 13:42:23 The following removes images created more than 10 days (`240h`) ago: -```bash +```console $ docker images REPOSITORY TAG IMAGE ID CREATED SIZE @@ -168,25 +168,25 @@ busybox latest e02e811dd08f 2 months ago The following example removes images with the label `deprecated`: -```bash +```console $ docker image prune --filter="label=deprecated" ``` The following example removes images with the label `maintainer` set to `john`: -```bash +```console $ docker image prune --filter="label=maintainer=john" ``` This example removes images which have no `maintainer` label: -```bash +```console $ docker image prune --filter="label!=maintainer" ``` This example removes images which have a maintainer label not set to `john`: -```bash +```console $ docker image prune --filter="label!=maintainer=john" ``` diff --git a/docs/reference/commandline/images.md b/docs/reference/commandline/images.md index e64fd32dc186..5577de44beae 100644 --- a/docs/reference/commandline/images.md +++ b/docs/reference/commandline/images.md @@ -48,7 +48,7 @@ uses up the `SIZE` listed only once. ### List the most recently created images -```bash +```console $ docker images REPOSITORY TAG IMAGE ID CREATED SIZE @@ -72,7 +72,7 @@ given repository. For example, to list all images in the "java" repository, run this command : -```bash +```console $ docker images java REPOSITORY TAG IMAGE ID CREATED SIZE @@ -88,7 +88,7 @@ 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: -```bash +```console $ docker images java:8 REPOSITORY TAG IMAGE ID CREATED SIZE @@ -97,7 +97,7 @@ java 8 308e519aac60 6 days ago If nothing matches `REPOSITORY[:TAG]`, the list is empty. -```bash +```console $ docker images java:0 REPOSITORY TAG IMAGE ID CREATED SIZE @@ -105,7 +105,7 @@ REPOSITORY TAG IMAGE ID CREATED ### List the full length image IDs -```bash +```console $ docker images --no-trunc REPOSITORY TAG IMAGE ID CREATED SIZE @@ -127,7 +127,7 @@ 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: -```bash +```console $ docker images --digests REPOSITORY TAG DIGEST IMAGE ID CREATED SIZE localhost:5000/test/busybox sha256:cbbf2f9a99b47fc460d422812b6a5adff7dfee951d8fa2e4a98caa0382cfbdbf 4986bf8c1536 9 weeks ago 2.43 MB @@ -153,7 +153,7 @@ The currently supported filters are: #### Show untagged images (dangling) -```bash +```console $ docker images --filter "dangling=true" REPOSITORY TAG IMAGE ID CREATED SIZE @@ -173,7 +173,7 @@ using it. By having this flag it allows for batch cleanup. You can use this in conjunction with `docker rmi ...`: -```bash +```console $ docker rmi $(docker images -f "dangling=true" -q) 8abc22fbb042 @@ -194,7 +194,7 @@ value. The following filter matches images with the `com.example.version` label regardless of its value. -```bash +```console $ docker images --filter "label=com.example.version" REPOSITORY TAG IMAGE ID CREATED SIZE @@ -204,7 +204,7 @@ match-me-2 latest dea752e4e117 About a minute ago The following filter matches images with the `com.example.version` label with the `1.0` value. -```bash +```console $ docker images --filter "label=com.example.version=1.0" REPOSITORY TAG IMAGE ID CREATED SIZE @@ -213,7 +213,7 @@ match-me latest 511136ea3c5a About a minute ago In this example, with the `0.1` value, it returns an empty set because no matches were found. -```bash +```console $ docker images --filter "label=com.example.version=0.1" REPOSITORY TAG IMAGE ID CREATED SIZE ``` @@ -223,7 +223,7 @@ REPOSITORY TAG IMAGE ID CREATED The `before` filter shows only images created before the image with given id or reference. For example, having these images: -```bash +```console $ docker images REPOSITORY TAG IMAGE ID CREATED SIZE @@ -234,7 +234,7 @@ image3 latest 511136ea3c5a 25 minutes ago Filtering with `before` would give: -```bash +```console $ docker images --filter "before=image1" REPOSITORY TAG IMAGE ID CREATED SIZE @@ -244,7 +244,7 @@ image3 latest 511136ea3c5a 25 minutes ago Filtering with `since` would give: -```bash +```console $ docker images --filter "since=image3" REPOSITORY TAG IMAGE ID CREATED SIZE image1 latest eeae25ada2aa 4 minutes ago 188.3 MB @@ -256,7 +256,7 @@ image2 latest dea752e4e117 9 minutes ago The `reference` filter shows only images whose reference matches the specified pattern. -```bash +```console $ docker images REPOSITORY TAG IMAGE ID CREATED SIZE @@ -268,7 +268,7 @@ busybox glibc 21c16b6787c6 5 weeks ago Filtering with `reference` would give: -```bash +```console $ docker images --filter=reference='busy*:*libc' REPOSITORY TAG IMAGE ID CREATED SIZE @@ -278,7 +278,7 @@ busybox glibc 21c16b6787c6 5 weeks ago Filtering with multiple `reference` would give, either match A or B: -```bash +```console $ docker images --filter=reference='busy*:uclibc' --filter=reference='busy*:glibc' REPOSITORY TAG IMAGE ID CREATED SIZE @@ -310,7 +310,7 @@ output the data exactly as the template declares or, when using the The following example uses a template without headers and outputs the `ID` and `Repository` entries separated by a colon (`:`) for all images: -```bash +```console $ docker images --format "{{.ID}}: {{.Repository}}" 77af4d6b9913: @@ -327,7 +327,7 @@ b6fa739cedf5: committ To list all images with their repository and tag in a table format you can use: -```bash +```console $ docker images --format "table {{.ID}}\t{{.Repository}}\t{{.Tag}}" IMAGE ID REPOSITORY TAG diff --git a/docs/reference/commandline/import.md b/docs/reference/commandline/import.md index 497f1aa8c25d..5542f166d6e2 100644 --- a/docs/reference/commandline/import.md +++ b/docs/reference/commandline/import.md @@ -39,39 +39,39 @@ Supported `Dockerfile` instructions: This will create a new untagged image. -```bash -$ docker import http://example.com/exampleimage.tgz +```console +$ docker import https://example.com/exampleimage.tgz ``` ### Import from a local file -- Import to docker via pipe and `STDIN`. +Import to docker via pipe and `STDIN`. - ```bash - $ 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. - ```bash - $ 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. - ```bash - $ docker import /path/to/exampleimage.tgz - ``` +```console +$ docker import /path/to/exampleimage.tgz +``` ### Import from a local directory -```bash +```console $ sudo tar -c . | docker import - exampleimagedir ``` ### Import from a local directory with new configurations -```bash +```console $ sudo tar -c . | docker import --change "ENV DEBUG=true" - exampleimagedir ``` @@ -87,6 +87,6 @@ does not match the default operating system, it may be necessary to add `--platform`. This would be necessary when importing a Linux image into a Windows daemon. -```bash +```console $ docker import --platform=linux .\linuximage.tar ``` diff --git a/docs/reference/commandline/info.md b/docs/reference/commandline/info.md index 185b6a8f859e..0071edd8623a 100644 --- a/docs/reference/commandline/info.md +++ b/docs/reference/commandline/info.md @@ -24,7 +24,7 @@ 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](http://golang.org/pkg/text/template/) package +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 @@ -44,8 +44,9 @@ The example below shows the output for a daemon running on Red Hat Enterprise Li using the `devicemapper` storage driver. As can be seen in the output, additional information about the `devicemapper` storage driver is shown: -```bash +```console $ docker info + Client: Context: default Debug Mode: false @@ -104,8 +105,9 @@ Server: Here is a sample output for a daemon running on Ubuntu, using the overlay2 storage driver and a node that is part of a 2-node swarm: -```bash -$ docker -D info +```console +$ docker --debug info + Client: Context: default Debug Mode: true @@ -194,7 +196,7 @@ The global `-D` option causes all `docker` commands to output debug information. You can also specify the output format: -```bash +```console $ docker info --format '{{json .}}' {"ID":"I54V:OLXT:HVMM:TPKO:JPHQ:CQCD:JNLC:O3BZ:4ZVJ:43XJ:PFHZ:6N2S","Containers":14, ...} diff --git a/docs/reference/commandline/inspect.md b/docs/reference/commandline/inspect.md index 4806546ff774..d6174340d59d 100644 --- a/docs/reference/commandline/inspect.md +++ b/docs/reference/commandline/inspect.md @@ -29,7 +29,7 @@ By default, `docker inspect` will render results in a JSON array. If a format is specified, the given template will be executed for each result. -Go's [text/template](http://golang.org/pkg/text/template/) package +Go's [text/template](https://golang.org/pkg/text/template/) package describes all the details of the format. ## Specify target type (--type) @@ -45,7 +45,7 @@ option. The following example inspects a _volume_ named "myvolume" -```bash +```console $ docker inspect --type=volume myvolume ``` @@ -56,25 +56,25 @@ $ docker inspect --type=volume myvolume For the most part, you can pick out any field from the JSON in a fairly straightforward manner. -```bash +```console $ docker inspect --format='{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' $INSTANCE_ID ``` ### Get an instance's MAC address -```bash +```console $ docker inspect --format='{{range .NetworkSettings.Networks}}{{.MacAddress}}{{end}}' $INSTANCE_ID ``` ### Get an instance's log path -```bash +```console $ docker inspect --format='{{.LogPath}}' $INSTANCE_ID ``` ### Get an instance's image name -```bash +```console $ docker inspect --format='{{.Config.Image}}' $INSTANCE_ID ``` @@ -83,7 +83,7 @@ $ docker inspect --format='{{.Config.Image}}' $INSTANCE_ID You can loop over arrays and maps in the results to produce simple text output: -```bash +```console $ docker inspect --format='{{range $p, $conf := .NetworkSettings.Ports}} {{$p}} -> {{(index $conf 0).HostPort}} {{end}}' $INSTANCE_ID ``` @@ -97,7 +97,7 @@ 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. -```bash +```console $ docker inspect --format='{{(index (index .NetworkSettings.Ports "8787/tcp") 0).HostPort}}' $INSTANCE_ID ``` @@ -108,6 +108,6 @@ 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. -```bash +```console $ docker inspect --format='{{json .Config}}' $INSTANCE_ID ``` diff --git a/docs/reference/commandline/kill.md b/docs/reference/commandline/kill.md index 942605ec52ad..4c6935bc9c74 100644 --- a/docs/reference/commandline/kill.md +++ b/docs/reference/commandline/kill.md @@ -20,8 +20,18 @@ Options: 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 kill a container using the -container's ID, ID-prefix, or name. +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`. + +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** > @@ -32,21 +42,21 @@ container's ID, ID-prefix, or name. ## Examples -### Send a KILL signal to a container +### Send a KILL signal to a container -The following example sends the default `KILL` signal to the container named +The following example sends the default `SIGKILL` signal to the container named `my_container`: -```bash +```console $ docker kill my_container ``` -### Send a custom signal to a container +### Send a custom signal to a container The following example sends a `SIGHUP` signal to the container named `my_container`: -```bash +```console $ docker kill --signal=SIGHUP my_container ``` @@ -54,11 +64,11 @@ $ 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: -```bash +```console $ docker kill --signal=SIGHUP my_container $ docker kill --signal=HUP my_container $ docker kill --signal=1 my_container ``` -Refer to the [`signal(7)`](http://man7.org/linux/man-pages/man7/signal.7.html) +Refer to the [`signal(7)`](https://man7.org/linux/man-pages/man7/signal.7.html) man-page for a list of standard Linux signals. diff --git a/docs/reference/commandline/load.md b/docs/reference/commandline/load.md index 565cc666bc64..a81756d1772c 100644 --- a/docs/reference/commandline/load.md +++ b/docs/reference/commandline/load.md @@ -18,6 +18,7 @@ Options: The tarball may be compressed with gzip, bzip, or xz -q, --quiet Suppress the load output but still outputs the imported images ``` + ## Description Load an image or repository from a tar archive (even if compressed with gzip, @@ -25,7 +26,7 @@ bzip2, or xz) from a file or STDIN. It restores both images and tags. ## Examples -```bash +```console $ docker image ls REPOSITORY TAG IMAGE ID CREATED SIZE diff --git a/docs/reference/commandline/login.md b/docs/reference/commandline/login.md index ae0f9406c829..66354f30c490 100644 --- a/docs/reference/commandline/login.md +++ b/docs/reference/commandline/login.md @@ -30,7 +30,7 @@ Login to a registry. If you want to login to a self-hosted registry you can specify this by adding the server name. -```bash +```console $ docker login localhost:8080 ``` @@ -44,7 +44,7 @@ or log-files. The following example reads a password from a file, and passes it to the `docker login` command using `STDIN`: -```bash +```console $ cat ~/my_password.txt | docker login --username foo --password-stdin ``` diff --git a/docs/reference/commandline/logout.md b/docs/reference/commandline/logout.md index 4d0dd362acde..24c51843dbab 100644 --- a/docs/reference/commandline/logout.md +++ b/docs/reference/commandline/logout.md @@ -18,7 +18,7 @@ Options: ## Examples -```bash +```console $ docker logout localhost:8080 ``` diff --git a/docs/reference/commandline/logs.md b/docs/reference/commandline/logs.md index 26bf9d3daa71..57b2f42c1aab 100644 --- a/docs/reference/commandline/logs.md +++ b/docs/reference/commandline/logs.md @@ -67,7 +67,7 @@ fraction of a second no more than nine digits long. You can combine the In order to retrieve logs before a specific point in time, run: -```bash +```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 diff --git a/docs/reference/commandline/manifest.md b/docs/reference/commandline/manifest.md index 73c60a8cc8a9..b67c066ad4f0 100644 --- a/docs/reference/commandline/manifest.md +++ b/docs/reference/commandline/manifest.md @@ -40,8 +40,8 @@ to two images -- one for windows on amd64, and one for darwin on amd64. ### manifest inspect -```bash -manifest inspect --help +```console +$ docker manifest inspect --help Usage: docker manifest inspect [OPTIONS] [MANIFEST_LIST] MANIFEST @@ -55,7 +55,7 @@ Options: ### manifest create -```bash +```console Usage: docker manifest create MANIFEST_LIST MANIFEST [MANIFEST...] Create a local manifest list for annotating and pushing to a registry @@ -68,7 +68,7 @@ Options: ### manifest annotate -```bash +```console Usage: docker manifest annotate [OPTIONS] MANIFEST_LIST MANIFEST Add additional information to a local image manifest @@ -85,7 +85,7 @@ Options: ### manifest push -```bash +```console Usage: docker manifest push [OPTIONS] MANIFEST_LIST Push a manifest list to a repository @@ -113,7 +113,7 @@ default requirements. ### Inspect an image's manifest object -```bash +```console $ docker manifest inspect hello-world { "schemaVersion": 2, @@ -143,7 +143,7 @@ without a tag, or by digest (e.g. `hello-world@sha256:f3b3b28a45160805bb16542c95 Here is an example of inspecting an image's manifest with the `--verbose` flag: -```bash +```console $ docker manifest inspect --verbose hello-world { "Ref": "docker.io/library/hello-world:latest", @@ -187,7 +187,7 @@ After you have created your local copy of the manifest list, you may optionally 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. -```bash +```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 \ @@ -197,11 +197,11 @@ $ docker manifest create 45.55.81.106:5000/coolapp:v1 \ Created manifest list 45.55.81.106:5000/coolapp:v1 ``` -```bash +```console $ docker manifest annotate 45.55.81.106:5000/coolapp:v1 45.55.81.106:5000/coolapp-arm-linux --arch arm ``` -```bash +```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 @@ -213,7 +213,7 @@ sha256:050b213d49d7673ba35014f21454c573dcbec75254a08f4a7c34f66a47c06aba ### Inspect a manifest list -```bash +```console $ docker manifest inspect coolapp:v1 { "schemaVersion": 2, @@ -264,7 +264,7 @@ $ docker manifest inspect coolapp:v1 Here is an example of creating and pushing a manifest list using a known insecure registry. -```bash +```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 \ diff --git a/docs/reference/commandline/network_connect.md b/docs/reference/commandline/network_connect.md index ae024b31ec8e..f7b2fe564467 100644 --- a/docs/reference/commandline/network_connect.md +++ b/docs/reference/commandline/network_connect.md @@ -30,7 +30,7 @@ the same network. ### Connect a running container to a network -```bash +```console $ docker network connect multi-host-network container1 ``` @@ -38,7 +38,7 @@ $ docker network connect multi-host-network container1 You can also use the `docker run --network=` option to start a container and immediately connect it to a network. -```bash +```console $ docker run -itd --network=multi-host-network busybox ``` @@ -46,7 +46,7 @@ $ docker run -itd --network=multi-host-network busybox You can specify the IP address you want to be assigned to the container's interface. -```bash +```console $ docker network connect --ip 10.10.36.122 multi-host-network container2 ``` @@ -54,7 +54,7 @@ $ docker network connect --ip 10.10.36.122 multi-host-network container2 You can use `--link` option to link another container with a preferred alias -```bash +```console $ docker network connect --link container1:c1 multi-host-network container2 ``` @@ -63,7 +63,7 @@ $ docker network connect --link container1:c1 multi-host-network container2 `--alias` option can be used to resolve the container by another name in the network being connected to. -```bash +```console $ docker network connect --alias db --alias mysql multi-host-network container2 ``` @@ -79,11 +79,11 @@ 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. -```bash +```console $ docker network create --subnet 172.20.0.0/16 --ip-range 172.20.240.0/20 multi-host-network ``` -```bash +```console $ docker network connect --ip 172.20.128.2 multi-host-network container2 ``` diff --git a/docs/reference/commandline/network_create.md b/docs/reference/commandline/network_create.md index a7e22a799ef6..c3b68d37c066 100644 --- a/docs/reference/commandline/network_create.md +++ b/docs/reference/commandline/network_create.md @@ -45,7 +45,7 @@ on. When you launch a new container with `docker run` it automatically connects this bridge network. You cannot remove this default bridge network, but you can create new ones using the `network create` command. -```bash +```console $ docker network create -d bridge my-bridge-network ``` @@ -75,7 +75,7 @@ discovery and server management tools that can assist your implementation. 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: -```bash +```console $ docker network create -d overlay my-multihost-network ``` @@ -102,7 +102,7 @@ for more information about different endpoint modes. 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: -```bash +```console $ docker run -itd --network=mynet busybox ``` @@ -126,14 +126,14 @@ 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: -```bash +```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. -```bash +```console $ docker network create \ --driver=bridge \ --subnet=172.28.0.0/16 \ @@ -148,7 +148,7 @@ 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. -```bash +```console $ docker network create -d overlay \ --subnet=192.168.10.0/25 \ --subnet=192.168.20.0/25 \ @@ -175,7 +175,7 @@ equivalent docker daemon flags used for docker0 bridge: | `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_interface_prefix` | - | Set a custom prefix for container interfaces | +| `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`. @@ -191,7 +191,7 @@ network driver, again with their approximate equivalents to `docker daemon`. For example, let's use `-o` or `--opt` options to specify an IP address binding when publishing ports: -```bash +```console $ docker network create \ -o "com.docker.network.bridge.host_binding_ipv4"="172.19.0.1" \ simple-network @@ -212,7 +212,7 @@ 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. -```bash +```console $ docker network create -d overlay \ --subnet=10.11.0.0/16 \ --ingress \ diff --git a/docs/reference/commandline/network_disconnect.md b/docs/reference/commandline/network_disconnect.md index 4e6f2f6d3163..59ff61578bed 100644 --- a/docs/reference/commandline/network_disconnect.md +++ b/docs/reference/commandline/network_disconnect.md @@ -23,7 +23,7 @@ disconnect it from the network. ## Examples -```bash +```console $ docker network disconnect multi-host-network container1 ``` diff --git a/docs/reference/commandline/network_inspect.md b/docs/reference/commandline/network_inspect.md index 29b89653cf44..365ad13430f7 100644 --- a/docs/reference/commandline/network_inspect.md +++ b/docs/reference/commandline/network_inspect.md @@ -27,7 +27,7 @@ all results in a JSON object. Connect two containers to the default `bridge` network: -```bash +```console $ sudo docker run -itd --name=container1 busybox f2870c98fd504370fb86e59f32cd0753b1ac9b69b7d80566ffc7192a82b3ed27 @@ -44,10 +44,10 @@ node are shown. You can specify an alternate format to execute a given template for each result. Go's -[text/template](http://golang.org/pkg/text/template/) package describes all the +[text/template](https://golang.org/pkg/text/template/) package describes all the details of the format. -```bash +```console $ sudo docker network inspect bridge ``` @@ -104,13 +104,13 @@ The output is in JSON format, for example: Create and inspect a user-defined network: -```bash +```console $ docker network create simple-network 69568e6336d8c96bbf57869030919f7c69524f71183b44d80948bd3927c87f6a ``` -```bash +```console $ docker network inspect simple-network ``` @@ -146,7 +146,7 @@ For swarm mode overlay networks `network inspect` also shows the IP address and of the peers. Peers are the nodes in the swarm cluster which have at least one task attached to the network. Node name is of the format `-`. -```bash +```console $ docker network inspect ingress ``` @@ -213,7 +213,7 @@ and the IPs of the nodes where the tasks are running. Following is an example output for an overlay network `ov1` that has one service `s1` attached to. service `s1` in this case has three replicas. -```bash +```console $ docker network inspect --verbose ov1 ``` diff --git a/docs/reference/commandline/network_ls.md b/docs/reference/commandline/network_ls.md index d48673aaba10..8b938b33bea3 100644 --- a/docs/reference/commandline/network_ls.md +++ b/docs/reference/commandline/network_ls.md @@ -31,8 +31,8 @@ networks that span across multiple hosts in a cluster. ### List all networks -```bash -$ sudo docker network ls +```console +$ docker network ls NETWORK ID NAME DRIVER SCOPE 7fca4eb8c647 bridge bridge local 9f904ee27bf5 none null local @@ -42,7 +42,7 @@ cf03ee007fb4 host host local Use the `--no-trunc` option to display the full network id: -```bash +```console $ docker network ls --no-trunc NETWORK ID NAME DRIVER SCOPE 18a2866682b85619a026c81b98a5e375bd33e1b0936a26cc497c283d27bae9b3 none null local @@ -74,7 +74,7 @@ The `driver` filter matches networks based on their driver. The following example matches networks with the `bridge` driver: -```bash +```console $ docker network ls --filter driver=bridge NETWORK ID NAME DRIVER SCOPE db9db329f835 test1 bridge local @@ -88,7 +88,7 @@ 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. -```bash +```console $ docker network ls --filter id=63d1ff1f77b07ca51070a8c227e962238358bd310bde1529cf62e6c307ade161 NETWORK ID NAME DRIVER SCOPE 63d1ff1f77b0 dev bridge local @@ -96,7 +96,7 @@ NETWORK ID NAME DRIVER SCOPE You can also filter for a substring in an ID as this shows: -```bash +```console $ docker network ls --filter id=95e74588f40d NETWORK ID NAME DRIVER SCOPE 95e74588f40d foo bridge local @@ -113,7 +113,7 @@ value. The following filter matches networks with the `usage` label regardless of its value. -```bash +```console $ docker network ls -f "label=usage" NETWORK ID NAME DRIVER SCOPE db9db329f835 test1 bridge local @@ -122,7 +122,7 @@ f6e212da9dfd test2 bridge local The following filter matches networks with the `usage` label with the `prod` value. -```bash +```console $ docker network ls -f "label=usage=prod" NETWORK ID NAME DRIVER SCOPE f6e212da9dfd test2 bridge local @@ -134,7 +134,7 @@ 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. -```bash +```console $ docker network ls --filter name=foobar NETWORK ID NAME DRIVER SCOPE 06e7eef0a170 foobar bridge local @@ -142,7 +142,7 @@ NETWORK ID NAME DRIVER SCOPE You can also filter for a substring in a name as this shows: -```bash +```console $ docker network ls --filter name=foo NETWORK ID NAME DRIVER SCOPE 95e74588f40d foo bridge local @@ -155,7 +155,7 @@ The `scope` filter matches networks based on their scope. The following example matches networks with the `swarm` scope: -```bash +```console $ docker network ls --filter scope=swarm NETWORK ID NAME DRIVER SCOPE xbtm0v4f1lfh ingress overlay swarm @@ -164,7 +164,7 @@ ic6r88twuu92 swarmnet overlay swarm The following example matches networks with the `local` scope: -```bash +```console $ docker network ls --filter scope=local NETWORK ID NAME DRIVER SCOPE e85227439ac7 bridge bridge local @@ -180,7 +180,7 @@ The `type` filter supports two values; `builtin` displays predefined networks The following filter matches all user defined networks: -```bash +```console $ docker network ls --filter type=custom NETWORK ID NAME DRIVER SCOPE 95e74588f40d foo bridge local @@ -190,7 +190,7 @@ NETWORK ID NAME DRIVER SCOPE By having this flag it allows for batch cleanup. For example, use this filter to delete all user defined networks: -```bash +```console $ docker network rm `docker network ls --filter type=custom -q` ``` @@ -223,7 +223,7 @@ output the data exactly as the template declares or, when using the The following example uses a template without headers and outputs the `ID` and `Driver` entries separated by a colon (`:`) for all networks: -```bash +```console $ docker network ls --format "{{.ID}}: {{.Driver}}" afaaab448eb2: bridge d1584f8dc718: host diff --git a/docs/reference/commandline/network_prune.md b/docs/reference/commandline/network_prune.md index c49ff5f0a860..3d4e742ed90e 100644 --- a/docs/reference/commandline/network_prune.md +++ b/docs/reference/commandline/network_prune.md @@ -24,7 +24,7 @@ by any containers. ## Examples -```bash +```console $ docker network prune WARNING! This will remove all custom networks not used by at least one container. @@ -64,7 +64,7 @@ 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: -```bash +```console $ docker network ls NETWORK ID NAME DRIVER SCOPE diff --git a/docs/reference/commandline/network_rm.md b/docs/reference/commandline/network_rm.md index 52a4265aa728..ecbcdd16f2c0 100644 --- a/docs/reference/commandline/network_rm.md +++ b/docs/reference/commandline/network_rm.md @@ -29,8 +29,8 @@ you must first disconnect any containers connected to it. To remove the network named 'my-network': -```bash - $ docker network rm my-network +```console +$ docker network rm my-network ``` ### Remove multiple networks @@ -39,8 +39,8 @@ 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`: -```bash - $ 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. diff --git a/docs/reference/commandline/node_demote.md b/docs/reference/commandline/node_demote.md index 103c57f697ac..7bb5b59bda71 100644 --- a/docs/reference/commandline/node_demote.md +++ b/docs/reference/commandline/node_demote.md @@ -28,7 +28,7 @@ Demotes an existing manager so that it is no longer a manager. ## Examples -```bash +```console $ docker node demote ``` diff --git a/docs/reference/commandline/node_inspect.md b/docs/reference/commandline/node_inspect.md index 16ad0b98c278..7f479046a4b6 100644 --- a/docs/reference/commandline/node_inspect.md +++ b/docs/reference/commandline/node_inspect.md @@ -22,7 +22,7 @@ Options: 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](http://golang.org/pkg/text/template/) package describes all the +[text/template](https://golang.org/pkg/text/template/) package describes all the details of the format. > **Note** @@ -36,7 +36,7 @@ details of the format. ### Inspect a node -```bash +```console $ docker node inspect swarm-manager ``` @@ -113,7 +113,7 @@ $ docker node inspect swarm-manager ### Specify an output format -```bash +```console $ docker node inspect --format '{{ .ManagerStatus.Leader }}' self false @@ -121,7 +121,7 @@ false Use `--format=pretty` or the `--pretty` shorthand to pretty-print the output: -```bash +```console $ docker node inspect --format=pretty self ID: e216jshn25ckzbvmwlnh5jr3g diff --git a/docs/reference/commandline/node_ls.md b/docs/reference/commandline/node_ls.md index 8e4eb703adb3..11e3296972bf 100644 --- a/docs/reference/commandline/node_ls.md +++ b/docs/reference/commandline/node_ls.md @@ -36,7 +36,7 @@ for more information about available filter options. ## Examples -```bash +```console $ docker node ls ID HOSTNAME STATUS AVAILABILITY MANAGER STATUS @@ -44,6 +44,7 @@ ID HOSTNAME STATUS AVAILABILITY MANAGER STATU 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 @@ -60,6 +61,7 @@ The currently supported filters are: * [id](#id) * [label](#label) +* [node.label](#nodelabel) * [membership](#membership) * [name](#name) * [role](#role) @@ -68,7 +70,7 @@ The currently supported filters are: The `id` filter matches all or part of a node's id. -```bash +```console $ docker node ls -f id=1 ID HOSTNAME STATUS AVAILABILITY MANAGER STATUS @@ -77,17 +79,56 @@ ID HOSTNAME STATUS AVAILABILITY MANAGER STATUS #### label -The `label` filter matches nodes based on engine labels and on the presence of a `label` alone or a `label` and a value. Node labels are currently not used for filtering. +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. -```bash +```console $ docker node ls -f "label=foo" ID HOSTNAME STATUS AVAILABILITY MANAGER STATUS 1bcef6utixb0l0ca7gxuivsj0 swarm-worker2 Ready Active ``` +#### 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 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 +``` + +Show all nodes that have a `region` node label set: + +```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 +``` + +Show all nodes that have a `region` node label, with value `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 +``` + #### membership The `membership` filter matches nodes based on the presence of a `membership` and a value @@ -95,7 +136,7 @@ The `membership` filter matches nodes based on the presence of a `membership` an The following filter matches nodes with the `membership` of `accepted`. -```bash +```console $ docker node ls -f "membership=accepted" ID HOSTNAME STATUS AVAILABILITY MANAGER STATUS @@ -109,7 +150,7 @@ 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. -```bash +```console $ docker node ls -f name=swarm-manager1 ID HOSTNAME STATUS AVAILABILITY MANAGER STATUS @@ -122,7 +163,7 @@ The `role` filter matches nodes based on the presence of a `role` and a value `w The following filter matches nodes with the `manager` role. -```bash +```console $ docker node ls -f "role=manager" ID HOSTNAME STATUS AVAILABILITY MANAGER STATUS @@ -155,8 +196,9 @@ The following example uses a template without headers and outputs the `ID`, `Hostname`, and `TLS Status` entries separated by a colon (`:`) for all nodes: -```bash +```console $ docker node ls --format "{{.ID}}: {{.Hostname}} {{.TLSStatus}}" + e216jshn25ckzbvmwlnh5jr3g: swarm-manager1 Ready 35o6tiywb700jesrt3dmllaza: swarm-worker1 Needs Rotation ``` diff --git a/docs/reference/commandline/node_promote.md b/docs/reference/commandline/node_promote.md index 8906e6737555..665dd9486a98 100644 --- a/docs/reference/commandline/node_promote.md +++ b/docs/reference/commandline/node_promote.md @@ -28,7 +28,7 @@ Promotes a node to manager. This command can only be executed on a manager node. ## Examples -```bash +```console $ docker node promote ``` diff --git a/docs/reference/commandline/node_ps.md b/docs/reference/commandline/node_ps.md index c6dcc9f891fb..45d517634189 100644 --- a/docs/reference/commandline/node_ps.md +++ b/docs/reference/commandline/node_ps.md @@ -36,8 +36,9 @@ information about available filter options. ## Examples -```bash +```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 @@ -64,7 +65,7 @@ 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. -```bash +```console $ docker node ps -f name=redis swarm-manager1 NAME IMAGE NODE DESIRED STATE CURRENT STATE @@ -79,7 +80,7 @@ redis.10.0tgctg8h8cech4w0k0gwrmr23 redis:3.0.6 swarm-manager1 Running The `id` filter matches a task's id. -```bash +```console $ docker node ps -f id=bg8c07zzg87di2mufeq51a2qp swarm-manager1 NAME IMAGE NODE DESIRED STATE CURRENT STATE @@ -93,7 +94,7 @@ value. The following filter matches tasks with the `usage` label regardless of its value. -```bash +```console $ docker node ps -f "label=usage" NAME IMAGE NODE DESIRED STATE CURRENT STATE @@ -132,8 +133,9 @@ output the data exactly as the template declares or, when using the The following example uses a template without headers and outputs the `Name` and `Image` entries separated by a colon (`:`) for all tasks: -```bash +```console $ docker node ps --format "{{.Name}}: {{.Image}}" + top.1: busybox top.2: busybox top.3: busybox diff --git a/docs/reference/commandline/node_rm.md b/docs/reference/commandline/node_rm.md index 53cd309eebfb..ea334f204b4b 100644 --- a/docs/reference/commandline/node_rm.md +++ b/docs/reference/commandline/node_rm.md @@ -34,11 +34,12 @@ Removes the specified nodes from a swarm. ### Remove a stopped node from the swarm -```bash +```console $ docker node rm swarm-node-02 Node swarm-node-02 removed from 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 @@ -58,7 +59,7 @@ 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. -```bash +```console $ docker node rm --force swarm-node-03 Node swarm-node-03 removed from swarm diff --git a/docs/reference/commandline/node_update.md b/docs/reference/commandline/node_update.md index f8dc40db6979..6ef0b1bd5fbc 100644 --- a/docs/reference/commandline/node_update.md +++ b/docs/reference/commandline/node_update.md @@ -43,7 +43,7 @@ $ docker node update --label-add foo worker1 To add multiple labels to a node, pass the `--label-add` flag for each label: -```bash +```console $ docker node update --label-add foo --label-add bar worker1 ``` diff --git a/docs/reference/commandline/pause.md b/docs/reference/commandline/pause.md index 515efb7f61fc..abdc1ea63ba7 100644 --- a/docs/reference/commandline/pause.md +++ b/docs/reference/commandline/pause.md @@ -30,7 +30,7 @@ for further details. ## Examples -```bash +```console $ docker pause my_container ``` diff --git a/docs/reference/commandline/plugin_create.md b/docs/reference/commandline/plugin_create.md index b56df04aa0fa..78cd78e87448 100644 --- a/docs/reference/commandline/plugin_create.md +++ b/docs/reference/commandline/plugin_create.md @@ -25,7 +25,7 @@ Creates a plugin. Before creating the plugin, prepare the plugin's root filesyst The following example shows how to create a sample `plugin`. -```bash +```console $ ls -ls /home/pluginDir total 4 diff --git a/docs/reference/commandline/plugin_disable.md b/docs/reference/commandline/plugin_disable.md index 927b6d580142..12a7c9368c71 100644 --- a/docs/reference/commandline/plugin_disable.md +++ b/docs/reference/commandline/plugin_disable.md @@ -27,7 +27,7 @@ a plugin that has references (e.g., volumes, networks) cannot be disabled. The following example shows that the `sample-volume-plugin` plugin is installed and enabled: -```bash +```console $ docker plugin ls ID NAME DESCRIPTION ENABLED @@ -36,7 +36,7 @@ ID NAME DESCRIPTION To disable the plugin, use the following command: -```bash +```console $ docker plugin disable tiborvass/sample-volume-plugin tiborvass/sample-volume-plugin diff --git a/docs/reference/commandline/plugin_enable.md b/docs/reference/commandline/plugin_enable.md index 2f6a5f5198a0..11a0b09a68a5 100644 --- a/docs/reference/commandline/plugin_enable.md +++ b/docs/reference/commandline/plugin_enable.md @@ -26,7 +26,7 @@ see [`docker plugin install`](plugin_install.md). The following example shows that the `sample-volume-plugin` plugin is installed, but disabled: -```bash +```console $ docker plugin ls ID NAME DESCRIPTION ENABLED @@ -35,7 +35,7 @@ ID NAME DESCRIPTION To enable the plugin, use the following command: -```bash +```console $ docker plugin enable tiborvass/sample-volume-plugin tiborvass/sample-volume-plugin diff --git a/docs/reference/commandline/plugin_inspect.md b/docs/reference/commandline/plugin_inspect.md index ab8679b7ac5e..30caa13a3612 100644 --- a/docs/reference/commandline/plugin_inspect.md +++ b/docs/reference/commandline/plugin_inspect.md @@ -27,7 +27,7 @@ in a JSON array. The following example example inspects the `tiborvass/sample-volume-plugin` plugin: -```bash +```console $ docker plugin inspect tiborvass/sample-volume-plugin:latest ``` @@ -144,7 +144,7 @@ Output is in JSON format (output below is formatted for readability): ### Formatting the output -```bash +```console $ docker plugin inspect -f '{{.Id}}' tiborvass/sample-volume-plugin:latest 8c74c978c434745c3ade82f1bc0acf38d04990eaf494fa507c16d9f1daa99c21 diff --git a/docs/reference/commandline/plugin_install.md b/docs/reference/commandline/plugin_install.md index 4028cc17c196..784edad46554 100644 --- a/docs/reference/commandline/plugin_install.md +++ b/docs/reference/commandline/plugin_install.md @@ -33,7 +33,7 @@ The following example installs `vieus/sshfs` plugin and [sets](plugin_set.md) it Hub and prompt the user to accept the list of privileges that the plugin needs, set the plugin's parameters and enable the plugin. -```bash +```console $ docker plugin install vieux/sshfs DEBUG=1 Plugin "vieux/sshfs" is requesting the following privileges: @@ -46,7 +46,7 @@ vieux/sshfs After the plugin is installed, it appears in the list of plugins: -```bash +```console $ docker plugin ls ID NAME DESCRIPTION ENABLED diff --git a/docs/reference/commandline/plugin_ls.md b/docs/reference/commandline/plugin_ls.md index dedd2270dc66..47a657d9d81b 100644 --- a/docs/reference/commandline/plugin_ls.md +++ b/docs/reference/commandline/plugin_ls.md @@ -31,7 +31,7 @@ Refer to the [filtering](#filtering) section for more information about availabl ## Examples -```bash +```console $ docker plugin ls ID NAME DESCRIPTION ENABLED @@ -58,7 +58,7 @@ The `capability` filter matches on plugin capabilities. One plugin might have multiple capabilities. Currently `volumedriver`, `networkdriver`, `ipamdriver`, `logdriver`, `metricscollector`, and `authz` are supported capabilities. -```bash +```console $ docker plugin install --disable vieux/sshfs Installed plugin vieux/sshfs @@ -90,7 +90,7 @@ output the data exactly as the template declares or, when using the The following example uses a template without headers and outputs the `ID` and `Name` entries separated by a colon (`:`) for all plugins: -```bash +```console $ docker plugin ls --format "{{.ID}}: {{.Name}}" 4be01827a72e: vieux/sshfs:latest diff --git a/docs/reference/commandline/plugin_push.md b/docs/reference/commandline/plugin_push.md index c554a747fd73..f00d2f56d3f3 100644 --- a/docs/reference/commandline/plugin_push.md +++ b/docs/reference/commandline/plugin_push.md @@ -26,7 +26,7 @@ Registry credentials are managed by [docker login](login.md). The following example shows how to push a sample `user/plugin`. -```bash +```console $ docker plugin ls ID NAME DESCRIPTION ENABLED diff --git a/docs/reference/commandline/plugin_rm.md b/docs/reference/commandline/plugin_rm.md index 184ab5f375dd..8dec068a404a 100644 --- a/docs/reference/commandline/plugin_rm.md +++ b/docs/reference/commandline/plugin_rm.md @@ -31,7 +31,7 @@ functioning of running containers using the plugin). The following example disables and removes the `sample-volume-plugin:latest` plugin: -```bash +```console $ docker plugin disable tiborvass/sample-volume-plugin tiborvass/sample-volume-plugin diff --git a/docs/reference/commandline/plugin_set.md b/docs/reference/commandline/plugin_set.md index 33ea04567c69..20a4ed24420b 100644 --- a/docs/reference/commandline/plugin_set.md +++ b/docs/reference/commandline/plugin_set.md @@ -84,7 +84,7 @@ On the contrary, the `LOGGING` environment variable doesn't have any settable fi The following example change the env variable `DEBUG` on the `sample-volume-plugin` plugin. -```bash +```console $ docker plugin inspect -f {{.Settings.Env}} tiborvass/sample-volume-plugin [DEBUG=0] @@ -99,7 +99,7 @@ $ docker plugin inspect -f {{.Settings.Env}} tiborvass/sample-volume-plugin The following example change the source of the `mymount` mount on the `myplugin` plugin. -```bash +```console $ docker plugin inspect -f '{{with $mount := index .Settings.Mounts 0}}{{$mount.Source}}{{end}}' myplugin /foo @@ -119,7 +119,7 @@ $ docker plugin inspect -f '{{with $mount := index .Settings.Mounts 0}}{{$mount. The following example change the path of the `mydevice` device on the `myplugin` plugin. -```bash +```console $ docker plugin inspect -f '{{with $device := index .Settings.Devices 0}}{{$device.Path}}{{end}}' myplugin /dev/foo @@ -139,7 +139,7 @@ $ docker plugin inspect -f '{{with $device := index .Settings.Devices 0}}{{$devi The following example change the value of the args on the `myplugin` plugin. -```bash +```console $ docker plugin inspect -f '{{.Settings.Args}}' myplugin ["foo", "bar"] diff --git a/docs/reference/commandline/plugin_upgrade.md b/docs/reference/commandline/plugin_upgrade.md index 23b063a8c418..fc70732fdc70 100644 --- a/docs/reference/commandline/plugin_upgrade.md +++ b/docs/reference/commandline/plugin_upgrade.md @@ -30,7 +30,7 @@ The plugin must be disabled before running the upgrade. The following example installs `vieus/sshfs` plugin, uses it to create and use a volume, then upgrades the plugin. -```bash +```console $ docker plugin install vieux/sshfs DEBUG=1 Plugin "vieux/sshfs:next" is requesting the following privileges: diff --git a/docs/reference/commandline/port.md b/docs/reference/commandline/port.md index 029df710f8fe..a35ae175f687 100644 --- a/docs/reference/commandline/port.md +++ b/docs/reference/commandline/port.md @@ -22,7 +22,7 @@ Options: You can find out all the ports mapped by not specifying a `PRIVATE_PORT`, or just a specific mapping: -```bash +```console $ docker ps CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES diff --git a/docs/reference/commandline/ps.md b/docs/reference/commandline/ps.md index 4a95d7b2f41c..02f8e27f22b0 100644 --- a/docs/reference/commandline/ps.md +++ b/docs/reference/commandline/ps.md @@ -45,7 +45,7 @@ Options: Running `docker ps --no-trunc` showing 2 linked containers. -```bash +```console $ docker ps CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES @@ -58,7 +58,7 @@ d7886598dbe2 crosbymichael/redis:latest /redis-server --dir 33 minut The `docker ps` command only shows running containers by default. To see all containers, use the `-a` (or `--all`) flag: -```bash +```console $ docker ps -a ``` @@ -70,7 +70,7 @@ the `PORTS` column. The `docker ps -s` command displays two different on-disk-sizes for each container: -```bash +```console $ docker ps -s CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES SIZE SIZE @@ -114,7 +114,7 @@ value. The following filter matches containers with the `color` label regardless of its value. -```bash +```console $ docker ps --filter "label=color" CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES @@ -124,7 +124,7 @@ d85756f57265 busybox "top" 52 seconds ago The following filter matches containers with the `color` label with the `blue` value. -```bash +```console $ docker ps --filter "label=color=blue" CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES @@ -137,7 +137,7 @@ 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. -```bash +```console $ docker ps --filter "name=nostalgic_stallman" CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES @@ -146,7 +146,7 @@ CONTAINER ID IMAGE COMMAND CREATED You can also filter for a substring in a name as this shows: -```bash +```console $ docker ps --filter "name=nostalgic" CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES @@ -160,7 +160,7 @@ CONTAINER ID IMAGE COMMAND CREATED The `exited` filter matches containers by exist status code. For example, to filter for containers that have exited successfully: -```bash +```console $ docker ps -a --filter 'exited=0' CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES @@ -174,7 +174,7 @@ ea09c3c82f6e registry:latest /srv/run.sh 2 weeks ago You can use a filter to locate containers that exited with status of `137` meaning a `SIGKILL(9)` killed them. -```bash +```console $ docker ps -a --filter 'exited=137' CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES @@ -194,7 +194,7 @@ 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: -```bash +```console $ docker ps --filter status=running CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES @@ -205,7 +205,7 @@ d5c976d3c462 busybox "top" 23 minutes ago To filter for `paused` containers: -```bash +```console $ docker ps --filter status=paused CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES @@ -226,7 +226,7 @@ it. The filter supports the following image representation: If you don't specify a `tag`, the `latest` tag is used. For example, to filter for containers that use the latest `ubuntu` image: -```bash +```console $ docker ps --filter ancestor=ubuntu CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES @@ -239,7 +239,7 @@ bab2a34ba363 ubuntu "top" 3 minutes ago Match containers based on the `ubuntu-c1` image which, in this case, is a child of `ubuntu`: -```bash +```console $ docker ps --filter ancestor=ubuntu-c1 CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES @@ -248,7 +248,7 @@ CONTAINER ID IMAGE COMMAND CREATED Match containers based on the `ubuntu` version `12.04.5` image: -```bash +```console $ docker ps --filter ancestor=ubuntu:12.04.5 CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES @@ -258,7 +258,7 @@ CONTAINER ID IMAGE COMMAND CREATED The following matches containers based on the layer `d0e008c6cf02` or an image that have this layer in its layer stack. -```bash +```console $ docker ps --filter ancestor=d0e008c6cf02 CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES @@ -272,7 +272,7 @@ CONTAINER ID IMAGE COMMAND CREATED The `before` filter shows only containers created before the container with given id or name. For example, having these containers created: -```bash +```console $ docker ps CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES @@ -283,7 +283,7 @@ CONTAINER ID IMAGE COMMAND CREATED STATUS Filtering with `before` would give: -```bash +```console $ docker ps -f before=9c3527ed70ce CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES @@ -296,7 +296,7 @@ CONTAINER ID IMAGE COMMAND CREATED STATUS 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: -```bash +```console $ docker ps -f since=6e63f6ff38b0 CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES @@ -309,7 +309,7 @@ CONTAINER ID IMAGE COMMAND CREATED STATUS The `volume` filter shows only containers that mount a specific volume or have a volume mounted in a specific path: -```bash +```console $ docker ps --filter volume=remote-volume --format "table {{.ID}}\t{{.Mounts}}" CONTAINER ID MOUNTS @@ -329,7 +329,7 @@ a given name or id. The following filter matches all containers that are connected to a network with a name containing `net1`. -```bash +```console $ docker run -d --net=net1 --name=test1 ubuntu top $ docker run -d --net=net2 --name=test2 ubuntu top @@ -343,7 +343,7 @@ 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; -```bash +```console $ docker network inspect --format "{{.ID}}" net1 8c0b4110ae930dbe26b258de9bc34a03f98056ed6f27f991d32919bfe401d7c5 @@ -361,7 +361,7 @@ number, port range, and/or protocol. The default protocol is `tcp` when not spec The following filter matches all containers that have published port of 80: -```bash +```console $ docker run -d --publish=80 busybox top $ docker run -d --expose=8080 busybox top @@ -378,7 +378,8 @@ fc7e477723b7 busybox "top" About a minute ago ``` The following filter matches all containers that have exposed TCP port in the range of `8000-8080`: -```bash + +```console $ docker ps --filter expose=8000-8080/tcp CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES @@ -386,7 +387,8 @@ CONTAINER ID IMAGE COMMAND CREATED ``` The following filter matches all containers that have exposed UDP port `80`: -```bash + +```console $ docker ps --filter publish=80/udp CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES @@ -423,7 +425,7 @@ 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: -```bash +```console $ docker ps --format "{{.ID}}: {{.Command}}" a87ecb4f327c: /bin/sh -c #(nop) MA @@ -434,7 +436,7 @@ c1d3b0166030: /bin/sh -c yum -y up To list all running containers with their labels in a table format you can use: -```bash +```console $ docker ps --format "table {{.ID}}\t{{.Labels}}" CONTAINER ID LABELS diff --git a/docs/reference/commandline/pull.md b/docs/reference/commandline/pull.md index 40cc99ff7d13..faa90ab681de 100644 --- a/docs/reference/commandline/pull.md +++ b/docs/reference/commandline/pull.md @@ -53,7 +53,7 @@ To download a particular image, or set of images (i.e., a repository), use `docker pull`. If no tag is provided, Docker Engine uses the `:latest` tag as a default. This command pulls the `debian:latest` image: -```bash +```console $ docker pull debian Using default tag: latest @@ -72,7 +72,7 @@ both layers with `debian:latest`. Pulling the `debian:jessie` image therefore only pulls its metadata, but not its layers, because all layers are already present locally: -```bash +```console $ docker pull debian:jessie jessie: Pulling from library/debian @@ -85,7 +85,7 @@ Status: Downloaded newer image for debian:jessie To see which images are present locally, use the [`docker images`](images.md) command: -```bash +```console $ docker images REPOSITORY TAG IMAGE ID CREATED SIZE @@ -109,8 +109,8 @@ refer to [understand images, containers, and storage drivers](https://docs.docke 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:14.04` pulls the latest version of the Ubuntu -14.04 image. +For example, `docker pull ubuntu:20.04` pulls the latest version of the Ubuntu +20.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 @@ -119,24 +119,24 @@ 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:14.04` image from Docker Hub: +`ubuntu:20.04` image from Docker Hub: -```bash -$ docker pull ubuntu:14.04 +```console +$ docker pull ubuntu:20.04 -14.04: Pulling from library/ubuntu -5a132a7e7af1: Pull complete -fd2731e4c50c: Pull complete -28a2f68d1120: Pull complete -a3ed95caeb02: Pull complete -Digest: sha256:45b23dee08af5e43a7fea6c4cf9c25ccf269ee113168c19722f87876677c5cb2 -Status: Downloaded newer image for ubuntu:14.04 +20.04: Pulling from library/ubuntu +16ec32c2132b: Pull complete +Digest: sha256:82becede498899ec668628e7cb0ad87b6e1c371cb8a1e597d83a47fac21d6af3 +Status: Downloaded newer image for ubuntu:20.04 +docker.io/library/ubuntu:20.04 ``` Docker prints the digest of the image after the pull has finished. In the example above, the digest of the image is: - sha256:45b23dee08af5e43a7fea6c4cf9c25ccf269ee113168c19722f87876677c5cb2 +```console +sha256:82becede498899ec668628e7cb0ad87b6e1c371cb8a1e597d83a47fac21d6af3 +``` 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. @@ -144,23 +144,20 @@ 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: -```bash -$ docker pull ubuntu@sha256:45b23dee08af5e43a7fea6c4cf9c25ccf269ee113168c19722f87876677c5cb2 +```console +$ docker pull ubuntu@sha256:82becede498899ec668628e7cb0ad87b6e1c371cb8a1e597d83a47fac21d6af3 -sha256:45b23dee08af5e43a7fea6c4cf9c25ccf269ee113168c19722f87876677c5cb2: Pulling from library/ubuntu -5a132a7e7af1: Already exists -fd2731e4c50c: Already exists -28a2f68d1120: Already exists -a3ed95caeb02: Already exists -Digest: sha256:45b23dee08af5e43a7fea6c4cf9c25ccf269ee113168c19722f87876677c5cb2 -Status: Downloaded newer image for ubuntu@sha256:45b23dee08af5e43a7fea6c4cf9c25ccf269ee113168c19722f87876677c5cb2 +docker.io/library/ubuntu@sha256:82becede498899ec668628e7cb0ad87b6e1c371cb8a1e597d83a47fac21d6af3: Pulling from library/ubuntu +Digest: sha256:82becede498899ec668628e7cb0ad87b6e1c371cb8a1e597d83a47fac21d6af3 +Status: Image is up to date for ubuntu@sha256:82becede498899ec668628e7cb0ad87b6e1c371cb8a1e597d83a47fac21d6af3 +docker.io/library/ubuntu@sha256:82becede498899ec668628e7cb0ad87b6e1c371cb8a1e597d83a47fac21d6af3 ``` Digest can also be used in the `FROM` of a Dockerfile, for example: ```dockerfile -FROM ubuntu@sha256:45b23dee08af5e43a7fea6c4cf9c25ccf269ee113168c19722f87876677c5cb2 -LABEL maintainer="some maintainer " +FROM ubuntu@sha256:82becede498899ec668628e7cb0ad87b6e1c371cb8a1e597d83a47fac21d6af3 +LABEL org.opencontainers.image.authors="some maintainer " ``` > **Note** @@ -181,7 +178,7 @@ 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`): -```bash +```console $ docker pull myregistry.local:5000/testing/test-image ``` @@ -200,7 +197,7 @@ can contain multiple images. To pull all images from a repository, provide the This command pulls all images from the `fedora` repository: -```bash +```console $ docker pull --all-tags fedora Pulling repository fedora @@ -217,7 +214,7 @@ After the pull has completed use the `docker images` command to see the images that were pulled. The example below shows all the `fedora` images that are present locally: -```bash +```console $ docker images fedora REPOSITORY TAG IMAGE ID CREATED SIZE @@ -232,7 +229,7 @@ fedora latest 105182bb5e8b 5 days ago 372.7 MB Killing the `docker pull` process, for example by pressing `CTRL-c` while it is running in a terminal, will terminate the pull operation. -```bash +```console $ docker pull fedora Using default tag: latest diff --git a/docs/reference/commandline/push.md b/docs/reference/commandline/push.md index 80b0a2248e51..f72036fad50f 100644 --- a/docs/reference/commandline/push.md +++ b/docs/reference/commandline/push.md @@ -50,7 +50,7 @@ First save the new image by finding the container ID (using [`docker container l and then committing it to a new image name. Note that only `a-z0-9-_.` are allowed when naming images: -```bash +```console $ docker container commit c16378f943fe rhel-httpd:latest ``` @@ -59,7 +59,7 @@ 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: -```bash +```console $ docker image tag rhel-httpd:latest registry-host:5000/myadmin/rhel-httpd:latest $ docker image push registry-host:5000/myadmin/rhel-httpd:latest @@ -67,7 +67,7 @@ $ docker image push registry-host:5000/myadmin/rhel-httpd:latest Check that this worked by running: -```bash +```console $ docker image ls ``` @@ -76,13 +76,13 @@ listed. ### Push all tags of an image -Use the `-a` (or `--all-tags`) option to push 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. -```bash +```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 @@ -91,7 +91,7 @@ $ docker image tag myimage registry-host:5000/myname/myimage:v1 The image is now tagged under multiple names: -```bash +```console $ docker image ls REPOSITORY TAG IMAGE ID CREATED SIZE @@ -106,7 +106,7 @@ When pushing with the `--all-tags` option, all tags of the `registry-host:5000/m image are pushed: -```bash +```console $ docker image push --all-tags registry-host:5000/myname/myimage The push refers to repository [registry-host:5000/myname/myimage] diff --git a/docs/reference/commandline/rename.md b/docs/reference/commandline/rename.md index d16890bb559b..f95f9c3457e3 100644 --- a/docs/reference/commandline/rename.md +++ b/docs/reference/commandline/rename.md @@ -21,6 +21,6 @@ The `docker rename` command renames a container. ## Examples -```bash +```console $ docker rename my_container my_new_container ``` diff --git a/docs/reference/commandline/restart.md b/docs/reference/commandline/restart.md index 28652c376afb..aa64257d8680 100644 --- a/docs/reference/commandline/restart.md +++ b/docs/reference/commandline/restart.md @@ -18,6 +18,6 @@ Options: ## Examples -```bash +```console $ docker restart my_container ``` diff --git a/docs/reference/commandline/rm.md b/docs/reference/commandline/rm.md index de04a26beeb9..703734f5dc22 100644 --- a/docs/reference/commandline/rm.md +++ b/docs/reference/commandline/rm.md @@ -24,7 +24,7 @@ Options: This removes the container referenced under the link `/redis`. -```bash +```console $ docker rm /redis /redis @@ -37,7 +37,7 @@ 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. -```bash +```console $ docker rm --link /webapp/redis /webapp/redis @@ -47,7 +47,7 @@ $ docker rm --link /webapp/redis This command force-removes a running container. -```bash +```console $ docker rm --force redis redis @@ -58,17 +58,37 @@ The main process inside the container referenced under the link `redis` will rec ### Remove all stopped containers -```bash -$ docker rm $(docker ps -a -q) +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. + +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: + +```console +$ docker rm $(docker ps --filter status=exited -q) ``` -This command deletes all stopped containers. The command -`docker ps -a -q` above returns all existing container IDs and passes them to -the `rm` command which deletes them. Running containers are not deleted. +Or, using the `xargs` Linux utility; + +```console +$ docker ps --filter status=exited -q | xargs docker rm +``` ### Remove a container and its volumes -```bash +```console $ docker rm -v redis redis ``` @@ -78,7 +98,7 @@ Note that if a volume was specified with a name, it will not be removed. ### Remove a container and selectively remove volumes -```bash +```console $ docker create -v awesome:/foo -v /bar --name hello redis hello diff --git a/docs/reference/commandline/rmi.md b/docs/reference/commandline/rmi.md index 78cc4909a84f..a63ffb7658c3 100644 --- a/docs/reference/commandline/rmi.md +++ b/docs/reference/commandline/rmi.md @@ -35,7 +35,7 @@ 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. -```bash +```console $ docker images REPOSITORY TAG IMAGE ID CREATED SIZE @@ -71,7 +71,7 @@ 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. -```bash +```console $ docker images REPOSITORY TAG IMAGE ID CREATED SIZE @@ -89,7 +89,7 @@ Deleted: fd484f19954f4920da7ff372b5067f5b7ddb2fd3830cecd17b96ea9e286ba5b8 An image pulled by digest has no tag associated with it: -```bash +```console $ docker images --digests REPOSITORY TAG DIGEST IMAGE ID CREATED SIZE @@ -98,7 +98,7 @@ localhost:5000/test/busybox sha256:cbbf2f9a99b47fc460d422812b6a5adf To remove an image using its digest: -```bash +```console $ docker rmi localhost:5000/test/busybox@sha256:cbbf2f9a99b47fc460d422812b6a5adff7dfee951d8fa2e4a98caa0382cfbdbf Untagged: localhost:5000/test/busybox@sha256:cbbf2f9a99b47fc460d422812b6a5adff7dfee951d8fa2e4a98caa0382cfbdbf Deleted: 4986bf8c15363d1c5d15512d5266f8777bfba4974ac56e3270e7760f6f0a8125 diff --git a/docs/reference/commandline/run.md b/docs/reference/commandline/run.md index d0024ad67ab0..efead707352c 100644 --- a/docs/reference/commandline/run.md +++ b/docs/reference/commandline/run.md @@ -120,7 +120,7 @@ Options: or `g` (gigabytes). If you omit the unit, the system uses bytes. --sig-proxy Proxy received signals to the process (default true) --stop-signal string Signal to stop a container (default "SIGTERM") - --stop-timeout=10 Timeout (in seconds) to stop a container + --stop-timeout int Timeout (in seconds) to stop a container --storage-opt value Storage driver options for the container (default []) --sysctl value Sysctl options (default map[]) --tmpfs value Mount a tmpfs directory (default []) @@ -161,7 +161,7 @@ For information on connecting a container to a network, see the ["*Docker networ ### Assign name and allocate pseudo-TTY (--name, -it) -```bash +```console $ docker run --name test -it debian root@d6c0fe130dba:/# exit 13 @@ -180,7 +180,7 @@ In the example, the `bash` shell is quit by entering ### Capture container ID (--cidfile) -```bash +```console $ docker run --cidfile /tmp/docker_test.cid ubuntu echo "test" ``` @@ -191,7 +191,7 @@ file when `docker run` exits. ### Full container capabilities (--privileged) -```bash +```console $ docker run -t -i --rm ubuntu bash root@bc338942ef20:/# mount -t tmpfs none /mnt mount: permission denied @@ -201,7 +201,7 @@ 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: -```bash +```console $ docker run -t -i --privileged ubuntu bash root@50e3f57e16e6:/# mount -t tmpfs none /mnt root@50e3f57e16e6:/# df -h @@ -216,7 +216,7 @@ flag exists to allow special use-cases, like running Docker within Docker. ### Set working directory (-w) -```bash +```console $ docker run -w /path/to/dir/ -i -t ubuntu pwd ``` @@ -225,7 +225,7 @@ The `-w` lets the command being executed inside directory given, here ### Set storage driver options per container -```bash +```console $ docker run -it --storage-opt size=120G fedora /bin/bash ``` @@ -240,7 +240,7 @@ Under these conditions, user can pass any size less than the backing fs size. ### Mount tmpfs (--tmpfs) -```bash +```console $ docker run -d --tmpfs /run:rw,noexec,nosuid,size=65536k my_image ``` @@ -249,7 +249,7 @@ The `--tmpfs` flag mounts an empty tmpfs into the container with the `rw`, ### Mount volume (-v, --read-only) -```bash +```console $ docker run -v `pwd`:`pwd` -w `pwd` -i -t ubuntu pwd ``` @@ -259,7 +259,7 @@ 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. -```bash +```console $ docker run -v /doesnt/exist:/foo -w /foo -i -t ubuntu bash ``` @@ -268,7 +268,7 @@ 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. -```bash +```console $ docker run --read-only -v /icanwrite busybox touch /icanwrite/here ``` @@ -277,7 +277,7 @@ 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. -```bash +```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 ``` @@ -327,17 +327,17 @@ Even though there is no plan to deprecate `--volume`, usage of `--mount` is reco Examples: -```bash +```console $ docker run --read-only --mount type=volume,target=/icanwrite busybox touch /icanwrite/here ``` -```bash +```console $ docker run -t -i --mount type=bind,src=/data,dst=/data busybox sh ``` ### Publish or expose port (-p, --expose) -```bash +```console $ docker run -p 127.0.0.1:80:8080/tcp ubuntu bash ``` @@ -348,10 +348,10 @@ 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 his +you configured UFW to block this specific port, as Docker manages its own iptables rules. [Read more](https://docs.docker.com/network/iptables/) -```bash +```console $ docker run --expose 80 ubuntu bash ``` @@ -360,7 +360,7 @@ system's interfaces. ### Set environment variables (-e, --env, --env-file) -```bash +```console $ docker run -e MYVAR1 --env MYVAR2=foo --env-file ./env.list ubuntu bash ``` @@ -370,7 +370,7 @@ that are defined in the Dockerfile of the image you're running. You can define the variable and its value when running the container: -```bash +```console $ docker run --env VAR1=value1 --env VAR2=value2 ubuntu env | grep VAR VAR1=value1 VAR2=value2 @@ -378,7 +378,7 @@ VAR2=value2 You can also use variables that you've exported to your local environment: -```bash +```console export VAR1=value1 export VAR2=value2 @@ -396,24 +396,24 @@ 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. -```bash +```console $ cat env.list # This is a comment VAR1=value1 VAR2=value2 USER -$ docker run --env-file env.list ubuntu env | grep VAR +$ docker run --env-file env.list ubuntu env | grep -E 'VAR|USER' VAR1=value1 VAR2=value2 -USER=denis +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: -```bash +```console $ docker run -l my-label --label com.example.foo=bar ubuntu bash ``` @@ -428,7 +428,7 @@ 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: -```bash +```console $ docker run --label-file ./labels ubuntu bash ``` @@ -456,21 +456,21 @@ the Docker User Guide. When you start a container use the `--network` flag to connect it to a network. This adds the `busybox` container to the `my-net` network. -```bash +```console $ 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. -```bash +```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 need only another container's IP address +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. @@ -486,7 +486,7 @@ disconnect` command. ### Mount volumes from container (--volumes-from) -```bash +```console $ docker run --volumes-from 777f7dc92da7 --volumes-from ba8c0c54f0f2:ro -i -t ubuntu pwd ``` @@ -516,14 +516,14 @@ The `-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. -```bash +```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`. -```bash +```console $ docker run -a stderr ubuntu echo test ``` @@ -531,7 +531,7 @@ 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`. -```bash +```console $ cat somefile | docker run -i -a stdin mybuilder dobuild ``` @@ -543,7 +543,7 @@ retrieve the container's ID once the container has finished running. ### Add host device to container (--device) -```bash +```console $ docker run --device=/dev/sdc:/dev/xvdc \ --device=/dev/sdd --device=/dev/zero:/dev/nulo \ -i -t \ @@ -564,7 +564,7 @@ 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. -```bash +```console $ docker run --device=/dev/sda:/dev/xvdc --rm -it ubuntu fdisk /dev/xvdc Command (m for help): q @@ -620,21 +620,21 @@ for more information. To use `--gpus`, specify which GPUs (or all) to use. If no value is provied, all available GPUs are used. The example below exposes all available GPUs. -```bash +```console $ docker run -it --rm --gpus all ubuntu nvidia-smi ``` Use the `device` option to specify GPUs. The example below exposes a specific GPU. -```bash +```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. -```bash -$ docker run -it --rm --gpus device=0,2 nvidia-smi +```console +$ docker run -it --rm --gpus '"device=0,2"' nvidia-smi ``` ### Restart policies (--restart) @@ -650,7 +650,7 @@ Docker supports the following restart policies: | `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. | -```bash +```console $ docker run --restart=always redis ``` @@ -667,16 +667,18 @@ 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`: -```bash -$ docker run --add-host=docker:10.180.0.1 --rm -it debian +```console +$ docker run --add-host=docker:93.184.216.34 --rm -it alpine -root@f38c87f2a42d:/# ping docker -PING docker (10.180.0.1): 48 data bytes -56 bytes from 10.180.0.1: icmp_seq=0 ttl=254 time=7.600 ms -56 bytes from 10.180.0.1: icmp_seq=1 ttl=254 time=30.705 ms -^C--- docker ping statistics --- -2 packets transmitted, 2 packets received, 0% packet loss -round-trip min/avg/max/stddev = 7.600/19.152/30.705/11.553 ms +/ # 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 ``` Sometimes you need to connect to the Docker host from within your @@ -688,7 +690,7 @@ 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`: -```bash +```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 ``` @@ -704,7 +706,7 @@ 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: -```bash +```console $ docker run --ulimit nofile=1024:1024 --rm debian sh -c "ulimit -n" 1024 ``` @@ -716,8 +718,8 @@ $ docker run --ulimit nofile=1024:1024 --rm debian sh -c "ulimit -n" > the default `ulimits` set on the daemon. The `as` option is disabled now. > In other words, the following script is not supported: > -> ```bash -> $ docker run -it --ulimit as=1024 fedora /bin/bash` +> ```console +> $ docker run -it --ulimit as=1024 fedora /bin/bash > ``` The values are sent to the appropriate `syscall` as they are set. @@ -729,7 +731,7 @@ Be careful setting `nproc` with the `ulimit` flag as `nproc` is designed by Linu maximum number of processes available to a user, not to a container. For example, start four containers with `daemon` user: -```bash +```console $ docker run -d -u daemon --ulimit nproc=3 busybox top $ docker run -d -u daemon --ulimit nproc=3 busybox top @@ -745,9 +747,12 @@ the three processes quota set for the `daemon` user. ### Stop container with signal (--stop-signal) -The `--stop-signal` flag sets the system call signal that will be sent to the container to exit. -This signal can be a valid unsigned number that matches a position in the kernel's syscall table, for instance 9, -or a signal name in the format SIGNAME, for instance SIGKILL. +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 default is `SIGTERM` if not specified. ### Optional security options (--security-opt) @@ -756,8 +761,16 @@ The `credentialspec` must be in the format `file://spec.txt` or `registry://keyn ### Stop container with timeout (--stop-timeout) -The `--stop-timeout` flag sets the timeout (in seconds) that a pre-defined (see `--stop-signal`) system call -signal that will be sent to the container to exit. After timeout elapses the container will be killed with SIGKILL. +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. + +If `--stop-timeout` is set to `-1`, no timeout is applied, and the daemon will +wait indefinitely for the container to exit. + +The default is determined by the daemon, and is 10 seconds for Linux containers, +and 30 seconds for Windows containers. ### Specify isolation technology for container (--isolation) @@ -766,7 +779,7 @@ Windows. The `--isolation ` option sets a container's isolation technolog On Linux, the only supported is the `default` option which uses Linux namespaces. These two commands are equivalent on Linux: -```bash +```console $ docker run -d busybox top $ docker run -d --isolation default busybox top ``` @@ -847,7 +860,7 @@ 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: -```bash +```console $ docker run --sysctl net.ipv4.ip_forward=1 someimage ``` diff --git a/docs/reference/commandline/save.md b/docs/reference/commandline/save.md index f7bf0593a3f6..562bf2d79912 100644 --- a/docs/reference/commandline/save.md +++ b/docs/reference/commandline/save.md @@ -26,7 +26,7 @@ each argument provided. ### Create a backup that can then be used with `docker load`. -```bash +```console $ docker save busybox > busybox.tar $ ls -sh busybox.tar @@ -48,14 +48,14 @@ $ docker save -o fedora-latest.tar fedora:latest You can use gzip to save the image file and make the backup smaller. -```bash -docker save myimage:latest | gzip > myimage_latest.tar.gz +```console +$ docker save myimage:latest | gzip > myimage_latest.tar.gz ``` ### Cherry-pick particular tags You can even cherry-pick particular tags of an image repository. -```bash +```console $ docker save -o ubuntu.tar ubuntu:lucid ubuntu:saucy ``` diff --git a/docs/reference/commandline/search.md b/docs/reference/commandline/search.md index 90d19e2631ed..51587921e943 100644 --- a/docs/reference/commandline/search.md +++ b/docs/reference/commandline/search.md @@ -32,7 +32,7 @@ Search [Docker Hub](https://hub.docker.com) for images This example displays images with a name containing 'busybox': -```bash +```console $ docker search busybox NAME DESCRIPTION STARS OFFICIAL AUTOMATED @@ -68,8 +68,9 @@ marclop/busybox-solr This example displays images with a name containing 'busybox', at least 3 stars and the description isn't truncated in the output: -```bash +```console $ docker search --filter=stars=3 --no-trunc busybox + NAME DESCRIPTION STARS OFFICIAL AUTOMATED busybox Busybox base image. 325 [OK] progrium/busybox 50 [OK] @@ -97,7 +98,7 @@ The currently supported filters are: This example displays images with a name containing 'busybox' and at least 3 stars: -```bash +```console $ docker search --filter stars=3 busybox NAME DESCRIPTION STARS OFFICIAL AUTOMATED @@ -111,7 +112,7 @@ radial/busyboxplus Full-chain, Internet enabled, busybox made... 8 This example displays images with a name containing 'busybox' and are automated builds: -```bash +```console $ docker search --filter is-automated=true busybox NAME DESCRIPTION STARS OFFICIAL AUTOMATED @@ -124,12 +125,11 @@ radial/busyboxplus Full-chain, Internet enabled, busybox made... 8 This example displays images with a name containing 'busybox', at least 3 stars and are official builds: -```bash +```console $ docker search --filter is-official=true --filter stars=3 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 +busybox Busybox base image. 325 [OK] ``` ### Format the output @@ -154,7 +154,7 @@ output the data exactly as the template declares. If you use the The following example uses a template without headers and outputs the `Name` and `StarCount` entries separated by a colon (`:`) for all images: -```bash +```console $ docker search --format "{{.Name}}: {{.StarCount}}" nginx nginx: 5441 @@ -171,7 +171,7 @@ maxexcloo/nginx: 7 This example outputs a table format: -```bash +```console $ docker search --format "table {{.Name}}\t{{.IsAutomated}}\t{{.IsOfficial}}" nginx NAME AUTOMATED OFFICIAL diff --git a/docs/reference/commandline/secret_create.md b/docs/reference/commandline/secret_create.md index 0c131b8a29c2..f09ffbd3c9d6 100644 --- a/docs/reference/commandline/secret_create.md +++ b/docs/reference/commandline/secret_create.md @@ -33,8 +33,8 @@ For detailed information about using secrets, refer to [manage sensitive data wi ### Create a secret -```bash -$ printf | docker secret create my_secret - +```console +$ printf "my super secret password" | docker secret create my_secret - onakdyv307se2tl7nl20anokv @@ -46,7 +46,7 @@ onakdyv307se2tl7nl20anokv my_secret 6 seconds ago 6 seconds ag ### Create a secret with a file -```bash +```console $ docker secret create my_secret ./secret.json dg426haahpi5ezmkkj5kyl3sn @@ -59,15 +59,16 @@ dg426haahpi5ezmkkj5kyl3sn my_secret 7 seconds ago 7 seconds ag ### Create a secret with labels -```bash -$ 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 ``` -```bash +```console $ docker secret inspect my_secret [ diff --git a/docs/reference/commandline/secret_inspect.md b/docs/reference/commandline/secret_inspect.md index ef4fe1e295a5..41c4724e4e83 100644 --- a/docs/reference/commandline/secret_inspect.md +++ b/docs/reference/commandline/secret_inspect.md @@ -23,7 +23,7 @@ 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. -Go's [text/template](http://golang.org/pkg/text/template/) package +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/). @@ -43,14 +43,14 @@ You can inspect a secret, either by its *name*, or *ID* For example, given the following secret: -```bash +```console $ docker secret ls ID NAME CREATED UPDATED eo7jnzguqgtpdah3cm5srfb97 my_secret 3 minutes ago 3 minutes ago ``` -```bash +```console $ docker secret inspect secret.json ``` @@ -82,7 +82,7 @@ You can use the --format option to obtain specific information about a secret. The following example command outputs the creation time of the secret. -```bash +```console $ docker secret inspect --format='{{.CreatedAt}}' eo7jnzguqgtpdah3cm5srfb97 2017-03-24 08:15:09.735271783 +0000 UTC diff --git a/docs/reference/commandline/secret_ls.md b/docs/reference/commandline/secret_ls.md index 45519b1ca847..395af6102eef 100644 --- a/docs/reference/commandline/secret_ls.md +++ b/docs/reference/commandline/secret_ls.md @@ -36,7 +36,7 @@ For detailed information about using secrets, refer to [manage sensitive data wi ## Examples -```bash +```console $ docker secret ls ID NAME CREATED UPDATED @@ -60,7 +60,7 @@ The currently supported filters are: The `id` filter matches all or prefix of a secret's id. -```bash +```console $ docker secret ls -f "id=6697bflskwj1998km1gnnjr38" ID NAME CREATED UPDATED @@ -75,7 +75,7 @@ a `label` and a value. The following filter matches all secrets with a `project` label regardless of its value: -```bash +```console $ docker secret ls --filter label=project ID NAME CREATED UPDATED @@ -85,7 +85,7 @@ mem02h8n73mybpgqjf0kfi1n0 test_secret About an hour ago Abou The following filter matches only services with the `project` label with the `project-a` value. -```bash +```console $ docker service ls --filter label=project=test ID NAME CREATED UPDATED @@ -98,7 +98,7 @@ 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`. -```bash +```console $ docker secret ls --filter name=test_secret ID NAME CREATED UPDATED @@ -128,7 +128,7 @@ output the data exactly as the template declares or, when using the The following example uses a template without headers and outputs the `ID` and `Name` entries separated by a colon (`:`) for all images: -```bash +```console $ docker secret ls --format "{{.ID}}: {{.Name}}" 77af4d6b9913: secret-1 @@ -139,7 +139,7 @@ b6fa739cedf5: secret-2 To list all secrets with their name and created date in a table format you can use: -```bash +```console $ docker secret ls --format "table {{.ID}}\t{{.Name}}\t{{.CreatedAt}}" ID NAME CREATED diff --git a/docs/reference/commandline/secret_rm.md b/docs/reference/commandline/secret_rm.md index 96505bfc060d..df99f958ca16 100644 --- a/docs/reference/commandline/secret_rm.md +++ b/docs/reference/commandline/secret_rm.md @@ -35,7 +35,7 @@ For detailed information about using secrets, refer to [manage sensitive data wi This example removes a secret: -```bash +```console $ docker secret rm secret.json sapth4csdo5b6wz2p5uimh5xg ``` diff --git a/docs/reference/commandline/service_create.md b/docs/reference/commandline/service_create.md index 800c9ae39345..77f8caf4bdec 100644 --- a/docs/reference/commandline/service_create.md +++ b/docs/reference/commandline/service_create.md @@ -101,7 +101,7 @@ Creates a service as described by the specified parameters. ### Create a service -```bash +```console $ docker service create --name redis redis:3.0.6 dmu1ept4cxcfe8k8lhtux3ro3 @@ -124,7 +124,7 @@ If your image is available on a private registry which requires login, use the your image is stored on `registry.example.com`, which is a private registry, use a command like the following: -```bash +```console $ docker login registry.example.com $ docker service create \ @@ -142,7 +142,7 @@ nodes are able to log into the registry and pull the image. 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: -```bash +```console $ docker service create --name redis --replicas=5 redis:3.0.6 4cdgfyky7ozwh3htjfw0d12qv @@ -156,7 +156,7 @@ 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`: -```bash +```console $ docker service ls ID NAME MODE REPLICAS IMAGE @@ -166,7 +166,7 @@ ID NAME MODE REPLICAS IMAGE Once all the tasks are created and `RUNNING`, the actual number of tasks is equal to the desired number: -```bash +```console $ docker service ls ID NAME MODE REPLICAS IMAGE @@ -180,7 +180,7 @@ Use the `--secret` flag to give a container access to a Create a service specifying a secret: -```bash +```console $ docker service create --name redis --secret secret.json redis:3.0.6 4cdgfyky7ozwh3htjfw0d12qv @@ -188,7 +188,7 @@ $ docker service create --name redis --secret secret.json redis:3.0.6 Create a service specifying the secret, target, user/group ID, and mode: -```bash +```console $ docker service create --name redis \ --secret source=ssh-key,target=ssh \ --secret source=app-key,target=app,uid=1000,gid=1001,mode=0400 \ @@ -217,13 +217,13 @@ 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`. -```bash +```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: -```bash +```console $ docker service create --name redis \ --config source=redis-conf,target=/etc/redis/redis.conf,mode=0400 redis:3.0.6 ``` @@ -236,7 +236,7 @@ the container. If a target is specified, that is used as the filename. ### Create a service with a rolling update policy -```bash +```console $ docker service create \ --replicas 10 \ --name redis \ @@ -254,7 +254,7 @@ tutorial](https://docs.docker.com/engine/swarm/swarm-tutorial/rolling-update/). This sets an environment variable for all tasks in a service. For example: -```bash +```console $ docker service create \ --name redis_2 \ --replicas 5 \ @@ -265,7 +265,7 @@ $ docker service create \ To specify multiple environment variables, specify multiple `--env` flags, each with a separate key-value pair. -```bash +```console $ docker service create \ --name redis_2 \ --replicas 5 \ @@ -279,7 +279,7 @@ $ docker service create \ This option sets the docker service containers hostname to a specific string. For example: -```bash +```console $ docker service create --name redis --hostname myredis redis:3.0.6 ``` @@ -288,7 +288,7 @@ $ docker service create --name redis --hostname myredis redis:3.0.6 A label is a `key=value` pair that applies metadata to a service. To label a service with two labels: -```bash +```console $ docker service create \ --name redis_2 \ --label com.example.foo="bar" @@ -592,7 +592,7 @@ or `--volume` flag for `docker run`, with some important exceptions: The following example creates a service that uses a named volume: -```bash +```console $ docker service create \ --name my-service \ --replicas 3 \ @@ -622,7 +622,7 @@ be deployed on a different node. The following command creates a service with three replicas with an anonymous volume on `/path/in/container`: -```bash +```console $ docker service create \ --name my-service \ --replicas 3 \ @@ -640,7 +640,7 @@ the task using them is complete. The following example bind-mounts a host directory at `/path/in/container` in the containers backing the service: -```bash +```console $ docker service create \ --name my-service \ --mount type=bind,source=/path/on/host,destination=/path/in/container \ @@ -655,7 +655,7 @@ service runs on each active node in the swarm. The following command creates a global service: -```bash +```console $ docker service create \ --name redis_2 \ --mode global \ @@ -688,7 +688,7 @@ 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: -```bash +```console $ docker service create \ --name redis_2 \ --constraint node.platform.os==linux \ @@ -703,7 +703,7 @@ 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: -```bash +```console $ docker service create \ --name web \ --constraint node.labels.region==east \ @@ -721,7 +721,7 @@ 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: -```bash +```console $ docker node update --label-add region=east yswe2dm4c5fdgtsrli1e8ya5l yswe2dm4c5fdgtsrli1e8ya5l @@ -736,7 +736,7 @@ 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: -```bash +```console $ docker service create \ --replicas 9 \ --name redis_2 \ @@ -787,7 +787,7 @@ 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): -```bash +```console $ docker service create \ --replicas 9 \ --name redis_2 \ @@ -812,7 +812,7 @@ 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. -```bash +```console $ docker service create --reserve-memory=4GB --name=too-big nginx:alpine ``` @@ -825,7 +825,7 @@ 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. -```bash +```console $ docker service create --limit-memory=4GB --name=too-big nginx:alpine ``` @@ -880,7 +880,7 @@ maintenance or datacenter failure. The example below illustrates this: -```bash +```console $ docker service create \ --name nginx \ --replicas 2 \ @@ -896,7 +896,7 @@ 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: -```bash +```console $ docker network create --driver overlay my-network etjpu59cykrptrgw0z0hk5snf @@ -908,7 +908,7 @@ access to the network. When you create a service and pass the `--network` flag to attach the service to the overlay network: -```bash +```console $ docker service create \ --replicas 3 \ --network my-network \ @@ -933,7 +933,7 @@ 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 (`:`). -```bash +```console $ docker service create --name my_web --replicas 3 --publish 8080:80 nginx ``` @@ -942,7 +942,7 @@ more options. The long format is preferred. You cannot specify the service's mode when using the short format. Here is an example of using the long format for the same service as above: -```bash +```console $ docker service create --name my_web --replicas 3 --publish published=8080,target=80 nginx ``` @@ -1018,7 +1018,7 @@ registry value must be located in: ### Create services using templates You can use templates for some flags of `service create`, using the syntax -provided by the Go's [text/template](http://golang.org/pkg/text/template/) package. +provided by the Go's [text/template](https://golang.org/pkg/text/template/) package. The supported flags are the following : @@ -1074,7 +1074,7 @@ Valid placeholders for the Go template are listed below: 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. -```bash +```console $ docker service create \ --name hosttempl \ --hostname="{{.Node.Hostname}}-{{.Node.ID}}-{{.Service.Name}}"\ @@ -1098,7 +1098,7 @@ By default, tasks scheduled on Windows nodes are run using the default isolation configured for this particular node. To force a specific isolation mode, you can use the `--isolation` flag: -```bash +```console $ docker service create --name myservice --isolation=process microsoft/nanoserver ``` @@ -1112,7 +1112,7 @@ Supported isolation modes on Windows are: 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): -```bash +```console $ docker service create \ --name cuda \ --generic-resource "NVIDIA-GPU=2" \ @@ -1129,7 +1129,7 @@ belonging to a job exits successfully (return value 0), the Task is marked as Jobs are started by using one of two modes, `replicated-job` or `global-job` -```bash +```console $ docker service create --name myjob \ --mode replicated-job \ bash "true" @@ -1159,12 +1159,13 @@ 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: -```bash -$ docker service create --name mythrottledjob \ - --mode replicated-job \ - --replicas 10 \ - --max-concurrent 2 \ - bash "true" +```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 diff --git a/docs/reference/commandline/service_inspect.md b/docs/reference/commandline/service_inspect.md index b3a97e6cd995..1c204ee0f3c4 100644 --- a/docs/reference/commandline/service_inspect.md +++ b/docs/reference/commandline/service_inspect.md @@ -24,7 +24,7 @@ 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. -Go's [text/template](http://golang.org/pkg/text/template/) package +Go's [text/template](https://golang.org/pkg/text/template/) package describes all the details of the format. > **Note** @@ -42,7 +42,7 @@ You can inspect a service, either by its *name*, or *ID* For example, given the following service; -```bash +```console $ docker service ls ID NAME MODE REPLICAS IMAGE dmu1ept4cxcf redis replicated 3/3 redis:3.0.6 @@ -51,7 +51,7 @@ dmu1ept4cxcf redis replicated 3/3 redis:3.0.6 Both `docker service inspect redis`, and `docker service inspect dmu1ept4cxcf` produce the same result: -```bash +```console $ docker service inspect redis ``` @@ -99,7 +99,7 @@ The output is in JSON format, for example: ] ``` -```bash +```console $ docker service inspect dmu1ept4cxcf [ @@ -118,7 +118,7 @@ $ docker service inspect dmu1ept4cxcf You can print the inspect output in a human-readable format instead of the default JSON output, by using the `--pretty` option: -```bash +```console $ docker service inspect --pretty frontend ID: c8wgl7q4ndfd52ni6qftkvnnp @@ -153,7 +153,7 @@ 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. -```bash +```console $ docker service inspect --format='{{.Spec.Mode.Replicated.Replicas}}' redis 10 diff --git a/docs/reference/commandline/service_ls.md b/docs/reference/commandline/service_ls.md index 8b9954b514c6..97f7763abe3f 100644 --- a/docs/reference/commandline/service_ls.md +++ b/docs/reference/commandline/service_ls.md @@ -36,14 +36,14 @@ This command lists services are running in the swarm. On a manager node: -```bash +```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 +hh08h9uu8uwr job replicated-job 1/1 (3/5 completed) nginx:latest ``` The `REPLICAS` column shows both the *actual* and *desired* number of tasks for @@ -67,7 +67,7 @@ The currently supported filters are: The `id` filter matches all or part of a service's id. -```bash +```console $ docker service ls -f "id=0bcjw" ID NAME MODE REPLICAS IMAGE 0bcjwfh8ychr redis replicated 1/1 redis:3.0.6 @@ -81,7 +81,7 @@ a `label` and a value. The following filter matches all services with a `project` label regardless of its value: -```bash +```console $ docker service ls --filter label=project ID NAME MODE REPLICAS IMAGE 01sl1rp6nj5u frontend2 replicated 1/1 nginx:alpine @@ -92,7 +92,7 @@ ID NAME MODE REPLICAS IMAGE The following filter matches only services with the `project` label with the `project-a` value. -```bash +```console $ docker service ls --filter label=project=project-a ID NAME MODE REPLICAS IMAGE 36xvvwwauej0 frontend replicated 5/5 nginx:alpine @@ -105,7 +105,7 @@ The `mode` filter matches on the mode (either `replicated` or `global`) of a ser The following filter matches only `global` services. -```bash +```console $ docker service ls --filter mode=global ID NAME MODE REPLICAS IMAGE w7y0v2yrn620 top global 1/1 busybox @@ -117,7 +117,7 @@ The `name` filter matches on all or part of a service's name. The following filter matches services with a name containing `redis`. -```bash +```console $ docker service ls --filter name=redis ID NAME MODE REPLICAS IMAGE 0bcjwfh8ychr redis replicated 1/1 redis:3.0.6 @@ -146,7 +146,7 @@ output the data exactly as the template declares or, when using the The following example uses a template without headers and outputs the `ID`, `Mode`, and `Replicas` entries separated by a colon (`:`) for all services: -```bash +```console $ docker service ls --format "{{.ID}}: {{.Mode}} {{.Replicas}}" 0zmvwuiu3vue: replicated 10/10 diff --git a/docs/reference/commandline/service_ps.md b/docs/reference/commandline/service_ps.md index 66c9a52d3b86..2e0ba6bef507 100644 --- a/docs/reference/commandline/service_ps.md +++ b/docs/reference/commandline/service_ps.md @@ -38,7 +38,7 @@ Lists the tasks that are running as part of the specified services. The following command shows all the tasks that are part of the `redis` service: -```bash +```console $ docker service ps redis ID NAME IMAGE NODE DESIRED STATE CURRENT STATE ERROR PORTS @@ -58,7 +58,7 @@ 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: -```bash +```console $ docker service ps redis ID NAME IMAGE NODE DESIRED STATE CURRENT STATE ERROR PORTS @@ -83,7 +83,7 @@ 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; -```bash +```console $ docker service ps --no-trunc redis ID NAME IMAGE NODE DESIRED STATE CURRENT STATE ERROR PORTS @@ -112,7 +112,7 @@ The currently supported filters are: The `id` filter matches on all or a prefix of a task's ID. -```bash +```console $ docker service ps -f "id=8" redis ID NAME IMAGE NODE DESIRED STATE CURRENT STATE ERROR PORTS @@ -124,8 +124,9 @@ ID NAME IMAGE NODE DESIRED STATE CURRENT STATE The `name` filter matches on task names. -```bash +```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 ``` @@ -135,8 +136,9 @@ qihejybwf1x5 redis.1 redis:3.0.6 manager1 Running Running 8 seconds The `node` filter matches on a node name or a node ID. -```bash +```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 @@ -173,8 +175,9 @@ output the data exactly as the template declares or, when using the The following example uses a template without headers and outputs the `Name` and `Image` entries separated by a colon (`:`) for all tasks: -```bash +```console $ docker service ps --format "{{.Name}}: {{.Image}}" top + top.1: busybox top.2: busybox top.3: busybox diff --git a/docs/reference/commandline/service_rm.md b/docs/reference/commandline/service_rm.md index ec8cddcb3cfb..015d43507611 100644 --- a/docs/reference/commandline/service_rm.md +++ b/docs/reference/commandline/service_rm.md @@ -33,7 +33,7 @@ Removes the specified services from the swarm. Remove the `redis` service: -```bash +```console $ docker service rm redis redis diff --git a/docs/reference/commandline/service_rollback.md b/docs/reference/commandline/service_rollback.md index 4d8745330b0e..2cd276fe1763 100644 --- a/docs/reference/commandline/service_rollback.md +++ b/docs/reference/commandline/service_rollback.md @@ -43,13 +43,13 @@ previous version, having one replica. Create a service with a single replica: -```bash +```console $ docker service create --name my-service -p 8080:80 nginx:alpine ``` Confirm that the service is running with a single replica: -```bash +```console $ docker service ls ID NAME MODE REPLICAS IMAGE PORTS @@ -58,7 +58,7 @@ xbw728mf6q0d my-service replicated 1/1 Update the service to use three replicas: -```bash +```console $ docker service update --replicas=3 my-service $ docker service ls @@ -70,7 +70,7 @@ xbw728mf6q0d my-service replicated 3/3 Now roll back the service to its previous version, and confirm it is running a single replica again: -```bash +```console $ docker service rollback my-service $ docker service ls diff --git a/docs/reference/commandline/service_scale.md b/docs/reference/commandline/service_scale.md index 866669ffa7d2..a61337d07b6c 100644 --- a/docs/reference/commandline/service_scale.md +++ b/docs/reference/commandline/service_scale.md @@ -37,7 +37,7 @@ service while keeping the service active in the swarm you can set the scale to 0 The following command scales the "frontend" service to 50 tasks. -```bash +```console $ docker service scale frontend=50 frontend scaled to 50 @@ -45,7 +45,7 @@ frontend scaled to 50 The following command tries to scale a global service to 10 tasks and returns an error. -```bash +```console $ docker service create --mode global --name backend backend:latest b4g08uwuairexjub6ome6usqh @@ -58,7 +58,7 @@ 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. -```bash +```console $ docker service ls --filter name=frontend ID NAME MODE REPLICAS IMAGE @@ -68,7 +68,7 @@ ID NAME MODE REPLICAS IMAGE You can also scale a service using the [`docker service update`](service_update.md) command. The following commands are equivalent: -```bash +```console $ docker service scale frontend=50 $ docker service update --replicas=50 frontend ``` @@ -79,7 +79,7 @@ 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: -```bash +```console $ docker service scale backend=3 frontend=5 backend scaled to 3 diff --git a/docs/reference/commandline/service_update.md b/docs/reference/commandline/service_update.md index 68626395b11d..a1545ae979ee 100644 --- a/docs/reference/commandline/service_update.md +++ b/docs/reference/commandline/service_update.md @@ -127,13 +127,13 @@ rolling restart without any changes to the service parameters. ### Update a service -```bash +```console $ docker service update --limit-cpu 2 redis ``` ### Perform a rolling restart with no parameter changes -```bash +```console $ docker service update --force --update-parallelism 1 --update-delay 30s redis ``` @@ -161,7 +161,7 @@ service name. - The `--mount-rm` flag takes the `target` path of the mount. -```bash +```console $ docker service create \ --name=myservice \ --mount type=volume,source=test-data,target=/somewhere \ @@ -189,7 +189,7 @@ reference. The following example adds a published service port to an existing service. -```bash +```console $ docker service update \ --publish-add published=8080,target=80 \ myservice @@ -204,7 +204,7 @@ reference. The following example adds a new alias name to an existing service already connected to network my-network: -```bash +```console $ docker service update \ --network-rm my-network \ --network-add name=my-network,alias=web1 \ @@ -219,7 +219,7 @@ This will revert the service to the configuration that was in place before the m The following example updates the number of replicas for the service from 4 to 5, and then rolls back to the previous configuration. -```bash +```console $ docker service update --replicas=5 web web @@ -230,9 +230,10 @@ ID NAME MODE REPLICAS IMAGE 80bvrzp6vxf3 web replicated 0/5 nginx:alpine ``` + Roll back the `web` service... -```bash +```console $ docker service update --rollback web web @@ -246,7 +247,7 @@ ID NAME MODE REPLICAS IMAGE Other options can be combined with `--rollback` as well, for example, `--update-delay 0s` to execute the rollback without a delay between tasks: -```bash +```console $ docker service update \ --rollback \ --update-delay 0s @@ -283,7 +284,7 @@ secrets. The following example adds a secret named `ssh-2` and removes `ssh-1`: -```bash +```console $ docker service update \ --secret-add source=ssh-2,target=ssh-2 \ --secret-rm ssh-1 \ diff --git a/docs/reference/commandline/stack_deploy.md b/docs/reference/commandline/stack_deploy.md index 0be6dc50c08c..858be7667657 100644 --- a/docs/reference/commandline/stack_deploy.md +++ b/docs/reference/commandline/stack_deploy.md @@ -43,7 +43,7 @@ Create and update a stack from a `compose` file on the swarm. The `deploy` command supports compose file version `3.0` and above. -```bash +```console $ docker stack deploy --compose-file docker-compose.yml vossibility Ignoring unsupported options: links @@ -60,7 +60,7 @@ Creating service vossibility_lookupd The Compose file can also be provided as standard input with `--compose-file -`: -```bash +```console $ cat docker-compose.yml | docker stack deploy --compose-file - vossibility Ignoring unsupported options: links @@ -79,7 +79,7 @@ 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. -```bash +```console $ docker stack deploy --compose-file docker-compose.yml -c docker-compose.prod.yml vossibility Ignoring unsupported options: links @@ -96,7 +96,7 @@ Creating service vossibility_lookupd You can verify that the services were correctly created: -```bash +```console $ docker service ls ID NAME MODE REPLICAS IMAGE diff --git a/docs/reference/commandline/stack_ls.md b/docs/reference/commandline/stack_ls.md index 0d7517a33693..96a42e729873 100644 --- a/docs/reference/commandline/stack_ls.md +++ b/docs/reference/commandline/stack_ls.md @@ -37,7 +37,7 @@ Lists the stacks. The following command shows all stacks and some additional information: -```bash +```console $ docker stack ls ID SERVICES ORCHESTRATOR @@ -65,7 +65,7 @@ the data exactly as the template declares or, when using the The following example uses a template without headers and outputs the `Name` and `Services` entries separated by a colon (`:`) for all stacks: -```bash +```console $ docker stack ls --format "{{.Name}}: {{.Services}}" web-server: 1 web-cache: 4 diff --git a/docs/reference/commandline/stack_ps.md b/docs/reference/commandline/stack_ps.md index bc0f27efc5ff..a427eeb8a110 100644 --- a/docs/reference/commandline/stack_ps.md +++ b/docs/reference/commandline/stack_ps.md @@ -40,8 +40,9 @@ Lists the tasks that are running as part of the specified stack. The following command shows all the tasks that are part of the `voting` stack: -```bash +```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 @@ -71,8 +72,9 @@ The currently supported filters are: The `id` filter matches on all or a prefix of a task's ID. -```bash +```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 @@ -82,8 +84,9 @@ t72q3z038jeh voting_redis.2 redis:alpine node3 Running The `name` filter matches on task names. -```bash +```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 @@ -93,8 +96,9 @@ t72q3z038jeh voting_redis.2 redis:alpine node3 Running The `node` filter matches on a node name or a node ID. -```bash +```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 @@ -105,8 +109,9 @@ tz6j82jnwrx7 voting_db.1 postgres:9.4 The `desired-state` filter can take the values `running`, `shutdown`, `ready` or `accepted`. -```bash +```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 @@ -142,8 +147,9 @@ output the data exactly as the template declares or, when using the The following example uses a template without headers and outputs the `Name` and `Image` entries separated by a colon (`:`) for all tasks: -```bash +```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 @@ -158,8 +164,9 @@ voting_redis.2: redis:alpine The `--no-resolve` option shows IDs for task name, without mapping IDs to Names. -```bash +```console $ docker stack ps --no-resolve voting + 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 @@ -178,8 +185,9 @@ 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: -```bash +```console $ docker stack ps --no-trunc voting + 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 @@ -196,7 +204,7 @@ t72q3z038jehe1wbh9gdum076 voting_redis.2 redis:alpine@sha256:9cd405cd1e The `-q ` or `--quiet` option only shows IDs of the tasks in the stack. This example outputs all task IDs of the "voting" stack; -```bash +```console $ docker stack ps -q voting xim5bcqtgk1b q7yik0ks1in6 @@ -212,14 +220,14 @@ 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; -```bash +```console $ docker inspect $(docker stack ps -q voting) [ { "ID": "xim5bcqtgk1b1gk0krq1", "Version": { -(...) +<...> ``` ## Related commands diff --git a/docs/reference/commandline/stack_rm.md b/docs/reference/commandline/stack_rm.md index a6fb12eb4d4b..ff2a9019d842 100644 --- a/docs/reference/commandline/stack_rm.md +++ b/docs/reference/commandline/stack_rm.md @@ -38,7 +38,7 @@ Remove the stack from the swarm. This will remove the stack with the name `myapp`. Services, networks, and secrets associated with the stack will be removed. -```bash +```console $ docker stack rm myapp Removing service myapp_redis @@ -52,7 +52,7 @@ Removing network myapp_frontend This will remove all the specified stacks, `myapp` and `vossibility`. Services, networks, and secrets associated with all the specified stacks will be removed. -```bash +```console $ docker stack rm myapp vossibility Removing service myapp_redis diff --git a/docs/reference/commandline/stack_services.md b/docs/reference/commandline/stack_services.md index a3ee74335b30..d689e728cb50 100644 --- a/docs/reference/commandline/stack_services.md +++ b/docs/reference/commandline/stack_services.md @@ -36,7 +36,7 @@ Lists the services that are running as part of the specified stack. The following command shows all services in the `myapp` stack: -```bash +```console $ docker stack services myapp ID NAME REPLICAS IMAGE COMMAND @@ -52,7 +52,7 @@ Multiple filter flags are combined as an `OR` filter. The following command shows both the `web` and `db` services: -```bash +```console $ docker stack services --filter name=myapp_web --filter name=myapp_db myapp ID NAME REPLICAS IMAGE COMMAND @@ -103,7 +103,7 @@ output the data exactly as the template declares or, when using the The following example uses a template without headers and outputs the `ID`, `Mode`, and `Replicas` entries separated by a colon (`:`) for all services: -```bash +```console $ docker stack services --format "{{.ID}}: {{.Mode}} {{.Replicas}}" 0zmvwuiu3vue: replicated 10/10 diff --git a/docs/reference/commandline/start.md b/docs/reference/commandline/start.md index 9c13505b1378..1a710048b984 100644 --- a/docs/reference/commandline/start.md +++ b/docs/reference/commandline/start.md @@ -20,6 +20,6 @@ Options: ## Examples -```bash +```console $ docker start my_container ``` diff --git a/docs/reference/commandline/stats.md b/docs/reference/commandline/stats.md index 5b5d3f6a1e5e..754a2f2316ff 100644 --- a/docs/reference/commandline/stats.md +++ b/docs/reference/commandline/stats.md @@ -53,7 +53,7 @@ the `/containers/(id)/stats` API endpoint. Running `docker stats` on all running containers against a Linux daemon. -```bash +```console $ docker stats CONTAINER ID NAME CPU % MEM USAGE / LIMIT MEM % NET I/O BLOCK I/O PIDS @@ -77,7 +77,7 @@ following columns are shown. Running `docker stats` on multiple containers by name and id against a Linux daemon. -```bash +```console $ docker stats awesome_brattain 67b2525d8ad1 CONTAINER ID NAME CPU % MEM USAGE / LIMIT MEM % NET I/O BLOCK I/O PIDS @@ -85,9 +85,16 @@ b95a83497c91 awesome_brattain 0.28% 5.629MiB / 1.952GiB 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. + +```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. -```bash +```console $ docker stats --all --format "table {{.Container}}\t{{.CPUPerc}}\t{{.MemUsage}}" fervent_panini 5acfcb1b4fd1 drunk_visvesvaraya big_heisenberg CONTAINER CPU % MEM USAGE / LIMIT @@ -151,7 +158,7 @@ outputs the data exactly as the template declares or, when using the The following example uses a template without headers and outputs the `Container` and `CPUPerc` entries separated by a colon (`:`) for all images: -```bash +```console $ docker stats --format "{{.Container}}: {{.CPUPerc}}" 09d3bb5b1604: 6.61% @@ -162,7 +169,7 @@ $ docker stats --format "{{.Container}}: {{.CPUPerc}}" To list all containers statistics with their name, CPU percentage and memory usage in a table format you can use: -```bash +```console $ docker stats --format "table {{.Container}}\t{{.CPUPerc}}\t{{.MemUsage}}" CONTAINER CPU % PRIV WORKING SET diff --git a/docs/reference/commandline/stop.md b/docs/reference/commandline/stop.md index e4c567fb7829..fdc7d0ae72c6 100644 --- a/docs/reference/commandline/stop.md +++ b/docs/reference/commandline/stop.md @@ -19,10 +19,12 @@ Options: ## Description The main process inside the container will receive `SIGTERM`, and after a grace -period, `SIGKILL`. +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`. ## Examples -```bash +```console $ docker stop my_container ``` diff --git a/docs/reference/commandline/swarm_ca.md b/docs/reference/commandline/swarm_ca.md index e342ce5a6c4c..c51157ca8236 100644 --- a/docs/reference/commandline/swarm_ca.md +++ b/docs/reference/commandline/swarm_ca.md @@ -38,8 +38,9 @@ View or rotate the current swarm CA certificate. Run the `docker swarm ca` command without any options to view the current root CA certificate in PEM format. -```bash +```console $ docker swarm ca + -----BEGIN CERTIFICATE----- MIIBazCCARCgAwIBAgIUJPzo67QC7g8Ebg2ansjkZ8CbmaswCgYIKoZIzj0EAwIw EzERMA8GA1UEAxMIc3dhcm0tY2EwHhcNMTcwNTAzMTcxMDAwWhcNMzcwNDI4MTcx @@ -55,7 +56,7 @@ lIwQqLkJ48SQqCjG1DBTSBsHmMSRT+6mE2My+Z3GKA== 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 @@ -65,7 +66,7 @@ desired root digest: sha256:05da740cf2577a25224c53019e2cce99bcc5ba09664ad6bb2a94 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 diff --git a/docs/reference/commandline/swarm_init.md b/docs/reference/commandline/swarm_init.md index 696aaa8dde57..310b8341dcc3 100644 --- a/docs/reference/commandline/swarm_init.md +++ b/docs/reference/commandline/swarm_init.md @@ -37,8 +37,9 @@ in the newly created single-node swarm. ## Examples -```bash +```console $ docker swarm init --advertise-addr 192.168.99.121 + Swarm initialized: current node (bvz81updecsj6wjz393c09vti) is now a manager. To add a worker to this swarm, run the following command: @@ -132,20 +133,21 @@ 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; -```bash -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: -```bash -docker info -... +```console +$ docker info +<...> ClusterID: 9vs5ygs0gguyyec4iqf2314c0 Managers: 1 Nodes: 1 Data Path Port: 7777 -... +<...> ``` ### `--default-addr-pool` diff --git a/docs/reference/commandline/swarm_join-token.md b/docs/reference/commandline/swarm_join-token.md index fd85af7e02a8..eab393d9c82d 100644 --- a/docs/reference/commandline/swarm_join-token.md +++ b/docs/reference/commandline/swarm_join-token.md @@ -40,7 +40,7 @@ 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: -```bash +```console $ docker swarm join-token worker To add a worker to this swarm, run the following command: @@ -60,7 +60,7 @@ To add a manager to this swarm, run the following command: Use the `--rotate` flag to generate a new join token for the specified role: -```bash +```console $ docker swarm join-token --rotate worker Successfully rotated worker join token. @@ -76,7 +76,7 @@ After using `--rotate`, only the new token will be valid for joining with the sp The `-q` (or `--quiet`) flag only prints the token: -```bash +```console $ docker swarm join-token -q worker SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-b30ljddcqhef9b9v4rs7mel7t diff --git a/docs/reference/commandline/swarm_join.md b/docs/reference/commandline/swarm_join.md index fd47a1076c28..9c2aa0dcf1d9 100644 --- a/docs/reference/commandline/swarm_join.md +++ b/docs/reference/commandline/swarm_join.md @@ -32,9 +32,10 @@ pass a worker token, the node joins as a worker. The example below demonstrates joining a manager node using a manager token. -```bash +```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 @@ -49,9 +50,10 @@ should join as workers instead. Managers should be stable hosts that have static The example below demonstrates joining a worker node using a worker token. -```bash +```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 diff --git a/docs/reference/commandline/swarm_leave.md b/docs/reference/commandline/swarm_leave.md index 0d1e8454783c..2ba2b758ee9d 100644 --- a/docs/reference/commandline/swarm_leave.md +++ b/docs/reference/commandline/swarm_leave.md @@ -31,7 +31,7 @@ no longer be used after the manager leaves, such as in a single-node swarm. Consider the following swarm, as seen from the manager: -```bash +```console $ docker node ls ID HOSTNAME STATUS AVAILABILITY MANAGER STATUS @@ -42,7 +42,7 @@ dvfxp4zseq4s0rih1selh0d20 * manager1 Ready Active Leader To remove `worker2`, issue the following command from `worker2` itself: -```bash +```console $ docker swarm leave Node left the default swarm. diff --git a/docs/reference/commandline/swarm_unlock-key.md b/docs/reference/commandline/swarm_unlock-key.md index 0d191dfb67dc..2f713bc193ff 100644 --- a/docs/reference/commandline/swarm_unlock-key.md +++ b/docs/reference/commandline/swarm_unlock-key.md @@ -35,7 +35,7 @@ run the `docker swarm unlock-key` command without any arguments: ## Examples -```bash +```console $ docker swarm unlock-key To unlock a swarm manager after it restarts, run the `docker swarm unlock` @@ -50,7 +50,7 @@ will not be able to restart the manager. Use the `--rotate` flag to rotate the unlock key to a new, randomly-generated key: -```bash +```console $ docker swarm unlock-key --rotate Successfully rotated manager unlock key. @@ -66,7 +66,7 @@ will not be able to restart the manager. The `-q` (or `--quiet`) flag only prints the key: -```bash +```console $ docker swarm unlock-key -q SWMKEY-1-7c37Cc8654o6p38HnroywCi19pllOnGtbdZEgtKxZu8 diff --git a/docs/reference/commandline/swarm_unlock.md b/docs/reference/commandline/swarm_unlock.md index dbcde50c7189..eb99300ab68d 100644 --- a/docs/reference/commandline/swarm_unlock.md +++ b/docs/reference/commandline/swarm_unlock.md @@ -31,7 +31,7 @@ enabled, and is also available from the `docker swarm unlock-key` command. ## Examples -```bash +```console $ docker swarm unlock Please enter unlock key: ``` diff --git a/docs/reference/commandline/swarm_update.md b/docs/reference/commandline/swarm_update.md index 0c190ef33145..e4a7f90ecb06 100644 --- a/docs/reference/commandline/swarm_update.md +++ b/docs/reference/commandline/swarm_update.md @@ -35,7 +35,7 @@ Updates a swarm with new parameter values. ## Examples -```bash +```console $ docker swarm update --cert-expiry 720h ``` diff --git a/docs/reference/commandline/system_df.md b/docs/reference/commandline/system_df.md index 015585ab9110..a5f1e6d23d1d 100644 --- a/docs/reference/commandline/system_df.md +++ b/docs/reference/commandline/system_df.md @@ -26,7 +26,7 @@ amount of disk space used by the docker daemon. By default the command will just show a summary of the data used: -```bash +```console $ docker system df TYPE TOTAL ACTIVE SIZE RECLAIMABLE @@ -37,7 +37,7 @@ Local Volumes 2 1 36 B A more detailed view can be requested using the `-v, --verbose` flag: -```bash +```console $ docker system df -v Images space usage: @@ -101,7 +101,7 @@ the data exactly as the template declares or, when using the The following example uses a template without headers and outputs the `Type` and `TotalCount` entries separated by a colon (`:`): -```bash +```console $ docker system df --format "{{.Type}}: {{.TotalCount}}" Images: 2 @@ -112,7 +112,7 @@ Local Volumes: 1 To list the disk usage with size and reclaimable size in a table format you can use: -```bash +```console $ docker system df --format "table {{.Type}}\t{{.Size}}\t{{.Reclaimable}}" TYPE SIZE RECLAIMABLE diff --git a/docs/reference/commandline/system_events.md b/docs/reference/commandline/system_events.md index 1f4a04ec2262..f9d7fe73650c 100644 --- a/docs/reference/commandline/system_events.md +++ b/docs/reference/commandline/system_events.md @@ -147,11 +147,11 @@ The currently supported filters are: If a format (`--format`) is specified, the given template will be executed instead of the default -format. Go's [text/template](http://golang.org/pkg/text/template/) package +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 http://jsonlines.org/ . +Lines. For information about JSON Lines, please refer to https://jsonlines.org/ . ## Examples @@ -161,13 +161,13 @@ You'll need two shells for this example. **Shell 1: Listening for events:** -```bash +```console $ docker system events ``` **Shell 2: Start and Stop containers:** -```bash +```console $ docker create --name test alpine:latest top $ docker start test $ docker stop test @@ -192,7 +192,7 @@ To exit the `docker system events` command, use `CTRL+C`. You can filter the output by an absolute timestamp or relative time on the host machine, using the following different time syntaxes: -```bash +```console $ docker system events --since 1483283804 2017-01-05T00:35:41.241772953+08:00 volume create testVol (driver=local) @@ -243,7 +243,7 @@ $ docker system events --since '10m' The following commands show several different ways to filter the `docker event` output. -```bash +```console $ docker system events --filter 'event=stop' 2017-01-05T00:40:22.880175420+08:00 container stop 0fdb...ff37 (image=alpine:latest, name=test) @@ -316,7 +316,7 @@ $ docker system events --filter 'type=plugin' ### Format the output -```bash +```console $ docker system events --filter 'type=container' --format 'Type={{.Type}} Status={{.Status}} ID={{.ID}}' Type=container Status=create ID=2ee349dac409e97974ce8d01b70d250b85e0ba8189299c126a87812311951e26 @@ -329,7 +329,7 @@ Type=container Status=destroy ID=2ee349dac409e97974ce8d01b70d250b85e0ba8189299 #### Format as JSON -```bash +```console $ docker system events --format '{{json .}}' {"status":"create","id":"196016a57679bf42424484918746a9474cd905dd993c4d0f4.. diff --git a/docs/reference/commandline/system_prune.md b/docs/reference/commandline/system_prune.md index d2fa825070ec..19213bae0cdb 100644 --- a/docs/reference/commandline/system_prune.md +++ b/docs/reference/commandline/system_prune.md @@ -26,7 +26,7 @@ and optionally, volumes. ## Examples -```bash +```console $ docker system prune WARNING! This will remove: @@ -56,7 +56,7 @@ 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: -```bash +```console $ docker system prune -a --volumes WARNING! This will remove: diff --git a/docs/reference/commandline/tag.md b/docs/reference/commandline/tag.md index 8eb7715bb770..421560a39d30 100644 --- a/docs/reference/commandline/tag.md +++ b/docs/reference/commandline/tag.md @@ -40,7 +40,7 @@ to [*Share images on Docker Hub*](https://docs.docker.com/get-started/part3/). To tag a local image with ID "0e5574283393" into the "fedora" repository with "version1.0": -```bash +```console $ docker tag 0e5574283393 fedora/httpd:version1.0 ``` @@ -49,7 +49,7 @@ $ docker tag 0e5574283393 fedora/httpd:version1.0 To tag a local image with name "httpd" into the "fedora" repository with "version1.0": -```bash +```console $ docker tag httpd fedora/httpd:version1.0 ``` @@ -61,7 +61,7 @@ existing local version `httpd:latest`. To tag a local image with name "httpd" and tag "test" into the "fedora" repository with "version1.0.test": -```bash +```console $ docker tag httpd:test fedora/httpd:version1.0.test ``` @@ -70,6 +70,6 @@ $ docker tag httpd:test fedora/httpd:version1.0.test 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). -```bash +```console $ docker tag 0e5574283393 myregistryhost:5000/fedora/httpd:version1.0 ``` diff --git a/docs/reference/commandline/trust_inspect.md b/docs/reference/commandline/trust_inspect.md index 7d4bde5db22b..48103117a908 100644 --- a/docs/reference/commandline/trust_inspect.md +++ b/docs/reference/commandline/trust_inspect.md @@ -29,7 +29,7 @@ new tags. Use the `docker trust inspect` to get trust information about an image. The following example prints trust information for the `alpine:latest` image: -```bash +```console $ docker trust inspect alpine:latest ``` @@ -79,7 +79,7 @@ and the `Signers` responsible for the signature. If signers are set up for the repository via other `docker trust` commands, `docker trust inspect` includes a `Signers` key: -```bash +```console $ docker trust inspect my-image:purple ``` @@ -157,7 +157,7 @@ The output is in JSON format, for example: If the image tag is unsigned or unavailable, `docker trust inspect` does not display any signed tags. -```bash +```console $ docker trust inspect unsigned-img No signatures or cannot access unsigned-img @@ -166,7 +166,7 @@ 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: -```bash +```console $ docker trust inspect alpine:unsigned ``` @@ -204,7 +204,7 @@ The output is in JSON format, for example: If no tag is specified, `docker trust inspect` will report details for all signed tags in the repository: -```bash +```console $ docker trust inspect alpine ``` @@ -273,7 +273,7 @@ The output is in JSON format, for example: `docker trust inspect` can take multiple repositories and images as arguments, and reports the results in an ordered list: -```bash +```console $ docker trust inspect alpine notary ``` @@ -388,7 +388,7 @@ JSON output, by using the `--pretty` option: ### Get details about signatures for a single image tag -```bash +```console $ docker trust inspect --pretty alpine:latest SIGNED TAG DIGEST SIGNERS @@ -410,7 +410,7 @@ 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`: -```bash +```console $ docker trust inspect --pretty my-image:purple SIGNED TAG DIGEST SIGNERS @@ -431,7 +431,7 @@ Root Key: 40b66ccc8b176be8c7d365a17f3e046d1c3494e053dd57cfeacfe2e19c4f8e8f However, if other tags are signed in the same image repository, `docker trust inspect` reports relevant key information. -```bash +```console $ docker trust inspect --pretty alpine:unsigned No signatures for alpine:unsigned @@ -444,7 +444,7 @@ Root Key: a2489bcac7a79aa67b19b96c4a3bf0c675ffdf00c6d2fabe1a5df1115e80adce ### Get details about signatures for all image tags in a repository -```bash +```console $ docker trust inspect --pretty alpine SIGNED TAG DIGEST SIGNERS @@ -466,7 +466,7 @@ Root Key: a2489bcac7a79aa67b19b96c4a3bf0c675ffdf00c6d2fabe1a5df1115e80adce Here's an example with signers that are set up by `docker trust` commands: -```bash +```console $ docker trust inspect --pretty my-image SIGNED TAG DIGEST SIGNERS diff --git a/docs/reference/commandline/trust_key_generate.md b/docs/reference/commandline/trust_key_generate.md index 7baa2be7fe0b..71634b96ee36 100644 --- a/docs/reference/commandline/trust_key_generate.md +++ b/docs/reference/commandline/trust_key_generate.md @@ -25,7 +25,7 @@ Options: ### Generate a key-pair -```bash +```console $ docker trust key generate alice Generating key for alice... @@ -44,7 +44,7 @@ be used directly by `docker trust signer add`. Provide the `--dir` argument to specify a directory to generate the key in: -```bash +```console $ docker trust key generate alice --dir /foo Generating key for alice... diff --git a/docs/reference/commandline/trust_key_load.md b/docs/reference/commandline/trust_key_load.md index 2d5280a15893..d0553af1ddd4 100644 --- a/docs/reference/commandline/trust_key_load.md +++ b/docs/reference/commandline/trust_key_load.md @@ -28,7 +28,7 @@ To add a signer to a repository use `docker trust signer add`. For a private key `alice.pem` with permissions `-rw-------` -```bash +```console $ docker trust key load alice.pem Loading key from "alice.pem"... @@ -39,7 +39,7 @@ Successfully imported key from alice.pem To specify a name use the `--name` flag: -```bash +```console $ docker trust key load --name alice-key alice.pem Loading key from "alice.pem"... diff --git a/docs/reference/commandline/trust_revoke.md b/docs/reference/commandline/trust_revoke.md index 8423c33ad857..e373b936cc89 100644 --- a/docs/reference/commandline/trust_revoke.md +++ b/docs/reference/commandline/trust_revoke.md @@ -27,7 +27,7 @@ Options: Here's an example of a repo with two signed tags: -```bash +```console $ docker trust inspect --pretty example/trust-demo SIGNED TAG DIGEST SIGNERS red 852cc04935f930a857b630edc4ed6131e91b22073bcc216698842e44f64d2943 alice @@ -46,7 +46,7 @@ Root Key: 3cb2228f6561e58f46dbc4cda4fcaff9d5ef22e865a94636f82450d1d2234949 When `alice`, one of the signers, runs `docker trust revoke`: -```bash +```console $ docker trust revoke example/trust-demo:red Enter passphrase for delegation key with ID 27d42a8: Successfully deleted signature for example/trust-demo:red @@ -54,7 +54,7 @@ Successfully deleted signature for example/trust-demo:red After revocation, the tag is removed from the list of released tags: -```bash +```console $ docker trust inspect --pretty example/trust-demo SIGNED TAG DIGEST SIGNERS blue f1c38dbaeeb473c36716f6494d803fbfbe9d8a76916f7c0093f227821e378197 alice, bob @@ -74,7 +74,7 @@ Root Key: 3cb2228f6561e58f46dbc4cda4fcaff9d5ef22e865a94636f82450d1d2234949 When no tag is specified, `docker trust` revokes all signatures that you have a signing key for. -```bash +```console $ docker trust inspect --pretty example/trust-demo SIGNED TAG DIGEST SIGNERS red 852cc04935f930a857b630edc4ed6131e91b22073bcc216698842e44f64d2943 alice @@ -93,7 +93,7 @@ Root Key: 3cb2228f6561e58f46dbc4cda4fcaff9d5ef22e865a94636f82450d1d2234949 When `alice`, one of the signers, runs `docker trust revoke`: -```bash +```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: @@ -102,7 +102,7 @@ Successfully deleted signature for example/trust-demo All tags that have `alice`'s signature on them are removed from the list of released tags: -```bash +```console $ docker trust inspect --pretty example/trust-demo No signatures for example/trust-demo diff --git a/docs/reference/commandline/trust_sign.md b/docs/reference/commandline/trust_sign.md index c623dac7d17e..9166f6690841 100644 --- a/docs/reference/commandline/trust_sign.md +++ b/docs/reference/commandline/trust_sign.md @@ -27,7 +27,7 @@ Options: Given an image: -```bash +```console $ docker trust inspect --pretty example/trust-demo SIGNED TAG DIGEST SIGNERS @@ -40,7 +40,7 @@ Root Key: 246d360f7c53a9021ee7d4259e3c5692f3f1f7ad4737b1ea8c7b8da741ad980b Sign a new tag with `docker trust sign`: -```bash +```console $ docker trust sign example/trust-demo:v2 Signing and pushing trust metadata for example/trust-demo:v2 @@ -60,7 +60,7 @@ Successfully signed docker.io/example/trust-demo:v2 Use `docker trust inspect --pretty` to list the new signature: -```bash +```console $ docker trust inspect --pretty example/trust-demo SIGNED TAG DIGEST SIGNERS @@ -76,7 +76,7 @@ Root Key: 246d360f7c53a9021ee7d4259e3c5692f3f1f7ad4737b1ea8c7b8da741ad980b Given an image: -```bash +```console $ docker trust inspect --pretty example/trust-demo No signatures for example/trust-demo @@ -95,7 +95,7 @@ Root Key: 3cb2228f6561e58f46dbc4cda4fcaff9d5ef22e865a94636f82450d1d2234949 Sign a new tag with `docker trust sign`: -```bash +```console $ docker trust sign example/trust-demo:v1 Signing and pushing trust metadata for example/trust-demo:v1 @@ -113,7 +113,7 @@ Successfully signed docker.io/example/trust-demo:v1 `docker trust inspect --pretty` lists the new signature: -```bash +```console $ docker trust inspect --pretty example/trust-demo SIGNED TAG DIGEST SIGNERS @@ -134,13 +134,13 @@ Root Key: 3cb2228f6561e58f46dbc4cda4fcaff9d5ef22e865a94636f82450d1d2234949 When signing an image on a repo for the first time, `docker trust sign` sets up new keys before signing the image. -```bash +```console $ docker trust inspect --pretty example/trust-demo No signatures or cannot access example/trust-demo ``` -```bash +```console $ docker trust sign example/trust-demo:v1 Signing and pushing trust metadata for example/trust-demo:v1 @@ -165,7 +165,7 @@ Enter passphrase for alice key with ID 6d52b29: Successfully signed docker.io/example/trust-demo:v1 ``` -```bash +```console $ docker trust inspect --pretty example/trust-demo SIGNED TAG DIGEST SIGNERS diff --git a/docs/reference/commandline/trust_signer_add.md b/docs/reference/commandline/trust_signer_add.md index 71c7197cc022..9c594a55508a 100644 --- a/docs/reference/commandline/trust_signer_add.md +++ b/docs/reference/commandline/trust_signer_add.md @@ -26,7 +26,7 @@ Options: To add a new signer, `alice`, to this repository: -```bash +```console $ docker trust inspect --pretty example/trust-demo No signatures for example/trust-demo @@ -44,7 +44,7 @@ Root Key: 3cb2228f6561e58f46dbc4cda4fcaff9d5ef22e865a94636f82450d1d2234949 Add `alice` with `docker trust signer add`: -```bash +```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: @@ -53,7 +53,7 @@ Successfully added signer: alice to example/trust-demo `docker trust inspect --pretty` now lists `alice` as a valid signer: -```bash +```console $ docker trust inspect --pretty example/trust-demo No signatures for example/trust-demo @@ -74,13 +74,13 @@ Root Key: 3cb2228f6561e58f46dbc4cda4fcaff9d5ef22e865a94636f82450d1d2234949 When adding a signer on a repo for the first time, `docker trust signer add` sets up a new repo if it doesn't exist. -```bash +```console $ docker trust inspect --pretty example/trust-demo No signatures or cannot access example/trust-demo ``` -```bash +```console $ docker trust signer add alice example/trust-demo --key alice.crt Initializing signed repository for example/trust-demo... @@ -93,7 +93,7 @@ Adding signer "alice" to example/trust-demo... Successfully added signer: alice to example/trust-demo ``` -```bash +```console $ docker trust inspect --pretty example/trust-demo No signatures for example/trust-demo @@ -113,7 +113,7 @@ Root Key: 748121c14bd1461f6c58cb3ef39087c8fdc7633bb11a98af844fd9a04e208103 ## Add a signer to multiple repos To add a signer, `alice`, to multiple repositories: -```bash +```console $ docker trust inspect --pretty example/trust-demo SIGNED TAG DIGEST SIGNERS @@ -128,7 +128,8 @@ Administrative keys for example/trust-demo: Repository Key: ecc457614c9fc399da523a5f4e24fe306a0a6ee1cc79a10e4555b3c6ab02f71e Root Key: 3cb2228f6561e58f46dbc4cda4fcaff9d5ef22e865a94636f82450d1d2234949 ``` -```bash + +```console $ docker trust inspect --pretty example/trust-demo2 SIGNED TAG DIGEST SIGNERS @@ -143,9 +144,10 @@ Administrative keys for example/trust-demo2: Repository Key: ece554f14c9fc399da523a5f4e24fe306a0a6ee1cc79a10e4553d2ab20a8d9268 Root Key: 3cb2228f6561e58f46dbc4cda4fcaff9d5ef22e865a94636f82450d1d2234949 ``` + Add `alice` to both repositories with a single `docker trust signer add` command: -```bash +```console $ docker trust signer add alice example/trust-demo example/trust-demo2 --key alice.crt Adding signer "alice" to example/trust-demo... @@ -160,7 +162,7 @@ Successfully added signer: alice to example/trust-demo2 `docker trust inspect --pretty` now lists `alice` as a valid signer of both `example/trust-demo` and `example/trust-demo2`: -```bash +```console $ docker trust inspect --pretty example/trust-demo SIGNED TAG DIGEST SIGNERS @@ -177,7 +179,7 @@ Repository Key: 95b9e5514c9fc399da523a5f4e24fe306a0a6ee1cc79a10e4555b3c6ab02f71e Root Key: 3cb2228f6561e58f46dbc4cda4fcaff9d5ef22e865a94636f82450d1d2234949 ``` -```bash +```console $ docker trust inspect --pretty example/trust-demo2 SIGNED TAG DIGEST SIGNERS @@ -197,7 +199,7 @@ Root Key: 3cb2228f6561e58f46dbc4cda4fcaff9d5ef22e865a94636f82450d1d2234949 `docker trust signer add` adds signers to repositories on a best effort basis, so it will continue to add the signer to subsequent repositories if one attempt fails: -```bash +```console $ docker trust signer add alice example/unauthorized example/authorized --key alice.crt Adding signer "alice" to example/unauthorized... diff --git a/docs/reference/commandline/trust_signer_remove.md b/docs/reference/commandline/trust_signer_remove.md index 55a2c65a7e72..5882def68920 100644 --- a/docs/reference/commandline/trust_signer_remove.md +++ b/docs/reference/commandline/trust_signer_remove.md @@ -25,7 +25,8 @@ Options: ### Remove a signer from a repo To remove an existing signer, `alice`, from this repository: -```bash + +```console $ docker trust inspect --pretty example/trust-demo No signatures for example/trust-demo @@ -44,7 +45,7 @@ Root Key: 3cb2228f6561e58f46dbc4cda4fcaff9d5ef22e865a94636f82450d1d2234949 Remove `alice` with `docker trust signer remove`: -```bash +```console $ docker trust signer remove alice example/trust-demo Removing signer "alice" from image example/trust-demo... @@ -54,7 +55,7 @@ Successfully removed alice from example/trust-demo `docker trust inspect --pretty` now does not list `alice` as a valid signer: -```bash +```console $ docker trust inspect --pretty example/trust-demo No signatures for example/trust-demo @@ -74,7 +75,7 @@ Root Key: 3cb2228f6561e58f46dbc4cda4fcaff9d5ef22e865a94636f82450d1d2234949 To remove an existing signer, `alice`, from multiple repositories: -```bash +```console $ docker trust inspect --pretty example/trust-demo SIGNED TAG DIGEST SIGNERS @@ -91,7 +92,7 @@ Repository Key: 95b9e5514c9fc399da523a5f4e24fe306a0a6ee1cc79a10e4555b3c6ab02f71e Root Key: 3cb2228f6561e58f46dbc4cda4fcaff9d5ef22e865a94636f82450d1d2234949 ``` -```bash +```console $ docker trust inspect --pretty example/trust-demo2 SIGNED TAG DIGEST SIGNERS @@ -110,7 +111,7 @@ Root Key: 3cb2228f6561e58f46dbc4cda4fcaff9d5ef22e865a94636f82450d1d2234949 Remove `alice` from both images with a single `docker trust signer remove` command: -```bash +```console $ docker trust signer remove alice example/trust-demo example/trust-demo2 Removing signer "alice" from image example/trust-demo... @@ -125,7 +126,7 @@ 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`: -```bash +```console $ docker trust inspect --pretty example/trust-demo SIGNED TAG DIGEST SIGNERS @@ -141,7 +142,7 @@ Repository Key: ecc457614c9fc399da523a5f4e24fe306a0a6ee1cc79a10e4555b3c6ab02f71e Root Key: 3cb2228f6561e58f46dbc4cda4fcaff9d5ef22e865a94636f82450d1d2234949 ``` -```bash +```console $ docker trust inspect --pretty example/trust-demo2 SIGNED TAG DIGEST SIGNERS @@ -161,7 +162,7 @@ Root Key: 3cb2228f6561e58f46dbc4cda4fcaff9d5ef22e865a94636f82450d1d2234949 basis, so it will continue to remove the signer from subsequent repositories if one attempt fails: -```bash +```console $ docker trust signer remove alice example/unauthorized example/authorized Removing signer "alice" from image example/unauthorized... diff --git a/docs/reference/commandline/unpause.md b/docs/reference/commandline/unpause.md index 0cced5fb60dd..9f47077093c8 100644 --- a/docs/reference/commandline/unpause.md +++ b/docs/reference/commandline/unpause.md @@ -26,7 +26,7 @@ for further details. ## Examples -```bash +```console $ docker unpause my_container my_container ``` diff --git a/docs/reference/commandline/update.md b/docs/reference/commandline/update.md index 43b650b7a26b..3264a4b468e7 100644 --- a/docs/reference/commandline/update.md +++ b/docs/reference/commandline/update.md @@ -59,7 +59,7 @@ 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: -```bash +```console $ docker update --cpu-shares 512 abebf7571666 ``` @@ -67,7 +67,7 @@ $ docker update --cpu-shares 512 abebf7571666 To update multiple resource configurations for multiple containers: -```bash +```console $ docker update --cpu-shares 512 -m 300M abebf7571666 hopeful_morse ``` @@ -85,19 +85,19 @@ the container before updating kernel memory. For example, if you started a container with this command: -```bash +```console $ docker run -dit --name test --kernel-memory 50M ubuntu bash ``` You can update kernel memory while the container is running: -```bash +```console $ docker update --kernel-memory 80M test ``` If you started a container *without* kernel memory initialized: -```bash +```console $ docker run -dit --name test2 --memory 300M ubuntu bash ``` @@ -116,7 +116,7 @@ container. To update restart policy for one or more containers: -```bash +```console $ docker update --restart=on-failure:3 abebf7571666 hopeful_morse ``` diff --git a/docs/reference/commandline/version.md b/docs/reference/commandline/version.md index fa02281b89b5..0ca8e19e7e22 100644 --- a/docs/reference/commandline/version.md +++ b/docs/reference/commandline/version.md @@ -22,14 +22,14 @@ Options: By default, this will render all version information in an easy to read layout. If a format is specified, the given template will be executed instead. -Go's [text/template](http://golang.org/pkg/text/template/) package +Go's [text/template](https://golang.org/pkg/text/template/) package describes all the details of the format. ## Examples ### Default output -```bash +```console $ docker version Client: @@ -64,7 +64,7 @@ Server: ### Get the server version -```bash +```console $ docker version --format '{{.Server.Version}}' 19.03.8 @@ -72,7 +72,7 @@ $ docker version --format '{{.Server.Version}}' ### Dump raw JSON data -```bash +```console $ docker version --format '{{json .}}' {"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"}} @@ -82,7 +82,7 @@ $ docker version --format '{{json .}}' The following example prints the currently used [`docker context`](context.md): -```bash +```console $ docker version --format='{{.Client.Context}}' default ``` @@ -94,7 +94,7 @@ 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` -```bash +```console function docker_context_prompt() { PS1="context: $(docker version --format='{{.Client.Context}}')> " } @@ -105,7 +105,7 @@ PROMPT_COMMAND=docker_context_prompt After reloading the `~/.bashrc`, the prompt now shows the currently selected `docker context`: -```bash +```console $ source ~/.bashrc context: default> docker context create --docker host=unix:///var/run/docker.sock my-context my-context diff --git a/docs/reference/commandline/volume_create.md b/docs/reference/commandline/volume_create.md index 0b34d5929cf3..c2054d189946 100644 --- a/docs/reference/commandline/volume_create.md +++ b/docs/reference/commandline/volume_create.md @@ -27,7 +27,7 @@ not specified, Docker generates a random name. Create a volume and then configure the container to use it: -```bash +```console $ docker volume create hello hello @@ -58,7 +58,7 @@ assumes you want to re-use the existing volume and does not return an error. Some volume drivers may take options to customize the volume creation. Use the `-o` or `--opt` flags to pass driver options: -```bash +```console $ docker volume create --driver fake \ --opt tardis=blue \ --opt timey=wimey \ @@ -74,12 +74,12 @@ 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](http://man7.org/linux/man-pages/man8/mount.8.html). +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. -```bash +```console $ docker volume create --driver local \ --opt type=tmpfs \ --opt device=tmpfs \ @@ -89,7 +89,7 @@ $ docker volume create --driver local \ Another example that uses `btrfs`: -```bash +```console $ docker volume create --driver local \ --opt type=btrfs \ --opt device=/dev/sda2 \ @@ -99,7 +99,7 @@ $ docker volume create --driver local \ Another example that uses `nfs` to mount the `/path/to/dir` in `rw` mode from `192.168.1.1`: -```bash +```console $ docker volume create --driver local \ --opt type=nfs \ --opt o=addr=192.168.1.1,rw \ diff --git a/docs/reference/commandline/volume_inspect.md b/docs/reference/commandline/volume_inspect.md index d7c6aa2cdd56..5204310ac754 100644 --- a/docs/reference/commandline/volume_inspect.md +++ b/docs/reference/commandline/volume_inspect.md @@ -21,12 +21,12 @@ Options: 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](http://golang.org/pkg/text/template/) package describes all the +[text/template](https://golang.org/pkg/text/template/) package describes all the details of the format. ## Examples -```bash +```console $ docker volume create myvolume myvolume @@ -34,7 +34,7 @@ myvolume Use the `docker volume inspect` comment to inspect the configuration of the volume: -```bash +```console $ docker volume inspect myvolume ``` @@ -53,10 +53,11 @@ The output is in JSON format, for example: } ] ``` + Use the `--format` flag to format the output using a Go template, for example, to print the `Mountpoint` property: -```bash +```console $ docker volume inspect --format '{{ .Mountpoint }}' myvolume /var/lib/docker/volumes/myvolume/_data diff --git a/docs/reference/commandline/volume_ls.md b/docs/reference/commandline/volume_ls.md index c697ead13313..f010cfd60500 100644 --- a/docs/reference/commandline/volume_ls.md +++ b/docs/reference/commandline/volume_ls.md @@ -34,7 +34,8 @@ information about available filter options. ## Examples ### Create a volume -```bash + +```console $ docker volume create rosemary rosemary @@ -66,7 +67,7 @@ The currently supported filters are: The `dangling` filter matches on all volumes not referenced by any containers -```bash +```console $ docker run -d -v tyler:/tmpwork busybox f86a7dd02898067079c99ceacd810149060a70528eff3754d0b0f1a93bd0af18 @@ -81,7 +82,7 @@ The `driver` filter matches volumes based on their driver. The following example matches volumes that are created with the `local` driver: -```bash +```console $ docker volume ls -f driver=local DRIVER VOLUME NAME @@ -96,7 +97,7 @@ a `label` and a value. First, let's create some volumes to illustrate this; -```bash +```console $ docker volume create the-doctor --label is-timelord=yes the-doctor @@ -108,7 +109,7 @@ daleks The following example filter matches volumes with the `is-timelord` label regardless of its value. -```bash +```console $ docker volume ls --filter label=is-timelord DRIVER VOLUME NAME @@ -121,7 +122,7 @@ As the above example demonstrates, both volumes with `is-timelord=yes`, and Filtering on both `key` *and* `value` of the label, produces the expected result: -```bash +```console $ docker volume ls --filter label=is-timelord=yes DRIVER VOLUME NAME @@ -131,7 +132,7 @@ local the-doctor Specifying multiple label filter produces an "and" search; all conditions should be met; -```bash +```console $ docker volume ls --filter label=is-timelord=yes --filter label=is-timelord=no DRIVER VOLUME NAME @@ -143,7 +144,7 @@ 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. -```bash +```console $ docker volume ls -f name=rose DRIVER VOLUME NAME @@ -173,7 +174,7 @@ output the data exactly as the template declares or, when using the The following example uses a template without headers and outputs the `Name` and `Driver` entries separated by a colon (`:`) for all volumes: -```bash +```console $ docker volume ls --format "{{.Name}}: {{.Driver}}" vol1: local diff --git a/docs/reference/commandline/volume_prune.md b/docs/reference/commandline/volume_prune.md index 074f3d1c8036..00eeff33328f 100644 --- a/docs/reference/commandline/volume_prune.md +++ b/docs/reference/commandline/volume_prune.md @@ -23,7 +23,7 @@ Remove all unused local volumes. Unused local volumes are those which are not re ## Examples -```bash +```console $ docker volume prune WARNING! This will remove all local volumes not used by at least one container. diff --git a/docs/reference/commandline/volume_rm.md b/docs/reference/commandline/volume_rm.md index 8095c489a74b..f7b63ed0592a 100644 --- a/docs/reference/commandline/volume_rm.md +++ b/docs/reference/commandline/volume_rm.md @@ -25,7 +25,7 @@ Remove one or more volumes. You cannot remove a volume that is in use by a conta ## Examples -```bash +```console $ docker volume rm hello hello diff --git a/docs/reference/commandline/wait.md b/docs/reference/commandline/wait.md index 2a903b13ed66..85e485452e38 100644 --- a/docs/reference/commandline/wait.md +++ b/docs/reference/commandline/wait.md @@ -24,27 +24,27 @@ Options: Start a container in the background. -```bash +```console $ docker run -dit --name=my_container ubuntu bash ``` Run `docker wait`, which should block until the container exits. -```bash +```console $ docker wait my_container ``` In another terminal, stop the first container. The `docker wait` command above returns the exit code. -```bash +```console $ docker stop my_container ``` This is the same `docker wait` command from above, but it now exits, returning `0`. -```bash +```console $ docker wait my_container 0 diff --git a/docs/reference/glossary.md b/docs/reference/glossary.md index 84963f38be1a..533b78185cf4 100644 --- a/docs/reference/glossary.md +++ b/docs/reference/glossary.md @@ -20,7 +20,7 @@ A list of terms used around the Docker project. aufs (advanced multi layered unification filesystem) is a Linux [filesystem](#filesystem) that Docker supports as a storage backend. It implements the -[union mount](http://en.wikipedia.org/wiki/Union_mount) for Linux file systems. +[union mount](https://en.wikipedia.org/wiki/Union_mount) for Linux file systems. ## base image @@ -28,7 +28,7 @@ An image that has no parent is a **base image**. ## boot2docker -[boot2docker](http://boot2docker.io/) is a lightweight Linux distribution made +[boot2docker](https://boot2docker.io/) is a lightweight Linux distribution made specifically to run Docker containers. The boot2docker management tool for Mac and Windows was deprecated and replaced by [`docker-machine`](#machine) which you can install with the Docker Toolbox. ## bridge @@ -56,7 +56,7 @@ For more information about Docker networking, see ## btrfs btrfs (B-tree file system) is a Linux [filesystem](#filesystem) that Docker -supports as a storage backend. It is a [copy-on-write](http://en.wikipedia.org/wiki/Copy-on-write) +supports as a storage backend. It is a [copy-on-write](https://en.wikipedia.org/wiki/Copy-on-write) filesystem. ## build @@ -241,7 +241,7 @@ for docker containers in a cluster. ## overlay storage driver OverlayFS is a [filesystem](#filesystem) service for Linux which implements a -[union mount](http://en.wikipedia.org/wiki/Union_mount) for other file systems. +[union mount](https://en.wikipedia.org/wiki/Union_mount) for other file systems. It is supported by the Docker daemon as a storage driver. ## registry diff --git a/docs/reference/run.md b/docs/reference/run.md index ad4dd36baf58..197af741abb7 100644 --- a/docs/reference/run.md +++ b/docs/reference/run.md @@ -1,6 +1,8 @@ --- description: "Configure containers at runtime" keywords: "docker, run, configure, runtime" +redirect_from: +- /reference/run/ ---