Forks, timeouts and what they cost · Ansible

Two settings decide how a run behaves at scale, and both ship with values chosen for a laptop talking to a handful of machines.

Read-only / Safethe two numbers— Both values are the built-in defaults on ansible-core 2.21.3, with no config file present.

$ ansible-config dump | grep -E '^(DEFAULT_FORKS|DEFAULT_TIMEOUT)'

DEFAULT_FORKS(default) = 5
DEFAULT_TIMEOUT(default) = 10

Neither is right for a fleet. Neither is safe to change without understanding what it was doing for you.

`forks`: how many hosts at once

forks is the maximum number of worker processes the controller runs in parallel. Under the default linear strategy, Ansible executes one task across all targeted hosts before moving to the next task, and forks caps how many of those hosts are worked on simultaneously.

For 300 hosts at forks = 5, each task proceeds in 60 sequential batches of 5. If a task takes two seconds, that task alone takes two minutes. Multiply by the number of tasks in the play and the arithmetic explains most complaints about Ansible being slow.

Configured in [defaults], overridable per run:

[defaults]
forks = 20

Read-only / Safethe three ways to set it— Precedence runs left to right: the command-line flag beats the environment, which beats the file.

ansible-playbook site.yml --check -f 20
ANSIBLE_FORKS=20 ansible-playbook site.yml --check
# or forks = 20 in the [defaults] section of ansible.cfg

The framing that matters

The obvious reading of forks is “how fast”. The reading this course insists on is how many machines are in a broken state at the same moment.

A play that reconfigures a service is, for a few seconds per host, a play that has stopped that service. At forks = 5, five hosts are in that state at once, and a task that turns out to be wrong affects five machines before anybody can interrupt it. At forks = 100, a hundred are.

forks = 5 is therefore an accidental safety limit. It is not a good one — it is unrelated to your service, your redundancy, or your capacity — but it is a limit, and raising it removes protection you were relying on without knowing it.

Raise forks and you must add a deliberate limit in its place

If you raise forks from 5 to 50 to make patching finish before the window closes, you have just multiplied simultaneous exposure tenfold. The correct move is to raise forks and introduce a real limit that reflects the service:

- name: Roll the web tier
  hosts: web:&live
  serial: 4              # four hosts at a time, whatever forks says
  max_fail_percentage: 0 # stop the whole rollout on any failure

serial batches the play by host and is the control that should be deciding your blast radius, because it is expressed in terms of the service rather than in terms of the controller. forks then governs how much parallelism is available within a batch.

The rollout mechanics are the subject of their own parts. What belongs here is the rule: forks is not a safety control, and it is currently acting as one. Replace it before you remove it.

What raising `forks` costs the controller

Every fork is a real process. On the controller, per host being worked on, you pay for:

a Python process, with the Ansible libraries loaded;
an SSH connection, plus a persistent control socket if ControlPersist is in use — the default ssh_args is -C -o ControlMaster=auto -o ControlPersist=60s;
file descriptors for that connection and its control path;
memory to hold the module payload and the result, which for a task returning large output is not small.

The controller is therefore the constraint, not the fleet. A forks value that a 32 GiB controller handles comfortably will make a 2 GiB one swap, and a swapping controller produces timeouts that look exactly like network faults on the managed nodes.

`timeout`: how long to wait for a connection

timeout is the connection timeout used by connection plugins, default 10 seconds. It is how long Ansible waits to establish a connection to a managed node before declaring it unreachable.

It is not a task timeout, and the name collision is a genuine trap — covered below.

What a raised timeout hides

The tempting fix for “some hosts intermittently fail as unreachable” is to raise timeout to 30 or 60. It works, in the sense that the failures stop.

Consider what it means for a host to need 45 seconds to accept an SSH connection. Something is wrong with that machine: it is under memory pressure, its disk is saturated, sshd is struggling, or the path to it is degraded. At timeout = 10 you learn this immediately, in the form of a clear unreachable result. At timeout = 60 the run succeeds and you learn nothing — and the sick host is now receiving configuration changes while it is sick.

A raised timeout converts a fast, accurate failure into a slow, misleading success. That is a bad trade in the direction that matters.

The legitimate reasons to raise it

There are real ones, and they share a property: the latency is expected and understood.

