path: root/devdocs/docker/engine%2Freference%2Fcommandline%2Flogin%2Findex.html

<h1>docker login</h1>  <p><br></p> <p>Log in to a Docker registry</p> <h2 id="usage">Usage</h2> <div class="highlight"><pre class="highlight" data-language="">$ docker login [OPTIONS] [SERVER]
</pre></div> <p>Refer to the <a href="#options">options section</a> for an overview of available <a href="#options"><code class="language-plaintext highlighter-rouge">OPTIONS</code></a> for this command.</p> <h2 id="description">Description</h2> <p name="extended-description">Login to a registry.</p> <p>For example uses of this command, refer to the <a href="#examples">examples section</a> below.</p> <h2 id="options">Options</h2> <table> <thead> <tr> <td>Name, shorthand</td> <td>Default</td> <td>Description</td> </tr> </thead> <tbody> <tr> <td>
<code class="language-plaintext highlighter-rouge">--password</code> , <code class="language-plaintext highlighter-rouge">-p</code>
</td> <td></td> <td>Password</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">--password-stdin</code></td> <td></td> <td>Take the password from stdin</td> </tr> <tr> <td>
<code class="language-plaintext highlighter-rouge">--username</code> , <code class="language-plaintext highlighter-rouge">-u</code>
</td> <td></td> <td>Username</td> </tr>  </tbody> </table>  <h2 id="examples">Examples</h2> <h3 id="login-to-a-self-hosted-registry">Login to a self-hosted registry</h3> <p>If you want to login to a self-hosted registry you can specify this by adding the server name.</p> <div class="highlight"><pre class="highlight" data-language="">$ docker login localhost:8080
</pre></div> <h3 id="provide-a-password-using-stdin">Provide a password using STDIN</h3> <p>To run the <code class="language-plaintext highlighter-rouge">docker login</code> command non-interactively, you can set the <code class="language-plaintext highlighter-rouge">--password-stdin</code> flag to provide a password through <code class="language-plaintext highlighter-rouge">STDIN</code>. Using <code class="language-plaintext highlighter-rouge">STDIN</code> prevents the password from ending up in the shell’s history, or log-files.</p> <p>The following example reads a password from a file, and passes it to the <code class="language-plaintext highlighter-rouge">docker login</code> command using <code class="language-plaintext highlighter-rouge">STDIN</code>:</p> <div class="highlight"><pre class="highlight" data-language="">$ cat ~/my_password.txt | docker login --username foo --password-stdin
</pre></div> <h3 id="privileged-user-requirement">Privileged user requirement</h3> <p><code class="language-plaintext highlighter-rouge">docker login</code> requires user to use <code class="language-plaintext highlighter-rouge">sudo</code> or be <code class="language-plaintext highlighter-rouge">root</code>, except when:</p> <ol> <li>connecting to a remote daemon, such as a <code class="language-plaintext highlighter-rouge">docker-machine</code> provisioned <code class="language-plaintext highlighter-rouge">docker engine</code>.</li> <li>user is added to the <code class="language-plaintext highlighter-rouge">docker</code> group. This will impact the security of your system; the <code class="language-plaintext highlighter-rouge">docker</code> group is <code class="language-plaintext highlighter-rouge">root</code> equivalent. See <a href="../../../security/index#docker-daemon-attack-surface">Docker Daemon Attack Surface</a> for details.</li> </ol> <p>You can log into any public or private repository for which you have credentials. When you log in, the command stores credentials in <code class="language-plaintext highlighter-rouge">$HOME/.docker/config.json</code> on Linux or <code class="language-plaintext highlighter-rouge">%USERPROFILE%/.docker/config.json</code> on Windows, via the procedure described below.</p> <h3 id="credentials-store">Credentials store</h3> <p>The Docker Engine can keep user credentials in an external credentials store, such as the native keychain of the operating system. Using an external store is more secure than storing credentials in the Docker configuration file.</p> <p>To use a credentials store, you need an external helper program to interact with a specific keychain or external store. Docker requires the helper program to be in the client’s host <code class="language-plaintext highlighter-rouge">$PATH</code>.</p> <p>This is the list of currently available credentials helpers and where you can download them from:</p> <ul> <li>D-Bus Secret Service: https://github.com/docker/docker-credential-helpers/releases</li> <li>Apple macOS keychain: https://github.com/docker/docker-credential-helpers/releases</li> <li>Microsoft Windows Credential Manager: https://github.com/docker/docker-credential-helpers/releases</li> <li>
<a href="https://www.passwordstore.org/">pass</a>: https://github.com/docker/docker-credential-helpers/releases</li> </ul> <h4 id="configure-the-credentials-store">Configure the credentials store</h4> <p>You need to specify the credentials store in <code class="language-plaintext highlighter-rouge">$HOME/.docker/config.json</code> to tell the docker engine to use it. The value of the config property should be the suffix of the program to use (i.e. everything after <code class="language-plaintext highlighter-rouge">docker-credential-</code>). For example, to use <code class="language-plaintext highlighter-rouge">docker-credential-osxkeychain</code>:</p> <div class="highlight"><pre class="highlight" data-language="">{
  "credsStore": "osxkeychain"
}
</pre></div> <p>If you are currently logged in, run <code class="language-plaintext highlighter-rouge">docker logout</code> to remove the credentials from the file and run <code class="language-plaintext highlighter-rouge">docker login</code> again.</p> <h4 id="default-behavior">Default behavior</h4> <p>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 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 stores the credentials (i.e. password) in base64 encoding in the config files described above.</p> <h4 id="credential-helper-protocol">Credential helper protocol</h4> <p>Credential helpers can be any program or script that follows a very simple protocol. This protocol is heavily inspired by Git, but it differs in the information shared.</p> <p>The helpers always use the first argument in the command to identify the action. There are only three possible values for that argument: <code class="language-plaintext highlighter-rouge">store</code>, <code class="language-plaintext highlighter-rouge">get</code>, and <code class="language-plaintext highlighter-rouge">erase</code>.</p> <p>The <code class="language-plaintext highlighter-rouge">store</code> 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 or an identity token.</p> <div class="highlight"><pre class="highlight" data-language="">{
  "ServerURL": "https://index.docker.io/v1",
  "Username": "david",
  "Secret": "passw0rd1"
}
</pre></div> <p>If the secret being stored is an identity token, the Username should be set to <code class="language-plaintext highlighter-rouge">&lt;token&gt;</code>.</p> <p>The <code class="language-plaintext highlighter-rouge">store</code> command can write error messages to <code class="language-plaintext highlighter-rouge">STDOUT</code> that the docker engine will show if there was an issue.</p> <p>The <code class="language-plaintext highlighter-rouge">get</code> command takes a string payload from the standard input. That payload carries the server address that the docker engine needs credentials for. This is an example of that payload: <code class="language-plaintext highlighter-rouge">https://index.docker.io/v1</code>.</p> <p>The <code class="language-plaintext highlighter-rouge">get</code> command writes a JSON payload to <code class="language-plaintext highlighter-rouge">STDOUT</code>. Docker reads the user name and password from this payload:</p> <div class="highlight"><pre class="highlight" data-language="">{
  "Username": "david",
  "Secret": "passw0rd1"
}
</pre></div> <p>The <code class="language-plaintext highlighter-rouge">erase</code> command takes a string payload from <code class="language-plaintext highlighter-rouge">STDIN</code>. That payload carries the server address that the docker engine wants to remove credentials for. This is an example of that payload: <code class="language-plaintext highlighter-rouge">https://index.docker.io/v1</code>.</p> <p>The <code class="language-plaintext highlighter-rouge">erase</code> command can write error messages to <code class="language-plaintext highlighter-rouge">STDOUT</code> that the docker engine will show if there was an issue.</p> <h3 id="credential-helpers">Credential helpers</h3> <p>Credential helpers are similar to the credential store above, but act as the designated programs to handle credentials for <em>specific registries</em>. The default credential store (<code class="language-plaintext highlighter-rouge">credsStore</code> or the config file itself) will not be used for operations concerning credentials of the specified registries.</p> <h4 id="configure-credential-helpers">Configure credential helpers</h4> <p>If you are currently logged in, run <code class="language-plaintext highlighter-rouge">docker logout</code> to remove the credentials from the default store.</p> <p>Credential helpers are specified in a similar way to <code class="language-plaintext highlighter-rouge">credsStore</code>, but 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 (i.e. everything after <code class="language-plaintext highlighter-rouge">docker-credential-</code>). For example:</p> <div class="highlight"><pre class="highlight" data-language="">{
  "credHelpers": {
    "registry.example.com": "registryhelper",
    "awesomereg.example.org": "hip-star",
    "unicorn.example.io": "vcbait"
  }
}
</pre></div> <div class="_attribution">
  <p class="_attribution-p">
    &copy; 2019 Docker, Inc.<br>Licensed under the Apache License, Version 2.0.<br>Docker and the Docker logo are trademarks or registered trademarks of Docker, Inc. in the United States and/or other countries.<br>Docker, Inc. and other parties may also have trademark rights in other terms used herein.<br>
    <a href="https://docs.docker.com/engine/reference/commandline/login/" class="_attribution-link">https://docs.docker.com/engine/reference/commandline/login/</a>
  </p>
</div>