Duplicate and Re-Registered Assets

When a forwarder is first installed it registers with Stairwell and receives an asset ID. From then on it identifies itself with that ID, and Stairwell attaches file history and policy to it.

The goal is continuity: a machine that is reinstalled or re-registered should come back as the same asset, carrying its history, rather than appearing as a new one. That is worth caring about because history is the product. An asset that splits into two is a machine whose file history is now in two places, and neither half is the whole answer.

How does Stairwell decide it is the same machine?

By a registration key, sent during registration. The key is built from information that is usually stable, the hostname and a MAC address, and Stairwell looks for an existing asset with that key before creating a new one.

"Usually stable" is doing real work in that sentence, and this is where duplicates come from:

• A machine can have several real and virtual MAC addresses, and picking the right one is not obvious.
• Hostnames change.
• A machine is decommissioned and replaced by a different one with the same name.

Any of those can change the key, and a changed key means a new asset ID. The machine looks new to Stairwell even though nothing about it is.

An asset ID and an asset name are not the same thing. The name is generally the hostname and is what you see in the assets list. Changing the registration key gives you a different asset ID; it does not otherwise change how the asset is displayed. So a duplicate is not always obvious from the list, which is why it is worth preventing rather than spotting.

How do I set my own registration key?

Supply a value that is stable and unique in your environment, such as an inventory or serial identifier. Stairwell uses it to find the existing asset, or to create one if there is none.

Windows, from forwarder v1.6.6. The forwarder reads the STAIRWELL_REGISTRATION_KEY environment variable during registration and sends its value as the key.

Unset or empty, it falls back to {hostname}{MAC address with lowest ID}, for example win-e77c9dut14e@00:15:5d:00:33:0d.

macOS, from forwarder v1.6.6. The key can be set through STAIRWELL_REGISTRATION_KEY in an MDM profile.

Unset, it falls back to {hostname}{MAC address of the internal network interface}, for example Marks MacBook Prof8:12:34:56:78:90.

Linux does not support custom registration keys yet.

The fallback algorithm has changed between forwarder releases and may change again. That is the argument for setting the key explicitly on any fleet where identity matters: a value you chose does not change underneath you, and one derived from hardware might.

What should I read next?

• Assets, for what an asset record holds and why it outlives the machine.
• Asset Identifiers, for finding an asset ID.
• Archive Inactive Assets, for tidying up duplicates that already exist.