[graphical gui] Whonix Setup Wizard / Anon Connection Wizard - Technical Discussion


TPO is working on a new Tor Browser Launcher with improved usability.




Minor nitpick: Could you please add a single space before comments? I.e. please not:

some-command#comment here

i.e. please use:

some-command # comment here


I think this is standard almost everywhere. Please correct me should I be wrong on anything.


Could you please port it to python3(.4)?

(highest Debian stretch python version available from packages.debian.org through apt-get)

(Optional: by looking at whonix-setup-wizard git commit history you could get many if not all pointers on what needs changed to make it work with python3.)

I don’t think I reviewed anon-connection-wizard before because it was never deployed. Going thorough the historic script as as well as your changes at once. Some comments are about old issues, where fixes would be appreciated anyhow.

proxy_password = ‘’#Q: Do we need special care for password? Like encryption? A: No. At least tor_launcher does not do that.


(This was probably not a bug introduced by you.)

        f = open('/var/cache/whonix-setup-wizard/status-files/whonix_connection.done', 'w')
        shutil.copy('/etc/tor/torrc', '/etc/tor/torrc.orig')

Please move the shutil.copy on top to make sure it really happens. (Race conditions, other corner cases.)


Typos. (Probably not be introduced by you.)

(Btw if not too much effort, please enable a spell checker in your editor.)

(I was wondering to fix some of these small nitpicks myself, however I abstained from it to not have your bigger more important changes merge conflict with mine.)

