Minor release: v1.1.0

PiHoleShell/PiHoleShell.psm1

@@ -38,7 +38,7 @@ Export-ModuleMember -Function @(
         #History
         'Get-PiHoleHistory', 'Get-PiHoleHistoryDatabase', 'Get-PiHoleHistoryClient', 'Get-PiHoleHistoryDatabaseClient', `
         #Teleporter
-        'Get-PiHoleTeleporterDownload', `
+        'Get-PiHoleTeleporterDownload', 'Import-PiHoleTeleporter', `
         #DomainManagement
         'Get-PiHoleDomain', 'New-PiHoleDomain', 'Update-PiHoleDomain', 'Remove-PiHoleDomain', `
         #ClientManagement

PiHoleShell/Public/Teleporter/Import-PiHoleTeleporter.ps1

@@ -0,0 +1,165 @@
+function Import-PiHoleTeleporter {
+    <#
+.SYNOPSIS
+Import Pi-hole settings
+
+.DESCRIPTION
+Uploads a Teleporter archive (as produced by Get-PiHoleTeleporterDownload) to restore Pi-hole
+from it. This overwrites your current configuration, so unlike most functions in this module it
+prompts for confirmation by default - pass -Confirm:$false to skip the prompt, or -WhatIf to see
+what would happen without making any change.
+
+By default every importable item in the archive is restored. Pass one or more of the switch
+parameters below to import only those specific items instead - anything not switched on is left
+alone.
+
+.PARAMETER PiHoleServer
+The URL to the PiHole Server, for example "http://pihole.domain.com:8080", or "http://192.168.1.100"
+
+.PARAMETER Password
+The API Password you generated from your PiHole server
+
+.PARAMETER FilePath
+Path to the Teleporter .zip archive to upload
+
+.PARAMETER Config
+Import Pi-hole's configuration
+
+.PARAMETER DhcpLeases
+Import Pi-hole's DHCP leases
+
+.PARAMETER Group
+Import Pi-hole's groups table
+
+.PARAMETER Adlist
+Import Pi-hole's adlist table
+
+.PARAMETER AdlistByGroup
+Import Pi-hole's table relating adlist entries to groups
+
+.PARAMETER Domainlist
+Import Pi-hole's domainlist table
+
+.PARAMETER DomainlistByGroup
+Import Pi-hole's table relating domainlist entries to groups
+
+.PARAMETER Client
+Import Pi-hole's client table
+
+.PARAMETER ClientByGroup
+Import Pi-hole's table relating client entries to groups
+
+.PARAMETER IgnoreSsl
+Set to $true to skip SSL certificate validation
+
+.PARAMETER RawOutput
+This will dump the response instead of the formatted object
+
+.EXAMPLE
+Import-PiHoleTeleporter -PiHoleServer "http://pihole.domain.com:8080" -Password "your-app-password" -FilePath "C:\Backups\pihole-backup.zip"
+
+.EXAMPLE
+Import-PiHoleTeleporter -PiHoleServer "http://pihole.domain.com:8080" -Password "your-app-password" -FilePath "C:\Backups\pihole-backup.zip" -Group -Adlist -AdlistByGroup
+
+.EXAMPLE
+Import-PiHoleTeleporter -PiHoleServer "http://pihole.domain.com:8080" -Password "your-app-password" -FilePath "C:\Backups\pihole-backup.zip" -WhatIf
+    #>
+    [CmdletBinding(SupportsShouldProcess = $true, ConfirmImpact = 'High', HelpUri = 'https://ftl.pi-hole.net/master/docs/#post-/teleporter')]
+    [System.Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSAvoidUsingPlainTextForPassword", "Password")]
+    param (
+        [Parameter(Mandatory = $true)]
+        [System.URI]$PiHoleServer,
+        [Parameter(Mandatory = $true)]
+        [string]$Password,
+        [Parameter(Mandatory = $true)]
+        [System.IO.FileInfo]$FilePath,
+        [switch]$Config,
+        [switch]$DhcpLeases,
+        [switch]$Group,
+        [switch]$Adlist,
+        [switch]$AdlistByGroup,
+        [switch]$Domainlist,
+        [switch]$DomainlistByGroup,
+        [switch]$Client,
+        [switch]$ClientByGroup,
+        [bool]$IgnoreSsl = $false,
+        [bool]$RawOutput = $false
+    )
+    try {
+        if (-not (Test-Path -Path $FilePath)) {
+            throw "$FilePath does not exist!"
+        }
+
+        # Flat switches rather than Pi-hole's own nested { config, dhcp_leases, gravity: {...} }
+        # shape - whether any were passed at all decides whether an "import" field is sent; if
+        # none were, the field is omitted entirely so Pi-hole imports everything (its own default
+        # when the field is missing), matching this function's own "import everything" default.
+        $ImportSwitchNames = 'Config', 'DhcpLeases', 'Group', 'Adlist', 'AdlistByGroup', 'Domainlist', 'DomainlistByGroup', 'Client', 'ClientByGroup'
+        $AnySwitchSpecified = $false
+        foreach ($Name in $ImportSwitchNames) {
+            if ($PSBoundParameters.ContainsKey($Name)) {
+                $AnySwitchSpecified = $true
+                break
+            }
+        }
+
+        $Target = "Pi-Hole at $PiHoleServer"
+        $Action = "Import Teleporter archive '$FilePath' (this will overwrite your current configuration)"
+        if ($PSCmdlet.ShouldProcess($Target, $Action)) {
+            $Sid = Request-PiHoleAuth -PiHoleServer $PiHoleServer -Password $Password -IgnoreSsl $IgnoreSsl
+
+            $FormData = @{
+                file = Get-Item -Path $FilePath
+            }
+
+            if ($AnySwitchSpecified) {
+                $ImportBody = [ordered]@{
+                    config      = [bool]$Config
+                    dhcp_leases = [bool]$DhcpLeases
+                    gravity     = [ordered]@{
+                        group               = [bool]$Group
+                        adlist              = [bool]$Adlist
+                        adlist_by_group     = [bool]$AdlistByGroup
+                        domainlist          = [bool]$Domainlist
+                        domainlist_by_group = [bool]$DomainlistByGroup
+                        client              = [bool]$Client
+                        client_by_group     = [bool]$ClientByGroup
+                    }
+                }
+                $FormData['import'] = $ImportBody | ConvertTo-Json -Depth 5 -Compress
+            }
+
+            $Params = @{
+                Headers              = @{sid = $($Sid) }
+                Uri                  = "$($PiHoleServer.OriginalString)/api/teleporter"
+                Method               = "Post"
+                SkipCertificateCheck = $IgnoreSsl
+                Form                 = $FormData
+            }
+
+            $Response = Invoke-RestMethod @Params
+
+            if ($RawOutput) {
+                Write-Output $Response
+            }
+            else {
+                # The live API returns this array under "files", despite the OpenAPI spec
+                # documenting the field as "processed" - confirmed against a real server.
+                $Object = [PSCustomObject]@{
+                    Processed = $Response.files
+                }
+                Write-Output $Object
+            }
+        }
+    }
+
+    catch {
+        Write-Error -Message $_.Exception.Message
+    }
+
+    finally {
+        if ($Sid) {
+            Remove-PiHoleCurrentAuthSession -PiHoleServer $PiHoleServer -Sid $Sid -IgnoreSsl $IgnoreSsl
+        }
+    }
+}

README.md

@@ -192,6 +192,7 @@ See [docs/EXAMPLES.md](docs/EXAMPLES.md) for real, captured output from every fu
 | `Get-PiHoleNetworkRoute` | Get info about the routes of your Pi-hole |
 | `Get-PiHolePadd` | Get summarized data for PADD |
 | `Get-PiHoleTeleporterDownload` | Export Pi-hole settings |
+| `Import-PiHoleTeleporter` | Import Pi-hole settings |
 | `Remove-PiHoleConfigArrayItem` | Delete config array item |
 | `Remove-PiHoleDhcpLease` | Remove a DHCP lease |
 | `Remove-PiHoleInfoMessage` | Delete a Pi-hole diagnosis message |