Liberal Boolean Parsing#

OPNsense and pfSense config.xml both emit a shared "liberal" boolean vocabulary for toggle-style fields. The truthy set is 1 | on | yes | true | enable | enabled (case-insensitive, whitespace-trimmed); the falsy set is 0 | off | no | false | disable | disabled | "". Before PR #577, the codebase had three divergent parsers: pfsense.isPfSenseValueTrue 1 accepted only 1|on|yes; internal/converter/formatters.IsTruthy 2 covered a broader set; and int-typed schema fields crashed with strconv.ParseInt: parsing "on" when OPNsense 26.1 started emitting non-numeric values (issue #558, 3).

Canonical Source of Truth (PR #577)#

PR #577 3 introduces pkg/schema/shared/ as the canonical boolean library, consolidating all truthy/falsy parsing. These files exist in PR #577 but are not yet on main.

3

Four Coexisting Types and Decision Rubric#

Current main has two types; after PR #577 merges, four types will coexist. The decision rubric lives in GOTCHAS §15:

Critical: BoolFlag is not a drop-in for value-based booleans. Its MarshalXML emits nothing when false — a field whose wire form must always be <tag>0</tag>/<tag>1</tag> cannot use BoolFlag 3.

BoolFlag: Current Implementation#

BoolFlag (pkg/schema/opnsense/common.go) is a type BoolFlag bool with pointer-receiver XML marshaling:

• UnmarshalXML 4: Any element presence → true; element body is consumed but ignored. On main today, it does not delegate body content to IsValueTrue — that delegation is part of PR #577's BoolFlag upgrade.
• MarshalXML 5: Emits <tag/> when true; emits nothing when false.

After PR #577 merges, UnmarshalXML will additionally apply shared.IsValueTrue(body) for non-empty element bodies, fixing <tag>0</tag> → false (previously a silent bug where any element presence returned true).

PR #577 field migrations 3: 10 OPNsense System fields (e.g., UseVirtualTerminal, DisableVLANHWFilter, DisableChecksumOffloading, PfShareForward, LbUseSticky) and 3 pfSense System fields migrate from int to BoolFlag. On current main, those fields are still typed as int 6.

GOTCHAS §15: MarshalXML Addressability#

GOTCHAS §15.1 documents the most common trap:

BoolFlag implements MarshalXML on a pointer receiver (*BoolFlag). When a struct containing a BoolFlag field is marshaled by value, encoding/xml cannot find the pointer-receiver method and falls back to default bool serialization — producing <enable>true</enable> instead of <enable/>.

Fix pattern: Add a private type alias (e.g., type interfaceAlias Interface) and a pointer-receiver MarshalXML on the parent struct that casts via e.EncodeElement((*alias)(ptr), start). Precedent: pkg/schema/pfsense/interfaces.go — interfaceAlias and (*Interface).MarshalXML. Also pass &value (not value) when encoding items inside map-based containers. This pattern applies equally to FlexBool/FlexInt after PR #577 merges.

Rule: Any pfSense struct forked from opnsense that adds a BoolFlag field must implement this alias pattern. 7

Legacy Parsers (Pre-PR #577)#

On current main, value-based truthy parsing is split:

• isPfSenseValueTrue (pkg/parser/pfsense/constants.go): Private pfSense-only helper; accepts 1|on|yes (3 values).
• formatters.IsTruthy (internal/converter/formatters/formatters.go): Formatter-layer helper; accepts a wider set including enabled|active|inactive|-1; also falls back to float parsing. Used only by FormatBooleanCheckbox / FormatBooleanWithUnset.

PR #577 retires isPfSenseValueTrue in favor of shared.IsValueTrue and does not change formatters.IsTruthy (different concern). 3

Key Reference Files#