skip to content

An OpenSSH client whose agent holds six keys is disconnected with 'Too many authentication failures'; why, and which ssh_config lines fix it?

level: middleimportance: should knowfreq 38%

answer

  1. every agent key is a candidate
  2. each rejected key is one attempt
  3. the server's per-connection limit
  4. pin the key per host

basics

~20 s

Without IdentitiesOnly the client offers every key the agent holds as well as its configured files, and each key the server rejects counts toward sshd's MaxAuthTries (6 by default). Set IdentityFile and IdentitiesOnly yes in that host's block.

solid answer

~40 s

In public-key login the client offers keys one at a time, and the server counts each key it turns down as a failed attempt. sshd's `MaxAuthTries` defaults to 6, so an agent holding six keys can exhaust the limit before the right key is offered, and the server disconnects with `Too many authentication failures`. The fix is client-side: in the host's block, `IdentityFile` names the key for that host and `IdentitiesOnly yes` tells ssh to offer only configured identity and certificate files, even if the agent offers more. The agent can still do the signing: `IdentityFile` may point at a `.pub` file whose private half lives only in the agent, and `IdentitiesOnly` then selects that one key from it.

go deeper

for a junior

Recall that ssh offers keys one by one and that IdentitiesOnly yes limits it to the keys you configured.

for a middle

Explain how agent keys join the candidate list, why each rejection counts toward MaxAuthTries, and why IdentityFile can name a .pub file.

for a senior

Show how pinning one key per environment avoids lockouts, keeps staging keys away from production hosts and makes automation failures obvious.

for a principal

Weigh per-environment keys pinned in a shared client file against one broad key, considering blast radius, rotation effort and audit clarity.

## What the client offers by default In SSH's **publickey** method the client proposes one public key at a time; the server answers whether it would accept it, and only an acceptable key is then used to sign. OpenSSH's client builds its candidate list from: - the identity files from `IdentityFile` lines, or the default key files in `~/.ssh` when none are configured; - **every key the agent holds**, unless `IdentitiesOnly` is set; - keys from a PKCS#11 or security-key provider, under the same rule. On a laptop whose agent holds a personal key, two work keys, a CI key, a hardware key and an old key, that is six or more candidates before the configured file is considered at all, and the order is not one you chose per host. ## Why the server cuts you off The server side of this lives in `sshd_config`, but one directive explains the symptom: `MaxAuthTries`, the maximum number of authentication attempts permitted per connection, **defaults to 6**. Each key the server declines counts as a failed attempt. When the count reaches the limit the server sends a disconnect whose reason reads `Too many authentication failures`, and the client prints it as `Received disconnect ... Too many authentication failures`. The right key may be seventh in line and never get its turn; password or keyboard-interactive login, if enabled, never gets reached either. | Setting | Who sets it | Default | Role here | |---|---|---|---| | `MaxAuthTries` | server (`sshd_config`) | 6 | how many rejected keys end the connection | | `IdentityFile` | client (`ssh_config`) | the default key files | which key file to offer for this host | | `IdentitiesOnly` | client (`ssh_config`) | `no` | whether agent keys beyond the configured files are offered | Raising `MaxAuthTries` on the server only hides the problem and gives password guessers more tries per connection; hardening the server is a separate subject. ## The client-side fix ```ini Host *.prod.internal.example IdentityFile ~/.ssh/id_prod IdentitiesOnly yes ``` `IdentitiesOnly yes` makes ssh use **only the configured authentication identity and certificate files** (the defaults or those named in config or on the command line), even if the agent or a provider offers more identities. The manual describes it as intended for situations where the agent offers many identities. Three practical points: 1. **The agent is not switched off.** If the agent holds the private key matching a configured file, the agent does the signing; `IdentitiesOnly` filters which agent keys are offered, it does not bypass the agent. 2. **A `.pub` file is enough.** `IdentityFile` may name a public key file so that the corresponding private key loaded in the agent is used when the private file is not present locally, which is how hardware-backed or agent-only keys are selected per host. 3. **IdentityFile accumulates.** Several matching `IdentityFile` lines (for example one under the host and one under `Host *`) add to the list rather than replacing each other, so keep the per-host key in the specific block and avoid scattering extras under `Host *`. For a one-off command, `ssh -o IdentitiesOnly=yes -i ~/.ssh/id_prod web1` does the same. ## Why this matters for a fleet Pinning one key per environment does more than avoid the disconnect. Each connection presents only the identity meant for that environment, so a staging key is never shown to a production host, server logs show one attempt per login instead of a burst of failures, and automation fails fast with a clear error when the wrong key is configured. Installing the key on the host in the first place, and holding keys in the agent with lifetimes or confirmation, are separate subjects; the client file's job is choosing which key is offered where. ## Checking the result - `ssh -G web1 | grep -E '^(identityfile|identitiesonly) '` shows the identity list and the flag that will apply, without connecting. - If several `IdentityFile` lines appear, an earlier general block probably added extras; move the per-host key into the specific block and keep `Host *` free of key files. - If the error persists with `IdentitiesOnly yes`, the configured key itself is not accepted by the server, which is a different problem from offering too many keys.

  • With `IdentitiesOnly yes`, can ssh still use a key whose private half exists only in the agent?
    Yes. Point `IdentityFile` at that key's `.pub` file; ssh then asks the agent to sign with the matching private key. `IdentitiesOnly` restricts which identities are offered to those configured, it does not stop the agent from performing the signature.
  • Why is raising `MaxAuthTries` on the server the wrong fix for this error?
    It treats the symptom on every connection for every user: clients still spray all their keys, and the server allows more guesses per connection. Pinning `IdentityFile` with `IdentitiesOnly yes` in the client fixes the cause, and the server limit keeps its value.

  • IdentitiesOnly yes disables the agent completely
  • The server rejected the key because it is too weak
  • Raising MaxAuthTries on the server is the proper fix
  • IdentityFile replaces the agent's keys without IdentitiesOnly
  • A failure on one key ends the login immediately