Please set your editor to remove trailing spaces.

        self.bridges = ['obfs4 (recommended)',
                        The following will be uncommented as soon as being implemented.
                        Detail: https://github.com/Whonix/anon-connection-wizard/pull/2

The closing bracket intent looks wrong.

            # Notice that the scramblesuit is even not supproted in offcial 6.5.1 TBB
            # Is this option still useful or safe?
            # No. Do not use it anymore.

Agreed. If a pluggable support was deprecated from TBB, we should not provide that option in anon-connection-wizard. (Well, unless a strong argument was made.)

Whonix Connection Wizard

Please strip out Whonix there so this can be a general purpose package, which is not really tied to Whonix.

shutil.copy('/etc/tor/torrc.orig', '/etc/tor/torrc')

Legacy. This is not so great. A very rudimentary implementation.

That way the user cannot add any custom customizations since these would be overwritten.

On the topic of configuration file edits, could you read please https://www.whonix.org/wiki/Dev/Tor and tell me what you think about that?

Until https://trac.torproject.org/projects/tor/ticket/1922 is implemented - which is likely not very soon - which is likely after anon-connection-wizard is finished… What do you think, should anon-connection-wizard edit /etc/tor/torrc using the ### BEGIN anon-connection-wizard ### / ### END anon-connection-wizard ### approach? Let’s call that the edit marker approach or can you think of a better term for this?

Another approach would be:

  • write the output of anon-connection-wizard to a file in /var/cache/anon-connection-wizard/output.conf (check if okay with FHS)
  • append /var/cache/anon-connection-wizard/output.conf to /usr/share/tor/tor-service-defaults-torrc (still use markers, but not for the user to add customizations, but to mark changes from anon-connection-wizard)
  • when the anon-gw-anonymizer-config package is upgraded, /usr/share/tor/tor-service-defaults-torrc would be overwritten
  • we’d to make sure using Debian maintainer scripts (or even Debian triggers if required) to re-append /var/cache/anon-connection-wizard/output.conf before Tor gets reload (so settings are not lost on upgrades)
  • That way we would not have to edit /etc/tor/torrc.

What do you think?

                        # Q: Why there is no those lines in torrc after using Torlauncher to configure that?
                        # Do we really need these?
                        # If so, can we just input them as default and mange them only use UseBridges 0/1 to control it?

Please see:

                    # TODO: Both proxy_ip and proxy_port are not implemented yet.
                    # Done.

In that case, please remove the comment. :slight_smile:

print 'ERROR: This must be run as root!\nUse "kdesudo".'# Q: But why?

Because of unix file permissions. torrc and status files are not owned by user user. However, gui applications have to be run as a user using kdesudo or gksudo. To simplify this we could provide a shell wrapper that automates prepending the kdesudo. Also on the gateway we can have anon-connection-wizard start passwordless as sudo using sudoers. (Which is one of the simplest parts, please ask me if you don’t know how to do that so I can save you the time from figuring that out.)


Hey Patrick!
I really appreciate your detailed feedback on my code!
Just let you know I have been working on the problems you mentioned. A detailed progress report will be provided soon!


Hi @Patrick! Again, thank you very much for your feedback! Because of your feedback, I realized a large number of mistakes I made without even knowing anout before! I did benefit a lot from it. The followings are my reply.

Done! I have learned more about programming style from PEP8.

Done. I have ported it to python3.4. However, some python3 dependencies and modules are not available in current Whonix Stable Repository, including python3-yaml, guimessage etc.

Btw, I tried to upgrade Whonix Stable Repository to Whonix Developer Repository in Whonix-gateway several times using GUI application Whonix Repository. But it kind of broking the VM: Tor control port unavailable, apt-get broken etc.
Could you please tell me what I have done wrong?

I have port it from PyQt4 to PyQt5, which took me an unexpected long time. This is because the way to use signal-and-slot in PyQt4 is no longer supported in PyQt5.

Done. But I still do not understand the point. Could you please explain more about the problem? Or could you please recommend me some resources that I can learn it myself? Thank you very much!

Done! Thank you for your suggestions!

I have change the “Whonix” to “anon”. But it seems “anon” is still a Whonix-related name, isn’t it?

Start to work on the rest of the problems! I will reply to them as soon as possible!

My pull request is as follows:

Main changes:

  • Port from Python2 to Python3.4
  • Port from PyQt4 to PyQt5

Minor changes:

  • Eliminate race conditions
  • Custom bridges allows multiple input
  • Change "Whonix" to "anon" in name
  • Programming style changed according to PEP8
  • Delete trailing spaces
  • Typo correction


Since I am a new forum user who is not allowed to reply more than three times in a same topic, I have to edit my previous replies to say more.
@Patrick just in case you can not receive new edit notification.

I agree with you. anon-connection-wizard should read the previous bridge/proxy configuration from the file and adjust the default UI accordingly. Just like what Tor Launcher has been doing.


According to the current knowledge I have, I strongly prefer the “edit marker approach” to the “output.conf approach”.


Let’s compare the “edit marker approach” and the “output.conf approach” in three different aspects:

####“output.conf approach”

Hiding the /var/cache/anon-connection-wizard/output.conf file from users will force users to do the proxy/bridges setting through anon-connection-wizard, which will cause some potential problems.

For example, a user used anon-connection-wizard to configured the bridge and proxy setting for at least once. Later, for some reasons (like the guidance of an online docs/tutorial, the attraction of exploring) he/she decided to configure the bridge and proxy setting from /etc/tor/torrc file manually. However, his/her setting might have a conflict between the old one appended in the /usr/share/tor/tor-service-defaults-torrc . Maybe the old bridge and proxy setting were not valid anymore, causing the Tor unable to connect successfully. However, there was no simply way that he/she could know the reason, because he/she see no error in /etc/tor/torrc setting.

What he/she can do is either starting anon-connection-wizard to configure nothing to remove the old setting, or removing the old bridge/proxy settings from both /var/cache/anon-connection-wizard/output.conf and
/usr/share/tor/tor-service-defaults-torrc. Either way will greatly reduce the usability because it requires users to ask or search for the solution and then a lot of work.

####"edit marker approach"
In this case, when users want to edit bridge/proxy setting manually from /etc/tor/torrc, they will see the setting generated by anon-connection-wizard and realize they may need to delete them.

To make it even more user-friendly, we can comment things like below in the ‘/etc/tor/torrc’:
### BEGIN anon-connection-wizard ###
### You may need to remove the following block to let your manually configured proxy/bridges setting work

###The purposes of the files:
According to the wiki:

/etc/tor/torrc is designed as a Tor configuration file that may be used by user.

/usr/share/tor/tor-service-defaults-torrc is designed as a Tor configuration file that should be only used by Whonix and should not be used by users.

The proxy/bridge settings is generated by users with the help of anon-connection-wizard, so the settings are considered as users’ configuration that naturally go to /etc/tor/torrc instead of

###Implementation and Maintenance cost:
The “output.conf approach” will create an extra file /var/cache/anon-connection-wizard/output.conf for the Tor configuration, making the Tor configuration in Whonix more separated/scattered.

The “output.conf approach” will also introduce a large amount of unnecessary work which includes:


Oh, I wasn’t aware of these forum restrictions. Just now upgraded your account. (Multi posting is very much fine since it’s very constructive and no “help!”, “help me faster” ;).)

