This page is for administrators and integrators who change device settings from Hermetry, by hand or through the API, on one device or on many. It explains the rules behind the Settings tab and how to use them safely. How to open the tab, create baselines and start jobs is in Remote device settings; the routes are in Firmware and device settings API.
Desired and reported values
For each settings section of a device, Hermetry keeps two documents:
- Desired: what Hermetry last asked the device to run, with a revision number that grows with every change.
- Reported: what the device says it runs, with the revision it applied.
Every change sends the whole section to the device, not only the keys that changed. The device applies a section only when its revision is higher than the last one it applied. A section that waited too long for the device is withdrawn; the device then keeps the settings it has.
| State on the Settings tab | Meaning |
|---|---|
| On its way | Sent, or waiting for the device to come online |
| Device is trying it | The device runs the change on trial and undoes it by itself if it cannot reach the cloud again |
| Applied | The device runs the change |
| Undone by the device | The device tried it and went back |
| Refused by the device | The device did not accept it |
| Device was offline | The change waited too long (7 days for a single change) and was withdrawn |
| Check after update | A firmware update changed the section’s description; a person must review and save |
| Changed on the device | Drift: the device runs other values than Hermetry asked for (below) |
| Not changed from here | Hermetry never set this section; it only shows what the device reports |
How a change is built
There are two ways to write a section, and they treat what you leave out differently.
| Way | Used by | What you send |
|---|---|---|
| Whole section | The Settings tab, PUT | Every value of the section. What you leave out is not part of the new section. |
| Merge patch | PATCH, baselines, settings jobs | Only what changes, as a JSON merge patch (RFC 7386) |
A merge patch follows these rules, exactly:
- Objects merge key by key. A key you do not name keeps its value.
nullremoves the key.- Any other value replaces the old one whole. A list is always replaced whole: to change one entry of a list, send the complete list.
The patch is applied to the section’s last desired document, not to what the device reports. Only when Hermetry has never set the section does a patch start from the reported values; if the device has not reported the section yet either, the write is refused (section_not_reported).
Good practice:
- Put only what you mean to change into a baseline. Everything else stays as it is on each device.
- Never put
nullinto a baseline unless the key should disappear from every device of the job. - Keep device-specific lists (for example address lists that differ per site) out of baselines: the baseline’s list replaces each device’s list.
- Settings the description marks as changeable only on the device are kept from the device’s report. A change to them is refused (
remote_forbidden). - Use
?dryRun=true(or Check in a job) to see which settings a change touches and whether it needs confirmation, before anything is sent.
Revisions and If-Match
Reading a section returns its desired revision as the ETag header, in the form W/"7". Every write must send that revision back in If-Match; "7" and 7 are accepted too.
| Answer | Meaning |
|---|---|
428 if_match_required | The write had no If-Match |
412 rev_mismatch | Someone changed the section after you read it |
On 412, read the section again, rebuild your change on the new document and write again. Do not copy the new revision into the header and resend the old document: that overwrites the other person’s change. The Settings tab does the same check (“Someone else changed these settings since you opened them. Load them again to see the latest.”).
Drift
A section has drifted when the device applied a change from Hermetry and later reports different values, usually because someone changed it on the device itself. The tab shows “Changed on the device” and what differs. Hermetry does not correct drift by itself. You choose:
| Action | Effect |
|---|---|
| Send ours again | Sends Hermetry’s desired values again as a new revision |
| Keep the device’s | Saves the device’s current values as the new desired values |
Resolve drift before you change a drifted section in another way. A merge patch, and therefore a settings job, starts from the last desired document, so it also sends back Hermetry’s values for the settings that drifted.
Decide who owns each setting. If technicians on site must be able to change something, keep it out of baselines and jobs.
Secrets
- Secret settings (passwords, keys) are never shown or returned. They read as
{ "set": true }. - A new secret travels to the device as a one-time reference. The device fetches the value once over a signed request; a reference that is not fetched expires after 30 days. A device whose firmware cannot fetch references gets no secret at all: the change is refused (
secret_ref_unsupported). - To keep the device’s current secret, leave the field unchanged (in the API,
{ "$keep": true }). - Baselines cannot hold secrets (
secret_not_allowed). Set them on each device. secret_pending: an earlier change carries a secret the device has not fetched yet. Wait for it, or enter the secret again.secrets_need_rewriteon Send again: the change carries secrets the device can no longer fetch. Enter them again and save.
Settings jobs
A job applies a baseline, or one change, to many devices in waves. Good practice:
- Select by model and firmware you have tested. The Check step shows the devices per model and firmware, and the sections a model does not have.
- Keep the waves. The default is 1 %, then 10 %, then the rest. The first wave is a fixed random cross-section of the selected devices.
- Understand the gate. A wave passes when, among the devices that answered, at least 95 % applied the change and at most 1 % undid it (the defaults). Devices that refused count among those that answered, so they lower the applied share. Devices still offline do not count. A wave is judged when all its devices have answered, or 30 minutes after it started (the default) on the devices that answered by then; the others go on in the background. A passed wave starts the next one at once, with no waiting time. A wave in which no device answered pauses the job.
- Choose what happens on a conflict. Only one change at a time may be under way on a device’s section. A job waits for another job’s change (and skips the device after 24 hours) or skips it at once. A change a person makes while the job waits wins.
- Set how long to wait for offline devices: 7 days by default, 1 to 90.
- Remember that cancelling does not roll back. Devices already changed keep their new settings.
A job writes with the permissions its creator had, and a job that changes dangerous settings must be confirmed when it is created. At most 5 jobs run or wait paused at a time, a job holds up to 5,000 devices, and it sends changes to at most 200 devices a minute.
Firmware updates and old firmware
- After a firmware update, Hermetry converts the stored desired values to the new firmware’s settings description. What it cannot convert safely is marked “Check after update”. The section stays in that state until a person saves it; reports from the device do not close it, and a job counts such a device as refused.
- Support window: settings writes stop 24 months after the release date of the device’s firmware, as recorded in its settings description. The settings stay readable (“Read only: update the firmware to change settings”). A write answers
409firmware_too_oldwith the date the window ended. - A job does not leave such devices out in advance. They are refused when their turn comes and count against the wave’s gate. Update their firmware first, or leave them out of the selection.
Rate of changes
Single changes from the Settings tab and the API, Send again included, are limited to 600 per minute per organisation; over that, 429 write_rate_limited. A job’s own writes to its devices do not count toward it.

