Stubby GUI for macOS

** 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.

StubbyManager.pkg

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.

Stopping Stubby

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

Known Issues

  1. Stubby sometimes gives false alerts that there is a problem with the service when laptops wake from sleep.

  2. 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

    sudo launchctl unload  /Library/LaunchDaemons/org.getdns.stubby.plist

    and relaunch StubbyManager app. (You may have to wait 10 minutes until the existing authorization token has expired).

  3. A standard macOS certificate store is provided in the App directory, so any certificates added locally will not be available to Stubby.

Code

StubbyManager is written in Qt. If you are interested in contributing the code is available here: https://github.com/Sinodun/stubby_manager_gui