Installation

Installation

What the packages contain, where files land, what the install scripts do, and how to remove it.

Requirements

• Windows 10 or 11. The packages carry a win-x64 build.
• Administrator rights to install.
• osquery at C:\Program Files\osquery\osqueryi.exe. The MSI post-install script checks for it and, if missing, attempts winget install --id osquery.osquery --silent. That step soft-fails: the install still succeeds, and the runner falls back to WMI where it can (the serial number, for example), but most module data needs osquery.
• Network reachability to your ReportMate API.

Packages

build.ps1 produces these into release/, and the GitHub release for a tag carries the same set:

Artifact	Use
ReportMate-<version>.msi	Primary format. Built by cimipkg from build/pkg/, not from WiX authoring
ReportMate-<version>.nupkg	Chocolatey-compatible package, built by cimipkg from build/nupkg/
ReportMate-<version>.zip	The NUPKG payload plus an install.bat, for manual deployment and testing

GitHub releases are built unsigned. Sign the binaries and the installer with your own code-signing certificate before distributing them; the release notes include a signtool recipe. See Building and Releasing.

The package identifier is com.github.reportmate.windows.

Install the MSI silently:

msiexec /i ReportMate-<version>.msi /qn

To configure the API at install time, set REPORTMATE_API_URL and REPORTMATE_PASSPHRASE in the installer's environment, or place a .env file carrying them in the package. See Configuration.

Install locations

C:\Program Files\ReportMate\

File	What it is
managedreportsrunner.exe	The agent. Self-contained, single file, trimmed
Managed Reports Runner.exe, resources.pri and the Windows App SDK runtime files	The Managed Reports Runner App
usagetracker.exe	Per-user foreground and active time tracker
speedtest.exe	Ookla Speedtest CLI, used by the network module's quality check
appsettings.yaml	Config template, copied to ProgramData at install time
appsettings.template.yaml	Untouched reference copy
appsettings.json	Shipped when present in the source; not read at runtime
module-schedules.json	Drives scheduled-task creation
uninstall-tasks.ps1	Removes the scheduled tasks
osquery\enabled-modules.json, osquery\modules\*.json	Query packs. The runner restores missing ones in ProgramData from here
cimian\postflight.ps1	Cimian integration script, copied into C:\Program Files\Cimian\
version.txt	Version, build date and commit

C:\ProgramData\ManagedReports\

Path	What it is
appsettings.yaml, appsettings.template.yaml	Copies of the config files. The runner reads appsettings.yaml only when it is trusted (see Configuration)
osquery\	Runtime copy of the query packs
cache\	Per-collection module JSON and event.json
logs\	Rolling log plus per-transmission payload copies
config\, data\	Created by the installer
usagetracker\	Per-user usage files written by usagetracker.exe

Registry keys are described in Configuration.

What the MSI post-install does

build/pkg/scripts/postinstall.ps1 runs after cimipkg copies the payload. It fails the install (exit 1) on anything the agent cannot run without, and keeps nice-to-have steps soft.

1. Verifies the payload contains managedreportsrunner.exe, usagetracker.exe, appsettings.yaml, module-schedules.json, Managed Reports Runner.exe and resources.pri, and fails if any is missing.
2. Appends C:\Program Files\ReportMate to the machine PATH, so a new terminal can call managedreportsrunner.exe directly.
3. Creates the Start Menu shortcut to the app for all users.
4. Enables process telemetry for usage tracking: Security-log process creation auditing (event 4688) through auditpol, falling back to enabling Microsoft-Windows-Kernel-Process/Analytic or /Operational with wevtutil.
5. Loads .env and the installer-time variables.
6. Configures the registry: secures HKLM\SOFTWARE\ReportMate\Secrets, moves any credential in a legacy key into it, copies legacy settings into HKLM\SOFTWARE\ReportMate\Settings where Settings lacks them, writes the supplied API URL and passphrase where nothing already sets them, and fills in defaults where Settings has no value. An upgrade never overwrites a value an administrator, the app or policy set.
7. Creates the ProgramData tree and locks C:\ProgramData\ManagedReports down: SYSTEM and Administrators full control, Users read, no inheritance from ProgramData, owned by Administrators. usagetracker\ additionally lets Users create files, and each user may change only the file they created.
8. Copies the config files and the osquery packs to ProgramData, verifying the module count.
9. Removes any existing ReportMate scheduled task by exact name, including the retired names ReportMate Data Collection, ReportMate Data Transmission and ReportMate Usage Tracker, then registers the current set from module-schedules.json.
10. Copies the files under C:\Program Files\ReportMate\cimian\ into C:\Program Files\Cimian\. A locked file there costs only that file.
11. Checks for osquery and installs it through winget if absent.
12. Runs managedreportsrunner.exe info as a smoke test, reporting only.
13. Starts the first check-in in a hidden background PowerShell, so the install is not held up: --hello first, so the device is listed within seconds, then --force --storage-mode quick, a full collection of every enabled module.

