Onboarding profiles

An onboarding profile is part of an enrollment. It says what happens to each machine that joins through that enrollment, beyond installing the agent. Set it under Machines > Add machines, in Onboarding profile when you create the enrollment, or with the profile field of the enrollments API. Everything in it is optional.

The parts that need the machine itself (the stage, custom commands, "fix first", and re-registration) are written into the enrollment's scripts and playbook. The rest is done by the server when the machine first connects. Each step is listed per machine under Machines > Add machines > Onboarding and recorded in the audit log. A step that does not work is reported there and does not stop the others.

Join and monitor, or join and fix first#

Every enrollment gives you both kinds of script. Choose under Scripts above the list of enrollments, or add fix=true to the script's address in the API. For the playbook, add -e gardience_fix_first=true.

Join and monitor is how machines have always joined: the machine is scanned and goes straight into its patch ring.

Join and fix first holds the machine out of production automation until it is clean:

1. The machine joins and carries the grain gardience_hold: onboarding. It is in the built-in group Onboarding and in neither patch ring (Ring0-Pilot and Ring1-Broad), so scheduled patching and Patch Tuesday workflows leave it alone.
2. Once the profile's other steps are done (so updates come through the update cache and company repositories), Gardience scans it and opens one fix request for every machine waiting in Onboarding: install pending updates, restart, wait until it is back, apply the security baseline. It waits for each new machine's first scan (up to 30 minutes), so a batch that joins together gets one request. The request names its machines, and its steps touch only those. Nothing runs until an approver approves it in Workflows.
3. After the run, Gardience scans again and releases each machine that is clean: no pending updates, no restart pending, and no vulnerability with a published fix that is on CISA's Known Exploited Vulnerabilities list or rated critical. Released machines join their patch ring.
4. A machine that is still not clean after two fix runs, or whose fix request was rejected, stays held and the notification channel is told. Release now releases it anyway (an admin's decision, in the audit log), and Ask again opens a new fix request. The message names the updates that would not install. On cloud images of Windows Server, the Windows Recovery Environment update often reports success and is offered again (the recovery environment has no partition of its own); Gardience says so, and you decide whether to release the machine.

A held machine is not cut off from the network. Gardience holds it out of patch rings and production workflows; it does not isolate it. Groups such as Linux, Windows, and All machines still include it, so a run you start on those groups reaches it too.

Stage: dev, test, or prod#

The stage becomes the grain gardience_stage and the built-in groups Stage-Dev, Stage-Test, and Stage-Prod. Dev and test machines are also put in the pilot ring, so they get each month's updates first. Prod machines are in the broad ring: with Patch Tuesday, tested set they get exactly what passed on the pilot ring.

Linux updates#

• Through the Gardience update cache: the machine's official sources (Debian, Ubuntu, Rocky, Alma, EPEL) are pointed at this server's update cache, as the Update cache page does. The cache must be on.
• Only through Gardience: the same, and every other source on the machine is turned off, so it gets packages only through Gardience and the company repositories below. Red Hat subscription repositories stay on (the cache cannot serve them). If nothing on the machine can come through Gardience, nothing is turned off and the step says so. Patching > Update cache > Back to their own sources restores every file exactly as it was.

Company repositories#

Add up to 10 repositories, each with its signing key (an ASCII-armored PGP public key block) and whether it is for dnf machines (Rocky, RHEL, Alma) or apt machines (Debian, Ubuntu). For apt, also give the suite and components, for example stable main.

• dnf: /etc/yum.repos.d/gardience-NAME.repo with gpgcheck=1, and the key in /etc/pki/rpm-gpg/, imported once the repository works.
• apt: /etc/apt/sources.list.d/gardience-NAME.sources, signed by /etc/apt/keyrings/gardience-NAME.asc.

Packages from these repositories must be signed by that key. If the package lists cannot be refreshed with the new repositories, every file the step wrote is removed and no key is imported.

Windows#

• Windows Update: from your WSUS server (give its address, for example http://wsus.example.com:8530) or from Microsoft. Gardience writes the standard Windows Update policy values, the same ones Group Policy writes, so a domain Group Policy that sets them later wins.
• BitLocker recovery keys: backed up into the vault when the machine joins. This needs the recovery kit (Security > Disk encryption).

Security baseline on first connect#

Applies the security baseline (the same as the Apply security baseline runbook) as soon as each machine connects. With "fix first", the fix request applies it as well.

Custom commands#

Commands the script runs, as root on Linux (sh) and as Administrator on Windows (PowerShell):

• Before joining: before the agent is installed. If they fail, the script stops and the machine does not join.
• After joining: once the agent is running. A failure is reported and the machine stays joined.

They run exactly as written, also from the playbook. They are part of the script, so anyone who reads the script sees them; the enrollment list and the audit log show only that a profile has them.

Rebuilt machines keep their name and history#

Turn on Let a rebuilt machine take over its old name and history and name the machines it may replace, for example web-* (* for any). When a machine is rebuilt (a new disk, so a new agent key) and joins with the same name, Salt refuses the new key because the old one is still accepted. The enrollment script then asks Gardience to retire the old key:

• Only names the enrollment lists, and only while the enrollment is open.
• Never while a machine with that name is online: switch the old one off first.
• The old key is retired the way every machine removal is: by the config keeper, not the web service, within the hourly removal limit, and held for 30 days (gardience machine restore NAME puts it back).
• The refusal or the replacement is in the audit log, and the notification channel is told.

Everything Gardience recorded under the name (the audit log, runs, evidence) stays with it. The rebuilt machine is onboarded again: its profile and join rules apply as for a new machine.

The machine reaches the server over HTTPS at the address agents use for Salt. Re-registration is not available in attach mode, where your own Salt master holds the keys.

From the API#

curl -s -X POST https://GARDIENCE/gardience/api/v1/enrollments -H "Authorization: Bearer gdn_..." \
  -H 'Content-Type: application/json' -d '{"label": "Web servers", "hours": 24, "profile": {
    "stage": "prod", "updates": "cache", "baseline": true,
    "repos": [{"name": "tools", "kind": "dnf", "url": "https://repo.example.com/el9/", "key": "-----BEGIN PGP ..."}],
    "replace": true, "replace_names": "web-*",
    "after_linux": "systemctl enable --now node_exporter"}}'
curl -s "https://GARDIENCE/gardience/api/v1/enrollments/ID/script?os=linux&node=web-07&fix=true" -H "Authorization: Bearer gdn_..."

Profile fields: updates (cache or only), repos (each name, kind dnf or apt, url, key, and for apt apt), stage (dev, test, prod), windows_update (microsoft or wsus with wsus_url), bitlocker, baseline, replace with replace_names, and before_linux, after_linux, before_windows, after_windows.

Related#

• Enrollment tokens
• Groups and patch rings
• Update cache