feat: add Stats (database) functions

PiHoleShell/PiHoleShell.psm1

@@ -28,7 +28,8 @@ Export-ModuleMember -Function @(
         #Padd
         'Get-PiHolePadd', `
         #Metrics
-        'Get-PiHoleStatsRecentBlocked', 'Get-PiHoleStatsQueryType', 'Get-PiHoleStatsTopDomain', 'Get-PiHoleStatsSummary', 'Get-PiHoleStatsTopClient', 'Get-PiHoleStatsQuerySuggestions' `
+        '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', `
         #FTLInformation

PiHoleShell/Private/Misc.ps1

@@ -64,7 +64,7 @@ function Remove-PiHoleCurrentAuthSession {
     }
 
     try {
-        Invoke-RestMethod @Params
+        $null = Invoke-RestMethod @Params
     }
 
     catch {

PiHoleShell/Public/Metrics/Get-PiHoleStatsDatabaseQueryType.ps1

@@ -0,0 +1,94 @@
+function Get-PiHoleStatsDatabaseQueryType {
+    <#
+.SYNOPSIS
+Get query types (long-term database)
+
+.DESCRIPTION
+Request a breakdown of query types (A, AAAA, ...) for a given time range from the long-term
+(on-disk) database, rather than the in-memory data returned by Get-PiHoleStatsQueryType.
+
+.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 From
+Unix timestamp from when the data should be requested
+
+.PARAMETER Until
+Unix timestamp until when the data should be requested
+
+.PARAMETER IgnoreSsl
+Set to $true to skip SSL certificate validation
+
+.PARAMETER RawOutput
+This will dump the response instead of the formatted object
+
+.EXAMPLE
+Get-PiHoleStatsDatabaseQueryType -PiHoleServer "http://pihole.domain.com:8080" -Password "fjdsjfldsjfkldjslafjskdl" -From 1672580025 -Until 1672666425
+    #>
+    [CmdletBinding(HelpUri = 'https://ftl.pi-hole.net/master/docs/#get-/stats/database/query_types')]
+    [System.Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSAvoidUsingPlainTextForPassword", "Password")]
+    param (
+        [Parameter(Mandatory = $true)]
+        [System.URI]$PiHoleServer,
+        [Parameter(Mandatory = $true)]
+        [string]$Password,
+        [Parameter(Mandatory = $true)]
+        [int]$From,
+        [Parameter(Mandatory = $true)]
+        [int]$Until,
+        [bool]$IgnoreSsl = $false,
+        [bool]$RawOutput = $false
+    )
+
+    try {
+        $Sid = Request-PiHoleAuth -PiHoleServer $PiHoleServer -Password $Password -IgnoreSsl $IgnoreSsl
+
+        $Params = @{
+            Headers              = @{sid = $($Sid) }
+            Uri                  = "$($PiHoleServer.OriginalString)/api/stats/database/query_types?from=$From&until=$Until"
+            Method               = "Get"
+            SkipCertificateCheck = $IgnoreSsl
+            ContentType          = "application/json"
+        }
+
+        $Response = Invoke-RestMethod @Params
+
+        if ($RawOutput) {
+            Write-Output $Response
+        }
+        else {
+            $Object = [PSCustomObject]@{
+                A      = $Response.types.A
+                AAAA   = $Response.types.AAAA
+                ANY    = $Response.types.ANY
+                SRV    = $Response.types.SRV
+                SOA    = $Response.types.SOA
+                PTR    = $Response.types.PTR
+                TXT    = $Response.types.TXT
+                NAPTR  = $Response.types.NAPTR
+                MX     = $Response.types.MX
+                DS     = $Response.types.DS
+                RRSIG  = $Response.types.RRSIG
+                DNSKEY = $Response.types.DNSKEY
+                NS     = $Response.types.NS
+                SVCB   = $Response.types.SVCB
+                HTTPS  = $Response.types.HTTPS
+                OTHER  = $Response.types.OTHER
+            }
+            Write-Output $Object
+        }
+    }
+
+    catch {
+        Write-Error -Message $_.Exception.Message
+    }
+
+    finally {
+        if ($Sid) {
+            Remove-PiHoleCurrentAuthSession -PiHoleServer $PiHoleServer -Sid $Sid -IgnoreSsl $IgnoreSsl
+        }
+    }
+}

PiHoleShell/Public/Metrics/Get-PiHoleStatsDatabaseSummary.ps1

@@ -0,0 +1,82 @@
+function Get-PiHoleStatsDatabaseSummary {
+    <#
+.SYNOPSIS
+Get database content details
+
+.DESCRIPTION
+Request various database content details (total/blocked queries, percent blocked, total
+clients) for a given time range from the long-term (on-disk) database.
+
+.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 From
+Unix timestamp from when the data should be requested
+
+.PARAMETER Until
+Unix timestamp until when the data should be requested
+
+.PARAMETER IgnoreSsl
+Set to $true to skip SSL certificate validation
+
+.PARAMETER RawOutput
+This will dump the response instead of the formatted object
+
+.EXAMPLE
+Get-PiHoleStatsDatabaseSummary -PiHoleServer "http://pihole.domain.com:8080" -Password "fjdsjfldsjfkldjslafjskdl" -From 1672580025 -Until 1672666425
+    #>
+    [CmdletBinding(HelpUri = 'https://ftl.pi-hole.net/master/docs/#get-/stats/database/summary')]
+    [System.Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSAvoidUsingPlainTextForPassword", "Password")]
+    param (
+        [Parameter(Mandatory = $true)]
+        [System.URI]$PiHoleServer,
+        [Parameter(Mandatory = $true)]
+        [string]$Password,
+        [Parameter(Mandatory = $true)]
+        [int]$From,
+        [Parameter(Mandatory = $true)]
+        [int]$Until,
+        [bool]$IgnoreSsl = $false,
+        [bool]$RawOutput = $false
+    )
+
+    try {
+        $Sid = Request-PiHoleAuth -PiHoleServer $PiHoleServer -Password $Password -IgnoreSsl $IgnoreSsl
+
+        $Params = @{
+            Headers              = @{sid = $($Sid) }
+            Uri                  = "$($PiHoleServer.OriginalString)/api/stats/database/summary?from=$From&until=$Until"
+            Method               = "Get"
+            SkipCertificateCheck = $IgnoreSsl
+            ContentType          = "application/json"
+        }
+
+        $Response = Invoke-RestMethod @Params
+
+        if ($RawOutput) {
+            Write-Output $Response
+        }
+        else {
+            $Object = [PSCustomObject]@{
+                SumQueries     = $Response.sum_queries
+                SumBlocked     = $Response.sum_blocked
+                PercentBlocked = $Response.percent_blocked
+                TotalClients   = $Response.total_clients
+            }
+            Write-Output $Object
+        }
+    }
+
+    catch {
+        Write-Error -Message $_.Exception.Message
+    }
+
+    finally {
+        if ($Sid) {
+            Remove-PiHoleCurrentAuthSession -PiHoleServer $PiHoleServer -Sid $Sid -IgnoreSsl $IgnoreSsl
+        }
+    }
+}

PiHoleShell/Public/Metrics/Get-PiHoleStatsDatabaseTopClient.ps1

@@ -0,0 +1,102 @@
+function Get-PiHoleStatsDatabaseTopClient {
+    <#
+.SYNOPSIS
+Get top clients (long-term database)
+
+.DESCRIPTION
+Request the top clients for a given time range from the long-term (on-disk) database, rather
+than the in-memory data returned by Get-PiHoleStatsTopClient.
+
+.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 From
+Unix timestamp from when the data should be requested
+
+.PARAMETER Until
+Unix timestamp until when the data should be requested
+
+.PARAMETER MaxResult
+How many results should be returned
+
+.PARAMETER Blocked
+If true, returns top clients by blocked queries instead of total queries
+
+.PARAMETER IgnoreSsl
+Set to $true to skip SSL certificate validation
+
+.PARAMETER RawOutput
+This will dump the response instead of the formatted object
+
+.EXAMPLE
+Get-PiHoleStatsDatabaseTopClient -PiHoleServer "http://pihole.domain.com:8080" -Password "fjdsjfldsjfkldjslafjskdl" -From 1672580025 -Until 1672666425 -MaxResult 10
+    #>
+    [CmdletBinding(HelpUri = 'https://ftl.pi-hole.net/master/docs/#get-/stats/database/top_clients')]
+    [System.Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSAvoidUsingPlainTextForPassword", "Password")]
+    param (
+        [Parameter(Mandatory = $true)]
+        [System.URI]$PiHoleServer,
+        [Parameter(Mandatory = $true)]
+        [string]$Password,
+        [Parameter(Mandatory = $true)]
+        [int]$From,
+        [Parameter(Mandatory = $true)]
+        [int]$Until,
+        [int]$MaxResult = 10,
+        [bool]$Blocked = $false,
+        [bool]$IgnoreSsl = $false,
+        [bool]$RawOutput = $false
+    )
+
+    try {
+        $Sid = Request-PiHoleAuth -PiHoleServer $PiHoleServer -Password $Password -IgnoreSsl $IgnoreSsl
+
+        switch ($Blocked) {
+            $false { $BlockedParam = "false" }
+            $true { $BlockedParam = "true" }
+            Default { throw "ERROR" }
+        }
+        Write-Verbose "Blocked: $BlockedParam"
+        Write-Verbose "MaxResult: $MaxResult"
+
+        $Params = @{
+            Headers              = @{sid = $($Sid) }
+            Uri                  = "$($PiHoleServer.OriginalString)/api/stats/database/top_clients?from=$From&until=$Until&blocked=$BlockedParam&count=$MaxResult"
+            Method               = "Get"
+            SkipCertificateCheck = $IgnoreSsl
+            ContentType          = "application/json"
+        }
+
+        $Response = Invoke-RestMethod @Params
+
+        if ($RawOutput) {
+            Write-Output $Response
+        }
+        else {
+            $ObjectFinal = @()
+            foreach ($Item in $Response.clients) {
+                $Object = [PSCustomObject]@{
+                    IP    = $Item.ip
+                    Name  = $Item.name
+                    Count = $Item.count
+                }
+                Write-Verbose -Message "Client - $($Item.ip) ($($Item.name)): $($Item.count)"
+                $ObjectFinal += $Object
+            }
+            Write-Output $ObjectFinal
+        }
+    }
+
+    catch {
+        Write-Error -Message $_.Exception.Message
+    }
+
+    finally {
+        if ($Sid) {
+            Remove-PiHoleCurrentAuthSession -PiHoleServer $PiHoleServer -Sid $Sid -IgnoreSsl $IgnoreSsl
+        }
+    }
+}