github.com/xdlianrong208/docker-ce-comments@v17.12.1-ce-rc2+incompatible/components/cli/docs/reference/commandline/login.md (about)

     1  ---
     2  title: "login"
     3  description: "The login command description and usage"
     4  keywords: "registry, login, image"
     5  ---
     6  
     7  <!-- This file is maintained within the docker/cli GitHub
     8       repository at https://github.com/docker/cli/. Make all
     9       pull requests against that repo. If you see this file in
    10       another repository, consider it read-only there, as it will
    11       periodically be overwritten by the definitive file. Pull
    12       requests which include edits to this file in other repositories
    13       will be rejected.
    14  -->
    15  
    16  # login
    17  
    18  ```markdown
    19  Usage:  docker login [OPTIONS] [SERVER]
    20  
    21  Log in to a Docker registry.
    22  If no server is specified, the default is defined by the daemon.
    23  
    24  Options:
    25        --help                    Print usage
    26    -p, --password       string   Password
    27        --password-stdin          Read password from stdin
    28    -u, --username       string   Username
    29  ```
    30  
    31  ## Description
    32  
    33  Login to a registry.
    34  
    35  ### Login to a self-hosted registry
    36  
    37  If you want to login to a self-hosted registry you can specify this by
    38  adding the server name.
    39  
    40  ```bash
    41  $ docker login localhost:8080
    42  ```
    43  
    44  ### Provide a password using STDIN
    45  
    46  To run the `docker login` command non-interactively, you can set the
    47  `--password-stdin` flag to provide a password through `STDIN`. Using
    48  `STDIN` prevents the password from ending up in the shell's history,
    49  or log-files.
    50  
    51  The following example reads a password from a file, and passes it to the
    52  `docker login` command using `STDIN`:
    53  
    54  ```bash
    55  $ cat ~/my_password.txt | docker login --username foo --password-stdin
    56  ```
    57  
    58  ### Privileged user requirement
    59  
    60  `docker login` requires user to use `sudo` or be `root`, except when:
    61  
    62  1.  connecting to a remote daemon, such as a `docker-machine` provisioned `docker engine`.
    63  2.  user is added to the `docker` group.  This will impact the security of your system; the `docker` group is `root` equivalent.  See [Docker Daemon Attack Surface](https://docs.docker.com/security/security/#docker-daemon-attack-surface) for details.
    64  
    65  You can log into any public or private repository for which you have
    66  credentials.  When you log in, the command stores credentials in
    67  `$HOME/.docker/config.json` on Linux or `%USERPROFILE%/.docker/config.json` on
    68  Windows, via the procedure described below.
    69  
    70  ### Credentials store
    71  
    72  The Docker Engine can keep user credentials in an external credentials store,
    73  such as the native keychain of the operating system. Using an external store
    74  is more secure than storing credentials in the Docker configuration file.
    75  
    76  To use a credentials store, you need an external helper program to interact
    77  with a specific keychain or external store. Docker requires the helper
    78  program to be in the client's host `$PATH`.
    79  
    80  This is the list of currently available credentials helpers and where
    81  you can download them from:
    82  
    83  - D-Bus Secret Service: https://github.com/docker/docker-credential-helpers/releases
    84  - Apple macOS keychain: https://github.com/docker/docker-credential-helpers/releases
    85  - Microsoft Windows Credential Manager: https://github.com/docker/docker-credential-helpers/releases
    86  - [pass](https://www.passwordstore.org/): https://github.com/docker/docker-credential-helpers/releases
    87  
    88  You need to specify the credentials store in `$HOME/.docker/config.json`
    89  to tell the docker engine to use it. The value of the config property should be
    90  the suffix of the program to use (i.e. everything after `docker-credential-`).
    91  For example, to use `docker-credential-osxkeychain`:
    92  
    93  ```json
    94  {
    95  	"credsStore": "osxkeychain"
    96  }
    97  ```
    98  
    99  If you are currently logged in, run `docker logout` to remove
   100  the credentials from the file and run `docker login` again.
   101  
   102  ### Default behavior
   103  
   104  By default, Docker looks for the native binary on each of the platforms, i.e.
   105  "osxkeychain" on macOS, "wincred" on windows, and "pass" on Linux. A special
   106  case is that on Linux, Docker will fall back to the "secretservice" binary if
   107  it cannot find the "pass" binary. If none of these binaries are present, it
   108  stores the credentials (i.e. password) in base64 encoding in the config files
   109  described above.
   110  
   111  ### Credential helper protocol
   112  
   113  Credential helpers can be any program or script that follows a very simple protocol.
   114  This protocol is heavily inspired by Git, but it differs in the information shared.
   115  
   116  The helpers always use the first argument in the command to identify the action.
   117  There are only three possible values for that argument: `store`, `get`, and `erase`.
   118  
   119  The `store` command takes a JSON payload from the standard input. That payload carries
   120  the server address, to identify the credential, the user name, and either a password
   121  or an identity token.
   122  
   123  ```json
   124  {
   125  	"ServerURL": "https://index.docker.io/v1",
   126  	"Username": "david",
   127  	"Secret": "passw0rd1"
   128  }
   129  ```
   130  
   131  If the secret being stored is an identity token, the Username should be set to
   132  `<token>`.
   133  
   134  The `store` command can write error messages to `STDOUT` that the docker engine
   135  will show if there was an issue.
   136  
   137  The `get` command takes a string payload from the standard input. That payload carries
   138  the server address that the docker engine needs credentials for. This is
   139  an example of that payload: `https://index.docker.io/v1`.
   140  
   141  The `get` command writes a JSON payload to `STDOUT`. Docker reads the user name
   142  and password from this payload:
   143  
   144  ```json
   145  {
   146  	"Username": "david",
   147  	"Secret": "passw0rd1"
   148  }
   149  ```
   150  
   151  The `erase` command takes a string payload from `STDIN`. That payload carries
   152  the server address that the docker engine wants to remove credentials for. This is
   153  an example of that payload: `https://index.docker.io/v1`.
   154  
   155  The `erase` command can write error messages to `STDOUT` that the docker engine
   156  will show if there was an issue.
   157  
   158  ### Credential helpers
   159  
   160  Credential helpers are similar to the credential store above, but act as the
   161  designated programs to handle credentials for *specific registries*. The default
   162  credential store (`credsStore` or the config file itself) will not be used for
   163  operations concerning credentials of the specified registries.
   164  
   165  ### Logging out
   166  
   167  If you are currently logged in, run `docker logout` to remove
   168  the credentials from the default store.
   169  
   170  Credential helpers are specified in a similar way to `credsStore`, but
   171  allow for multiple helpers to be configured at a time. Keys specify the
   172  registry domain, and values specify the suffix of the program to use
   173  (i.e. everything after `docker-credential-`).
   174  For example:
   175  
   176  ```json
   177  {
   178    "credHelpers": {
   179      "registry.example.com": "registryhelper",
   180      "awesomereg.example.org": "hip-star",
   181      "unicorn.example.io": "vcbait"
   182    }
   183  }
   184  ```