opnsense_dhcp_find_lease
Search for DHCPv4 leases using an IP address, MAC address, or hostname. Automatically detects whether Kea or ISC DHCP is active.
Instructions
Search DHCPv4 leases by IP address, MAC address, or hostname. Supports both Kea DHCP and ISC DHCP (legacy) backends — auto-detects which is active.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Search term — IP address, MAC address, or hostname |
Implementation Reference
- src/tools/dhcp.ts:447-456 (handler)Handler case for 'opnsense_dhcp_find_lease' in handleDhcpTool. It validates input with FindLeaseSchema, then tries to find the lease via Kea backend; if that fails (Kea plugin not installed), it falls back to ISC DHCP backend.
case "opnsense_dhcp_find_lease": { const parsed = FindLeaseSchema.parse(args); try { const result = await keaFindLease(client, parsed.query); return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] }; } catch { const result = await iscFindLease(client, parsed.query); return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] }; } } - src/tools/dhcp.ts:371-375 (helper)Kea backend helper: keaFindLease queries /kea/leases4/search with the searchPhrase parameter.
async function keaFindLease(client: OPNsenseClient, query: string): Promise<unknown> { return await client.get( `/kea/leases4/search?searchPhrase=${encodeURIComponent(query)}`, ); } - src/tools/dhcp.ts:385-389 (helper)ISC DHCP (legacy) backend helper: iscFindLease queries /dhcpv4/leases/searchLease with the searchPhrase parameter.
async function iscFindLease(client: OPNsenseClient, query: string): Promise<unknown> { return await client.get( `/dhcpv4/leases/searchLease?searchPhrase=${encodeURIComponent(query)}`, ); } - src/tools/dhcp.ts:9-11 (schema)Zod schema FindLeaseSchema that validates the input: requires a non-empty string 'query' for searching leases by IP, MAC, or hostname.
const FindLeaseSchema = z.object({ query: z.string().min(1, "Search query is required (IP, MAC, or hostname)"), }); - src/tools/dhcp.ts:85-99 (registration)Tool definition registration in dhcpToolDefinitions array: defines the tool name 'opnsense_dhcp_find_lease', description, and input schema with required 'query' string property.
{ name: "opnsense_dhcp_find_lease", description: "Search DHCPv4 leases by IP address, MAC address, or hostname. Supports both Kea DHCP and ISC DHCP (legacy) backends — auto-detects which is active.", inputSchema: { type: "object" as const, properties: { query: { type: "string", description: "Search term — IP address, MAC address, or hostname", }, }, required: ["query"], }, },