Write Guardrails¶
Write guardrails are policy rules that control what values can be written to points through the command subsystem. They are enforced before any write reaches the underlying system.
Each guardrail has three parts:
- Target -- which points the rule applies to
- Constraint -- what condition constitutes a violation
- Action -- what happens when violated (Reject, Clamp, or Allow/Log)
Rules are evaluated in priority order (lowest number first).
Actions¶
| Action | Behavior |
|---|---|
| Reject | The write fails with the rule's violation message; nothing is written. |
| Clamp | A numeric value outside the rule's minimum/maximum is replaced by the nearest bound, and that value is written -- including writes made inside a command 3.10.11. Inside a command, the write reply shows the clamped value. A write that can't be clamped (a non-numeric value, or a rule with no minimum or maximum) is rejected. |
| Allow (Log) | The violation is logged and evaluation continues with the next rule. |
Allow Rules¶
A rule with the Allow (Log) action and no constraints acts as an exemption -- when it matches a point, the write is immediately allowed and no further rules are evaluated. This enables a "deny by default, allow specific" pattern:
| Priority | Name | Target | Constraint | Action |
|---|---|---|---|---|
| 0 | Allow AHU-1 | device_id = 260001 | (none) | Allow (Log) |
| 10 | Deny all | (all points) | Writes disabled | Reject |
Per-Application Policies¶
Guardrails can be scoped globally or to a specific API key. Use the application dropdown on the Settings > Guardrails page to switch between global and per-application rules.
When a client authenticates with an API key, its per-application rules are merged with the global rules and sorted by priority together. This lets you set a restrictive global baseline and relax it for trusted applications:
| Scope | Priority | Name | Constraint | Action |
|---|---|---|---|---|
| Global | 10 | Block all writes | Writes disabled | Reject |
App: hvac-ctrl |
0 | Allow HVAC | (none) | Allow (Log) |
Configuration¶
| Variable | Default | Description |
|---|---|---|
GUARDRAIL_CONFIG_DIR |
/var/nf/guardrails |
Directory for guardrail policy files |
GUARDRAIL_ENABLED |
true |
Enable or disable the guardrail system |