Two years ago, I documented the integration of Pi-Hole with VMware Aria Operations using the Aria Operations Management Pack Builder (MPB) and Pi-Hole’s API. Since then, both tools have undergone significant updates: MPB has a revamped 2.0 interface, and Pi-Hole 6 introduced a completely new API with formal documentation and session-based authentication. In this updated guide, I’ll walk you through building a Pi-Hole Management Pack using these modern tools, highlighting key changes and providing a detailed, hands-on tutorial for tech enthusiasts and system admins.
What’s New with the Pi-Hole API?
Formal Documentation and Accessibility
With the release of Pi-Hole 6, the API has been overhauled to be more robust and user-friendly. Official documentation is now available at http://pi.hole/api/docs, which resolves to your local Pi-Hole server to ensure version compatibility. If you haven’t installed Pi-Hole yet, you can explore the documentation for all branches online, such as the Pi-Hole API documentation (master branch). Additionally, Pi-Hole provides a built-in UI at https://YourPi-holeServerName/api/docs/ where you can test API requests directly—a fantastic feature for developers.
Session ID Authentication: A Shift from Tokens
One major change in Pi-Hole 6 is the move from token-based to session ID-based authentication. I discovered this shift when my existing Management Pack stopped collecting data after upgrading to version 6. The API authentication documentation outlines several authentication options, I opted for the App Password method. Here’s how to set it up:
- In the Pi-Hole Admin UI, navigate to the Web Interface / API section of Settings, make sure the interface is toggled from Basic to Expert and click Configure App Password.
- The UI will display a one-time App Password—copy it immediately, as it won’t be shown again. Store it securely (e.g., in a password manager).
To verify the new authentication method, I used the API UI (https://YourPi-holeServerName/api/docs/) to test a request with my App Password. After clicking Try, I received a session.sid, confirming successful authentication.
I then tested the /stats/summary endpoint (used in my original article) with the session ID, ensuring it returned the expected data. I now had a basic enough understanding of the API to apply it to building a Management Pack.
Introducing Aria Operations Management Pack Builder 2.0
Released in October 2024, version 2.0 of the Aria Operations Management Pack Builder brings a refreshed UI and improved functionality. While MPs from version 1 can be imported, the Pi-Hole API changes require a fresh build for this example. I’ll assume you’ve already deployed the MPB appliance (refer to the official MPB deployment guide) and are ready to start.
Step 1: Configure the Connection in MPB
First, connect MPB to your Aria Operations server:
- Access the MPB Web UI.
- Navigate to the VMware Aria Operations Connection tab.
- Create and test a connection to your Aria Operations server.
With the connection established, you’re ready to build your Management Pack.
Step 2: Define the Source
The Source defines the environment (your Pi-Hole server) that MPB will interact with. Here’s how to set it up:
- In the Designs tab, click Create.
- Name your Management Pack (e.g., “Pi-Hole MP”) and add a description, then click Save.
- Configure the Source:
- Enter the Hostname, Port, SSL Configuration, and Base API Path of your Pi-Hole server.
- Click Next.
Set Up Authentication
Pi-Hole 6 uses session-based authentication, so we’ll configure MPB accordingly:
- On the Authentication tab, change the dropdown from Basic to Custom.
- Create a label called “App Password” and paste the App Password you generated earlier into the value field.
- Check the Sensitive box to secure the password, then click Add Field. This creates a variable
${authentication.credentials.app_password}for use in the MP. - Enable the Session Authentication toggle and click Next.
Configure the Session API Request
From the Pi-Hole API documentation, we know the authentication endpoint is a POST request to /auth. Configure it on the Get Session API Request tab as follows:
- Select POST from the dropdown HTTP Method list
- In the API Path field, enter
auth.
We saw in the API documentation that we need to pass our App Password in the Body of our request in the JSON Format of:
{"password": "${authentication.credentials.app_password}"}So on the Get Session Request Advanced tab we will use the variable created earlier to pass the App Password (note the use of double-quotes):
3. Click Request to test the configuration. If successful, you’ll see a session.sid in the response.
4. Select the session.sid field from the response body and copy the session ID variable for later use
The Pi-Hole API documentation lists four ways to use the session ID when making requests.
We’ll use the X-FTL-SID header option.
- In the Global Request Settings tab, add a header:
- Header Name:
X-FTL-SID - Header Value:
${session.sid}
This ensures the session ID is included in all API requests.
- Header Name:
In the Release Session Request tab:
- Enable the toggle to request a release
- Choose an HTTP Method of DELETE
- Set the API Path to auth
We do not add any additional values on the “Release Session Request Advanced” tab. Click Next.
On the Make Release Session Request tab click the Request button to verify a successful session release.
To verify the setup, test the /stats/summary endpoint:
- On the Test Connection Request tab, set the API Path to
stats/summary. - Click Request and confirm that summary data (e.g., total queries, blocked queries) is returned.
- Click Save to complete the Source configuration.
Step 3: Create API Requests
With a Source section successfully tested against our reference environment, we move to the Requests section of the design. This is where we define the API requests to collect the data that our MP uses. Since the point is to just demonstrate a concept, we are going to create just two requests, one named “summary” and one named “hostname”.
From the previous blog we determined that the /stats/summary API endpoint will return most of the data that we would use in our MP. And we used it in our Source section to test our reference environment. If you had read the previous blog you will recall that there was no endpoint that would return the pi-hole server name. Thankfully that has been resolved with the /info/host endpoint so we will use that as our second request for this test.
Request 1: Summary Statistics
- In the Requests tab, click Add API Request.
- Skip chaining (click Next).
- Set the HTTP Method to
GET, the API Path tostats/summary, and keep the default Request Name. - No advanced options are needed—click Next.
- On the Preview screen, click Request to confirm data is returned (e.g., total queries, blocked queries).
Request 2: Hostname
- Repeat the steps above, setting the API Path to
info/host. - Test the request to ensure data (e.g.,
host.uname.nodename) is returned.
Step 4: Define Objects
In the Objects section, select the data from your API requests to include in the Management Pack:
- Click Add New Object.
- Set the Object Type to “Pi-Hole Server” and click Next.
- On the Attributes from the API Request tab:
- Expand the
stats/summaryrequest and select key metrics like:queries.totalqueries.blockedqueries.percent_blockedqueries.cached
- Expand the
info/hostrequest and selecthost.uname.nodenamefor the server name.
- Expand the
- On the Properties and Metrics tab, adjust labels and data types as needed (e.g., use “Count” for total queries, “%” for percent blocked). For more on KPIs, check VMware’s KPI documentation.
- Set the Object Instance Name and Object Identifiers to “Pi-Hole Server Name” for clarity.
Step 5: Configure and Build the Management Pack
With the design complete, move to the Configuration section to review settings like MP version and labels. Then:
- In the Build section, click Perform Collection to run a test collection and verify the results.
- Click Build to generate the
.pakfile. - New in MPB 2.0: Deploy the Management Pack directly to your Aria Operations server by selecting it from the list and clicking Deploy.
Step 6: Configure the Management Pack in Aria Operations
Install the .pak file in Aria Operations as you would any other Management Pack:
- Navigate to Administration > Integrations > Repositories.
- Enable the new Management Pack
- Add an account for each Pi-Hole server, including the App Password as a credential in Aria Operations.
Within minutes, you’ll be tracking Pi-Hole performance metrics—like total queries and blocked queries—directly in Aria Operations.
Conclusion: Monitor Pi-Hole Like a Pro
By leveraging the updated Pi-Hole API and Aria Operations MPB 2.0, you can seamlessly integrate Pi-Hole metrics into your monitoring environment. This tutorial demonstrates a simple yet powerful Management Pack, but the possibilities are endless—what other applications would you like to monitor with Aria Operations?
I’d love to hear your thoughts! Drop a comment below with your experiences building Management Packs or any other apps you’d like to integrate with Aria Operations. If you found this guide helpful, share it with your network and stay tuned for more tech tutorials.
