Add network troubleshooting guide #16
Conversation
eloquence
force-pushed
the
network-troubleshooting
branch
from
30f27c9 to
0ebb6b6
Compare
There was a problem hiding this comment.
Great guide! Left some comments throughout, mostly with subjective impressions, with a few suggested edits for clarity. Setting review as a "comment" so as not to block merge, since several of the recommendations may not require an edit. Happy to take another look, just ping for re-review, @eloquence !
| 1. Click the "Q" icon in the in the system tray (top right area). | ||
| 2. A list of running VMs should appear. Select ``sys-net`` from the list, and | ||
| click **Run Terminal**. | ||
| 3. In the terminal window, type the command ``ping google.com``. |
There was a problem hiding this comment.
Consider using -c 5 in the command to save the trouble of explaining ctrl+c to stop the forever-ping command.
| @@ -2,3 +2,218 @@ Troubleshooting network issues | |||
| ============================== | |||
There was a problem hiding this comment.
The document is titled "Troubleshooting network issues", but really it strikes me as a "Troubleshooting connection issues" guide, given that step 1 is debugging network, and step 2 is debugging client-login. Sounds like splitting hairs, but on a full read-through, when I reached the end of "Step 1: Verify you are connected to the internet," it felt like I was done "Troubleshooting network issues", when of course there are additional steps that will almost certainly be relevant to Admins.
There was a problem hiding this comment.
I agree, "connection issues" is friendlier and encompasses more, will use that.
| Not all VMs in Qubes OS have Internet access. For example, opening the Qubes | ||
| menu (top left) and clicking **Terminal Emulator** opens a ``dom0`` terminal | ||
| without Internet access. See our :ref:`networking architecture <Networking Architecture>` | ||
| overview for additional background. |
There was a problem hiding this comment.
The "important" box is great info, feels a bit too late here, since I've already finished debugging. Consider moving between paragraphs beginning:
- "Common causes for lost connections" and
- "If the network manager shows"
Placed there, it's a helpful primer for why I'm using sys-net specifically to debug.
| .. important:: | ||
|
|
||
| After a failed login, wait for a new two-factor code from your app before | ||
| trying again. |
| You can reveal the passphrase by clicking the "eye" icon next to it in the login | ||
| dialog (ensure you are in a fully private setting before doing so). Check for | ||
| extra characters at the beginning at the end, or subtle differences like | ||
| capitalization. |
There was a problem hiding this comment.
Consider "like capitalization or whitespace". Given that we've been automatically generated diceware passphrases for SD accounts for some time now, perhaps mentioning whitespace is too confusing.
There was a problem hiding this comment.
Added "Note that the spaces between words in SecureDrop passphrases are part of the passphrase" to make it super explicit.
| If you have narrowed down the problem to ``sd-whonix``, try restarting Tor. | ||
|
|
||
| To do so, right-click the Tor icons in the top right corner of your Qubes | ||
| desktop. They look like this: |
There was a problem hiding this comment.
It'd be a shame not to reference the GUI icons, but given that we were using the terminal in sd-whonix in Step 4, it might simpler for an Admin to run sudo systemctl restart tor. We can take a closer look once the screenshots are proposed, but on my system, the sd-whonix / sys-whonix combination makes for a very confusing tooltray experience. If I were following the instructions, I might end up bouncing tor in sys-whonix rather than sd-whonix without realizing it.
There was a problem hiding this comment.
You're right, it's a massive simplification in this context to just do it on the terminal. If Tor issues are frequent it'd be great to be able to teach journalists how to use the widget, but given the current UX issues with it, we may just want to steer clear for now, also pending a final decision whether we'll continue to use Whonix.
Cross-ref:
- icon glitchiness: Whonix system tray icon breaks when right-clicking it QubesOS/qubes-issues#5704 - there's a PR for it so hopefully will be resolved soon
- widget redesign proposal: https://phabricator.whonix.org/T963
| 4. Right-click ``sd-proxy`` in the list of VMs. Click **Shutdown qube**. | ||
| 5. Right-click ``sd-whonix`` in the list of VMs. Click **Shutdown qube**. | ||
| 6. Right-click ``sd-proxy`` in the list of VMs. Click **Start/Resume qube**. | ||
| The ``sd-whonix`` VM should start automatically. |
| By design, the Qubes OS host domain, ``dom0``, also does not have Internet | ||
| access. | ||
|
|
||
| .. note: |
There was a problem hiding this comment.
s/:/::/, doesn't display as written
| connect to the network, which is provided via ``sys-net``. All four VMs must be | ||
| running for the client to successfully connect to the server. | ||
|
|
||
| .. important: |
There was a problem hiding this comment.
As above, s/:/::/, doesn't display as written
|
|
||
| Like all networked VMs, ``sd-whonix`` uses the ``sys-firewall`` service to | ||
| connect to the network, which is provided via ``sys-net``. All four VMs must be | ||
| running for the client to successfully connect to the server. |
There was a problem hiding this comment.
Nit: s/client/Client/ for consistency with the rest of the doc.
There was a problem hiding this comment.
changed to SecureDrop Client (client is IMO correct but I don't think we should ever use it as a technical term, only as an application name we can change globally)
| 1. Click the "Q" icon in the in the system tray (top right area). | ||
| 2. A list of running VMs should appear. Select ``sys-net`` from the list, and | ||
| click **Run Terminal**. | ||
| 3. In the terminal window, type the command ``ping google.com``. |
There was a problem hiding this comment.
Maybe ping 8.8.8.8 to avoid DNS gotchas? 🤔
There was a problem hiding this comment.
I think that's a great additional step we can suggest here, will add.
|
|
||
| You can reveal the passphrase by clicking the "eye" icon next to it in the login | ||
| dialog (ensure you are in a fully private setting before doing so). Check for | ||
| extra characters at the beginning at the end, or subtle differences like |
There was a problem hiding this comment.
"at the beginning at the and end"
|
|
||
| Because the SecureDrop Client must connect to the SecureDrop | ||
| *Application Server* in order to send or retrieve messages, documents, and | ||
| replies, it can communicate through Qubes-internal system calls with another |
There was a problem hiding this comment.
Consider:
"...it can communicate through Qubes' internal Remote Procedure Call (RPC) mechanism with another..."
| to only connect to work servers, and a personal VM that always uses Tor. | ||
|
|
||
| In the context of SecureDrop Workstation, these capabilities are used to | ||
| minimize the risk that an adversary who is able to exploit a security |
There was a problem hiding this comment.
nit: "minimize the risk of an adversary who [...]" or "minimize the risk that an adversary who [...] can exfiltrate documents"
There was a problem hiding this comment.
Agreed, that was also very inaccessible writing, let me know what you think of the new wording in 3e082f9
Status
Ready for a first round review.
Description
This adds a step-by-step troubleshooting how-to for resolving network issues with SecureDrop Workstation. It starts with the basics (is the Internet working) and goes all the way to restarting Tor, restarting VMs, etc.
The step-by-step format imposes some constraints, but it seems to me most suitable for this guide. Per this good blog post on documentation best practices (thanks to @ninavizz for the link), I've offloaded explanatory content to a separate chapter about architecture.
Screenshots are deliberately omitted for now so we can take those still a little closer to the release date.