We’ll include anon-connection-wizard on stretch based Whonix, i.e. the next release, Whonix 14. Then these dependencies will be available. (There won’t be any more major Whonix upgrades for jessie based Whonix 13.)

You might have more luck using these instructions:

(I’ll stress luck. I’ll leave a notification in the forums when I want to encourage developers or testers to upgrade when I made sure it’s working out of the box.)

Resources, well not so much directly. Perhaps TOCTU (time of check time of use) and perhaps “atomic commit” applies. (Enough to understand roughly what these concepts are about.)

In theoretic terms: do an action first, then create a status file that it’s done.

In case of sh.copy, first the status file was created and the action after that. In case

  • the VM crashes (power loss) (not very likely, but with thousands of users at some point it may happen to someone and since it’s easily avoidable to run into such a corner case why not)
  • or in case the action fails for whatever reasons (perhaps hdd hardware failure, code issues, whatnot)

then we’re better off not having the status file created since the action did not happen. By that we avoid inconsistent states, where another run of the program would think “status file exists, that state is already true, not doing again, skipping”, while that is not true.

anon just stands for anonymity or anonymous whatever sounds better in that case. Components developed under the Whonix umbrella with that name are easily reused by other anonymity related projects or other custom builds.

I’ll agree with “edit marker approach” being better. Will be looking into your pull request early next week.


Thank you very much for your help, Patrick!

Sounds great! Looking forward to the mature upgrade.

Thank you! I found your explanation very clear. And I am still going to search and learn more from the resources you recommended.

I am going to implement that soon.

Thank you very much, Patrick!


TODO List:

  • edit mark approach

###start page:

  • if customized file exists, a warning will appear when users choose to connect to the Tor network directly
  • a kind reminder may be added, saying that “if you are using a VPN to circumvent the Tor censorship, you can click the connect button without further configuration.”

###censorship circumvention options page:

  • research if the three options make the instructions more clear or more confusing
  • research if the first bridge button page should be called a “censorship circumvention options” page and adjust the options accordingly
  • Is a FascistFirewall option commonly used by users? if so, maybe we can support it in censorship circumvention tools option page. For example, an option saying “My ISP only allows 80 and 443 port”.

###bridge page:

  • make customized bridge input supports syntax highlighting

###proxy page:

  • sock4 should disable username and password textboxes
  • username and password can be hide with a “advanced button”
  • add a help button to make it more friendly to first time users
  • if the proxy_type is “-” then a warning will appear (like what Tor Launcher has been doing), however, not sure if we really need a proxy_type as “-”.
  • add clear instructions for the proxy settings


  • custom CSS

  • Does the current GUI need changing entirely? If so, a Qt designer may be used for efficiency. If only small change on GUI, change it manually should be fine. If other application, like whonix-setup-wizard and welcome-application used by Tails are also using Qt designer, a UI file generated by Qt designer may help the future integration.

###setting confirmation page:

  • add a setting confirmation page before going to the tor_status page


Hi @Patrick! My current TODO list for the anon-connection-wizard is above. Please let me know if you have any feedback, new idea or answers to some mentioned questions.

Apart from the questions above, the following is a general development question. I can make a separate topic if it is the preferred:

  1. Two of my recent commits are shown “unverified” by Github because “The email in this signature doesn’t match the committer email”. However, the signatures themselves are good. In such a case, can a future “verified” commit be interpreted as “I have audited the previous code and newly-added code”? Or can it only be interpreted as “I am only responsible for what I commit this time”?

Thank you very much for your time! :slight_smile:


CSS? You lost me at hello.[quote=“iry, post:229, topic:650”]
Qt designer may be used for efficiency


You tell me.

That could worsen usability.

Not that I know.

