Forwarder Throttles
The limits that cap how hard a forwarder works and how often it reports, what each one does when it engages, and how to tell a throttle from a fault.
A throttle is a ceiling on how much of a machine the forwarder is allowed to use, or on how often it reports. Every throttle lives in the policy attached to the group the asset belongs to, not on the host, so a forwarder that looks stalled on one machine and healthy on another is usually two different policies rather than two different problems. All of them are off or generous by default, which means an unmodified deployment is not throttled and a throttled one was configured that way deliberately.
This page is for reading a throttle from its symptoms. Asset Configuration is where the settings are described as settings, with the screens to change them.
How do I tell a throttle from a fault?
A throttle produces slowness that is steady, proportional, and specific to the machines under one policy. A fault produces silence, errors in the host's logs, or a status that says Failed.
| What you observe | Throttle or fault |
|---|---|
| A backscan crawling for far longer than on a comparable machine | Throttle. Look at the CPU limit, the network limit, and the process priority in that asset's policy |
| Backscan status Sleeping | Throttle. The scan ran out of its allowed window and will resume at the next one |
| Backscan status Failed | Fault. The host's logs will say why |
| A file's last seen time not moving every time the file runs | Throttle, by design. Repeat sightings are suppressed for a window |
| No sightings at all from an asset that is still checking in | Neither, usually. Check for sleep mode and for exclusions before suspecting a limit |
| Nothing arriving from every asset on one network | Fault, and almost certainly not on the endpoint. See What to Check First |
The reason the distinction matters: raising a limit will not fix a fault, and there is a real cost to raising limits on machines whose users notice.
Which throttles apply to reporting?
Two, and they apply to every platform. Both trade timestamp precision against load, and both have a default that suits most fleets.
| Setting | Range | Default | What it does |
|---|---|---|---|
| Repeat sightings | 1 to 24 hours | 6 hours | Suppresses further sightings of the same file, at the same path, on the same asset, for this long |
| Batch upload rate limit | 1 second to 1 minute | 20 seconds | How long sightings are held and batched before being sent as one request |
Read the repeat-sightings window correctly, because it is the throttle most often mistaken for missing data. A file that executes fifty times in an afternoon produces one sighting, not fifty. The suppression is keyed on the file, the path, and the asset together, so a new sighting is still recorded the moment any of those three changes. It affects the last seen time you read in the app, and it does not affect whether the file was collected or analyzed.
Lowering it sharpens time-based analysis and costs forwarder load. Raising it does the reverse and makes a timeline coarser. Six hours is the balance point Stairwell ships.
The batch upload rate limit is the other side of the same trade: a shorter batch means more frequent requests and more CPU spent on them, and a longer batch means fewer requests and a slightly wider window in which unsent sightings could be lost if the host goes down.
Which throttles apply to how hard the forwarder works?
Three, and on assets running Windows. They sit under the advanced settings of a policy and each one is off until you turn it on.
| Setting | What it does | Notes |
|---|---|---|
| CPU limit | Caps the forwarder at a percentage of the machine's total available CPU | Off by default. The minimum is 5 percent, it moves in steps of 5, and the maximum is 100 |
| Process priority | Sets the forwarder's priority relative to other processes, Normal or Low | Off by default. Normal when you turn it on |
| Network limit | Caps the bandwidth the forwarder may use | Off by default |
A CPU limit is the one that most often surprises people, because 5 percent of a busy server is a small amount of a machine and a full pass over a dense filesystem is a lot of work. The forwarder will honor it and the scan will take as long as that arithmetic demands.
The same three settings can be given at install time on Windows, as installer parameters, which is how a scripted rollout applies them from the first run. For a fleet, prefer the policy: it is one change for a group rather than a reinstall per host, and it is visible to whoever picks up the ticket after you.
Which throttles apply to when scanning happens?
Scan mode, which decides whether the forwarder reacts to files as they appear, or only during a nightly window.
- Real time scanning is the default. After the initial backscan, the forwarder responds to new and changed files as they happen and runs no further scheduled scans.
- Only backscan mode turns that around: no real time scanning, and a daily backscan inside a window you set, with start and end times in 30 minute increments. Jitter spreads the start across assets by up to 30 minutes either side of the time you chose, so a large group does not begin scanning in unison.
Three consequences worth knowing before you choose it. A backscan can take a few minutes past its start time to actually begin. An asset that is offline when its window opens skips that night rather than catching up immediately. And if the window is short and the resource limits above are tight, the scan may not finish, which is the state that reports as Sleeping. If you use backscan-only mode, give it either a generous window or generous limits, and preferably both.
You can see which mode an asset is in from the Scan mode column in the Assets view, and a one-off backscan can be run at any time regardless of the mode. See Force or Skip a Backscan.
How many connections will a forwarder open?
Separately from anything in a policy, each forwarder bounds its own concurrency. These are build-time limits, not settings, and they are the reason a forwarder does not open a connection per file it wants to send.
| Platform | Concurrent uploads | Adjustable? |
|---|---|---|
| Windows | 5 | Yes, via MAXNUMBEROFUPLOADERS at install time |
| macOS | 5 | No. Hard-coded, and fixed for a given forwarder version |
| Linux | No fixed cap; the connection pool holds at most 5 idle connections, 1 per host | No |
macOS is the one worth knowing about, because it is the only platform where the answer is not negotiable. The limit is compiled into each release, so a Mac fleet uploading more slowly than you expected is not a policy you can loosen -- it is the forwarder being deliberately quiet on the network, and the way to speed it up is to give it less to send rather than more room to send it.
On Windows the same number is a default rather than a ceiling. See Windows Install Parameters.
These limits are about connections, not bandwidth. If the concern is how much of the link the forwarder uses rather than how many sockets it holds, the network limit above is the setting you want.
What happens when an asset is in two groups?
It takes the most restrictive value of each setting, evaluated per setting rather than by picking one policy to win.
That is the single most common reason a machine behaves more conservatively than the policy you are looking at appears to allow. Before you raise a limit, list every group the asset belongs to, because raising it in one policy changes nothing if another policy is the one binding.
What should I read next?
- Asset Configuration, for each of these settings as a setting, and the screens that hold them.
- What to Check First, if the forwarder is delivering nothing rather than delivering slowly.
- Force or Skip a Backscan, to run a full pass now instead of waiting for a window.
Updated 2 days ago