Repository: freedomofpress/securedrop

Issue:
iterm2 corrupting QR codes
When you run `./manage.py add_admin` and use Google Authenticator for the two-factor auth, it outputs a QR Code to the terminal for you to scan with your phone's camera. The font rendering in iterm2, a popular terminal emulator on Mac OS X, corrupts the QR Code to the point where it cannot be scanned. The font rendering in Terminal.app, Mac OS X's default Terminal emulator, does not cause this problem.

`add_admin` also outputs the shared secret to enter manually in case the bar code cannot be scanned, but this does create a frustrating bit of friction in the setup process. Until we can figure out why iterm2 corrupts the QR code and develop a fix or workaround, it would be best to recommend people use Terminal.app when running `add_admin` to avoid this problem.

![QR Code rendering in Terminal.app](https://cloud.githubusercontent.com/assets/407302/4603992/c3f73a38-5181-11e4-9fe2-ae11e8802c95.png)

![QR Code rendering in iterm2](https://cloud.githubusercontent.com/assets/407302/4603994/e482aaa8-5181-11e4-9143-3f2f2c527ccf.png)

iterm2 corrupting QR codes
When you run `./manage.py add_admin` and use Google Authenticator for the two-factor auth, it outputs a QR Code to the terminal for you to scan with your phone's camera. The font rendering in iterm2, a popular terminal emulator on Mac OS X, corrupts the QR Code to the point where it cannot be scanned. The font rendering in Terminal.app, Mac OS X's default Terminal emulator, does not cause this problem.

`add_admin` also outputs the shared secret to enter manually in case the bar code cannot be scanned, but this does create a frustrating bit of friction in the setup process. Until we can figure out why iterm2 corrupts the QR code and develop a fix or workaround, it would be best to recommend people use Terminal.app when running `add_admin` to avoid this problem.

![QR Code rendering in Terminal.app](https://cloud.githubusercontent.com/assets/407302/4603992/c3f73a38-5181-11e4-9fe2-ae11e8802c95.png)

![QR Code rendering in iterm2](https://cloud.githubusercontent.com/assets/407302/4603994/e482aaa8-5181-11e4-9143-3f2f2c527ccf.png)



Discussion:
We could add a sentence above the QR code that warns the user and suggests using Terminal.app instead, but I wonder if it's possible to switch terminals at that point in the process. Thoughts?

It's not possible to switch Terminals at that point in the process. This is only a problem in iterm2, I have tested Terminal.app and various Linux terminals on Ubuntu, Debian, and Tails without encountering this issue. The docs should simply point out that if you cannot scan the QR code, you can enter the shared secret (printed below the code) manually, which is already documented.

This is an issue with fonts: iTerm2's default non-ASCII font is 12pt Monaco, which doesn't properly handle the QR characters.  Switching the iTerm's non-ASCII font to Menlo, (which is what Terminal uses,) fixes the issue.  This can be done at any time, and fixes an already-printed QR.

So, the question is, where should we document that: in the docs, or on the CLI?

my preference is for a tip to show up under the QR code when it appears

The font in iTerm can be changed in Preferences > Profiles > Text > Non-ASCII Font.

iTerm with default Monaco font:

![screen shot 2014-11-08 at 2 49 53 pm](https://cloud.githubusercontent.com/assets/368416/4965849/e1717668-6799-11e4-8d45-49a9ea4ac6a7.png)

iTerm with Menlo:

![screen shot 2014-11-08 at 2 50 13 pm](https://cloud.githubusercontent.com/assets/368416/4965851/f0850340-6799-11e4-91ac-d4b1a731551a.png)

The QR in iTerm configured with Menlo is confirmed as readable.

We could add a sentence above the QR code that warns the user and suggests using Terminal.app instead, but I wonder if it's possible to switch terminals at that point in the process. Thoughts?

It's not possible to switch Terminals at that point in the process. This is only a problem in iterm2, I have tested Terminal.app and various Linux terminals on Ubuntu, Debian, and Tails without encountering this issue. The docs should simply point out that if you cannot scan the QR code, you can enter the shared secret (printed below the code) manually, which is already documented.

This is an issue with fonts: iTerm2's default non-ASCII font is 12pt Monaco, which doesn't properly handle the QR characters.  Switching the iTerm's non-ASCII font to Menlo, (which is what Terminal uses,) fixes the issue.  This can be done at any time, and fixes an already-printed QR.

So, the question is, where should we document that: in the docs, or on the CLI?

my preference is for a tip to show up under the QR code when it appears

The font in iTerm can be changed in Preferences > Profiles > Text > Non-ASCII Font.

iTerm with default Monaco font:

![screen shot 2014-11-08 at 2 49 53 pm](https://cloud.githubusercontent.com/assets/368416/4965849/e1717668-6799-11e4-8d45-49a9ea4ac6a7.png)

iTerm with Menlo:

![screen shot 2014-11-08 at 2 50 13 pm](https://cloud.githubusercontent.com/assets/368416/4965851/f0850340-6799-11e4-91ac-d4b1a731551a.png)

The QR in iTerm configured with Menlo is confirmed as readable.


Resolving patch:
diff --git a/securedrop/manage.py b/securedrop/manage.py
--- a/securedrop/manage.py
+++ b/securedrop/manage.py
@@ -173,7 +173,10 @@ def add_admin():
             qr.add_data(uri)
             qr.print_ascii(tty=sys.stdout.isatty())
             print
+            print "If the barcode does not render correctly, try changing your terminal's font, (Monospace for Linux, Menlo for OS X)."
+            print
             print "Can't scan the barcode? Enter the shared secret manually: {}".format(admin.formatted_otp_secret)
+            print
 
 
 def clean_tmp():


Test patch: