Censusby Steward IT

Documentation › Inventory

Census agent

The Census agent is a small program (about 7 MB, no dependencies) that inventories the computer it runs on and reports to your Steward IT Census server over HTTPS. Use it for:

  • laptops that are often away from the office (it reports from anywhere the server is reachable, e.g. over VPN or a published port)
  • computers on other subnets / sites or behind firewalls
  • computers where you can't enable WinRM or SSH
  • instant actions: the agent keeps a connection open to the server, so deployments, scripts, console commands, service control and screenshots start within a second or two

It's available for Windows (x64, ARM64), Linux (x64, ARM64, 32-bit ARM) and macOS (Intel, Apple Silicon). It collects the same data as a WinRM/SSH scan, and runs as SYSTEM (Windows) or root (Linux/macOS).

Installing#

All methods need three values, shown on Scanning › Census agents: the server URL, the agent key and the certificate fingerprint.

The Install panel on that page has one section per program, closed until you click it: Census agent, Census Action Launcher and Census Remote Scanner. Each has the build, how to install it (a deployment, a download, and for the agent the USB installer), and its command lines for a manual install.

  • Agent key: proves the agent belongs to your organization. Without it, anyone who can reach the server could submit fake inventory or use up your licensed assets.
  • Certificate fingerprint: pins the server's self-signed certificate, so no other machine can impersonate your server. It's not needed if you install a certificate trusted by your computers (see Installation).

You never have to type them. Use one of these methods.

USB / file share installer (easiest)#

  1. On Census agents › Install, choose your platform and USB / network share installer (.zip), then Continue.
  2. Unzip it to a thumb drive or network share.
  3. On each computer, right-click install-census-agent.cmd › Run as administrator (Linux/macOS: sudo sh install-census-agent.sh).

The bundle contains your agent key, so keep it on trusted media. Rotate the key if it's lost (see below).

Push from the server (WinRM / SSH)#

Choosing Install Census agent as the package under Deployment › New deployment (also Push to computers on the Census agents page, or Install agent… for assets selected on the Assets list) installs the agent remotely over WinRM/SSH using your stored credentials, choosing the right build for each computer. See Deployment.

Install with the MSI (Intune, Group Policy, PDQ)#

For software deployment tools there is a Windows installer: Census agents › Install › Census agent › Download the agent MSI (census-agent-windows-amd64.msi; the release download calls it steward-it-census-agent-<version>-x64.msi). It's for 64-bit Windows and installs silently with your server's settings. The page shows the command with your values filled in:

msiexec /i census-agent-windows-amd64.msi /qn SERVER_URL=https://census.corp.local:8443 AGENT_KEY=<agent key> FINGERPRINT=<fingerprint>
Property Meaning
SERVER_URL The server's address, https://<server>:<port>. Required for a first installation.
AGENT_KEY The agent key. Required for a first installation; it is kept out of the installer's log.
FINGERPRINT The server certificate's fingerprint. Leave it out only if your computers trust the server's certificate.
  • Intune: package the MSI as a Win32 app with the Microsoft Win32 Content Prep Tool and use the command above as the install command. Intune fills in the uninstall command and the MSI detection rule.
  • Group Policy: use a computer startup script that runs the command above from a share the computers can read. Running it again at the next startup changes nothing once the agent is installed. (Group Policy software installation can't pass the properties, so use a startup script.)
  • PDQ Deploy and similar tools: run the same command.

The MSI installs the agent to C:\Program Files\Steward IT Census\census-agent.exe, sends a test report, and installs and starts the Census Agent service. If the server answers that the key or fingerprint is wrong, the installation stops and nothing is changed. If the server can't be reached at that moment (a laptop away from the office), the agent is installed anyway and keeps trying. A first installation without SERVER_URL and AGENT_KEY is refused with a message in the installer's log.

An agent that was installed with the install command or the USB installer can be replaced by the MSI: it keeps its settings and identity, and its own Programs and Features entry is replaced by the MSI's.

Upgrades and uninstall: a newer agent MSI upgrades the installed one in place. The properties can be left out then: the agent keeps its settings and its identity (the same agent, with the same history, in Census). Update on the Census agents page also works for agents installed with the MSI, and Programs and Features shows the new version afterwards. Uninstalling (Programs and Features, msiexec /x, or removing the Intune app) removes the service, the configuration and the program.

What the installer did is logged on each computer in C:\ProgramData\CensusAgent\msi-install.log. For the installer's own log, add /l*v C:\Windows\Temp\census-agent-msi.log to the command.

Raspberry Pi and other ARM computers#

Use census-agent-linux-arm64 on 64-bit ARM Linux (Raspberry Pi OS 64-bit, Ubuntu on a Pi 4/5, ARM servers) and census-agent-linux-arm on 32-bit Raspberry Pi OS (every Raspberry Pi model, including Zero and Pi 1). Install Census agent and agent updates pick the right one automatically.

Command line#

# Windows (administrator PowerShell)
.\census-agent-windows-amd64.exe install -server https://census.corp.local:8443 -key <agent key> -fingerprint <fingerprint>

# Linux / macOS
sudo ./census-agent-linux-amd64 install -server https://census.corp.local:8443 -key <agent key> -fingerprint <fingerprint>

The exact command for your server is shown on the Census agents page. install first sends a test report (so mistakes show immediately), then copies the agent to C:\Program Files\Steward IT Census\ (Linux/macOS /usr/local/bin/census-agent), installs it as a service and starts it. On Windows it also adds a Control Panel uninstall entry.

Group Policy (no service)#

To install the agent as a service with Group Policy, use the MSI. To inventory computers at every logon or startup without installing a service, use a startup script:

\\server\share\census-agent-windows-amd64.exe run-once -server https://census.corp.local:8443 -key <agent key> -fingerprint <fingerprint>

How often it reports#

The agent sends a full inventory at startup and then every 4 hours (change it under Configuration › General settings). Rescan now on an asset asks an online agent for a fresh inventory immediately.

Performance history#

From version 0.45.0, the agent (running as a service) measures CPU use, memory in use and how full the system disk is every 5 minutes, and sends 15-minute averages to the server. They're shown as charts on the computer's Performance tab (24 hours, 7 or 30 days) and used by the report Busy computers (last 7 days). History is kept for 30 days. While the server can't be reached the agent keeps up to 2 days of averages and sends them later. The one-time run-once mode (Group Policy) doesn't measure performance.

Upgrading#

From the web interface (recommended): after upgrading the server, copy the new census-agent-* files from the release into the server's agents data folder. Scanning › Census agents then marks older agents with update available:

  • click Update on one agent, or Update all outdated agents;
  • the new agent is sent like a deployment: within seconds when the agent is online, otherwise over WinRM/SSH with your stored credentials, or when the agent next connects. Its progress is under Deployment;
  • the agent replaces its program file, keeps its settings and identity, and restarts a few seconds later. The new version appears on the Agents page after its next report.

The update uses the build matching each computer (Windows/Linux/macOS, x64/ARM64); computers whose build is missing from the agents folder are skipped with a message. It works for agents of every earlier version.

The Agents page shows the version of each file in the agents folder next to its download link. An agent is offered an update only when the folder holds a different version than the agent runs; a warning appears when the folder's files are older than the server, which usually means the new files haven't been copied yet. (Files from releases before 0.13.2 show "version unknown"; the server's version is assumed for them.)

Manually: run install again with the new version (the same command, or the USB installer), or run census-agent upgrade with the new file as administrator/root. Settings and identity are kept.

Uninstalling#

  • Windows: Control Panel › Programs and Features › Steward IT Census Agent › Uninstall.
  • MSI installs: the same entry, msiexec /x with the MSI, or remove the Intune app.
  • Remotely: Census agents page › Uninstall. The agent removes itself the next time it connects (immediately if online), then disappears from the list.
  • Command line: "C:\Program Files\Steward IT Census\census-agent.exe" uninstall (administrator) or sudo census-agent uninstall.

Uninstalling removes the service, the configuration and the program. The asset stays in your inventory; archive or delete it there if wanted. Forget on the Agents page only removes the list entry, and an agent that is still installed reappears at its next report. Forget also withdraws a remote uninstall that hasn't run yet, and so does installing the agent again on that computer, so an old request can never remove a fresh install.

Each agent's own key#

Since version 0.33.0, every agent creates its own key the first time it connects and registers it with the server, using the shared agent key once. From then on it signs every request with its own key, and the server refuses anything for that agent that isn't signed with it. The shared key is in every installer, so on its own it can only add new agents; it can't be used to pose as an existing computer, pick up its tasks or replace its inventory. The Identity column on Census agents shows 🔑 own key, or shared key only for agents that still need an update. Nothing changes for installing: new and reimaged computers simply register as new agents.

A computer also stays with its agent: while an agent with its own key has been in touch within the last 24 hours, the server refuses an inventory report for the same computer (same serial number or MAC address) from a different agent, unless it comes from the same network address. The refusal is noted in the asset's history. A reimaged computer normally comes back from the same address and takes over at once; if it doesn't, or you want the handover sooner, Forget or Revoke the old agent on Census agents first (the install then succeeds; a refused install says so).

Revoke (next to an agent with its own key) locks that agent out for good, for example for a lost or stolen laptop. It moves to the Revoked agents section below the list, which keeps it locked out. To add the computer again, reinstall the agent on it: it registers as a new agent. Once a revoked computer no longer has the agent (reinstalled, wiped or retired), Remove clears it from that section; the lockout goes with it, so for a lost or stolen computer keep it listed (or rotate the agent key).

Rotating the agent key#

Census agents › Rotate agent key issues a new key. Existing agents stop reporting until they are reinstalled with the new key, so only do this if the key has leaked. For a single lost or stolen computer, use Revoke instead.

Files and locations#

Windows Linux macOS
Program C:\Program Files\Steward IT Census\census-agent.exe /usr/local/bin/census-agent /usr/local/bin/census-agent
Configuration C:\ProgramData\CensusAgent\agent.json /etc/census-agent.json /Library/Application Support/CensusAgent/agent.json
Service Census Agent (CensusAgent) CensusAgent.service launchd CensusAgent

Command reference#

census-agent install  -server URL -key KEY [-fingerprint FP]   install/upgrade as a service
census-agent run-once -server URL -key KEY [-fingerprint FP]   one report, no service
census-agent upgrade                                           replace the installed agent with this file and restart it (keeps settings)
census-agent uninstall                                         remove service, config and program
census-agent start | stop | status
census-agent print                                             show the inventory locally (JSON)
census-agent version