** THIS PROJECT IS NO LONGER MAINTAINED. WORK ON A NEWER STUBBY MANAGER GUI IS IN PROGRESS, SEE Stubby Manager GUI **
An installer package for an alpha release of the StubbyManager GUI App is now available:
This is the 0.2.6 of the prototype Stubby GUI. It is still very much a work in progress and has only very basic functionality! It is being released at this stage to gain feedback and review from users. We welcome early testing of this application.
SHA256 Checksum: 0b9de130ac55e02928a21f334ac5c481b092e6535445a402caa7bb165b0b3dba
This will overwrite any existing installation so if you have customised your Stubby configuration (either using the 'Advanced' button or by directly editing the stubby.yml file then make a backup before installing!
This version is built with
getdns version: 1.5.2
openssl version: 1.1.1b
stubby version: 0.2.6
It has only been tested on Sierra and High Sierra.
Using the GUI
When the App is first opened for the very first time, Stubby is not running at this point. It is helpful at this point to monitor the logs while first setting Stubby up - click the View the log... button.
You will be asked at various times to authorise Stubby with your password - this is needed periodically when changing the setup and configuration.
Starting the Stubby service
Use the buttons in the top section of the dialog to:
- Start the Stubby service. At this point the service is running but the system is not sending queries to Stubby.
- Test the service. This performs a single query to the Stubby service to make sure it is working. If this works then move on to the next step
Using Stubby for DNS queries
Check the box that says Use Stubby DNS and then click Apply. From this point the system will be using Stubby for all DNS queries, you should start seeing connections opening and closing in the log window as Stubby uses the default servers.
With the default configuration (Strict mode) you will see the Stubby Icon in the menu bar change from greyed out to active when you make this change. It therefore indicates that all DNS queries are encrypted. If the configuration is changed to Opportunistic (see below) the icon remains greyed out since some or all queries could be sent in clear text. This will be improved in the next release to better indicate Strict vs Opportunistic mode. Currently the icon is only visible when the App is running (again, to be fixed). Note that Stubby continues to run whilst the App is closed.
Stop stop using Stubby, simply click on the Stop button at the top of the dialog. This stops the stubby service and returns the DNS settings to their defaults.
You can also restart the service using the Restart button if the logs indicate there is some sort of problem.
Editing the configuration
Users may want to modify the settings by changing the servers or switching to Opportunistic mode (Strict is the default). To do this click the Advanced... button. This is currently just a text editor view of the stubby.yml configuration file (this will evolve to be more user friendly in future!). A syntax check is performed on the file before it is saved, a more detailed report of syntax problems is also planned.
For details on the contents of the file see this page Configuring Stubby.
After updating the configuration the changes must be applied by clicking the Apply button!
Revert to default
If you run into problems changing the configuration (for example the window reports the configuration is not valid), Stubby can be reverted to use the default configuration by:
- clicking the Revert to default button
- clicking Apply
In no particular order the following is a list of TODOs
- Add Help file and About details
- Simplified interface with a simple 'on/off' switch.
- Show the menu bar icon all the time. Make sure it indicates the different states: Stubby not running, Stubby using Opportunistic mode, Stubby using Strict mode
- Have a check box on the main panel to switch between Strict and Opportunistic
- Add syntax highlighting to the configuration edit dialog. Longer term use drop downs, checkboxes etc, for the configuration options
- Have a simple way the user can control the logging level (currently requires the user to edit to /Library/LaunchDaemons/org.getdns.stubby.plist file
- Parser for the log file to have simple reporting of connection status (possible inspired by Connection Doctor for Mail)
- Be more aware of network changes
- Report the specific issue if the configuration file cannot be parsed when getdns 1.2.2 is available
- Add standard items to the App menu and Stubby menu bar icon
- Better error reporting and debugging
- Add option to download the latest default configuration file from the github repo
Longer term we plan to port the GUI to Windows and Linux
Stubby sometimes gives false alerts that there is a problem with the service when laptops wake from sleep.
Occasionally Stubby gets confused and cannot start or stop the service. A workaround for this is to close StubbyManger and then run the following from a terminal
and relaunch StubbyManager app. (You may have to wait 10 minutes until the existing authorization token has expired).
- A standard macOS certificate store is provided in the App directory, so any certificates added locally will not be available to Stubby.
StubbyManager is written in Qt. If you are interested in contributing the code is available here: https://github.com/Sinodun/stubby_manager_gui