Here's how you can fetch your DNS and DHCP records from your pfSense box with IP address `192.168.0.1` using the API:

Pfsense_DHCP_Over_API.md

Here's how you can fetch your DNS and DHCP records from your pfSense box with IP address 192.168.0.1 using the API:

Fetching DNS Host Overrides

Use the following curl command to fetch DNS Host Overrides:

curl -X GET "http://192.168.0.1/api/v1/services/dnsmasq/host_override" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer your-api-key"

Replace your-api-key with the actual API key you generated.

Fetching DHCP Leases

Use the following curl command to fetch DHCP leases:

curl -X GET "http://192.168.0.1/api/v1/services/dhcpd/lease" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer your-api-key"

Again, replace your-api-key with the actual API key you generated.

Example

Here's a step-by-step example for clarity:

1. Fetch DNS Host Overrides:

   curl -X GET "http://192.168.0.1/api/v1/services/dnsmasq/host_override" \
   -H "Content-Type: application/json" \
   -H "Authorization: Bearer your-api-key"

   This command will return a JSON response similar to:

   [
       {
           "id": "1",
           "host": "server1",
           "domain": "example.com",
           "ip": "192.168.1.10",
           "descr": "Primary server"
       },
       {
           "id": "2",
           "host": "server2",
           "domain": "example.com",
           "ip": "192.168.1.20",
           "descr": "Secondary server"
       }
   ]

2. Fetch DHCP Leases:

   curl -X GET "http://192.168.0.1/api/v1/services/dhcpd/lease" \
   -H "Content-Type: application/json" \
   -H "Authorization: Bearer your-api-key"

   This command will return a JSON response similar to:

   [
       {
           "ip": "192.168.1.100",
           "mac": "00:11:22:33:44:55",
           "hostname": "client1",
           "start": "2024-06-12 12:34:56",
           "end": "2024-06-13 12:34:56",
           "state": "active"
       },
       {
           "ip": "192.168.1.101",
           "mac": "66:77:88:99:aa:bb",
           "hostname": "client2",
           "start": "2024-06-12 12:34:56",
           "end": "2024-06-13 12:34:56",
           "state": "expired"
       }
   ]

These commands allow you to programmatically access and manage your pfSense DNS and DHCP records. If you have any specific configurations or additional parameters to include, refer to the pfSense API documentation for further details.

Getting a Bearer Token aka API Key

To get a bearer token for accessing the pfSense API, you need to follow these steps:

Step 1: Create an API User

1. Login to your pfSense web interface: Open a web browser and go to http://192.168.0.1 (replace with your pfSense IP address).

2. Navigate to System > User Manager:

   • Go to System -> User Manager.
   • Click on the +Add button to create a new user.

3. Create a new user with API permissions:

   • Fill in the username, password, and other necessary fields.
   • Under Effective Privileges, add the necessary permissions for accessing the API. You can use WebCfg - All pages for full access or specify more granular permissions.
   • Click Save.

Step 2: Generate an API Token

1. Generate an API token for the user:

   • After creating the user, go back to the User Manager.
   • Find the user you just created and click on the e (edit) button.
   • Scroll down to the User Certificates section and click +Add to generate a new certificate.
   • Fill in the certificate details and click Save.

2. Export the user certificate:

   • After creating the certificate, export it by clicking on the Download button next to the certificate entry.

Step 3: Get the Bearer Token

To get the bearer token, you will use the generated certificate to authenticate via the API. Here’s how you can do it using curl:

1. Convert the certificate to a format usable by curl:

   • If the certificate is in p12 format, you need to convert it to pem format.

   openssl pkcs12 -in user_cert.p12 -out user_cert.pem -nodes

2. Use the certificate to get a bearer token:

   curl -X POST "http://192.168.0.1/api/v1/access_token" \
   --cert user_cert.pem \
   --key user_key.pem \
   -H "Content-Type: application/json" \
   -d '{"client_id":"your-client-id","client_secret":"your-client-secret"}'

   Replace user_cert.pem and user_key.pem with the paths to your certificate and key files. You might also need to provide client_id and client_secret if your pfSense API setup requires it.

Example Request

Here’s an example curl command to get the bearer token:

curl -X POST "http://192.168.0.1/api/v1/access_token" \
--cert /path/to/user_cert.pem \
--key /path/to/user_key.pem \
-H "Content-Type: application/json" \
-d '{"username":"api-user","password":"api-password"}'

The response will include the bearer token you can use for subsequent API requests.

Using the Bearer Token

Once you have the bearer token, you can include it in the header of your API requests like this:

curl -X GET "http://192.168.0.1/api/v1/services/dnsmasq/host_override" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer your-bearer-token"

Replace your-bearer-token with the actual token obtained from the previous step.

Summary

Creating an API user and generating a bearer token involves setting up a user with API permissions, generating a user certificate, and using the certificate to obtain a bearer token for API access. This token is then used in the Authorization header for subsequent API requests. Make sure to secure your certificates and tokens properly to prevent unauthorized access.