Force or Skip a Backscan

A backscan is the pass a forwarder makes over the files already on a machine, as distinct from reacting to files as they appear. It runs once at install so that the machine's history is in Stairwell from the start, and you can run it again on demand. The fastest way to force one is from the Assets view in the app, and it does not need anyone to touch the host. Skipping it is an install-time decision, and it means the machine's pre-existing files are not in Stairwell until a backscan does run.

Force one after a policy change that widens what gets collected, on a machine whose initial scan was skipped, or when you have reason to think a machine's coverage is incomplete. Check the Backscan status column before you do, because a scan already in progress does not need starting again.

How do I run a backscan now?

From the Assets view, on one asset, on many at once, or on a whole group.

1. Open Assets.
2. Select the assets you want. To do a whole group, switch to the Groups tab and select the group instead.
3. Right click to open the context menu.
4. Choose Run backscan.

The status moves to In progress, and a one-off backscan runs to completion regardless of the scan mode the asset's policy sets. That last part is the reason to prefer this route: an asset in backscan-only mode with a narrow nightly window will finish a one-off scan rather than stopping at the end of the window.

Two things to expect while it runs. Disk read activity on the host will be elevated, which is normal and temporary. And the resource limits in the asset's policy still apply, so a machine with a tight CPU or network limit will take proportionally longer. See Throttles if the scan seems not to be progressing.

How do I force a backscan from the host itself?

Only when the app route is not available to you, for example on a machine that has lost its connection to Stairwell and is being repaired locally. Forcing from the host means clearing the local record of scan progress and letting the forwarder start over.

Linux

Stop the service, remove the scan state file, and start it again.

sudo systemctl stop stairwell
sudo rm /var/lib/stairwell/scansession.json
sudo systemctl start stairwell

Windows

Ask Stairwell support for the current backscan reset script. The steps are to stop the forwarder service, clear the backscan values under the forwarder's registry key, re-enable the full volume scan, and start the service again, and the script handles both the current and the older service names. Doing it by hand is not recommended, because the specific values differ across forwarder versions.

macOS

There is no supported local procedure. Use Run backscan from the Assets view, or contact Stairwell support.

How do I skip the backscan at install time?

On Windows, pass DOSCAN=0 to the installer. The default is 1, meaning perform the scan.

.\StairwellForwarderBundle-1.7.9.1.exe TOKEN="<AUTH_TOKEN>" ENVIRONMENT_ID="<ENV_ID>" DOSCAN=0 /quiet /norestart /log C:\stairwell.log

Take the exact installer filename from Windows v1.7.9, since it carries a build number that changes with each release. The interactive installer offers the same choice during setup.

There is a second Windows option worth knowing, on forwarder 1.7.2 and later: ENABLESLEEPMODE=1 installs the forwarder asleep, and a forwarder that starts asleep does not run its initial backscan until it is woken. Use that when you want to stage installs now and start collecting on a schedule you control, rather than when you want to skip the historical files permanently.

On Linux and macOS, skipping the initial backscan needs a configuration change before the service first starts. Contact Stairwell support for the platform-specific instructions.

What do I give up by skipping it?

Everything that was on the machine before the forwarder arrived, until a backscan runs.

Files appear in Stairwell going forward as they are written, modified, or executed, so the machine's future is covered and its past is not. That matters most in exactly the situation you want Stairwell for: a report published next month names a hash, you search your fleet, and a machine that has held that file untouched for a year does not answer, because nothing has caused the forwarder to notice it.

Skipping is a reasonable choice when you are deploying at speed and will backfill deliberately, or when you only need forward-looking visibility from a particular class of machine. It is not a reasonable default. If the reason you want to skip is the resource cost of the first pass, the better tools are the resource limits and the nightly window described in Throttles, which slow the scan down rather than remove it.

What should I read next?

• Throttles, for the limits that decide how fast a backscan is allowed to go.
• What to Check First, if a backscan says it is running and you cannot see the result.
• Asset Configuration, for scan modes, nightly windows, and the exclusions that decide what a scan collects.