OpnsenseInstall

First-boot OPNsense install: SSH into a freshly provisioned OPNsense VM via the prebuilt image’s pre-enabled root SSH (master key), scp a customer-specific config.xml to /conf/, run configctl service reload all, and persist API credentials on the Proxmox host (/etc/netsetup/opnsense-api.env) for subsequent REST API converge runs.

Image prerequisite: the bundled opnsense.img ships with SSH enabled and the netsetup master public key in /root/.ssh/authorized_keys. See update-opnsense-image skill.

public static class OpnsenseInstall

1. Fields

1.1. ApiEnvPath

Path on the Proxmox host where API creds are persisted for the API converge agent.

public const string ApiEnvPath

1.2. ConfigXmlPath

Path on the OPNsense VM where the active config lives.

public const string ConfigXmlPath

1.3. SshUser

SSH user on the prebuilt OPNsense image.

public const string SshUser

2. Methods

2.1. BuildInstallConfigXml(NETSetupConfig, string, string, string, string)

Emits a MINIMAL OPNsense config.xml sufficient to bootstrap API reachability
the LAN interface with DHCP + DNS forwarder. Full convergence (firewall rules, NAT outbound, port-fwd, static reservations) is the responsibility of the REST API agent reading ApiEnvPath. See wip-opnsense.md.

public static string BuildInstallConfigXml(NETSetupConfig config, string lanCidr, string lanGw, string apiKey, string apiSecret)

Table 1. Parameters
Name	Type	Description
config	NETSetupConfig
lanCidr	string
lanGw	string
apiKey	string
apiSecret	string

Returns: string

2.2. DeriveApiKey(NETSetupConfig)

Deterministic API key derived from stable config identity. Same config → same key on every run, so the env file always matches the key baked into config.xml on first install.

public static string DeriveApiKey(NETSetupConfig config)

Table 2. Parameters
Name	Type	Description
config	NETSetupConfig

Returns: string

2.3. DeriveApiSecret(NETSetupConfig)

Deterministic API secret. Distinct label keeps it independent of the key.

public static string DeriveApiSecret(NETSetupConfig config)

Table 3. Parameters
Name	Type	Description
config	NETSetupConfig

Returns: string

2.4. Install(Host, SystemManagement.Entities.Machine, NETSetupConfig, ISystemHost)

Installs customer config onto a freshly provisioned OPNsense VM.

EVERY run (regardless of install marker): derives DETERMINISTIC API creds from stable config values and (re-)writes the local Proxmox-host env file (/etc/netsetup/opnsense-api.env). This needs no OPNsense connection, so the API converge agent always finds creds that match config.xml. ONLY the first-install config.xml push (gated by the /conf/.netsetup-installed marker on the OPNsense VM) requires reaching the VM over the network.

public static OpnsenseInstall.OpnsenseInstallResult Install(Host proxmoxHost, SystemManagement.Entities.Machine opnsenseMachine, NETSetupConfig config, ISystemHost sysHost)

Table 4. Parameters
Name	Type	Description
proxmoxHost	Host
opnsenseMachine	SystemManagement.Entities.Machine
config	NETSetupConfig
sysHost	ISystemHost

Returns: OpnsenseInstall.OpnsenseInstallResult

2.5. ParseIpFromNeighbourTable(string, string)

Pure parser: matches normalizedMac against ip neigh show output (lines like 192.168.1.50 dev vmbr0 lladdr aa:bb:cc:dd:ee:ff REACHABLE). Returns the first IPv4 whose lladdr matches, ignoring FAILED/INCOMPLETE entries. Null on no match.

public static IPAddress? ParseIpFromNeighbourTable(string neighOutput, string normalizedMac)

Table 5. Parameters
Name	Type	Description
neighOutput	string
normalizedMac	string

Returns: IPAddress?