feat: add DHCP lease API area

PiHoleShell/PiHoleShell.psm1

@@ -44,5 +44,7 @@ Export-ModuleMember -Function @(
         #ClientManagement
         'Get-PiHoleClient', 'New-PiHoleClient', 'Update-PiHoleClient', 'Remove-PiHoleClient', 'Get-PiHoleClientSuggestion', `
         #NetworkInformation
-        'Get-PiHoleNetworkGateway', 'Get-PiHoleNetworkRoute', 'Get-PiHoleNetworkInterface', 'Get-PiHoleNetworkDevice', 'Remove-PiHoleNetworkDevice'
+        'Get-PiHoleNetworkGateway', 'Get-PiHoleNetworkRoute', 'Get-PiHoleNetworkInterface', 'Get-PiHoleNetworkDevice', 'Remove-PiHoleNetworkDevice', `
+        #DHCP
+        'Get-PiHoleDhcpLease', 'Remove-PiHoleDhcpLease'
 )

PiHoleShell/Public/DHCP/Get-PiHoleDhcpLease.ps1

@@ -0,0 +1,81 @@
+function Get-PiHoleDhcpLease {
+    <#
+.SYNOPSIS
+Get currently active DHCP leases
+
+.DESCRIPTION
+Returns the currently active DHCP leases handed out by Pi-hole's DHCP server.
+
+.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-PiHoleDhcpLease -PiHoleServer "http://pihole.domain.com:8080" -Password "your-app-password"
+    #>
+    [CmdletBinding(HelpUri = 'https://ftl.pi-hole.net/master/docs/#get-/dhcp/leases')]
+    [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/dhcp/leases"
+            Method               = "Get"
+            SkipCertificateCheck = $IgnoreSsl
+            ContentType          = "application/json"
+        }
+
+        $Response = Invoke-RestMethod @Params
+
+        if ($RawOutput) {
+            Write-Output $Response
+        }
+        else {
+            $ObjectFinal = foreach ($Item in $Response.leases) {
+                # A lease's expires value of 0 means the lease is infinite and never expires.
+                if ($Item.expires -eq 0) {
+                    $Expires = $null
+                }
+                else {
+                    $Expires = (Convert-PiHoleUnixTimeToLocalTime -UnixTime $Item.expires).LocalTime
+                }
+
+                [PSCustomObject]@{
+                    Name     = $Item.name
+                    Ip       = $Item.ip
+                    HwAddr   = $Item.hwaddr
+                    ClientId = $Item.clientid
+                    Expires  = $Expires
+                }
+            }
+            Write-Output $ObjectFinal
+        }
+    }
+
+    catch {
+        Write-Error -Message $_.Exception.Message
+    }
+
+    finally {
+        if ($Sid) {
+            Remove-PiHoleCurrentAuthSession -PiHoleServer $PiHoleServer -Sid $Sid -IgnoreSsl $IgnoreSsl
+        }
+    }
+}

PiHoleShell/Public/DHCP/Remove-PiHoleDhcpLease.ps1

@@ -0,0 +1,80 @@
+function Remove-PiHoleDhcpLease {
+    <#
+.SYNOPSIS
+Remove a DHCP lease
+
+.DESCRIPTION
+Removes a currently active DHCP lease. Managing DHCP leases is only possible when the DHCP
+server is enabled.
+
+.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 Ip
+The IP address of the lease to remove, as shown by Get-PiHoleDhcpLease
+
+.PARAMETER IgnoreSsl
+Set to $true to skip SSL certificate validation
+
+.PARAMETER RawOutput
+This will dump the response instead of the formatted object
+
+.EXAMPLE
+Remove-PiHoleDhcpLease -PiHoleServer "http://pihole.domain.com:8080" -Password "your-app-password" -Ip "192.168.1.50"
+    #>
+    [CmdletBinding(SupportsShouldProcess = $true, HelpUri = 'https://ftl.pi-hole.net/master/docs/#delete-/dhcp/leases/-ip-')]
+    [System.Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSAvoidUsingPlainTextForPassword", "Password")]
+    param (
+        [Parameter(Mandatory = $true)]
+        [System.URI]$PiHoleServer,
+        [Parameter(Mandatory = $true)]
+        [string]$Password,
+        [Parameter(Mandatory = $true)]
+        [string]$Ip,
+        [bool]$IgnoreSsl = $false,
+        [bool]$RawOutput = $false
+    )
+    try {
+        $Target = "Pi-Hole DHCP lease $Ip"
+        if ($PSCmdlet.ShouldProcess($Target, "Remove DHCP lease")) {
+            $Sid = Request-PiHoleAuth -PiHoleServer $PiHoleServer -Password $Password -IgnoreSsl $IgnoreSsl
+
+            $Params = @{
+                Headers              = @{sid = $($Sid) }
+                Uri                  = "$($PiHoleServer.OriginalString)/api/dhcp/leases/$Ip"
+                Method               = "Delete"
+                SkipCertificateCheck = $IgnoreSsl
+                ContentType          = "application/json"
+            }
+
+            $Response = Invoke-RestMethod @Params
+
+            if ($RawOutput) {
+                Write-Output $Response
+            }
+
+            else {
+                # A successful delete returns 204 No Content, so there's no response body to
+                # build a rich object from.
+                $Object = [PSCustomObject]@{
+                    Ip     = $Ip
+                    Status = "Removed"
+                }
+                Write-Output $Object
+            }
+        }
+    }
+
+    catch {
+        Write-Error -Message $_.Exception.Message
+    }
+
+    finally {
+        if ($Sid) {
+            Remove-PiHoleCurrentAuthSession -PiHoleServer $PiHoleServer -Sid $Sid -IgnoreSsl $IgnoreSsl
+        }
+    }
+}

README.md

@@ -165,6 +165,7 @@ See [docs/EXAMPLES.md](docs/EXAMPLES.md) for real, captured output from every fu
 | `Add-PiHoleConfigArrayItem` | Add config array item |
 | `Get-PiHoleConfig` | Get current configuration of Pi-hole |
 | `Get-PiHoleConfigProperty` | Get special properties of your Pi-hole configuration |
+| `Get-PiHoleDhcpLease` | Get currently active DHCP leases |
 | `Get-PiHoleHistory` | Get activity graph data |
 | `Get-PiHoleHistoryClient` | Get per-client activity graph data |
 | `Get-PiHoleHistoryDatabase` | Get activity graph data (long-term data) |
@@ -190,6 +191,7 @@ See [docs/EXAMPLES.md](docs/EXAMPLES.md) for real, captured output from every fu
 | `Get-PiHolePadd` | Get summarized data for PADD |
 | `Get-PiHoleTeleporterDownload` | Export Pi-hole settings |
 | `Remove-PiHoleConfigArrayItem` | Delete config array item |
+| `Remove-PiHoleDhcpLease` | Remove a DHCP lease |
 | `Remove-PiHoleInfoMessage` | Delete a Pi-hole diagnosis message |
 | `Remove-PiHoleNetworkDevice` | Delete a device from the network table |
 | `Set-PiHoleConfig` | Change configuration of your Pi-hole |