-
Notifications
You must be signed in to change notification settings - Fork 0
Backup and Restore
Groundskeeper keeps everything it needs in a small number of files on the server. Backing up is mostly a matter of copying those somewhere safe; the installer already preserves them across upgrades.
Everything lives under C:\ProgramData\RSJ Software\Groundskeeper\Server (not
the install directory -- as of v0.66.0, Groundskeeper's writable data is kept
separate from the application binaries in C:\Program Files\Groundskeeper, so
the service account only ever needs write access to the ProgramData folder;
as of v0.181.0 that folder sits under the RSJ Software company folder, beside
the other RSJ products). The
two files that matter are:
-
config.yaml-- all your configuration: enabled connectors, their settings, and credentials. Sensitive values (API keys, passwords, tokens) are encrypted at rest using Windows DPAPI. The admin password hash and session key also live here. -
groundskeeper.db-- the SQLite database: feed history, cached summaries, connector state and other stored data. (You may also seegroundskeeper.db-walandgroundskeeper.db-shmsidecar files next to it while the service is running -- these are SQLite's write-ahead-log files and don't need to be backed up separately; stopping the service first folds them back into the main.dbfile.)
Back up both together and you have everything.
You no longer have to arrange this yourself for groundskeeper.db. Every
night, Groundskeeper takes a copy of the database, checks that the copy is
readable before keeping it, and deletes the oldest once it has more than it is
asked to keep.
Settings -> Backup -> Database Backup shows the schedule, where the files go, and what is there, with a Back up now button if you would rather not wait for tonight.
Defaults, all changeable in config.yaml under backup::
| When | 02:30 daily |
| Where | a backups folder next to the database |
| How many kept | 7 |
Point directory at another drive or a file share if you can. A backup on
the same disk protects you from a corrupted file or a bad change; it does not
protect you from that disk failing. The service account needs write access to
wherever you choose.
If a backup fails -- no space, no permission, an unreadable copy -- it appears once on the dashboard feed, with the reason, and once more when it starts working again. It will not repeat every night.
You can, but stop the service first. Groundskeeper's database runs in SQLite's
WAL mode, where a recently-saved change lives in the groundskeeper.db-wal
file until it is folded into the main one. Copying groundskeeper.db on its
own while the service is running can therefore miss recent data without any
sign that anything went wrong -- you get a file that looks fine and quietly
restores to an earlier state.
The built-in backup uses SQLite's own backup mechanism, which is safe to run while the service is working and always produces a complete copy.
Each nightly database copy gets a groundskeeper-<stamp>.config.yaml beside
it -- that night's config.yaml, as it was. It lives and dies with its
database copy, and the restore dialog can put the two back together (below).
Two things to know: the saved credentials in it can only be read on the machine
that saved them, so it does not move settings to a new server -- Settings
-> Backup -> Backup & Restore still does that, as a password-protected file
you can download; and everything else in it is as you typed it (community
strings, server names), so a backup folder on a share deserves the same
access control as config.yaml itself. include_config: false under
backup: turns the copy off.
Each backup in the list on Settings -> Backup -> Database Backup has a Restore... button. It is deliberately not a quick click:
- The confirmation says exactly what is lost -- everything Groundskeeper
recorded after that backup was taken (alerts and their acknowledgements,
incidents, device check-ins, connector state) -- and you type
RESTOREto go on. Your settings and credentials inconfig.yamlare not touched -- unless you tick Also put back the settings saved with this backup, offered when that night's settings were saved beside it, which restores thatconfig.yamltoo and keeps the one it replaced beside it asconfig.pre-restore-<stamp>.yaml. - Groundskeeper checks the backup is readable before anything is replaced, and refuses if it is not, leaving the live database alone.
- It then stops and restarts itself to swap the file in, which takes about a
minute; the page reloads on its own when the service is back. (If the
automatic restart cannot be scheduled -- the account running the service
needs to be a local Administrator for that, the same as the About screen's
Restart Service button -- the page says so, and restarting the service
yourself from
services.mscwithin 30 minutes applies it instead.) - The database it replaced is kept, beside the live one, as
groundskeeper.pre-restore-YYYYMMDD-HHMMSS.db(with any-wal/-shmrenamed alongside it). If the restore was a mistake, stop the service, rename that file back togroundskeeper.db(deleting the newergroundskeeper.db,-waland-shmfirst), and start the service. Only the most recent such copy is kept.
A restore that is staged but not applied within 30 minutes -- because the restart never happened -- is abandoned rather than applied on some later, unrelated restart, and the dashboard feed says so. The feed also records every restore that was applied, naming the backup it came from.
Restoring onto a different machine is still the manual sequence under Restoring below: the button only knows about the backups on this server.
An automatic backup on the server is a floor, not a ceiling. Including
C:\ProgramData\RSJ Software\Groundskeeper\Server in your normal server backup
regime (Veeam or similar) is still the right thing to do -- it gets the backups
off the box, and covers config.yaml at the same time.
Upgrading from a version before v0.181.0? Groundskeeper moves your existing data folder from
C:\ProgramData\Groundskeeper\ServertoC:\ProgramData\RSJ Software\Groundskeeper\Serverautomatically the first time the service starts on the new version (and, from a version before v0.66.0, out of the install directory in the same step). You don't need to do anything -- just make sure any existing backup job pointed at the old location gets updated to the new path after upgrading. Nothing is deleted: if a file could not be moved, it stays where it was and the log says so.One confusing side effect worth knowing about: you may still find an old
config.yamlorgroundskeeper.dbsitting inC:\Program Files\Groundskeeperafterwards, frozen at the date of that upgrade. The migration deliberately never deletes anything from the old location, so stale copies can linger there for ever. They are not the live files -- the app only reads the ProgramData location -- and their small size or old date does not mean anything is wrong. If they bother you, the only leftover names areconfig.yaml,config.yaml.bak,groundskeeper.db(plus-wal/-shm), and thelogsfolder; everything else in the install directory belongs to the product (in particular,certsholds your live HTTPS certificate andconfig.example.yamlis the shipped settings reference -- leave both alone).
The encrypted secrets in config.yaml are protected using Windows DPAPI,
which ties the encryption to the machine they were encrypted on. This is a
good security property, but it has one consequence:
A
config.yamlrestored onto a different machine will not be able to decrypt its stored credentials -- the encrypted values are only readable on the original server.
So:
- Restoring onto the same server (e.g. after a reinstall): everything works, including the encrypted credentials.
-
Moving to a new server: restore
config.yamlandgroundskeeper.dbto get all your non-secret configuration and history back, then re-enter the connector credentials once via Settings. Groundskeeper re-encrypts them to the new machine on save. (Your connector choices, thresholds and history carry over -- it's only the secret values that need re-entering.)
If you're planning a server migration and want to avoid re-entering everything, note the credentials you'll need ahead of the move.
- Install the same (or newer) version of Groundskeeper on the target server.
- Stop the Groundskeeper service.
- Copy your backed-up
config.yamlandgroundskeeper.dbintoC:\ProgramData\RSJ Software\Groundskeeper\Server, replacing the fresh ones (create the folder first if it doesn't exist yet -- a fresh install creates it on first service start). If you are restoring one of Groundskeeper's own nightly backups, it will be namedgroundskeeper-YYYYMMDD-HHMMSS.db-- copy it in and rename it togroundskeeper.db. Delete anygroundskeeper.db-walandgroundskeeper.db-shmfiles sitting beside it before starting the service. They belong to the database you are replacing, and leaving them there can undo the restore. - Start the service.
- If you've moved to a new machine, open Settings and re-save each connector's credentials (see the DPAPI note above).
You don't need to back up specially before an upgrade: running a newer
GroundskeeperSetup.exe over an existing install preserves config.yaml,
groundskeeper.db and your licence automatically. The installer detects the
existing install and shows an "Update" flow rather than a clean install. A
backup is still good practice, but the upgrade itself is non-destructive.
Most of what Groundskeeper stores in groundskeeper.db prunes itself
automatically on a rolling window (feed history and AI query logs after 90
days, password reset tokens after 7 days, and so on). Two tables are
exceptions worth knowing about specifically -- a MAT's Data Protection
Officer may well ask "how long do you keep this?", and for these two the
honest answer is "until you delete it yourself":
- Device records. Each device the agent checks in from has one row holding its most recent snapshot (hostname, logged-in user, installed software, and similar). This is a live snapshot, not a history -- it's overwritten on every checkin -- but the row itself is kept indefinitely. There's no automatic expiry. To remove a retired device's record, delete it manually from the dashboard.
- Incident log entries. "Deleting" an incident from the Incident Log only hides it from the normal view. The underlying record is never permanently removed -- this is deliberate, so the log can serve as a reliable audit trail, not an accident.
Both tables live inside groundskeeper.db, entirely on your own server (see
"What to back up" above) -- Groundskeeper never sends this data anywhere.
As the data controller for your own installation, decisions about how long
to keep old device records or incidents are yours to make; if your school
or trust has its own retention schedule, a periodic manual review of these
two tables against it is worth building into your routine.
- Schedule a copy of
C:\ProgramData\RSJ Software\Groundskeeper\Server\config.yaml-
groundskeeper.dbto a file share, or include that folder in your existing server backup job.
-
- Keep at least one copy off the server itself.
- Test a restore once, onto the same machine, so you know the process before you ever need it in anger. The Restore... button on the Database Backup card is the easiest way to do that with one of last week's nightly backups -- the database it replaces is kept, so the rehearsal costs nothing.
- Getting Started -- installation and upgrades.
- Troubleshooting & FAQ.
Last updated: 2026-09-22 (v0.181.0)