From 763606cdde553d77bf473488b733785d82186b46 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Miloslav=20Trma=C4=8D?= Date: Thu, 29 May 2025 00:30:19 +0200 Subject: [PATCH] Improve documentation of --authfile MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Don't claim that Windows uses XDG_RUNTIME_DIR, defer to the authoritative man page. - Consistently document the (regrettable?) REGISTRY_AUTH_FILE environment variable. - Consistently refer to "registry credentials file", not "authentication file". - (Also deemphasizes (docker login), I'm not sure we want that.) Signed-off-by: Miloslav Trmač --- cmd/skopeo/utils.go | 4 ++-- .../skopeo-experimental-image-proxy.1.md | 8 ++++++-- docs/skopeo-copy.1.md | 13 +++++++------ docs/skopeo-delete.1.md | 8 ++++++-- docs/skopeo-inspect.1.md | 8 ++++++-- docs/skopeo-list-tags.1.md | 10 +++++++--- docs/skopeo-login.1.md | 10 +++++----- docs/skopeo-logout.1.md | 9 ++++----- docs/skopeo-sync.1.md | 12 ++++++++---- docs/skopeo.1.md | 4 +++- 10 files changed, 54 insertions(+), 32 deletions(-) diff --git a/cmd/skopeo/utils.go b/cmd/skopeo/utils.go index 3008443b..bf277e3a 100644 --- a/cmd/skopeo/utils.go +++ b/cmd/skopeo/utils.go @@ -109,7 +109,7 @@ type sharedImageOptions struct { func sharedImageFlags() (pflag.FlagSet, *sharedImageOptions) { opts := sharedImageOptions{} fs := pflag.FlagSet{} - fs.StringVar(&opts.authFilePath, "authfile", os.Getenv("REGISTRY_AUTH_FILE"), "path of the authentication file. Default is ${XDG_RUNTIME_DIR}/containers/auth.json") + fs.StringVar(&opts.authFilePath, "authfile", os.Getenv("REGISTRY_AUTH_FILE"), "path of the registry credentials file. Default is ${XDG_RUNTIME_DIR}/containers/auth.json") return fs, &opts } @@ -152,7 +152,7 @@ func dockerImageFlags(global *globalOptions, shared *sharedImageOptions, depreca fs := pflag.FlagSet{} if flagPrefix != "" { // the non-prefixed flag is handled by a shared flag. - fs.Var(commonFlag.NewOptionalStringValue(&flags.authFilePath), flagPrefix+"authfile", "path of the authentication file. Default is ${XDG_RUNTIME_DIR}/containers/auth.json") + fs.Var(commonFlag.NewOptionalStringValue(&flags.authFilePath), flagPrefix+"authfile", "path of the registry credentials file. Default is ${XDG_RUNTIME_DIR}/containers/auth.json") } fs.Var(commonFlag.NewOptionalStringValue(&flags.credsOption), flagPrefix+"creds", "Use `USERNAME[:PASSWORD]` for accessing the registry") fs.Var(commonFlag.NewOptionalStringValue(&flags.userName), flagPrefix+"username", "Username for accessing the registry") diff --git a/docs-experimental/skopeo-experimental-image-proxy.1.md b/docs-experimental/skopeo-experimental-image-proxy.1.md index a1d2cd24..226b30f7 100644 --- a/docs-experimental/skopeo-experimental-image-proxy.1.md +++ b/docs-experimental/skopeo-experimental-image-proxy.1.md @@ -100,8 +100,12 @@ The command also supports common skopeo options for interacting with image regis **--authfile**=*path* -Path of the authentication file. Default is ${XDG_RUNTIME\_DIR}/containers/auth.json, which is set using `skopeo login`. -If the authorization state is not found there, $HOME/.docker/config.json is checked, which is set using `docker login`. +Path of the primary registry credentials file. On Linux, the default is ${XDG\_RUNTIME\_DIR}/containers/auth.json. +See **containers-auth.json**(5) for more details about the credential search mechanism and defaults on other platforms. + +Use `skopeo login` to manage the credentials. + +The default value of this option is read from the `REGISTRY\_AUTH\_FILE` environment variable. **--cert-dir**=*path* diff --git a/docs/skopeo-copy.1.md b/docs/skopeo-copy.1.md index 5cea7981..c16d20e0 100644 --- a/docs/skopeo-copy.1.md +++ b/docs/skopeo-copy.1.md @@ -34,19 +34,20 @@ the images in the list, and the list itself. **--authfile** _path_ -Path of the authentication file. Default is ${XDG_RUNTIME\_DIR}/containers/auth.json, which is set using `skopeo login`. -If the authorization state is not found there, $HOME/.docker/config.json is checked, which is set using `docker login`. +Path of the primary registry credentials file. On Linux, the default is ${XDG\_RUNTIME\_DIR}/containers/auth.json. +See **containers-auth.json**(5) for more details about the credential search mechanism and defaults on other platforms. -Note: You can also override the default path of the authentication file by setting the REGISTRY\_AUTH\_FILE -environment variable. `export REGISTRY_AUTH_FILE=path` +Use `skopeo login` to manage the credentials. + +The default value of this option is read from the `REGISTRY\_AUTH\_FILE` environment variable. **--src-authfile** _path_ -Path of the authentication file for the source registry. Uses path given by `--authfile`, if not provided. +Path of the primary registry credentials file for the source registry. Uses path given by `--authfile`, if not provided. **--dest-authfile** _path_ -Path of the authentication file for the destination registry. Uses path given by `--authfile`, if not provided. +Path of the primary registry credentials file for the destination registry. Uses path given by `--authfile`, if not provided. **--dest-shared-blob-dir** _directory_ diff --git a/docs/skopeo-delete.1.md b/docs/skopeo-delete.1.md index 4aa0a8dd..6f6ab6eb 100644 --- a/docs/skopeo-delete.1.md +++ b/docs/skopeo-delete.1.md @@ -35,8 +35,12 @@ See also [skopeo(1)](skopeo.1.md) for options placed before the subcommand name. **--authfile** _path_ -Path of the authentication file. Default is ${XDG_RUNTIME\_DIR}/containers/auth.json, which is set using `skopeo login`. -If the authorization state is not found there, $HOME/.docker/config.json is checked, which is set using `docker login`. +Path of the primary registry credentials file. On Linux, the default is ${XDG\_RUNTIME\_DIR}/containers/auth.json. +See **containers-auth.json**(5) for more details about the credential search mechanism and defaults on other platforms. + +Use `skopeo login` to manage the credentials. + +The default value of this option is read from the `REGISTRY\_AUTH\_FILE` environment variable. **--creds** _username[:password]_ diff --git a/docs/skopeo-inspect.1.md b/docs/skopeo-inspect.1.md index f8877626..c3034506 100644 --- a/docs/skopeo-inspect.1.md +++ b/docs/skopeo-inspect.1.md @@ -21,8 +21,12 @@ See also [skopeo(1)](skopeo.1.md) for options placed before the subcommand name. **--authfile** _path_ -Path of the authentication file. Default is ${XDG\_RUNTIME\_DIR}/containers/auth.json, which is set using `skopeo login`. -If the authorization state is not found there, $HOME/.docker/config.json is checked, which is set using `docker login`. +Path of the primary registry credentials file. On Linux, the default is ${XDG\_RUNTIME\_DIR}/containers/auth.json. +See **containers-auth.json**(5) for more details about the credential search mechanism and defaults on other platforms. + +Use `skopeo login` to manage the credentials. + +The default value of this option is read from the `REGISTRY\_AUTH\_FILE` environment variable. **--cert-dir** _path_ diff --git a/docs/skopeo-list-tags.1.md b/docs/skopeo-list-tags.1.md index 64257a79..fb5f470d 100644 --- a/docs/skopeo-list-tags.1.md +++ b/docs/skopeo-list-tags.1.md @@ -16,8 +16,12 @@ See also [skopeo(1)](skopeo.1.md) for options placed before the subcommand name. **--authfile** _path_ -Path of the authentication file. Default is ${XDG\_RUNTIME\_DIR}/containers/auth.json, which is set using `skopeo login`. - If the authorization state is not found there, $HOME/.docker/config.json is checked, which is set using `docker login`. +Path of the updated registry credentials file. On Linux, the default is ${XDG\_RUNTIME\_DIR}/containers/auth.json. +See **containers-auth.json**(5) for more details about the credential search mechanism and defaults on other platforms. + +Use `skopeo login` to manage the credentials. + +The default value of this option is read from the `REGISTRY\_AUTH\_FILE` environment variable. **--creds** _username[:password]_ for accessing the registry. @@ -64,7 +68,7 @@ Repository names are transport-specific references as each transport may have it This commands refers to repositories using a _transport_`:`_details_ format. The following formats are supported: **docker://**_docker-repository-reference_ - A repository in a registry implementing the "Docker Registry HTTP API V2". By default, uses the authorization state in either `$XDG_RUNTIME_DIR/containers/auth.json`, which is set using `(skopeo login)`. If the authorization state is not found there, `$HOME/.docker/config.json` is checked, which is set using `(docker login)`. + A repository in a registry implementing the "Docker Registry HTTP API V2". A _docker-repository-reference_ is of the form: **registryhost:port/repositoryname** which is similar to an _image-reference_ but with no tag or digest allowed as the last component (e.g no `:latest` or `@sha256:xyz`) Examples of valid docker-repository-references: diff --git a/docs/skopeo-login.1.md b/docs/skopeo-login.1.md index 28189d9c..c843966a 100644 --- a/docs/skopeo-login.1.md +++ b/docs/skopeo-login.1.md @@ -10,8 +10,8 @@ skopeo\-login - Login to a container registry. **skopeo login** logs into a specified registry server with the correct username and password. **skopeo login** reads in the username and password from STDIN. The username and password can also be set using the **username** and **password** flags. -The path of the authentication file can be specified by the user by setting the **authfile** -flag. The default path used is **${XDG\_RUNTIME\_DIR}/containers/auth.json**. +The path of the credentials file can be specified by the user by setting the **authfile** +flag. ## OPTIONS @@ -31,10 +31,10 @@ Username for registry **--authfile**=*path* -Path of the authentication file. Default is ${XDG\_RUNTIME\_DIR}/containers/auth.json +Path of the managed registry credentials file. On Linux, the default is ${XDG\_RUNTIME\_DIR}/containers/auth.json. +See **containers-auth.json**(5) for more details about the default on other platforms. -Note: You can also override the default path of the authentication file by setting the REGISTRY\_AUTH\_FILE -environment variable. `export REGISTRY_AUTH_FILE=path` +The default value of this option is read from the `REGISTRY\_AUTH\_FILE` environment variable. **--compat-auth-file**=*path* diff --git a/docs/skopeo-logout.1.md b/docs/skopeo-logout.1.md index 1837bb44..c7470575 100644 --- a/docs/skopeo-logout.1.md +++ b/docs/skopeo-logout.1.md @@ -8,8 +8,7 @@ skopeo\-logout - Logout of a container registry. ## DESCRIPTION **skopeo logout** logs out of a specified registry server by deleting the cached credentials -stored in the **auth.json** file. The path of the authentication file can be overridden by the user by setting the **authfile** flag. -The default path used is **${XDG\_RUNTIME\_DIR}/containers/auth.json**. +stored in the **auth.json** file. The path of the credentials file can be overridden by the user by setting the **authfile** flag. All the cached credentials can be removed by setting the **all** flag. ## OPTIONS @@ -18,10 +17,10 @@ See also [skopeo(1)](skopeo.1.md) for options placed before the subcommand name. **--authfile**=*path* -Path of the authentication file. Default is ${XDG\_RUNTIME\_DIR}/containers/auth.json +Path of the managed registry credentials file. On Linux, the default is ${XDG\_RUNTIME\_DIR}/containers/auth.json. +See **containers-auth.json**(5) for more details about the default on other platforms. -Note: You can also override the default path of the authentication file by setting the REGISTRY\_AUTH\_FILE -environment variable. `export REGISTRY_AUTH_FILE=path` +The default value of this option is read from the `REGISTRY\_AUTH\_FILE` environment variable. **--compat-auth-file**=*path* diff --git a/docs/skopeo-sync.1.md b/docs/skopeo-sync.1.md index ef48790f..8addfa21 100644 --- a/docs/skopeo-sync.1.md +++ b/docs/skopeo-sync.1.md @@ -39,16 +39,20 @@ the images in the list, and the list itself. **--authfile** _path_ -Path of the authentication file. Default is ${XDG\_RUNTIME\_DIR}/containers/auth.json, which is set using `skopeo login`. -If the authorization state is not found there, $HOME/.docker/config.json is checked, which is set using `docker login`. +Path of the primary registry credentials file. On Linux, the default is ${XDG\_RUNTIME\_DIR}/containers/auth.json. +See **containers-auth.json**(5) for more details about the credential search mechanism and defaults on other platforms. + +Use `skopeo login` to manage the credentials. + +The default value of this option is read from the `REGISTRY\_AUTH\_FILE` environment variable. **--src-authfile** _path_ -Path of the authentication file for the source registry. Uses path given by `--authfile`, if not provided. +Path of the primary registry credentials file for the source registry. Uses path given by `--authfile`, if not provided. **--dest-authfile** _path_ -Path of the authentication file for the destination registry. Uses path given by `--authfile`, if not provided. +Path of the primary registry credentials file for the destination registry. Uses path given by `--authfile`, if not provided. **--dry-run** diff --git a/docs/skopeo.1.md b/docs/skopeo.1.md index d1448062..497ced55 100644 --- a/docs/skopeo.1.md +++ b/docs/skopeo.1.md @@ -33,7 +33,9 @@ Most commands refer to container images, using a _transport_`:`_details_ format. An existing local directory _path_ storing the manifest, layer tarballs and signatures as individual files. This is a non-standardized format, primarily useful for debugging or noninvasive container inspection. **docker://**_docker-reference_ - An image in a registry implementing the "Docker Registry HTTP API V2". By default, uses the authorization state in either `$XDG_RUNTIME_DIR/containers/auth.json`, which is set using `(skopeo login)`. If the authorization state is not found there, `$HOME/.docker/config.json` is checked, which is set using `(docker login)`. + An image in a registry implementing the "Docker Registry HTTP API V2". + Credentials are typically managed using `(skopeo login)`; + see **containers-auth.json**(5) for more details about the credential search mechanism. **docker-archive:**_path_[**:**_docker-reference_] An image is stored in the `docker save` formatted file. _docker-reference_ is only used when creating such a file, and it must not contain a digest.