From 9e31a872ac4ae0314d8bf89fb4457bb029ca76b5 Mon Sep 17 00:00:00 2001 From: Tom Elliott Date: Fri, 11 Sep 2026 07:47:39 -0500 Subject: [PATCH] Document agent update modes, update rings, the minimum version, and the server's release copy FOG 1.6 schema 438 and fog-agent 0.1.8 changed how agents update. The docs said that no latest exists, that an empty FOG_AGENT_DESIRED_VERSION turns updates off, and that the agent settings are in General Settings and FOG Client. All three are now false. Agent Self-Update now describes the Off, Pinned and Latest modes, update rings, FOG_AGENT_MIN_VERSION, the FOGAgentReleaseSync service and its cache, the agent's fallback to the origin, and what to examine when a host does not update. The FOG Agent page, the reference and the install guide get the new host field, the new settings categories, the payload route and the release sync timing. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_013Sbto9eLVhLiCPyGERUZ27 --- docs/installation/client/install-fog-agent.md | 8 +- docs/kb/reference/fog-agent-reference.md | 33 ++- docs/management/web/agent-self-update.md | 257 ++++++++++++++---- docs/management/web/fog-agent.md | 53 ++-- 4 files changed, 262 insertions(+), 89 deletions(-) diff --git a/docs/installation/client/install-fog-agent.md b/docs/installation/client/install-fog-agent.md index 9c2d2af..bf7b6c5 100644 --- a/docs/installation/client/install-fog-agent.md +++ b/docs/installation/client/install-fog-agent.md @@ -285,10 +285,10 @@ has done. ## Upgrading -An enrolled agent can update itself once you name a version on the server — -see [[management/web/agent-self-update|Agent Self-Update]]. That is the -normal way to move a fleet, and it is off until you set a version, so -nothing starts moving on its own. +An enrolled agent can update itself once you choose an update mode on the +server — see [[management/web/agent-self-update|Agent Self-Update]]. That is +the normal way to move a fleet, and it is off until you choose Pinned or +Latest, so nothing starts moving on its own. By hand, which is how you get to a version that can self-update and how you fix a machine you are standing at: on Windows run the newer MSI, on Linux diff --git a/docs/kb/reference/fog-agent-reference.md b/docs/kb/reference/fog-agent-reference.md index a902be6..c363603 100644 --- a/docs/kb/reference/fog-agent-reference.md +++ b/docs/kb/reference/fog-agent-reference.md @@ -36,7 +36,7 @@ platform's state directory below. | `fog-agent status` | Prints the state directory, server URL, host id, whether a key exists and whether the machine is enrolled | | `fog-agent renew` | Renews the certificate now for the same key, regardless of expiry | | `fog-agent version` | Prints the version, OS and architecture | -| `fog-agent update --to VERSION [--manifest URL]` | Verifies and installs a version now, instead of waiting for a poll. Takes the same path the server-driven update takes — same signature check, same rollback arming, same swap. There is deliberately no `latest` | +| `fog-agent update --to VERSION [--manifest URL]` | Verifies and installs a version now, instead of waiting for a poll. Takes the same path the server-driven update takes — same signature check, same rollback arming, same swap. It takes an exact version only. The server resolves Latest mode, see [[management/web/agent-self-update#Update modes\|Agent Self-Update]] | | `fog-agent update-revert` | Puts back the binary an update replaced. A separate command on purpose: the code that reverts must not live inside a process too broken to run | | `fog-agent setup --server URL --ca FILE [--token T]` | Windows. Prepares the state directory, its permissions and the first enrollment request without registering a service. The MSI runs this | | `fog-agent service install --server URL --ca FILE [--token T]` | Windows. `setup`, then copies the binary to Program Files, registers and starts the service | @@ -102,14 +102,17 @@ The agent trusts only the CA bundle it was given at install, never the operating system trust store, and it talks to exactly one server. A different server with a valid public certificate is still not its server. -Self-update is the one narrow exception, and it costs nothing. Fetching a -release manifest and its artifact consults the system trust store plus the -FOG server's own CA, because that fetch may go to a mirror rather than to -FOG — but TLS is not what is trusted there. The manifest carries its own -signature and the artifact carries its own hash, both checked against a -code-signing certificate compiled into the agent binary. That is why the -server is allowed to nominate a mirror at all: the transport is bandwidth -and privacy, not a trust decision. +Self-update is the one narrow exception, and it costs nothing. From 0.1.8, +the agent first takes the release manifest and the file from its own FOG +server, over its client certificate. When that copy fails a check, or the +server has none, the agent fetches from the origin: the manifest URL and +the download address in the manifest. That fetch consults the system trust +store plus the FOG server's own CA, because it goes to `fogproject.org`, +GitHub or a mirror rather than to FOG — but TLS is not what is trusted +there. The manifest carries its own signature and the artifact carries its +own hash, both checked against a code-signing certificate compiled into the +agent binary. That is why the server may hand over the bytes or nominate a +mirror at all: the transport is bandwidth and privacy, not a trust decision. Where the FOG certificate authorities sit relative to each other is on [[1.6/kb/reference/pki-zones|FOG PKI Infrastructure]]. @@ -124,7 +127,7 @@ document, see [[api-openapi-reference|the API reference]]. |---|---| | `POST /agent/v1/enroll` | Server-authenticated TLS only; the agent has no certificate yet. Idempotent: the agent repeats the identical request until it gets `issued` or `denied` | | `POST /agent/v1/poll` | The heartbeat. Carries the agent version, the desired-state revision it applied, and any facts or sessions that changed. The answer carries the poll interval, and the full desired state only when the revision the agent applied is not current | -| `GET /agent/v1/payload/{capability}/{id}` | Fetches a snapin payload over the authenticated session, checked against the SHA-512 the desired state declared | +| `GET /agent/v1/payload/{capability}/{id}` | Fetches a payload over the authenticated session: a snapin, checked against the SHA-512 the desired state declared, or the server's copy of an agent release (`update`), checked against the SHA-256 in the signed manifest | | `POST /agent/v1/result` | What the agent did with one capability at one revision. The server answers with the outcome, which is what the agent acts on | | `POST /agent/v1/renew` | A new certificate for the same key | @@ -135,10 +138,11 @@ idle, with one informative log line, never an error. This is why a current agent runs against an older 1.6 server without complaint, and why the project releases the agent independently of FOG. -Self-update needed no route of its own. The desired version is a value in -the poll answer's existing state, alongside every other capability, and an -older agent that does not understand it ignores it — the agent discards -fields it does not know. The agent's own version rides up on every poll, +Self-update needed no route of its own. The desired version, the server's +copy of the manifest and the id of its copy of the file are values in the +poll answer's existing state, alongside every other capability, and the file +comes through the payload route above. An older agent that does not +understand a field ignores it — the agent discards fields it does not know. The agent's own version rides up on every poll, which is what the host list's Agent Version column shows. Credentials never ride a routine poll. The domain-join credential appears @@ -161,6 +165,7 @@ is not sent again once the host reports it is joined. | Printer set re-check | Hourly, plus at every change of the assigned set | | Power schedules | On their own cron minute, on the machine's clock | | Update probation | 15 minutes from the swap. One successful authenticated poll clears it; the deadline passing without one puts the previous binary back | +| Release sync, on the server | `AGENTRELEASESYNCSLEEPTIME`, default 3600 seconds. A new release reaches a host at the first poll after the sync that sees it and the host's ring delay | ## What the agent sends diff --git a/docs/management/web/agent-self-update.md b/docs/management/web/agent-self-update.md index ce17c0b..4a7dbec 100644 --- a/docs/management/web/agent-self-update.md +++ b/docs/management/web/agent-self-update.md @@ -5,7 +5,9 @@ aliases: - Agent Updates - Updating the FOG Agent - Desired Agent Version -description: How the FOG Agent updates its own binary, what it verifies before it will run one, how to stage a rollout, and how a bad version rolls back + - Agent Update Mode + - Agent Update Rings +description: How the FOG Agent updates itself — update modes, update rings, the minimum version, the server's copy of each release, what the agent verifies, and how a bad version rolls back context_id: agent-self-update tags: - 1_6-changes @@ -23,9 +25,10 @@ tags: >server. The legacy FOG client has no equivalent — it was updated by a >separate module that pushed binaries from your own server. -An agent can replace its own binary. You name a version; the agents on your -fleet fetch that release, check it, install it and restart into it, without -anyone visiting the machines. +An agent can replace its own binary. You choose how the fleet updates: not +at all, to one version that you name, or to each new release in stages. +The agents fetch the release, check it, install it and restart into it. +Nobody has to visit the machines. The one idea to hold onto: **this server names a version, and cannot invent one.** What that version *is* comes from a release manifest signed by FOG @@ -37,43 +40,174 @@ reason it is safe to point an unattended update channel at every managed machine you have. >[!warning] Nothing updates until you say so ->`FOG_AGENT_DESIRED_VERSION` ships empty, and empty means no host ever ->updates itself. Upgrading your FOG server does not start moving agent ->versions. Unlike every other agent capability, this one is not gated on a ->module switch — it is gated on you having named a version. +>`FOG_AGENT_UPDATE_MODE` ships as **Off**. Upgrading your FOG server does +>not start moving agent versions. A server that already had +>`FOG_AGENT_DESIRED_VERSION` set is upgraded to **Pinned** on that version, +>so it continues to do what it did. -## Turning it on +## Update modes -**FOG Configuration → FOG Settings → General Settings → -`FOG_AGENT_DESIRED_VERSION`.** Put an exact version in it, for example -`0.4.2`. Every enrolled host that is not already running that version will -move to it on its next poll. +**FOG Configuration → FOG Settings → FOG Agent → `FOG_AGENT_UPDATE_MODE`.** -There is deliberately no `latest`. A fleet-wide channel that tracks whatever -was published this morning hands the decision to the release process rather -than to you, and the whole point of the design is that you choose. - -## Staging a rollout - -A host's own **Desired Agent Version** beats the global setting, which is -what makes a staged rollout possible: +| Mode | What hosts do | +|---|---| +| **Off** | No host updates. The exceptions are a host with its own **Desired Agent Version**, and a host below `FOG_AGENT_MIN_VERSION` | +| **Pinned** | Every host runs `FOG_AGENT_DESIRED_VERSION`, an exact version such as `0.1.8` | +| **Latest** | Every host runs the newest release, after the delay of its update ring | + +In every mode, a host's own **Desired Agent Version** wins over the mode, +and `FOG_AGENT_MIN_VERSION` is a floor under all of them. + +**The server decides what Latest means.** It reads the signed release +manifest and turns "the newest release for this host's ring" into an exact +version. The agent still receives an exact version and still checks the +signature. So Latest does not change what a server can do: it can choose +only a published version. Every agent that can update itself follows +Latest, because it receives a version as before. + +## Update rings + +Latest mode sends a new release to your hosts in stages. A ring is a delay +in days. + +- **`FOG_AGENT_UPDATE_RINGS`** lists the delays, separated by commas. The + default is `0,3,7`: ring 0 gets a release at once, ring 1 after 3 days, + and ring 2 after 7 days. +- **Agent Update Ring** on each host sets its ring. Set it on the host's + **General** tab, or select hosts in the host list and use mass edit. Mass + edit shows each ring with its delay, for example *Ring 1 (3 days)*. +- **A blank ring is the last ring.** A ring number past the end of the list + is also the last ring. So a new host is never among the first to update. + +A delay counts from **when this server first saw the release**, not from +the release date. The release sync records that time when a release first +appears in the manifest it downloads. + +>[!note] The first sync starts every clock +>At its first sync, the server sees every published release for the first +>time. A host in ring 2 then waits 7 days for any release, even a release +>that is months old. To move a host now, set its ring to 0. + +Latest never moves a host below the version it runs. A host that a pin or +an override took to a newer version stays there when you clear the pin. The +exception is a withdrawn release. When FOG Project removes a version from +the manifest, that version does not hold its hosts, and they go to the +newest release that their ring allows. + +### A rollout with rings + +1. Put a few test machines in ring 0, and the rest of the fleet in rings 1 + and 2. Select the machines with a group filter in the host list, then + mass edit **Agent Update Ring**. +2. Set `FOG_AGENT_UPDATE_MODE` to **Latest**. +3. When a new release appears, ring 0 gets it at the first poll after the + next release sync. Watch **Agent Version** in the host list, and + **History Items → Agent Activity** for failures. +4. If ring 0 shows a problem, stop the later rings before their delay ends. + Set the mode to **Pinned** with the version they run in + `FOG_AGENT_DESIRED_VERSION`, or give those hosts that version as their own + **Desired Agent Version**. + +## Staging a rollout by hand + +A host's own **Desired Agent Version** wins over the mode. In Pinned mode, +that is how you stage a rollout without rings: 1. Set **Desired Agent Version** on a handful of hosts — the host's **General** tab, or select a group in the host list and use mass edit. 2. Watch the host list. **Agent Version** is what each machine is actually running; **Desired Agent Version** is what you told it to become. The only question worth asking is whether those two agree. -3. When you are satisfied, set `FOG_AGENT_DESIRED_VERSION` globally and - clear the per-host values. Clearing them is one mass edit. +3. When you are satisfied, set `FOG_AGENT_DESIRED_VERSION` to that version + and clear the per-host values. Clearing them is one mass edit. >[!note] A per-host override is sticky ->It wins even when it names a version *lower* than the global one. That is +>It wins even when it names a version *lower* than the mode does. That is >deliberate and it is the whole recovery story — see >[[management/web/agent-self-update#Going backwards on purpose|Going backwards on purpose]] >below. The cost is that a forgotten override holds a machine back silently, >which is why the host list carries the column: "everything not following >the fleet" is a filter, and clearing them is one edit. +## Minimum version + +**`FOG_AGENT_MIN_VERSION`** is the lowest version that any enrolled host may +run. Use it after a security release, to move every host off the older +versions at once. + +- No host is told to run a version below the minimum. A pinned version, a + host's own **Desired Agent Version**, or the version of a ring that is + below the minimum is raised to the minimum. +- A host that runs a release below the minimum is updated to it, **also in + Off mode**. +- The settings page does not save a `FOG_AGENT_DESIRED_VERSION` below the + minimum. The host page does not save a **Desired Agent Version** below + it. +- After the server has synced a manifest, the minimum must be a version in + that manifest. +- A host that runs a build that is not a release, such as + `0.1.7-2-gabc1234` from a source build, is not changed. That version + cannot be compared with a release, so the server does not replace it. + +## Where agents get the release + +**FOGAgentReleaseSync** is a service on the FOG server. It runs as the web +server user, not as root. Every `AGENTRELEASESYNCSLEEPTIME` seconds (default +3600), it does these steps: + +- It downloads the signed release manifest and its signature from + `FOG_AGENT_UPDATE_MANIFEST_URL`. When that setting is empty, it uses + `https://fogproject.org/version/agent-stable.json`. +- It records the time it first sees each release. The ring delays count + from that time. +- It downloads each file that an enrolled host runs or must run, for that + host's OS and architecture, into `/opt/fog/agent/versions//`. It + compares each file's size and SHA-256 with the manifest before it keeps + the file. +- It deletes the files that no host needs. It keeps the newest + `FOG_AGENT_KEEP_VERSIONS` releases (default 3), so a rollback works when + the internet is not available. + +The service is idle while the mode is Off, no host has its own **Desired +Agent Version**, and `FOG_AGENT_MIN_VERSION` is empty. Its log is under +**FOG Configuration → Log Viewer**, file **Agent Release Sync**. + +Agents 0.1.8 and later get the manifest and the file from this server. The +poll answer carries the manifest, and the file comes over the agent's +client certificate. So the hosts do not need internet access. The FOG +server needs access to `fogproject.org` and to GitHub, where the files are. + +If the server's copy fails a check, or the server has no copy, the agent +tries the origin once: the manifest URL, and the download address in the +manifest. So a server whose sync stopped does not strand its hosts while +the internet is available. Agents older than 0.1.8 ignore the server's copy +and download both from the origin themselves. + +>[!important] The server's copy is not trusted, and does not need to be +>The server does not check the signature. Every agent checks it against the +>certificate compiled into the agent, and checks the hash of each file. A +>server that sends the wrong bytes, including a server that somebody else +>controls, cannot change what your machines run. The worst it can do is +>send nothing or send something old. The agent then goes to the origin, and +>the sequence floor refuses an old manifest. + +>[!tip] Sync now +>A new release, or a change that needs a new file, takes effect at the next +>sync. To sync now, restart the service: +>`sudo systemctl restart FOGAgentReleaseSync`. + +### Hosting a mirror + +**`FOG_AGENT_UPDATE_MANIFEST_URL`** changes where the server downloads the +manifest. Empty is the default and means `fogproject.org`. Agents older than +0.1.8 also use this address for the manifest. + +A mirror changes only where the manifest comes from. Each file still comes +from the address inside the signed manifest, and a mirror cannot change that +address without breaking the signature. Whatever a mirror serves must still +carry FOG Project's signature, and the sequence floor refuses a manifest +older than one an agent has already accepted. + ## What the agent checks before it runs anything TLS proves where bytes came from. It does not prove who wrote them, and a @@ -84,7 +218,7 @@ transport is not trusted, and four things are checked instead: |---|---| | **Signature.** The release manifest is signed, and the agent verifies it against a code-signing certificate compiled into its own binary | Anything not published by FOG Project — including something served by your own FOG server, or by a mirror you host | | **Sequence floor.** Each manifest carries a number that only goes up, and the agent remembers the highest it has accepted | A manifest that FOG Project really did sign, months ago, being replayed to walk a fleet back onto a version with a known hole | -| **Artifact hash.** The manifest names the SHA-256 of every download, and the agent streams the file and stops at the size the manifest gave | A mirror that serves a genuine manifest and different bytes. This is the case TLS cannot help with at all | +| **Artifact hash.** The manifest names the SHA-256 of every download, and the agent streams the file and stops at the size the manifest gave | A server or mirror that serves a genuine manifest and different bytes. This is the case TLS cannot help with at all | | **Version floor.** An agent refuses to become a version older than the first one that carried self-update | Downgrading a fleet onto a build with no way to update itself forward again. That is not a rollback, it is a fleet you have to visit | If any check fails, **nothing is installed and the running binary is not @@ -103,17 +237,38 @@ one of these: | `below_floor` | You asked for something older than the oldest version that can update itself | | `no_signing_root` | This build carries no signing certificate, so it can never accept an update. A packaging fault — report it | | `signature_invalid` | The manifest is not signed by a key this build trusts | -| `stale_manifest` | The manifest is older than one this agent has already accepted | +| `stale_manifest` | The manifest is older than one this agent has already accepted, or it has expired | | `no_artifact` | The version exists but publishes nothing for this host's OS and architecture | | `hash_mismatch` | The bytes served are not the bytes the manifest describes | | `fetch_failed` | The manifest or the download could not be retrieved | | `cannot_arm_rollback` | The agent could not record what it was replacing, so it refused to replace it | | `swap_failed` | Replacing the file failed. The old binary is still in place | +When the server's copy and the origin both fail, the detail names the two +attempts, for example `signature_invalid: server copy: stale_manifest: the +manifest has expired; origin: signature_invalid: …`. The code at the start +is the result of the origin attempt. + `cannot_arm_rollback` is worth reading twice: an update that cannot arm its own rollback does not happen. The agent will not put itself somewhere it cannot come back from. +### A host does not update + +Examine these items: + +- **The ring.** In Latest mode, the delay counts from when this server + first saw the release. A host with a blank ring waits for the longest + delay. +- **The release sync.** The server sees a new release only at its next + sync. Read the **Agent Release Sync** log. *Agent releases are current* + means that the last sync was successful. +- **An override.** A host's own **Desired Agent Version** wins over the + mode, and keeps the host on the version it names. +- **The agent's report.** **Agent Version** in the host list is what the + machine runs. **History Items → Agent Activity** gives the reason when the + agent refused an update. + ## Rollback Three layers, and it is worth knowing what each one actually catches. @@ -143,39 +298,39 @@ this server naming an older version, which is the next section. ## Going backwards on purpose -Set the **Desired Agent Version** to the older version. A per-host value -beats the global one in both directions, so you can pull one machine back -without touching the fleet, or set the global lower to pull everything back. - -The floor still applies: an agent will not go below the first version that -carried self-update, because a version without this feature cannot be -updated forward again by anything the agent itself carries. - -## Hosting a mirror - -**`FOG_AGENT_UPDATE_MANIFEST_URL`** points agents somewhere other than the -location built into them. Empty is the default and means "wherever this -build was told to look". +Set the **Desired Agent Version** of a host to the older version, or set +the mode to **Pinned** with the older version in +`FOG_AGENT_DESIRED_VERSION`. A per-host value wins over the mode in both +directions, so you can pull one machine back without touching the fleet. -Set it for a site with no route to the internet, or simply to stop every -machine fetching the same file separately. A copy on any web server will do, -including this one. +The server keeps the newest `FOG_AGENT_KEEP_VERSIONS` releases and every +version that a host runs. So the older file is usually on the server +already. If it is not, the next sync downloads it. ->[!important] The mirror is not trusted, and does not need to be ->Whatever it serves still has to carry FOG Project's signature and match the ->hash in the signed manifest. Hosting a mirror gives nobody — including you, ->and including anyone who takes over your FOG server — the ability to change ->what your machines run. The worst a hostile mirror can do is serve nothing, ->or serve something old, and the sequence floor covers the second one. +Two floors still apply. `FOG_AGENT_MIN_VERSION` raises a version below it. +And an agent will not go below the first version that carried self-update, +because a version without this feature cannot be updated forward again by +anything the agent itself carries. ## Settings -Both under **FOG Configuration → FOG Settings**. +All under **FOG Configuration → FOG Settings**. | Setting | Category | Default | Meaning | |---|---|---|---| -| `FOG_AGENT_DESIRED_VERSION` | General Settings | empty | The version every enrolled host should be running. Empty means no host ever updates itself. A host's own Desired Agent Version overrides it | -| `FOG_AGENT_UPDATE_MANIFEST_URL` | General Settings | empty | Where agents look for the signed release manifest. Empty means the location built into the agent | +| `FOG_AGENT_UPDATE_MODE` | FOG Agent | Off | Off, Pinned or Latest. See [[management/web/agent-self-update#Update modes\|Update modes]] | +| `FOG_AGENT_DESIRED_VERSION` | FOG Agent | empty | The exact version that every host runs in Pinned mode | +| `FOG_AGENT_UPDATE_RINGS` | FOG Agent | `0,3,7` | The ring delays in days for Latest mode | +| `FOG_AGENT_MIN_VERSION` | FOG Agent | empty | The lowest version that any host may run, in every mode. Empty means no minimum | +| `FOG_AGENT_KEEP_VERSIONS` | FOG Agent | 3 | How many of the newest releases the server keeps after hosts stop needing them | +| `FOG_AGENT_UPDATE_MANIFEST_URL` | FOG Agent | empty | Where the server downloads the signed release manifest. Empty means `https://fogproject.org/version/agent-stable.json` | +| `AGENTRELEASESYNCGLOBALENABLED` | FOG Linux Service Enabled | 1 | Turns the release sync service on or off | +| `AGENTRELEASESYNCSLEEPTIME` | FOG Linux Service Sleep Times | 3600 | Seconds between syncs. It is also the longest a new release waits before the server sees it | +| `AGENTRELEASESYNCLOGFILENAME` | FOG Linux Service Logs | `fogagentreleasesync.log` | The sync's log file, in the `agentreleasesync/` folder of the service log path | +| `AGENTRELEASESYNCDEVICEOUTPUT` | FOG Linux Service TTY Output | `/dev/tty3` | The terminal that the sync writes to | + +Two settings are on each host, on the **General** tab and in mass edit: +**Agent Update Ring** and **Desired Agent Version**. ## See also diff --git a/docs/management/web/fog-agent.md b/docs/management/web/fog-agent.md index fdea6f0..494fca9 100644 --- a/docs/management/web/fog-agent.md +++ b/docs/management/web/fog-agent.md @@ -60,12 +60,12 @@ agent stays idle on it and logs one line saying so. | Task reboot | Task Reboot | Reboots the machine into a queued imaging task, arming a one-time network boot first where the firmware allows | | User sessions | User Tracker | Reports who is logged in, as sessions with a start and an end | | Facts | `FOG_AGENT_INVENTORY_ENABLED` | Hardware inventory, installed software, Secure Boot posture, printers present, directory membership, network interfaces | -| Self-update | *none — a version, not a switch* | Replaces its own binary with a version you name, after verifying it against a signing certificate compiled into itself. See [[agent-self-update\|Agent Self-Update]] | +| Self-update | *none — an update mode, not a module* | Replaces its own binary with the version the server names, after verifying it against a signing certificate compiled into itself. See [[agent-self-update\|Agent Self-Update]] | Self-update is the one row with no module behind it, because there was no -legacy module to inherit. It is gated on `FOG_AGENT_DESIRED_VERSION` being -set, and that ships empty — so no host starts updating itself because you -upgraded a server. +legacy module to inherit. It is gated on `FOG_AGENT_UPDATE_MODE`, and that +ships as Off — so no host starts updating itself because you upgraded a +server. Display Manager, GreenFOG and the auto log out background image are gone. The agent does not implement them and their settings were removed from 1.6. @@ -91,13 +91,17 @@ approving anything further; enrollments it already approved are unaffected. ## The host page -Three places on a host's page belong to the agent: +These places on a host's page belong to the agent: - **General → Desired Agent Version.** The version this host should be - running, overriding the fleet-wide setting. Empty means it follows the - fleet. The host list carries both this and **Agent Version**, what the - machine is actually running, so a rollout is a matter of watching the two - agree — see [[agent-self-update|Agent Self-Update]]. + running, overriding the update mode. Empty means it follows the mode. The + host list carries both this and **Agent Version**, what the machine is + actually running, so a rollout is a matter of watching the two agree — + see [[agent-self-update|Agent Self-Update]]. +- **General → Agent Update Ring.** The host's ring when the update mode is + Latest. Ring 0 updates first, and a blank ring is the last ring. Mass edit + sets it for many hosts — see + [[management/web/agent-self-update#Update rings|Update rings]]. - **General → Last Agent Check-In.** When the agent last polled. It sits beside Last Client Check-In and Last Successful Ping, and the same "ping recent, check-in old" reading described on @@ -189,7 +193,7 @@ domain, OU and join credential you already fill in, seeded from the computer object itself with one LDAP rename, no reboot, no re-join. That writes to your directory, so it is off until you set `FOG_DIRECTORY_PLACEMENT_ENABLED` and give FOG a bind account under the - **FOG Directory** settings (`FOG_DIRECTORY_LDAP_URI`, `FOG_DIRECTORY_BIND_DN`, + **FOG Agent - Directory Placement** settings (`FOG_DIRECTORY_LDAP_URI`, `FOG_DIRECTORY_BIND_DN`, `FOG_DIRECTORY_BIND_PASSWORD`, `FOG_DIRECTORY_BASE_DN`, `FOG_DIRECTORY_CA_CERT`). Delegate that account only *create and delete computer objects* on the OU subtree FOG should manage. An account refused @@ -342,21 +346,30 @@ All under **FOG Configuration → FOG Settings**, in the category named. | Setting | Category | Default | Meaning | |---|---|---|---| -| `FOG_AGENT_ENROLL_DEPLOY_WINDOW` | General Settings | 24 | Hours after a deploy during which the deployed host's agent enrolls without approval. 0 turns the shortcut off | -| `FOG_AGENT_DESIRED_VERSION` | General Settings | empty | The agent version every enrolled host should run. Empty means no host ever updates itself. A host's own Desired Agent Version overrides it | -| `FOG_AGENT_UPDATE_MANIFEST_URL` | General Settings | empty | Where agents look for the signed release manifest. Empty means the location built into the agent | -| `FOG_AGENT_INVENTORY_ENABLED` | FOG Client | 1 | Whether agents collect and report facts at all | +| `FOG_AGENT_ENROLL_DEPLOY_WINDOW` | FOG Agent | 24 | Hours after a deploy during which the deployed host's agent enrolls without approval. 0 turns the shortcut off | +| `FOG_AGENT_UPDATE_MODE` | FOG Agent | Off | How enrolled hosts update: Off, Pinned or Latest. See [[agent-self-update\|Agent Self-Update]] | +| `FOG_AGENT_DESIRED_VERSION` | FOG Agent | empty | The exact version every host runs in Pinned mode. A host's own Desired Agent Version overrides it | +| `FOG_AGENT_UPDATE_RINGS` | FOG Agent | `0,3,7` | The update ring delays in days, for Latest mode | +| `FOG_AGENT_MIN_VERSION` | FOG Agent | empty | The lowest version any host may run, in every mode | +| `FOG_AGENT_KEEP_VERSIONS` | FOG Agent | 3 | How many of the newest releases the server keeps after hosts stop needing them | +| `FOG_AGENT_UPDATE_MANIFEST_URL` | FOG Agent | empty | Where the server downloads the signed release manifest. Empty means `fogproject.org` | +| `FOG_AGENT_INVENTORY_ENABLED` | FOG Agent | 1 | Whether agents collect and report facts at all | | `FOG_AGENT_WAKE_RELAY_ENABLED` | FOG Agent | 0 | Whether the server may ask an agent to wake a neighbour | -| `FOG_SOFTWARE_DRIFT_INTERVAL` | FOG Client | 21600 | Seconds between software re-checks when the set has not changed. Shown as *Re-check Interval* on the Software module's settings | -| `FOG_SOFTWARE_CHOCO_BOOTSTRAP_URL` | FOG Client | empty | Chocolatey install script for hosts with software assigned but no Chocolatey. Empty means never install it | -| `FOG_SOFTWARE_CHOCO_NUPKG_URL` | FOG Client | empty | A `.nupkg` the bootstrap script installs Chocolatey from, for hosts with no route to the community feed | +| `FOG_SOFTWARE_DRIFT_INTERVAL` | FOG Agent | 21600 | Seconds between software re-checks when the set has not changed. Shown as *Re-check Interval* on the Software module's settings | +| `FOG_SOFTWARE_CHOCO_BOOTSTRAP_URL` | FOG Agent | empty | Chocolatey install script for hosts with software assigned but no Chocolatey. Empty means never install it | +| `FOG_SOFTWARE_CHOCO_NUPKG_URL` | FOG Agent | empty | A `.nupkg` the bootstrap script installs Chocolatey from, for hosts with no route to the community feed | | `FOG_CLIENT_AUTOLOGOFF_WARN` | FOG Client - Auto Log Off | 60 | Seconds of warning before an automatic log out | -| `FOG_USERTRACKING_COMPAT_WRITE` | FOG Client | 1 | Also write agent sessions to the legacy user tracking table | +| `FOG_USERTRACKING_COMPAT_WRITE` | FOG Agent | 1 | Also write agent sessions to the legacy user tracking table | | `FOG_HOSTUSERSESSION_RETENTION_DAYS` | FOG Audit | 365 | Days of agent-reported sessions to keep. 0 keeps them forever | -| `FOG_DIRECTORY_PLACEMENT_ENABLED` and the `FOG_DIRECTORY_*` account settings | FOG Directory | off, empty | Server-side OU placement, described above | +| `FOG_DIRECTORY_PLACEMENT_ENABLED` and the `FOG_DIRECTORY_*` account settings | FOG Agent - Directory Placement | off, empty | Server-side OU placement, described above | + +The release sync service has four more settings, in the service +categories. They are listed on [[agent-self-update|Agent Self-Update]]. `FOG_GRACE_TIMEOUT` and `FOG_TASK_FORCE_REBOOT` are existing settings the -agent's reboot coordinator now honours. +agent's reboot coordinator now honours. Both clients read them, so they +stay in their own categories, and their descriptions say that the agent +reads them too. ## Reports