https://www.whonix.org/wiki/Censorship_Circumvention_Tools here? Why not. Doesn’t hurt. It’s mentioned here https://www.whonix.org/wiki/Bridges#Better_Connectivity_Without_Real_Censorship_Circumvention



The following is a brief instruction on how to set up a anon-connection-wizard testing environment on Whonix13:

  1. create a new whonix-gateway vm
  2. install dependecies:
    sudo apt-get install python3-yaml
    sudo apt-get install python3-pyqt5
    sudo apt-get install python3-stem
  3. copy guimessage module, anon-connection-wiazard.py and tor_status.py to /usr/lib/python3/dist-packages/

Open question: What is the best way to develop applications used in Whonix-gateway? Currently, I have been developing anon-connection-wizard in Whonix-workstation and only copy it to a whonix-gateway for testing. I am not sure if this is the best way to do things in terms of developing anonymously or/and efficiently.


I think you could as well as develop it in Whonix-Gateway. I don’t see any risks since it’s not a network using application.

And you have to test anon-connection-wizard anyhow. Lots of Tor restarts. Lots of different pluggable transports being tested. These lots of Tor restarts and using various transports may not look great from a perspective of an ISP level observer. Perhaps once all dependencies are installed in the gateway, take remove the virtual network cable so you can always have anon-connection-wizard restart Tor without worrying?

But you still need to git push your changes. I’d say host the master git folder copy on the gateway. Then copy it over to an online workstation (using a script) to for git pushing. Most comfortable using Qubes-Whonix. There are of course many ways to do this. Whatever is most comfortable. Does that help?


I have not tired it yet so I may be wrong. It seems that PyQt accepts customized style-sheets. If none of the available styles is good enough, maybe we can design it ourselves.

    # Available styles: "windows", "motif", "cde", "sgi", "plastique" and "cleanlooks"
    # TODO: use customized css instead. Take Tor Launcher's css as a reference


I see. But do you think we need to let users who are using VPN know they do not need to do a further configuration somehow?[quote=“Patrick, post:231, topic:650”]
You tell me.

No problem! I will try my best to figure that out.

I am sorry for my confusing expression. By say “censorship circumvention tools option page”, I meant a wizard page in anon-connection-wizard. However, I can also add a instruction to the wiki page :slight_smile:

That is true. I will take care of that.[quote=“Patrick, post:233, topic:650”]
Does that help?

Yes! Your advice is very helpful to me! Thank you very much, Patrick!


Done. I also added a lantern section to the Table on that page. Not sure if the edit is lost.


Perhaps worth mentioning on any or all of these pages?

The name Bridges might also not be a great page name? Which user would put “Bridges” into a search engine? Perhaps a user who knows what Whonix is, and what bridges are, who wants to lookup Whonix instructions for Tor bridges. It should be more focused on what the user wants. That’s a better point of view.

The not so great point of view might have been mine. “Let’s explain how this technical thingy (bridges) can be used with Whonix.”

From the users point of view, who is looking for censorship circumvention, theoretically it might make sense to mention https://www.whonix.org/wiki/Tunnels/Introduction. In practice, I would avoid mentioning https://www.whonix.org/wiki/Tunnels/Introduction since it’s far too complicated.

Also if I remember right, many users not able to visit a website, starting Tor, often don’t even equate that with “oh, my ISP is blocking Tor, I need censorship circumvention”. The terms censorship and censorship circumvention might not even be in their mind.

//cc @torjunkie

Well, from what I learned from usability research, less is more. Any new sentence / more content probably adds confusion. Therefore perhaps best to go conservative, use suggestions from UX papers or UX testing.


Small nitpick change, using internal rather than external links. (Don’t worry about such small issues.)



Thank you so much for your tip, Patrick! One advantage of using internal links is that when users are browsing from .onion wiki, they do not have to jump out to clearnet.


I agree with you. The case you mentioned happens a lot. People are often not aware of the censorship when the environment is “so free” or too unfree.

No problem! I will make the anon-connection-wizard based on the UX paper and try to ask the UX teams opinions on how to provide the support of third-party censorship circumvention tools in the wizard.

I have tried to contact the UX team through the ticket. But I have not gotten response. Do you have any suggested place I can jump to? Maybe tbb-dev@ ? I have tried to mention the issue on several places, so do you think it will be rude to mention it again, Patrick?