Troubleshooting & FAQ

This page is also in the Groundskeeper wiki: https://github.com/rsjsoftwareltd/groundskeeper/wiki/Troubleshooting

Common issues and questions. If something here doesn't cover it, ask in Discussions.

Installation & access #

My browser shows a security / certificate warning #

This is expected. Groundskeeper serves the dashboard over HTTPS using a self-signed certificate made the first time the service starts, so browsers warn that they can't verify it. On a self-hosted tool on your own network this is normal.

For a one-off, click through the warning (Advanced -> proceed).
To remove it on managed devices, the installer ships tools\Trust-GroundskeeperCert.ps1, which can be pushed via Group Policy to trust the certificate estate-wide -- handy for a wall display or shared machine where you don't want a warning every time.

Can I use it on my phone? #

Yes. Open the same address in your phone's browser (you will meet the same certificate warning as above). On a screen narrower than a tablet the sidebar becomes a narrow icon rail down the left, and the first page you open in a session slides the full menu out with its names for a moment so you can see what the icons mean. Tap the chevrons at the bottom of the rail to open the full menu over the page, tap the page to close it. The activity feed puts each event's buttons in a row under its title, sized for a thumb. Nothing changes on a laptop or desktop.

The dashboard won't load #

Work through:

Is the service running? Check the Groundskeeper Windows service is started (services.msc, or sc query Groundskeeper). The Start Menu folder also has a Stop Service shortcut, which asks for administrator approval. There is no Start shortcut: start it from services.msc, or reboot.
Right address? It's HTTPS on port 8443 -- https://<server-address>:8443 (not http, not port 8000).
Firewall: if you're reaching it from another machine, make sure inbound TCP 8443 is allowed to the server on the local network.
Logs: check the logs folder under C:\ProgramData\RSJ Software\Groundskeeper\Server (not the install directory) for startup errors.
The service stops straight after starting, and the log mentions the TLS key? Groundskeeper never quietly replaces its HTTPS key, because every agent is pinned to it. Usually the service account has lost read access to the key. In services.msc, set the service's Log On to Local System for now and start it; then open General Settings > About > Service account and click Apply now, which grants the account read access to the key again. If the key is lost or damaged for good, delete the certs folder in the program folder and restart to make a new one, then re-deploy the agents from Agent Settings (see below).
The service won't start after the service account's password changed in Active Directory? Windows then refuses to start it (error 1069, "logon failure"), and nothing in Groundskeeper can say so because it isn't running. In services.msc, open Groundskeeper > Log On and enter the new password (or switch it to Local System for now), start the service, then update the password under General Settings > About > Service account and click Apply now. See Service Account.

I've forgotten the admin password #

If your account has a recovery email and email is set up, use Forgot password? on the login page, or ask another admin to reset it from Settings > Users. If you are the only admin and neither works, recovery is done on the server: in config.yaml, delete the users: list under app: and restart the Groundskeeper service. The login page then offers to create the first admin account again -- from a browser on the server itself. Your configuration and data are untouched; any other accounts need adding again in Settings > Users. (Keep the admin password somewhere safe to avoid needing this.)

Connectors #

A connector shows an error #

Use Test connection on that connector's card on the Connector Settings page -- it exchanges the credentials and does a small live check, and the error it returns usually points straight at the cause (bad key, wrong region, unreachable host).
Check the credential is current and has the permission level the connector needs (these are listed per connector on the Connectors page).
For the Windows-infrastructure connectors, confirm the relevant RSAT feature is installed and that Groundskeeper is running on a domain-joined server.
Active Directory discovery or the AD connector fails: install the AD module (Install-WindowsFeature RSAT-AD-PowerShell, as Administrator), and run the service as a domain account rather than Local System -- see Service Account.

The AI says Ollama isn't running #

The local AI needs Ollama on the server. Install or update it from Settings > AI > Ollama on this server, then use Test connection and download a model from the same tab.
If Ollama runs on another machine, check the address under Settings > AI and that the machine accepts connections on port 11434 from this server -- see AI Features.
Everything else keeps working without the AI; only the summaries and "Ask Groundskeeper" wait for it.

Asking for help #

General Settings > Logs shows the live log, lets you change how much is logged, and has Collect logs for support. That builds a .zip on your own computer -- nothing is sent anywhere -- with passwords and keys taken out as far as it can. Look through it before you attach it to a post in Discussions.

I can only enable 5 connectors #