The NUPKG post-install performs the same registry, directory and task work; build.ps1 inlines build/resources/install-tasks.ps1 into it.

What pre-install does

build/pkg/scripts/preinstall.ps1 frees the install location before the payload is copied. It disables the ReportMate scheduled tasks, then stops managedreportsrunner, usagetracker, Managed Reports Runner, any older runner binary and any osqueryi child, falling back to taskkill /F /T. Every Task Scheduler call is time-bounded, because a degraded scheduler can otherwise hang the install with the old payload already removed.

If a binary stays locked, the installer engine defers replacement to the next reboot, which leaves the registry and Add/Remove Programs claiming the new version while the task keeps firing the old binary. Preventing that is why the script exists.

Scheduled tasks

Tasks are addressed by exact name through the Task Scheduler COM API rather than by enumerating the task store. One broken entry anywhere in the store, typically another product's task whose definition file is gone, makes every enumeration fail; lookups by name are unaffected.

The four collection tasks run managedreportsrunner.exe as SYSTEM at highest privilege, hidden, with a 30-minute execution limit, three restarts five minutes apart, only when a network is available, and allowed to start on battery.

Task	Arguments	Trigger
ReportMate Hourly Collection	--run-modules security,network,management,identity,hardware --storage-mode quick	Every hour, random delay up to 55 min
ReportMate 4-Hourly Collection	--run-modules applications,inventory,system,peripherals	Every 4 hours, random delay up to 55 min
ReportMate Daily Collection	--run-modules hardware --storage-mode deep	Daily at 09:00, random delay up to 120 min
ReportMate All Modules Collection	MSI: --storage-mode quick. NUPKG: --run-modules with every module except installs, plus --storage-mode quick	Daily at 04:00, random delay up to 120 min
ReportMate User Session Tracker	runs usagetracker.exe	At logon, plus a daily 09:00 watchdog

The MSI registers the all-modules task with no module filter, so it is a full collection of every enabled module, installs included, and is subject to the MaxDataAgeMinutes check. The NUPKG passes the explicit list from module-schedules.json, which leaves installs out.

The random delays matter. Pinning every device to the same absolute clock concentrated a fleet's check-ins into the first minutes of each hour; each device draws its own offset within the window instead.

The all-modules task carries -StartWhenAvailable and -DontStopIfGoingOnBatteries, which the others do not, because a once-daily overnight trigger has no second chance: a portable device asleep through the window would otherwise never run it.

The session tracker task uses a BUILTIN\Users (S-1-5-32-545) group principal at limited run level, so it runs as whichever user logged on, with no elevation and no time limit. A named mutex inside the tracker makes the daily watchdog trigger a no-op when it is already running.

Edit module-schedules.json in the install directory and reinstall to change the schedule.

Cimian integration

When Cimian is present, the package places postflight.ps1 in C:\Program Files\Cimian\. After a Cimian run it calls:

& 'C:\Program Files\ReportMate\managedreportsrunner.exe' --run-modules inventory,installs

so install state reaches the dashboard right after Cimian changes it.

Verifying

Get-ScheduledTask -TaskName 'ReportMate*' | Select-Object TaskName, State

managedreportsrunner.exe info -v

managedreportsrunner.exe --run-modules inventory,system -vv

Uninstalling

Uninstall the package as normal. To remove the scheduled tasks, run the bundled script from an elevated shell:

& 'C:\Program Files\ReportMate\uninstall-tasks.ps1'

It removes the five current task names and the three retired ones, and does not fail if a task cannot be removed. HKLM\SOFTWARE\ReportMate (with its Settings and Secrets subkeys), HKLM\SOFTWARE\Policies\ReportMate and everything under C:\ProgramData\ManagedReports\ are left in place; remove them by hand for a clean machine.