Promote develop to main

PiHoleShell/PiHoleShell.psm1

@@ -31,9 +31,10 @@ Export-ModuleMember -Function @(
         'Get-PiHoleStatsRecentBlocked', 'Get-PiHoleStatsQueryType', 'Get-PiHoleStatsTopDomain', 'Get-PiHoleStatsSummary', 'Get-PiHoleStatsTopClient', 'Get-PiHoleStatsQuerySuggestions', `
         'Get-PiHoleStatsUpstream', 'Get-PiHoleStatsDatabaseUpstream', 'Get-PiHoleStatsDatabaseSummary', 'Get-PiHoleStatsDatabaseTopDomain', 'Get-PiHoleStatsDatabaseTopClient', 'Get-PiHoleStatsDatabaseQueryType' `
         #ListManagement
-        'Get-PiHoleList', 'Search-PiHoleListDomain', 'Add-PiHoleList', 'Remove-PiHoleList', `
+        'Get-PiHoleList', 'Search-PiHoleListDomain', 'Add-PiHoleList', 'Remove-PiHoleList', 'Update-PiHoleList', `
         #FTLInformation
-        'Get-PiHoleInfoMessage', 'Get-PiHoleInfoHost', `
+        'Get-PiHoleInfoMessage', 'Get-PiHoleInfoHost', 'Get-PiHoleInfoClient', 'Get-PiHoleInfoLogin', 'Get-PiHoleInfoSystem', 'Get-PiHoleInfoFtl', `
+        'Get-PiHoleInfoSensors', 'Get-PiHoleInfoDatabase', 'Get-PiHoleInfoVersion', 'Get-PiHoleInfoMetrics', 'Get-PiHoleInfoMessageCount', 'Remove-PiHoleInfoMessage', `
         #History
         'Get-PiHoleHistory', 'Get-PiHoleHistoryDatabase', 'Get-PiHoleHistoryClient', 'Get-PiHoleHistoryDatabaseClient'
 )

PiHoleShell/Public/FTLInformation/Get-PiHoleInfoClient.ps1

@@ -0,0 +1,65 @@
+function Get-PiHoleInfoClient {
+    <#
+.SYNOPSIS
+Get information about the requesting client
+
+.DESCRIPTION
+Returns information about how the Pi-hole server sees this request: your remote address, the
+HTTP version and method used, and the request headers sent. This endpoint does not require
+authentication.
+
+.PARAMETER PiHoleServer
+The URL to the PiHole Server, for example "http://pihole.domain.com:8080", or "http://192.168.1.100"
+
+.PARAMETER IgnoreSsl
+Set to $true to skip SSL certificate validation
+
+.PARAMETER RawOutput
+This will dump the response instead of the formatted object
+
+.EXAMPLE
+Get-PiHoleInfoClient -PiHoleServer "http://pihole.domain.com:8080"
+    #>
+    [CmdletBinding(HelpUri = 'https://ftl.pi-hole.net/master/docs/#get-/info/client')]
+    param (
+        [Parameter(Mandatory = $true)]
+        [System.URI]$PiHoleServer,
+        [bool]$IgnoreSsl = $false,
+        [bool]$RawOutput = $false
+    )
+
+    try {
+        $Params = @{
+            Uri                  = "$($PiHoleServer.OriginalString)/api/info/client"
+            Method               = "Get"
+            SkipCertificateCheck = $IgnoreSsl
+            ContentType          = "application/json"
+        }
+
+        $Response = Invoke-RestMethod @Params
+
+        if ($RawOutput) {
+            Write-Output $Response
+        }
+        else {
+            $Headers = foreach ($Item in $Response.headers) {
+                [PSCustomObject]@{
+                    Name  = $Item.name
+                    Value = $Item.value
+                }
+            }
+
+            $Object = [PSCustomObject]@{
+                RemoteAddress = $Response.remote_addr
+                HttpVersion   = $Response.http_version
+                Method        = $Response.method
+                Headers       = $Headers
+            }
+            Write-Output $Object
+        }
+    }
+
+    catch {
+        Write-Error -Message $_.Exception.Message
+    }
+}

PiHoleShell/Public/FTLInformation/Get-PiHoleInfoDatabase.ps1

@@ -0,0 +1,95 @@
+function Get-PiHoleInfoDatabase {
+    <#
+.SYNOPSIS
+Get info about the long-term database
+
+.DESCRIPTION
+Request details about Pi-hole's long-term (on-disk) query database file: its size and
+ownership on disk, how many queries are stored in-memory versus on-disk, and the earliest
+timestamp in each.
+
+.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 IgnoreSsl
+Set to $true to skip SSL certificate validation
+
+.PARAMETER RawOutput
+This will dump the response instead of the formatted object
+
+.EXAMPLE
+Get-PiHoleInfoDatabase -PiHoleServer "http://pihole.domain.com:8080" -Password "your-app-password"
+    #>
+    [CmdletBinding(HelpUri = 'https://ftl.pi-hole.net/master/docs/#get-/info/database')]
+    [System.Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSAvoidUsingPlainTextForPassword", "Password")]
+    param (
+        [Parameter(Mandatory = $true)]
+        [System.URI]$PiHoleServer,
+        [Parameter(Mandatory = $true)]
+        [string]$Password,
+        [bool]$IgnoreSsl = $false,
+        [bool]$RawOutput = $false
+    )
+
+    try {
+        $Sid = Request-PiHoleAuth -PiHoleServer $PiHoleServer -Password $Password -IgnoreSsl $IgnoreSsl
+
+        $Params = @{
+            Headers              = @{sid = $($Sid) }
+            Uri                  = "$($PiHoleServer.OriginalString)/api/info/database"
+            Method               = "Get"
+            SkipCertificateCheck = $IgnoreSsl
+            ContentType          = "application/json"
+        }
+
+        $Response = Invoke-RestMethod @Params
+
+        if ($RawOutput) {
+            Write-Output $Response
+        }
+        else {
+            # The API defaults these to 0.0 when there are no queries stored in-memory/on-disk yet.
+            $EarliestTimestamp = if ($Response.earliest_timestamp -eq 0) { $null } else { (Convert-PiHoleUnixTimeToLocalTime -UnixTime $Response.earliest_timestamp).LocalTime }
+            $EarliestTimestampDisk = if ($Response.earliest_timestamp_disk -eq 0) { $null } else { (Convert-PiHoleUnixTimeToLocalTime -UnixTime $Response.earliest_timestamp_disk).LocalTime }
+
+            $Object = [PSCustomObject]@{
+                Size                  = $Response.size
+                Type                  = $Response.type
+                Mode                  = $Response.mode
+                AccessTime            = (Convert-PiHoleUnixTimeToLocalTime -UnixTime $Response.atime).LocalTime
+                ModifiedTime          = (Convert-PiHoleUnixTimeToLocalTime -UnixTime $Response.mtime).LocalTime
+                ChangeTime            = (Convert-PiHoleUnixTimeToLocalTime -UnixTime $Response.ctime).LocalTime
+                Owner                 = [PSCustomObject]@{
+                    User  = [PSCustomObject]@{
+                        Uid  = $Response.owner.user.uid
+                        Name = $Response.owner.user.name
+                        Info = $Response.owner.user.info
+                    }
+                    Group = [PSCustomObject]@{
+                        Gid  = $Response.owner.group.gid
+                        Name = $Response.owner.group.name
+                    }
+                }
+                Queries               = $Response.queries
+                EarliestTimestamp     = $EarliestTimestamp
+                QueriesDisk           = $Response.queries_disk
+                EarliestTimestampDisk = $EarliestTimestampDisk
+                SqliteVersion         = $Response.sqlite_version
+            }
+            Write-Output $Object
+        }
+    }
+
+    catch {
+        Write-Error -Message $_.Exception.Message
+    }
+
+    finally {
+        if ($Sid) {
+            Remove-PiHoleCurrentAuthSession -PiHoleServer $PiHoleServer -Sid $Sid -IgnoreSsl $IgnoreSsl
+        }
+    }
+}

PiHoleShell/Public/FTLInformation/Get-PiHoleInfoFtl.ps1

@@ -0,0 +1,108 @@
+function Get-PiHoleInfoFtl {
+    <#
+.SYNOPSIS
+Get info about various FTL parameters
+
+.DESCRIPTION
+Request a collection of FTL process information: gravity database counts, privacy level,
+query frequency, client counts, process ID/uptime/resource usage, whether destructive actions
+are allowed, and metrics from the embedded dnsmasq resolver.
+
+.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 IgnoreSsl
+Set to $true to skip SSL certificate validation
+
+.PARAMETER RawOutput
+This will dump the response instead of the formatted object
+
+.EXAMPLE
+Get-PiHoleInfoFtl -PiHoleServer "http://pihole.domain.com:8080" -Password "your-app-password"
+    #>
+    [CmdletBinding(HelpUri = 'https://ftl.pi-hole.net/master/docs/#get-/info/ftl')]
+    [System.Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSAvoidUsingPlainTextForPassword", "Password")]
+    param (
+        [Parameter(Mandatory = $true)]
+        [System.URI]$PiHoleServer,
+        [Parameter(Mandatory = $true)]
+        [string]$Password,
+        [bool]$IgnoreSsl = $false,
+        [bool]$RawOutput = $false
+    )
+
+    try {
+        $Sid = Request-PiHoleAuth -PiHoleServer $PiHoleServer -Password $Password -IgnoreSsl $IgnoreSsl
+
+        $Params = @{
+            Headers              = @{sid = $($Sid) }
+            Uri                  = "$($PiHoleServer.OriginalString)/api/info/ftl"
+            Method               = "Get"
+            SkipCertificateCheck = $IgnoreSsl
+            ContentType          = "application/json"
+        }
+
+        $Response = Invoke-RestMethod @Params
+
+        if ($RawOutput) {
+            Write-Output $Response
+        }
+        else {
+            $Object = [PSCustomObject]@{
+                Database         = [PSCustomObject]@{
+                    Gravity     = $Response.ftl.database.gravity
+                    Antigravity = $Response.ftl.database.antigravity
+                    Groups      = $Response.ftl.database.groups
+                    Lists       = $Response.ftl.database.lists
+                    Clients     = $Response.ftl.database.clients
+                    Domains     = [PSCustomObject]@{
+                        Allowed = [PSCustomObject]@{
+                            Total   = $Response.ftl.database.domains.allowed.total
+                            Enabled = $Response.ftl.database.domains.allowed.enabled
+                        }
+                        Denied  = [PSCustomObject]@{
+                            Total   = $Response.ftl.database.domains.denied.total
+                            Enabled = $Response.ftl.database.domains.denied.enabled
+                        }
+                    }
+                    Regex       = [PSCustomObject]@{
+                        Allowed = [PSCustomObject]@{
+                            Total   = $Response.ftl.database.regex.allowed.total
+                            Enabled = $Response.ftl.database.regex.allowed.enabled
+                        }
+                        Denied  = [PSCustomObject]@{
+                            Total   = $Response.ftl.database.regex.denied.total
+                            Enabled = $Response.ftl.database.regex.denied.enabled
+                        }
+                    }
+                }
+                PrivacyLevel     = $Response.ftl.privacy_level
+                QueryFrequency   = $Response.ftl.query_frequency
+                Clients          = [PSCustomObject]@{
+                    Total  = $Response.ftl.clients.total
+                    Active = $Response.ftl.clients.active
+                }
+                Pid              = $Response.ftl.pid
+                Uptime           = $Response.ftl.uptime
+                PercentMemory    = $Response.ftl.'%mem'
+                PercentCpu       = $Response.ftl.'%cpu'
+                AllowDestructive = $Response.ftl.allow_destructive
+                Dnsmasq          = ConvertTo-PiHolePascalCaseObject -InputObject $Response.ftl.dnsmasq
+            }
+            Write-Output $Object
+        }
+    }
+
+    catch {
+        Write-Error -Message $_.Exception.Message
+    }
+
+    finally {
+        if ($Sid) {
+            Remove-PiHoleCurrentAuthSession -PiHoleServer $PiHoleServer -Sid $Sid -IgnoreSsl $IgnoreSsl
+        }
+    }
+}

PiHoleShell/Public/FTLInformation/Get-PiHoleInfoLogin.ps1

@@ -0,0 +1,56 @@
+function Get-PiHoleInfoLogin {
+    <#
+.SYNOPSIS
+Get login page information
+
+.DESCRIPTION
+Returns information used on Pi-hole's login page (the HTTPS port, and whether the DNS server
+is currently running). This endpoint does not require authentication, since it's meant to be
+usable before logging in.
+
+.PARAMETER PiHoleServer
+The URL to the PiHole Server, for example "http://pihole.domain.com:8080", or "http://192.168.1.100"
+
+.PARAMETER IgnoreSsl
+Set to $true to skip SSL certificate validation
+
+.PARAMETER RawOutput
+This will dump the response instead of the formatted object
+
+.EXAMPLE
+Get-PiHoleInfoLogin -PiHoleServer "http://pihole.domain.com:8080"
+    #>
+    [CmdletBinding(HelpUri = 'https://ftl.pi-hole.net/master/docs/#get-/info/login')]
+    param (
+        [Parameter(Mandatory = $true)]
+        [System.URI]$PiHoleServer,
+        [bool]$IgnoreSsl = $false,
+        [bool]$RawOutput = $false
+    )
+
+    try {
+        $Params = @{
+            Uri                  = "$($PiHoleServer.OriginalString)/api/info/login"
+            Method               = "Get"
+            SkipCertificateCheck = $IgnoreSsl
+            ContentType          = "application/json"
+        }
+
+        $Response = Invoke-RestMethod @Params
+
+        if ($RawOutput) {
+            Write-Output $Response
+        }
+        else {
+            $Object = [PSCustomObject]@{
+                HttpsPort = $Response.https_port
+                Dns       = $Response.dns
+            }
+            Write-Output $Object
+        }
+    }
+
+    catch {
+        Write-Error -Message $_.Exception.Message
+    }
+}

PiHoleShell/Public/FTLInformation/Get-PiHoleInfoMessage.ps1

@@ -2,9 +2,28 @@ function Get-PiHoleInfoMessage {
     <#
 .SYNOPSIS
 Get Pi-hole diagnosis messages
-Request Pi-hole diagnosis messages
+
+.DESCRIPTION
+Request Pi-hole's diagnosis messages - warnings FTL has generated about its own configuration
+or operation (e.g. rate-limiting a noisy client). See Get-PiHoleInfoMessageCount for just the
+count, and Remove-PiHoleInfoMessage to dismiss one.
+
+.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 IgnoreSsl
+Set to $true to skip SSL certificate validation
+
+.PARAMETER RawOutput
+This will dump the response instead of the formatted object
+
+.EXAMPLE
+Get-PiHoleInfoMessage -PiHoleServer "http://pihole.domain.com:8080" -Password "your-app-password"
     #>
-    [CmdletBinding()]
+    [CmdletBinding(HelpUri = 'https://ftl.pi-hole.net/master/docs/#get-/info/messages')]
     [System.Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSAvoidUsingPlainTextForPassword", "Password")]
     param (
         [Parameter(Mandatory = $true)]
@@ -58,7 +77,6 @@ Request Pi-hole diagnosis messages
 
     catch {
         Write-Error -Message $_.Exception.Message
-        break
     }
 
     finally {