github.com/panekj/cli@v0.0.0-20230304125325-467dd2f3797e/docs/reference/commandline/login.md (about)

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