Introduction
Pi-hole is an outstanding way to block advertisements and trackers from your home network. If you are not familiar with Pi-hole, it is an ad blocker that blocks internet advertisements at the DNS level, similar to the way a firewall blocks bad things from getting into your network. The only way to control Pi-Hole from your iPhone is to visit the dashboard in the browser.
Sometimes in order to debug issues on your home network, you need to disable your Pi-hole from filtering advertisements for a short period of time. Customarily, in order to temporarily disable filtering, you need to login to your Pi-hole dashboard and select disable. Then, when you are ready to re-enable ad blocking, you need to log back into the Pi-hole dashboard and click enable. Logging into Pi-hole on a computer can be time consuming and inconvenient. Wouldn’t it be awesome if you could control Pi-hole from your iPhone?
That’s where the Shortcuts app on iOS can be helpful. This tutorial assumes you already have Pi-hole Installed. If not, you can visit my post about running Pi-hole on Docker. This tutorial also assumes that you have downloaded the iOS Shortcuts app (app store link).
Preparing the Shortcuts App
You will be downloading this shortcut file from the internet. Because of that, your iPhone will consider it an “Untrusted Shortcut“. In order to be able to integrate this shortcut, you will have to go to your iPhone Settings and click on Shortcuts. Once you see this screen you need to toggle the “Allow Untrusted Shortcuts” slider as seen in the image below. You may need to open the Shortcuts app and run a random shortcut once before it will allow you to toggle the slider.
Once you are able to successfully toggle the slider, you will be presented with the below warning.
After clicking allow, you will be able to download the shortcut.
Download the Shortcut
The iOS Shortcuts app is finally gaining some traction and there are some really interesting Shortcuts that are starting to appear. Because of this traction, websites that allow developers to post their homemade iOS shortcuts are starting to grow in popularity. This particular shortcut was submitted to RoutineHub.
To download to the shortcut you need to add to your iOS device, click this link from your iPhone or iPad. The link will take you directly to the shortcut page.
When you click the link from your iOS device, it will open up the shortcut details to show you the various steps the device will take throughout the routine. Scroll down to the bottom of the routine and you will be presented with the following dialog:
Click “Add Untrusted Shortcut” to add the Shortcut to your Shortcuts app.
Connect the Shortcut to Pi-Hole
After you click “Add Untrusted Shortcut” this icon will appear inside the dashboard of your Shortcuts application. Now it is time to connect it your local Pi-Hole installation. In order to do that, the routine must be edited.
Click the three dots in the top right-hand corner of the icon to open the routine. When the routine opens, scroll down to the “Dictionary” section. It should look like this:
You will see two fields that need to be updated. The first field is called “Pi-Hole Server“. Type in the URL or DNS name that you use to access your Pi-hole.
Finding your Pi-hole API Key
Next, you need to add your Pi-hole API key into the routine in order for it to be able to properly control Pi-hole. The easiest way to obtain your API key, in this case, is to log in to your Pi-hole Dashboard from your phone. Once Pi-hole gives you your API key, you’ll be able to copy it and paste it directly into the routine, rather than type it manually after obtaining it from a desktop browser.
To obtain your API key login to your Pi-hole dashboard from your iOS device. Click the three menu lines in the top left-hand corner of the screen and when the menu pops up, click on settings. Once the settings screen pops up, click on the tab labeled API / Web interface. When the tab opens click on the “Show API token” button. You will be greeted with a dialog box asking you to confirm that you want to show your API key. Click the button labeled “Yes, show API token“
After you click the button, a new tab will pop up that shows a large QR code. Under the QR code, you will see a long string of characters after the term “Raw API Token:“. Copy that entire string of characters. When it is copied, you can return to the Shortcuts app and paste the key into the API Key field under the dictionary section of the routine.
When you have both the Pi-hole Server and API Key fields completed, you can click Done at the top right-hand corner of the screen to save your settings.
Shortcut Usage
Now that you have connected the Shortcut to your Pi-hole server, it’s time to test it out! When you click the icon to activate the shortcut you’ll be presented with a fancy dialog box that shows your Pi-hole statistics.
After you finish reading your statistics, you are presented with a simple question, “Would you like to disable Pi-hole?”. If you click on Cancel you will return to your home screen, but if you click OK, you will be presented with a dialog box that allows you to enter how long, in minutes, that you would like to disable your Pi-hole.
When you click OK, your Pi-hole will be disabled. If you click the shortcut icon when the Pi-hole is disabled, you will be asked if you would like to enable your Pi-hole. Once you click OK, Pi-hole will be enabled and will start filtering advertisements.
Adding the Shortcut to your Home Screen
To make running this shortcut even more convenient you can actually add the shortcut icon as an icon on your iPhone or iPad home screen. After opening the Shortcuts app, click on the three dots to open the routine. Once the routine is open, you will see the share icon along the bottom of the screen. The icon looks like the icon in the image on the right. Once you click this icon the share menu will pop up. Scrolling down, you will see an option to “Add to Home Screen“. Clicking on that option will bring up a preview of the icon as it will appear on your home screen. Clicking Add at the top right-hand corner will place the icon on your desktop as seen below.
Success!
Thanks to the iOS Shortcuts app, you will now be able to quickly control Pi-hole from your iPhone. I’m looking forward to finding more useful shortcuts to experiment with in the future.
If you have any questions or suggestions, please leave them in the comments below.