OpnSenseXMLConfig.psm1

<#
.SYNOPSIS

Validate that a file is indeed an OPNsense config file.

.DESCRIPTION

This function does some superficial checks to make sure a recognised
OPNsense configuration file is represented by the supplied DOM.

.OUTPUT

The function throws an exception if the configuration is invalid.

#>

function Validate-OpnSenseXMLConfig {
    Param(
    # The DOM object representing the OPNsense configuration.
    $XMLConfig
    )
    # This is a very lame attempt at checking this. Check to see if there is a
    # schema we can check against (doubtful).
    try {
        $v = $XMLConfig.opnsense.version
    } catch {
        throw "This doesn't look like an OPNsense configuration file."
    }
    switch ($v) {
        '11.2' {}
        default {
            throw "Unrecognised configuration file version: $v"
        }
    }
}

<#
.SYNOPSIS

Load an OPNsense config file into memory

.DESCRIPTION

The Get-OpnSenseXMLConfig function parses and loads an OPNsense configuration
file. It performs some cursory checks (see Validate-OpnSenseXMLConfig).

.OUTPUT

Returns an xml object if the file was valid, otherwise throws an exception.

.EXAMPLE
$ConfigXML = Get-OpnSenseXMLConfig config.xml

Sets the $ConfigXML variable that can then be piped into or sent as an
argument to other cmdlets in the module.
#>
function Get-OpnSenseXMLConfig {
    [CmdletBinding()]
    Param(
    # The path on the filesystem to look for the config file in.
    [string]$FilePath
    )
    [xml]$XMLConfig = Get-Content $FilePath
    Validate-OpnSenseXMLConfig $XMLConfig # Throws an exception if broken
    return $XMLConfig
}

<#
.SYNOPSIS

Write an OPNsense config file to disk

.DESCRIPTION

The Out-OpnSenseXMLConfig function writes an an OPNsense configuration
file to disk.

When writing the file, revision data will also be updated.
#>
function Out-OpnSenseXMLConfig {
    [CmdletBinding()]
    Param(
        # The path on the filesystem to write for the config file in.
        [Parameter(Mandatory=$True)]
        [string]$FilePath,

        # The DOM of an OPNsense configuration file. The DOM specified will be
        # changed in place as a result of executing the cmdlet.
        [Parameter(Mandatory=$True, ValueFromPipeline=$true)]
        [xml]$ConfigXML,

        # A string describing the latest revision.
        [Parameter(Mandatory=$False)]
        [string]$Description
    )

    $r = $ConfigXML.SelectSingleNode('/opnsense/revision')
    $r.RemoveAll()
    foreach ($elementname in @("time", "description", "username")) {
        $child = $ConfigXML.CreateElement($elementname)
        $r.AppendChild($child) | Out-Null
    }
    # Get-Date will format dates according to the current culture. The XML
    # file expects numbers in US format. So, we need to temporarilly switch
    # the culture for this to work.
    $CulturalHeritage = [Threading.Thread]::CurrentThread.CurrentCulture
    [Threading.Thread]::CurrentThread.CurrentCulture = "en-US"
    [string]$r.time = Get-Date -UFormat "%s"
    [Threading.Thread]::CurrentThread.CurrentCulture = $CulturalHeritage

    if ($Description) {
        $r.description = $Description
    } else {
        $r.description = "Configuration file generated by PoshOpnSense"
    }
    
    $r.username = [System.Security.Principal.WindowsIdentity]::GetCurrent().Name
    # We need to do this load of nonsense because Powershell paths are a royal
    # pain in the behind.
    $sw = New-Object System.IO.StringWriter
    $ConfigXML.Save($sw)
    Set-Content -Value $sw.ToString() -Path $FilePath
    $sw.Dispose()
}