A bastion or ProxyJump chain, where establishing the connection genuinely involves two hops.
High-latency or satellite links, where 10 seconds is not a generous budget.
Hosts that are slow to accept connections during boot, in a workflow that deliberately waits for a machine to come up.

For the last case, prefer ansible.builtin.wait_for_connection as an explicit task over a global timeout increase. It states the intent — “wait for this host to become reachable” — in one place, rather than making every connection in every play more patient.

Where you do raise the global value, write the reason next to it. A bare timeout = 60 in a config file is indistinguishable from somebody having made a failure go away.

What a raised timeout costs in wall-clock

The two settings interact, and the interaction shows up on the worst day.

An unreachable host occupies a fork for the whole timeout period. With forks = 5 and timeout = 60, fifty dead hosts occupy the controller for ten batches of sixty seconds — ten minutes before any healthy host is touched. With timeout = 10 the same fifty cost about one hundred seconds.

During an incident, when unreachable hosts are exactly what you have, a generous timeout turns your diagnostic run into something you sit and watch.

Under the hood

timeout is a base setting that connection plugins consume, and each plugin also exposes it in its own namespace. Both views agree:

$ ansible-config dump | grep '^DEFAULT_TIMEOUT'
DEFAULT_TIMEOUT(default) = 10

$ ansible-config dump -t connection | grep '^timeout'
timeout(default) = 10

The ssh connection plugin documents its own name for the same value: the inventory variable is ansible_ssh_timeout, not ansible_timeout — the latter is not a recognised variable for that plugin, and setting it does nothing. The plugin also accepts it under [ssh_connection] as well as [defaults] in the ini file, and under ANSIBLE_SSH_TIMEOUT as well as ANSIBLE_TIMEOUT.

That matters when you want a different value for one group of hosts, which is almost always better than a global change:

# inventory/production/group_vars/satellite_site.yml
ansible_ssh_timeout: 45

Verified on 2.21.3: a host in that group resolves ansible_ssh_timeout to 45 while a host outside it resolves to 10. The hosts that genuinely need patience get it; the rest keep telling you the truth quickly.

One more detail from the plugin documentation, because it slightly widens what the setting covers: the value is the time allowed to establish the connection and how long Ansible will wait to read from the connection once established. It is still not a limit on how long a task runs.

timeout the setting is not timeout the keyword

Ansible has two unrelated things called timeout, and confusing them produces a fix that does nothing.

timeout in ansible.cfg — the connection timeout. Verified default 10. Controls how long establishing a connection may take.
timeout as a playbook keyword — applies to a Play, Role, Block, Task or Handler, and is documented as the time limit for the task action to execute in, after which Ansible interrupts the process. It explicitly does not include templating or looping.

A task that hangs for twenty minutes running a slow command is not affected by the configuration setting at all; the connection was established in under a second. It is the keyword you want:

- name: Rebuild the search index
  ansible.builtin.command: /usr/local/bin/reindex
  timeout: 600

Raising the configuration timeout to fix a hanging task is a common and completely ineffective response, and because it changes behaviour elsewhere it is worse than doing nothing.

What happens if you set forks higher than the number of target hosts?

Nothing bad, and nothing useful. forks is a ceiling, not a target: Ansible starts at most one worker per host in the current batch, so forks = 50 against 12 hosts runs 12 workers.

That is worth knowing for two reasons.

First, it means a generous forks costs nothing on small runs, so the argument for raising it is not “small runs get slower”. It is entirely about what happens on the large ones.

Second, it interacts with serial. A play with serial: 4 never has more than four hosts in flight regardless of forks, and the throttle keyword is explicit about the relationship: it cannot raise concurrency above the forks and serial limits, so with forks: 10 and throttle: 15 at most ten hosts are operated on in parallel.

The practical reading: forks sets what the controller is willing to do, and serial and throttle set what the play is allowed to do. Set the ceiling for your controller, and the limit for your service.

forks: how many hosts at once

The framing that matters

What raising forks costs the controller

timeout: how long to wait for a connection

What a raised timeout hides

What a raised timeout costs in wall-clock

Knowledge check

`forks`: how many hosts at once

What raising `forks` costs the controller

`timeout`: how long to wait for a connection