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

docs: update docker login reference 

Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>
This commit is contained in:
David Karlsson 2024-09-02 12:03:45 +02:00
parent 6273e65cee
commit 2f206fff3c
3 changed files with 129 additions and 60 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
cli/command/registry/login.go
View File

@ -34,8 +34,8 @@ func NewLoginCommand(dockerCli command.Cli) *cobra.Command {
cmd := &cobra.Command{ cmd := &cobra.Command{
Use: "login [OPTIONS] [SERVER]", Use: "login [OPTIONS] [SERVER]",
Short: "Log in to a registry", Short: "Authenticate to a registry",
Long: "Log in to a registry.\nIf no server is specified, the default is defined by the daemon.", Long: "Authenticate to a registry.\nDefaults to Docker Hub if no server is specified.",
Args: cli.RequiresMaxArgs(1), Args: cli.RequiresMaxArgs(1),
RunE: func(cmd *cobra.Command, args []string) error { RunE: func(cmd *cobra.Command, args []string) error {
if len(args) > 0 { if len(args) > 0 {

2
docs/reference/commandline/docker.md
View File

@ -29,7 +29,7 @@ The base command for the Docker CLI.
| [`inspect`](inspect.md) | Return low-level information on Docker objects | | [`inspect`](inspect.md) | Return low-level information on Docker objects |
| [`kill`](kill.md) | Kill one or more running containers | | [`kill`](kill.md) | Kill one or more running containers |
| [`load`](load.md) | Load an image from a tar archive or STDIN | | [`load`](load.md) | Load an image from a tar archive or STDIN |
| [`login`](login.md) | Log in to a registry | | [`login`](login.md) | Authenticate to a registry |
| [`logout`](logout.md) | Log out from a registry | | [`logout`](logout.md) | Log out from a registry |
| [`logs`](logs.md) | Fetch the logs of a container | | [`logs`](logs.md) | Fetch the logs of a container |
| [`manifest`](manifest.md) | Manage Docker image manifests and manifest lists | | [`manifest`](manifest.md) | Manage Docker image manifests and manifest lists |

183
docs/reference/commandline/login.md
View File

@ -1,60 +1,51 @@
# login # login
<!---MARKER_GEN_START--> <!---MARKER_GEN_START-->
Log in to a registry. Authenticate to a registry.
If no server is specified, the default is defined by the daemon. Defaults to Docker Hub if no server is specified.
### Options ### Options
| Name | Type | Default | Description | | Name | Type | Default | Description |
|:--------------------------------------|:---------|:--------|:-----------------------------| |:---------------------------------------------|:---------|:--------|:-----------------------------|
| `-p`, `--password` | `string` | | Password | | `-p`, `--password` | `string` | | Password |
| [`--password-stdin`](#password-stdin) | `bool` | | Take the password from stdin | | [`--password-stdin`](#password-stdin) | `bool` | | Take the password from stdin |
| `-u`, `--username` | `string` | | Username | | [`-u`](#username), [`--username`](#username) | `string` | | Username |
<!---MARKER_GEN_END--> <!---MARKER_GEN_END-->
## Description ## Description
Log in to a registry. Authenticate to a registry.
## Examples You can authenticate to any public or private registry for which you have
credentials. Authentication may be required for pulling and pushing images.
Other commands, such as `docker scout` and `docker build`, may also require
authentication to access subscription-only features or data related to your
Docker organization.
### Login to a self-hosted registry Authentication credentials are stored in the configured [credential
store](#credential-stores). If you use Docker Desktop, credentials are
automatically saved to the native keychain of your operating system. If you're
not using Docker Desktop, you can configure the credential store in the Docker
configuration file, which is located at `$HOME/.docker/config.json` on Linux or
`%USERPROFILE%/.docker/config.json` on Windows. If you don't configure a
credential store, Docker stores credentials in the `config.json` file in a
base64-encoded format. This method is less secure than configuring and using a
credential store.
If you want to log in to a self-hosted registry you can specify this by `docker login` also supports [credential helpers](#credential-helpers) to help
adding the server name. you handle credentials for specific registries.
```console ### Authentication methods
$ docker login localhost:8080
```
### <a name="password-stdin"></a> Provide a password using STDIN (--password-stdin) You can authenticate to a registry using a username and access token or
password. Docker Hub also supports a web-based sign-in flow, which signs you in
To run the `docker login` command non-interactively, you can set the to your Docker account without entering your password. For Docker Hub, the
`--password-stdin` flag to provide a password through `STDIN`. Using `docker login` command uses a device code flow by default, unless the
`STDIN` prevents the password from ending up in the shell's history, `--username` flag is specified. The device code flow is a secure way to sign
or log-files. in. See [Authenticate to Docker Hub using device code](#authenticate-to-docker-hub-using-device-code).
The following example reads a password from a file, and passes it to the
`docker login` command using `STDIN`:
```console
$ cat ~/my_password.txt | docker login --username foo --password-stdin
```
### Privileged user requirement
`docker login` requires you to use `sudo` or be `root`, except when:
- Connecting to a remote daemon, such as a `docker-machine` provisioned `docker engine`.
- The user is added to the `docker` group. This will impact the security of your system; the `docker` group is `root` equivalent. See [Docker Daemon Attack Surface](https://docs.docker.com/engine/security/#docker-daemon-attack-surface) for details.
You can log in to any public or private repository for which you have
credentials. When you log in, the command stores credentials in
`$HOME/.docker/config.json` on Linux or `%USERPROFILE%/.docker/config.json` on
Windows, via the procedure described below.
### Credential stores ### Credential stores
@ -75,6 +66,10 @@ Helpers are available for the following credential stores:
- Microsoft Windows Credential Manager - Microsoft Windows Credential Manager
- [pass](https://www.passwordstore.org/) - [pass](https://www.passwordstore.org/)
With Docker Desktop, the credential store is already installed and configured
for you. Unless you want to change the credential store used by Docker Desktop,
you can skip the following steps.
#### Configure the credential store #### Configure the credential store
You need to specify the credential store in `$HOME/.docker/config.json` You need to specify the credential store in `$HOME/.docker/config.json`
@ -94,22 +89,22 @@ the credentials from the file and run `docker login` again.
#### Default behavior #### Default behavior
By default, Docker looks for the native binary on each of the platforms, i.e. By default, Docker looks for the native binary on each of the platforms, i.e.
"osxkeychain" on macOS, "wincred" on windows, and "pass" on Linux. A special `osxkeychain` on macOS, `wincred` on Windows, and `pass` on Linux. A special
case is that on Linux, Docker will fall back to the "secretservice" binary if case is that on Linux, Docker will fall back to the `secretservice` binary if
it cannot find the "pass" binary. If none of these binaries are present, it it cannot find the `pass` binary. If none of these binaries are present, it
stores the credentials (i.e. password) in base64 encoding in the config files stores the base64-encoded credentials in the `config.json` configuration file.
described above.
#### Credential helper protocol #### Credential helper protocol
Credential helpers can be any program or script that follows a very simple protocol. Credential helpers can be any program or script that implements the credential
This protocol is heavily inspired by Git, but it differs in the information shared. helper protocol. This protocol is inspired by Git, but differs in the
information shared.
The helpers always use the first argument in the command to identify the action. The helpers always use the first argument in the command to identify the action.
There are only three possible values for that argument: `store`, `get`, and `erase`. There are only three possible values for that argument: `store`, `get`, and `erase`.
The `store` command takes a JSON payload from the standard input. That payload carries The `store` command takes a JSON payload from the standard input. That payload carries
the server address, to identify the credential, the user name, and either a password the server address, to identify the credential, the username, and either a password
or an identity token. or an identity token.
```json ```json
@ -149,10 +144,10 @@ will show if there was an issue.
### Credential helpers ### Credential helpers
Credential helpers are similar to the credential store above, but act as the Credential helpers are similar to [credential stores](#credential-stores), but
designated programs to handle credentials for specific registries. The default act as the designated programs to handle credentials for specific registries.
credential store (`credsStore` or the config file itself) will not be used for The default credential store will not be used for operations concerning
operations concerning credentials of the specified registries. credentials of the specified registries.
#### Configure credential helpers #### Configure credential helpers
@ -162,19 +157,93 @@ the credentials from the default store.
Credential helpers are specified in a similar way to `credsStore`, but Credential helpers are specified in a similar way to `credsStore`, but
allow for multiple helpers to be configured at a time. Keys specify the allow for multiple helpers to be configured at a time. Keys specify the
registry domain, and values specify the suffix of the program to use registry domain, and values specify the suffix of the program to use
(i.e. everything after `docker-credential-`). (i.e. everything after `docker-credential-`). For example:
For example:
```json ```json
{ {
"credHelpers": { "credHelpers": {
"registry.example.com": "registryhelper", "myregistry.example.com": "secretservice",
"awesomereg.example.org": "hip-star", "docker.internal.example": "pass",
"unicorn.example.io": "vcbait"
} }
} }
``` ```
## Examples
### Authenticate to Docker Hub with web-based login
By default, the `docker login` command authenticates to Docker Hub, using a
device code flow. This flow lets you authenticate to Docker Hub without
entering your password. Instead, you visit a URL in your web browser, enter a
code, and authenticate.
```console
$ docker login
USING WEB BASED LOGIN
To sign in with credentials on the command line, use 'docker login -u <username>'
Your one-time device confirmation code is: LNFR-PGCJ
Press ENTER to open your browser or submit your device code here: https://login.docker.com/activate
Waiting for authentication in the browser…
```
After entering the code in your browser, you are authenticated to Docker Hub
using the account you're currently signed in with on the Docker Hub website or
in Docker Desktop. If you aren't signed in, you are prompted to sign in after
entering the device code.
### Authenticate to a self-hosted registry
If you want to authenticate to a self-hosted registry you can specify this by
adding the server name.
```console
$ docker login registry.example.com
```
By default, the `docker login` command assumes that the registry listens on
port 443 or 80. If the registry listens on a different port, you can specify it
by adding the port number to the server name.
```console
$ docker login registry.example.com:1337
```
> [!NOTE]
> Registry addresses should not include URL path components, only the hostname
> and (optionally) the port. Registry addresses with URL path components may
> result in an error. For example, `docker login registry.example.com/foo/`
> is incorrect, while `docker login registry.example.com` is correct.
>
> The exception to this rule is the Docker Hub registry, which may use the
> `/v1/` path component in the address for historical reasons.
### <a name="username"></a> Authenticate to a registry with a username and password
To authenticate to a registry with a username and password, you can use the
`--username` or `-u` flag. The following example authenticates to Docker Hub
with the username `moby`. The password is entered interactively.
```console
$ docker login -u moby
```
### <a name="password-stdin"></a> Provide a password using STDIN (--password-stdin)
To run the `docker login` command non-interactively, you can set the
`--password-stdin` flag to provide a password through `STDIN`. Using
`STDIN` prevents the password from ending up in the shell's history,
or log-files.
The following example reads a password from a file, and passes it to the
`docker login` command using `STDIN`:
```console
$ cat ~/my_password.txt | docker login --username foo --password-stdin
```
## Related commands ## Related commands
* [logout](logout.md) * [logout](logout.md)