That's the Community edition limit. Pro lifts it. Note that AI and the Central hub don't count against the connector limit -- only actual connectors do.

Licensing #

My licence key won't activate #

Confirm the server can reach api.rsjsoftware.com over outbound HTTPS -- that's where activation and the periodic heartbeat happen.
If you requested a Community key with a school email address, it is issued and activated straight away. From a webmail address it is checked by hand and emailed within a business day; activation is then automatic. Not arrived? Check spam, or email licences@rsjsoftware.com.
If you already have a key, enter it under Settings > Licence (the "Already have a key?" link on the dashboard banner takes you there).
Groundskeeper has a 7-day offline grace period, so a brief loss of internet won't stop it working.

Privacy & data #

Does my school's data leave the network? #

No school monitoring data is stored externally. Groundskeeper runs on your server and reads from your systems locally. The only outbound traffic is:

The licence heartbeat to api.rsjsoftware.com (install identity and status -- no monitoring data).
Periodic version checks to GitHub (to tell you when an update is available -- no monitoring data).
If you enable a cloud AI provider, scrubbed monitoring context is sent to that provider. Local Ollama AI sends nothing. See AI Features.

See the privacy notice on the marketing site for the full statement.

Does Groundskeeper change anything on the systems it monitors? #

No. Every connector is read-only -- Groundskeeper reads status and never writes to, reconfigures or controls a monitored system.

Agent (RSJ Agent) #

Do I need the agent? #

No -- it's optional. The agentless connectors cover a lot on their own. The RSJ Agent, the endpoint agent, adds richer per-device detail (BitLocker, Defender, firewall, pending reboots, SMART disk health, battery, crash events, local admin audit, update compliance) by running on each endpoint and checking in to your local Groundskeeper server. It's deployed separately, from Agent Settings or via Group Policy.

The agent version doesn't match the server #

That's expected: the RSJ Agent has its own version number, separate from Groundskeeper's. Each Groundskeeper release bundles a version of the agent and offers it to your machines, and each machine updates itself at a following check-in. Agent Settings -> Devices shows each machine's agent version and, if an update failed, the reason. The agent only checks in to your local Groundskeeper server, never to the internet.

How does the agent know it's talking to the right server? #

Each machine's RSJ Agent is pinned to your Groundskeeper server: it records which certificate the server presents, and refuses to talk to anything presenting a different one. It is recorded in two ways:

Groundskeeper's own certificate (the default, self-signed one). The agent records the certificate's fingerprint and accepts only that certificate.
A certificate your machines already trust (one you configured in config.yaml's app.tls section, issued by a certificate authority your machines trust). The agent records system and accepts any certificate your machines trust for that name, so renewing the certificate does not cut the agents off, while a home-made certificate is still refused.

When the pin is made. A machine installed from Agent Settings (the deploy script or push-deploy, v0.183.2 and later) is pinned during the install: the script carries the server's fingerprint, checks the installer's download against it and against the installer's own checksum, and enrols the agent with the pin. A machine enrolled any other way, or before v0.183.2, is pinned the first time it reaches the server after its agent updates to host 0.8.27, and keeps that pin from then on.

That first contact is a trust-establishing moment: the agent cannot tell a genuine first contact from an intercepted one. So:

Deploy on a network you trust -- the school's own managed LAN, not a guest network or an untrusted wireless access point.
For extra assurance, check the pin. It is the pin line in the [server:groundskeeper] section of C:\ProgramData\RSJ Software\Agent\agent.conf (readable by administrators only). Compare it with your server's certificate fingerprint (SHA-256), shown in your browser's certificate details when you visit the dashboard.

When the certificate renews. Groundskeeper's own certificate lasts about two years and renews itself a month before it ends, keeping the same key. The agents remember the key as well as the certificate, so they follow the renewal on their own (RSJ Agent 0.8.28 and later). Machines pinned as system follow any certificate your machines trust, so renewing your own is fine too.

If you replace the certificate -- you switch to your own, or you delete the certs folder to get a new key -- machines pinned by fingerprint refuse the new one and stop checking in, and each one's log says why. So set up your own certificate before rolling out the agents if you can. If you change it later, re-deploy the agents: run the deploy script from Agent Settings again (by Group Policy or by hand). Each machine takes the new pin at once, with no restart. For a single machine you can instead remove the pin line from its agent.conf; it pins the new certificate at its next connection.

This is standard Trust-On-First-Use (TOFU) behaviour -- the same model SSH uses for host keys -- but it's worth knowing before a wide agent rollout.