From 0ebb6b6baf048ff729ef43f60503473531b41041 Mon Sep 17 00:00:00 2001 From: Erik Moeller Date: Thu, 13 Feb 2020 22:55:37 -0800 Subject: [PATCH 1/8] Starting outline --- docs/admin/troubleshooting_network.rst | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/docs/admin/troubleshooting_network.rst b/docs/admin/troubleshooting_network.rst index 3a378bc..cbd9e29 100644 --- a/docs/admin/troubleshooting_network.rst +++ b/docs/admin/troubleshooting_network.rst @@ -2,3 +2,20 @@ Troubleshooting network issues ============================== .. include:: ../includes/top-warning.rst + + +Issues to cover: + +- Use of network manager in Qubes +- Networking architecture of the workstation + + Networkless VMs +- "Can't log in" - excluding other causes + + 2FA errors + + Double-checking passphrase + + Problems with ``sd-proxy`` +- Ensuring all required VMs are running +- Restarting Tor in ``sd-whonix`` via control panel +- Restarting ``sd-proxy`` and ``sd-whonix`` +- Testing network connection without Tor +- Testing network connection in ``sd-whonix`` +- Inspecting logs \ No newline at end of file From 9c6398ee04016a442c620727b9c8f36c64f72ba5 Mon Sep 17 00:00:00 2001 From: Erik Moeller Date: Fri, 14 Feb 2020 18:32:01 -0800 Subject: [PATCH 2/8] Start on intro and architecture overview --- docs/admin/troubleshooting_network.rst | 69 ++++++++++++++++++++++++++ 1 file changed, 69 insertions(+) diff --git a/docs/admin/troubleshooting_network.rst b/docs/admin/troubleshooting_network.rst index cbd9e29..a89d6d8 100644 --- a/docs/admin/troubleshooting_network.rst +++ b/docs/admin/troubleshooting_network.rst @@ -4,6 +4,75 @@ Troubleshooting network issues .. include:: ../includes/top-warning.rst +Verifying connectivity +---------------------- + +You can use both wireless and wired networks in Qubes, although we recommend using +a wired connection whenever possible. You can manage network access through the +network manager, which you can find in the area populated with icons in the top +right corner of your Qubes desktop. + +The network manager looks like this for a wired connection: + +[insert network manager wired icon] + +And it looks like this for a wireless connection: + +[insert network manager wired icon] + +.. note:: + If Qubes is able to connect to both a wired and a wireless network, the wired + connection will take precedence, and the network manager icon for a wired + connection will be shown. However, Qubes may still maintain a wireless + connection in parallel, and fall back to it if the wired connection is lost. + +When a network connection is lost, Qubes will display an alert like the +following: + +[insert lost connection notification] + +Common causes for lost connections include fully or partly unplugged network cables, +lost power to networking equipment, and ISP service outages. What's specific +to Qubes and SecureDrop Workstation is how access to the network is managed +across different VMs, and how the Tor network is used. + +To effectively troubleshoot these system-specific issues, it is necessary to +understand the SecureDrop Workstation networking architecture at a high level. + + +SecureDrop Workstation networking architecture +---------------------------------------------- +One key security feature of Qubes OS is that it enables users to configure the +appropriate level of network access for each VM. For example, you could have a +VM for password storage that has no network access, a work VM that is firewalled +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 +vulnerability could exfiltrate documents or private keys. Specifically, the +following VMs have no network access: + +- ``sd-app``, which runs the SecureDrop Client, and holds decrypted messages, + replies, and documents. +- ``sd-viewer``, which is the template used for disposable VMs for opening + documents from the SecureDrop Client. +- ``sd-gpg``, which holds the *Submission Private Key* required to decrypt + messages, replies, and documents. +- ``sd-devices``, which passes exported documents through to USB devices like + printers and encrypted flash drives. + +.. important: + + If you attempt to directly access the network in any of these VMs, it will + not work, and that is the expected behavior. + +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 +VM, ``sd-proxy``. + + + Issues to cover: - Use of network manager in Qubes From deb64bc239725f34df64b06d84cebb8f62b13202 Mon Sep 17 00:00:00 2001 From: Erik Moeller Date: Tue, 18 Feb 2020 23:58:34 -0800 Subject: [PATCH 3/8] Flesh out architecture, start on troubleshooting specifics --- docs/admin/troubleshooting_network.rst | 44 +++++++++++++++++++------- 1 file changed, 33 insertions(+), 11 deletions(-) diff --git a/docs/admin/troubleshooting_network.rst b/docs/admin/troubleshooting_network.rst index a89d6d8..f874496 100644 --- a/docs/admin/troubleshooting_network.rst +++ b/docs/admin/troubleshooting_network.rst @@ -54,7 +54,7 @@ following VMs have no network access: - ``sd-app``, which runs the SecureDrop Client, and holds decrypted messages, replies, and documents. -- ``sd-viewer``, which is the template used for disposable VMs for opening +- ``sd-viewer``, which is the template for disposable VMs used for opening documents from the SecureDrop Client. - ``sd-gpg``, which holds the *Submission Private Key* required to decrypt messages, replies, and documents. @@ -64,24 +64,46 @@ following VMs have no network access: .. important: If you attempt to directly access the network in any of these VMs, it will - not work, and that is the expected behavior. + not work. That is the expected behavior. 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 -VM, ``sd-proxy``. +VM, ``sd-proxy``, which can only access the open Internet through the Tor +network, using the separate ``sd-whonix`` VM. +Qubes OS ships with a Whonix service called ``sys-whonix``. When troubleshooting +network issues specific to SecureDrop, ``sys-whonix`` is only relevant during +updates of the Whonix VMs. +SecureDrop Workstation uses the ``sd-whonix`` service to connect to SecureDrop. +It contains a sensitive authentication token required to access the SecureDrop +API via Tor, and should not be attached to VMs that are unrelated to SecureDrop. -Issues to cover: +Troubleshooting login issues +---------------------------- +If you experience difficulty logging into SecureDrop using the SecureDrop +Client, this may or may not be a network issue. Before taking other steps, +please make sure that your username, passphrase, and two-factor code are correct. + +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. + +Wait for a new two-factor code from your app before trying again. If you access +multiple sites and services using a single two-factor app, make sure that the +correct site or service is selected. + +If you have access to a Tails-based *Journalist Workstation*, verify whether you +can access SecureDrop using the same credentials that do not work in Qubes. + +Troubleshooting network access via ``sd-proxy`` and ``sd-whonix`` +----------------------------------------------------------------- +If you are confident that your login credentials are correct, or you are +experiencing network issues past the login stage, we recommend the following +steps: -- Use of network manager in Qubes -- Networking architecture of the workstation - + Networkless VMs -- "Can't log in" - excluding other causes - + 2FA errors - + Double-checking passphrase - + Problems with ``sd-proxy`` - Ensuring all required VMs are running - Restarting Tor in ``sd-whonix`` via control panel - Restarting ``sd-proxy`` and ``sd-whonix`` From 8f8cbe6b2885f5536d9b7f41b9d30f13901acbf5 Mon Sep 17 00:00:00 2001 From: Erik Moeller Date: Tue, 25 Feb 2020 23:50:32 -0800 Subject: [PATCH 4/8] Expand troubleshooting --- docs/admin/troubleshooting_network.rst | 46 ++++++++++++++++++++++++-- 1 file changed, 44 insertions(+), 2 deletions(-) diff --git a/docs/admin/troubleshooting_network.rst b/docs/admin/troubleshooting_network.rst index f874496..39be085 100644 --- a/docs/admin/troubleshooting_network.rst +++ b/docs/admin/troubleshooting_network.rst @@ -98,13 +98,55 @@ correct site or service is selected. If you have access to a Tails-based *Journalist Workstation*, verify whether you can access SecureDrop using the same credentials that do not work in Qubes. +Ensuring that all required VMs are running +------------------------------------------ +The following VMs must be running for all network-bound operations to be +successfully completed: + +- ``sd-app`` +- ``sd-gpg`` +- ``sd-log`` +- ``sd-proxy`` +- ``sd-whonix`` +- ``sys-firewall`` +- ``sys-net`` +- ``sys-whonix`` + +You can verify whether a VM is running or not by clicking the "Q" icon in the +top right corner of your Qubes desktop. Only VMs that are currently running are +listed: + +[insert Q widget with VM list expanded] + +If a required VM is not running, you can launch it from the Qube Manager. Open +the Qube Manager by clicking **Open Qube Manager** in the menu above. A window +like the following should appear: + +[insert qube manager screenshot] + +To start a VM, select it from the list and press the "play" button in the +toolbar. + +In ordinary operation, VMs should start when they are needed. If you repeatedly +experience problems with a necessary VM not running, or if an error message +is displayed when attempting to start the VM, please contact us for assistance. + Troubleshooting network access via ``sd-proxy`` and ``sd-whonix`` ----------------------------------------------------------------- If you are confident that your login credentials are correct, or you are -experiencing network issues past the login stage, we recommend the following +experiencing network issues past the login stage, we recommend the following steps: -- Ensuring all required VMs are running +Restart ``sd-proxy`` and ``sd-whonix`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Both VMs are required to successfully connect to the SecureDrop servers. You can +restart them from the Qube Manager. It may take a moment for Tor connectivity +to be fully re-established. Tor is ready to use when the icon transitions to +this state: + +[insert sdwdate-gui icon screenshot after time synchronization is complete] + + - Restarting Tor in ``sd-whonix`` via control panel - Restarting ``sd-proxy`` and ``sd-whonix`` - Testing network connection without Tor From ff5273688ddb1a9963be4f204b85615db51d9a4e Mon Sep 17 00:00:00 2001 From: Erik Moeller Date: Thu, 27 Feb 2020 00:01:30 -0800 Subject: [PATCH 5/8] Further flesh out troubleshooting; split out architecture docs --- docs/admin/troubleshooting_network.rst | 167 ++++++++++++------------ docs/admin/workstation_architecture.rst | 52 ++++++++ docs/index.rst | 1 + 3 files changed, 134 insertions(+), 86 deletions(-) create mode 100644 docs/admin/workstation_architecture.rst diff --git a/docs/admin/troubleshooting_network.rst b/docs/admin/troubleshooting_network.rst index 39be085..fa07dff 100644 --- a/docs/admin/troubleshooting_network.rst +++ b/docs/admin/troubleshooting_network.rst @@ -3,24 +3,30 @@ Troubleshooting network issues .. include:: ../includes/top-warning.rst +Before troubleshooting network issues, we recommend reading about the +:ref:`networking architecture ` +of SecureDrop Workstation. If you are in a hurry, this guide offers quick +diagnostic and remedial steps. -Verifying connectivity ----------------------- +Step 1: Verify you are connected to the Internet +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -You can use both wireless and wired networks in Qubes, although we recommend using -a wired connection whenever possible. You can manage network access through the -network manager, which you can find in the area populated with icons in the top -right corner of your Qubes desktop. +You can use both wireless and wired networks in Qubes. You can manage network +access through the network manager, which you can find in the area populated +with icons in the top right corner of your Qubes desktop. The network manager looks like this for a wired connection: -[insert network manager wired icon] +[SCREENSHOT: network manager wired icon] -And it looks like this for a wireless connection: +It looks like this for a wireless connection: -[insert network manager wired icon] +[SCREENSHOT: network manager wired icon] .. note:: + Like most operating systems, Qubes gives you the option to remember any + wireless network you have previously connected to. + If Qubes is able to connect to both a wired and a wireless network, the wired connection will take precedence, and the network manager icon for a wired connection will be shown. However, Qubes may still maintain a wireless @@ -29,79 +35,41 @@ And it looks like this for a wireless connection: When a network connection is lost, Qubes will display an alert like the following: -[insert lost connection notification] +[SCREENSHOT: lost connection notification] Common causes for lost connections include fully or partly unplugged network cables, -lost power to networking equipment, and ISP service outages. What's specific -to Qubes and SecureDrop Workstation is how access to the network is managed -across different VMs, and how the Tor network is used. +lost power to networking equipment, and ISP service outages. When you see a lost +connection notification, it is most likely due to one of these causes. -To effectively troubleshoot these system-specific issues, it is necessary to -understand the SecureDrop Workstation networking architecture at a high level. +If you are experiencing other connectivity issues, move on to the next step. +Step 2: Troubleshooting login issues +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +If the issue occurs on the login screen of the SecureDrop Client (the dialog +with the SecureDrop logo), this may not be a network issue. Make sure that your +username, passphrase, and two-factor code are correct. -SecureDrop Workstation networking architecture ----------------------------------------------- -One key security feature of Qubes OS is that it enables users to configure the -appropriate level of network access for each VM. For example, you could have a -VM for password storage that has no network access, a work VM that is firewalled -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 -vulnerability could exfiltrate documents or private keys. Specifically, the -following VMs have no network access: - -- ``sd-app``, which runs the SecureDrop Client, and holds decrypted messages, - replies, and documents. -- ``sd-viewer``, which is the template for disposable VMs used for opening - documents from the SecureDrop Client. -- ``sd-gpg``, which holds the *Submission Private Key* required to decrypt - messages, replies, and documents. -- ``sd-devices``, which passes exported documents through to USB devices like - printers and encrypted flash drives. - -.. important: - - If you attempt to directly access the network in any of these VMs, it will - not work. That is the expected behavior. - -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 -VM, ``sd-proxy``, which can only access the open Internet through the Tor -network, using the separate ``sd-whonix`` VM. - -Qubes OS ships with a Whonix service called ``sys-whonix``. When troubleshooting -network issues specific to SecureDrop, ``sys-whonix`` is only relevant during -updates of the Whonix VMs. - -SecureDrop Workstation uses the ``sd-whonix`` service to connect to SecureDrop. -It contains a sensitive authentication token required to access the SecureDrop -API via Tor, and should not be attached to VMs that are unrelated to SecureDrop. - -Troubleshooting login issues ----------------------------- -If you experience difficulty logging into SecureDrop using the SecureDrop -Client, this may or may not be a network issue. Before taking other steps, -please make sure that your username, passphrase, and two-factor code are correct. +.. 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. -Wait for a new two-factor code from your app before trying again. If you access -multiple sites and services using a single two-factor app, make sure that the -correct site or service is selected. +If you access multiple sites and services using a single two-factor app, make +sure that the correct user account is selected. If you have access to a Tails-based *Journalist Workstation*, verify whether you can access SecureDrop using the same credentials that do not work in Qubes. -Ensuring that all required VMs are running ------------------------------------------- -The following VMs must be running for all network-bound operations to be -successfully completed: +Step 3: Verify that all required VMs are running +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The following VMs must be running for all actions requiring network connectivity +to work (e.g., logging in, checking for messages, downloading documents, replying +to sources, starring sources, deleting sources): - ``sd-app`` - ``sd-gpg`` @@ -116,13 +84,13 @@ You can verify whether a VM is running or not by clicking the "Q" icon in the top right corner of your Qubes desktop. Only VMs that are currently running are listed: -[insert Q widget with VM list expanded] +[SCREENSHOT: Q widget with VM list expanded] If a required VM is not running, you can launch it from the Qube Manager. Open the Qube Manager by clicking **Open Qube Manager** in the menu above. A window like the following should appear: -[insert qube manager screenshot] +[SCREENSHOT: qube manager screenshot] To start a VM, select it from the list and press the "play" button in the toolbar. @@ -131,24 +99,51 @@ In ordinary operation, VMs should start when they are needed. If you repeatedly experience problems with a necessary VM not running, or if an error message is displayed when attempting to start the VM, please contact us for assistance. -Troubleshooting network access via ``sd-proxy`` and ``sd-whonix`` ------------------------------------------------------------------ -If you are confident that your login credentials are correct, or you are -experiencing network issues past the login stage, we recommend the following -steps: +If this does not resolve the issue, proceed to the next step. + +Step 4: Verify that required VMs have connectivity and examine logs +------------------------------------------------------------------- + +Step 5: Restart Tor +------------------- +If all required VMs are running, you may be experiencing issues with the Tor +network. You can check the Tor status and try restarting Tor. + +To do so, right-click the Tor icons in the top right corner of your Qubes +desktop. They look like this: + +[SCREENSHOT: sdwdate-gui widget] + +One of the two icons should display the option **sd-whonix**. Select that option +from the menu with your mouse, and then click **Tor control panel**: + +[SCREENSHOT: sdwdate-gui widget with Tor control panel option shown] + +You should now see the following dialog: + +[SCREENSHOT: Tor control panel screenshot] + +Click **Restart Tor** in the bottom right of this dialog. You should see a +progress bar which will indicate when Tor is available again. If this does not +resolve the issue, proceed to the next step. + +Step 6: Restart ``sd-proxy`` and ``sd-whonix`` +---------------------------------------------- +The VMs ``sd-whonix`` and ``sd-proxy`` are the two most important VMs for +maintaining the connection between the SecureDrop app and the SecureDrop server. +You can restart VMs using the Qube Manager: -Restart ``sd-proxy`` and ``sd-whonix`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Both VMs are required to successfully connect to the SecureDrop servers. You can -restart them from the Qube Manager. It may take a moment for Tor connectivity -to be fully re-established. Tor is ready to use when the icon transitions to -this state: +[SCREENSHOT: Qube Manager screenshot] -[insert sdwdate-gui icon screenshot after time synchronization is complete] +Select the VM you wish to restart from the list, right-click its entry, and click +**Restart qube**. (You can also click the restart icon in the toolbar instead.) +This will take several seconds, and it will take additional time to re-establish +a Tor connection. +If this does not resolve the issue, proceed to the next step. -- Restarting Tor in ``sd-whonix`` via control panel -- Restarting ``sd-proxy`` and ``sd-whonix`` -- Testing network connection without Tor -- Testing network connection in ``sd-whonix`` -- Inspecting logs \ No newline at end of file +Step 7: Restart ``sys-net`` and ``sys-firewall`` +------------------------------------------------ +Using the same method employed in the previous step, you can restart the two +VMs that are underlying most network operations in Qubes OS, ``sys-net`` and +``sys-firewall``. \ No newline at end of file diff --git a/docs/admin/workstation_architecture.rst b/docs/admin/workstation_architecture.rst new file mode 100644 index 0000000..744173d --- /dev/null +++ b/docs/admin/workstation_architecture.rst @@ -0,0 +1,52 @@ +SecureDrop Workstation Architecture +=================================== + +.. include:: ../includes/top-warning.rst + +.. _Networking Architecture: + +SecureDrop Workstation networking architecture +---------------------------------------------- +One key security feature of Qubes OS is that it enables users to configure the +appropriate level of network access for each VM. For example, you could have a +VM for password storage that has no network access, a work VM that is firewalled +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 +vulnerability in order to exfiltrate documents or private keys. Specifically, +the following VMs have no network access: + +- ``sd-app``, which runs the SecureDrop Client, and holds decrypted messages, + replies, and documents. +- ``sd-viewer``, which is the template for disposable VMs used for opening + documents from the SecureDrop Client. +- ``sd-gpg``, which holds the *Submission Private Key* required to decrypt + messages, replies, and documents. +- ``sd-devices``, which passes exported documents through to USB devices like + printers and encrypted flash drives. + +.. note: + + If you attempt to directly access the network in any of these VMs, it will + not work. That is the expected behavior. + +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 +VM, ``sd-proxy``, which can only access the open Internet through the Tor +network, using the separate ``sd-whonix`` VM. + +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. + +.. important: + + The ``sd-whonix`` VM contains a sensitive authentication token required to + access the SecureDrop API via Tor, and should not be attached to VMs that are + unrelated to SecureDrop. + +Qubes OS ships with a Whonix service called ``sys-whonix``. When troubleshooting +network issues specific to SecureDrop, ``sys-whonix`` is only relevant during +updates of the Whonix VMs (e.g., while the preflight updater is running). \ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst index c3511da..e7e839a 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -33,6 +33,7 @@ submitted documents with a reasonable level of security. admin/troubleshooting_network admin/provisioning_usb admin/known_issues + admin/workstation_architecture * :ref:`genindex` From fa239c03329db9a806388de5ff42492fa267f063 Mon Sep 17 00:00:00 2001 From: Erik Moeller Date: Thu, 27 Feb 2020 17:54:54 -0800 Subject: [PATCH 6/8] Further flesh out and organize troubleshooting guide --- docs/admin/troubleshooting_network.rst | 166 +++++++++++++++++------- docs/admin/workstation_architecture.rst | 3 + 2 files changed, 121 insertions(+), 48 deletions(-) diff --git a/docs/admin/troubleshooting_network.rst b/docs/admin/troubleshooting_network.rst index fa07dff..4390e74 100644 --- a/docs/admin/troubleshooting_network.rst +++ b/docs/admin/troubleshooting_network.rst @@ -13,41 +13,62 @@ Step 1: Verify you are connected to the Internet You can use both wireless and wired networks in Qubes. You can manage network access through the network manager, which you can find in the area populated -with icons in the top right corner of your Qubes desktop. +with icons in the top right corner of your Qubes desktop, known as the *system +tray*. The network manager looks like this for a wired connection: -[SCREENSHOT: network manager wired icon] +**[SCREENSHOT: network manager wired icon]** It looks like this for a wireless connection: -[SCREENSHOT: network manager wired icon] +**[SCREENSHOT: network manager wired icon]** -.. note:: - Like most operating systems, Qubes gives you the option to remember any - wireless network you have previously connected to. +It looks like this when you are not connected to the Internet at all: - If Qubes is able to connect to both a wired and a wireless network, the wired - connection will take precedence, and the network manager icon for a wired - connection will be shown. However, Qubes may still maintain a wireless - connection in parallel, and fall back to it if the wired connection is lost. +**[SCREENSHOT: no connection icon]** When a network connection is lost, Qubes will display an alert like the following: -[SCREENSHOT: lost connection notification] +**[SCREENSHOT: lost connection notification]** Common causes for lost connections include fully or partly unplugged network cables, lost power to networking equipment, and ISP service outages. When you see a lost connection notification, it is most likely due to one of these causes. -If you are experiencing other connectivity issues, move on to the next step. +If the network manager shows that you are connected to the Internet, you can +verify whether your connection is working by opening a terminal in ``sys-net``: + +**[SCREENSHOT: Q widget with VM list and "Run terminal" expanded]** + +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``. + +You should see a sequence of lines starting with ``64 bytes from`` and ending with +the number of milliseconds it took to complete the request. If you do not see +similar output, your network access may be misconfigured, or the Internet may be +wholly or partially unreachable. + +If you have verified that you are able to connect to the Internet using +``sys-net``, but you are experiencing other connectivity issues, move on to the +next step. + +.. important:: + + 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 ` + overview for additional background. Step 2: Troubleshooting login issues ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -If the issue occurs on the login screen of the SecureDrop Client (the dialog -with the SecureDrop logo), this may not be a network issue. Make sure that your -username, passphrase, and two-factor code are correct. +Issues logging in may not be network-related. If you are experiencing +connectivity issues before or after logging in, you can skip ahead to the next section. + +Make sure that your username, passphrase, and two-factor code are correct. .. important:: @@ -59,11 +80,14 @@ 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. -If you access multiple sites and services using a single two-factor app, make -sure that the correct user account is selected. +If you use the two-factor app on your phone for other websites and services, +make sure that you have selected the correct user account. If you have access to a Tails-based *Journalist Workstation*, verify whether you -can access SecureDrop using the same credentials that do not work in Qubes. +can access SecureDrop from Tails. + +If you are certain that your credentials are correct but you are unable to log +in, proceed to the next step. Step 3: Verify that all required VMs are running ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -78,50 +102,73 @@ to sources, starring sources, deleting sources): - ``sd-whonix`` - ``sys-firewall`` - ``sys-net`` -- ``sys-whonix`` +- ``sys-whonix`` (during updates) You can verify whether a VM is running or not by clicking the "Q" icon in the -top right corner of your Qubes desktop. Only VMs that are currently running are -listed: +system tray (top right). Only VMs that are currently running will appear in the +list: -[SCREENSHOT: Q widget with VM list expanded] +**[SCREENSHOT: Q widget with VM list]** If a required VM is not running, you can launch it from the Qube Manager. Open the Qube Manager by clicking **Open Qube Manager** in the menu above. A window like the following should appear: -[SCREENSHOT: qube manager screenshot] +**[SCREENSHOT: Qube manager screenshot]** -To start a VM, select it from the list and press the "play" button in the -toolbar. +To start a VM, select it from the list, right-click it, and click **Start/Resume +Qube**. Alternatively, you can click the "Play" button in the toolbar. -In ordinary operation, VMs should start when they are needed. If you repeatedly -experience problems with a necessary VM not running, or if an error message -is displayed when attempting to start the VM, please contact us for assistance. +In ordinary use, VMs required by SecureDrop should be started on boot or when +they are needed. If you repeatedly experience problems with a necessary VM not +running, or if an error message is displayed when attempting to start the VM, +please contact us for assistance. -If this does not resolve the issue, proceed to the next step. +If all required VMs are running, proceed to the next step. + +Step 4: Verify that required VMs have connectivity +-------------------------------------------------- +In step 1, you have already verified that you can connect to the +Internet using ``sys-net``. Now, test whether ``sys-firewall``, ``sd-whonix`` +and ``sd-proxy`` are working. + +First, open a terminal in ``sys-firewall`` and run the ``ping google.com`` command. +You should see similar as in ``sys-net`` before. + +Now, open a terminal in ``sd-whonix`` and run the following command: -Step 4: Verify that required VMs have connectivity and examine logs -------------------------------------------------------------------- +``curl -s https://check.torproject.org/ | cat | grep -m 1 "Congratulations"`` + +This command contacts a service intended for web browsers to verify whether your +Tor connection is working. + +You should see the text "Congratulations. This browser is configured to use Tor." +or a similar message on the terminal. + +If this command fails, proceed to the next step. + +If the command succeeds in ``sd-whonix``, run exactly the same command in +``sd-proxy``. If it only fails in ``sd-proxy``, your workstation may be +misconfigured, or the proxy may have crashed. In that case, skip ahead to step 6. +We also recommend that you contact us, so we can help identify the root cause. Step 5: Restart Tor ------------------- -If all required VMs are running, you may be experiencing issues with the Tor -network. You can check the Tor status and try restarting Tor. +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: -[SCREENSHOT: sdwdate-gui widget] +**[SCREENSHOT: sdwdate-gui widget]** One of the two icons should display the option **sd-whonix**. Select that option -from the menu with your mouse, and then click **Tor control panel**: +from the menu with your mouse, and click **Tor control panel**: -[SCREENSHOT: sdwdate-gui widget with Tor control panel option shown] +**[SCREENSHOT: sdwdate-gui widget with Tor control panel option shown]** You should now see the following dialog: -[SCREENSHOT: Tor control panel screenshot] +**[SCREENSHOT: Tor control panel screenshot]** Click **Restart Tor** in the bottom right of this dialog. You should see a progress bar which will indicate when Tor is available again. If this does not @@ -129,21 +176,44 @@ resolve the issue, proceed to the next step. Step 6: Restart ``sd-proxy`` and ``sd-whonix`` ---------------------------------------------- -The VMs ``sd-whonix`` and ``sd-proxy`` are the two most important VMs for -maintaining the connection between the SecureDrop app and the SecureDrop server. -You can restart VMs using the Qube Manager: +Restart ``sd-proxy`` and ``sd-whonix`` to attempt to restore connectivity: -[SCREENSHOT: Qube Manager screenshot] - -Select the VM you wish to restart from the list, right-click its entry, and click -**Restart qube**. (You can also click the restart icon in the toolbar instead.) -This will take several seconds, and it will take additional time to re-establish -a Tor connection. +1. Exit the SecureDrop app if it is running. +2. Click the "Q" icon in the system tray (top right). +3. Click **Run Qube Manager** +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. If this does not resolve the issue, proceed to the next step. Step 7: Restart ``sys-net`` and ``sys-firewall`` ------------------------------------------------ -Using the same method employed in the previous step, you can restart the two -VMs that are underlying most network operations in Qubes OS, ``sys-net`` and + +.. note:: + + You will temporarily lose all Internet connectivity in Qubes OS during this + step. + +Using the same procedure as in the previous step, shut down ``sd-proxy``, +``sd-whonix`` and ``sys-whonix`` (in this order). Attempt to shut down +``sys-firewall``. You may see an error message telling you that other VMs still +require access to ``sys-firewall``. Save your work in those VMs, shut them +down, and attempt to shut down ``sys-firewall`` again. + +Finally, shut down ``sys-net``. The network manager icon should disappear. + +Now, start ``sys-whonix``, which will bring up ``sys-net`` and ``sys-firewall`` +at the same time. Start ``sd-proxy``, which will bring up ``sd-whonix``. + +If this does not resolve the issue, please contact us for assistance. + +Examining logs +-------------- +You may wish to examine system logs on your own, or with our guidance. You can +examine consolidated syslogs from all SecureDrop-related VMs in the ``sd-log`` +VM. They can be found in the default user's ``~/QubesIncomingLogs`` directory. + +In addition, you may want to examine ``/var/log/syslog`` in ``sys-net`` and ``sys-firewall``. \ No newline at end of file diff --git a/docs/admin/workstation_architecture.rst b/docs/admin/workstation_architecture.rst index 744173d..5df0206 100644 --- a/docs/admin/workstation_architecture.rst +++ b/docs/admin/workstation_architecture.rst @@ -26,6 +26,9 @@ the following VMs have no network access: - ``sd-devices``, which passes exported documents through to USB devices like printers and encrypted flash drives. +By design, the Qubes OS host domain, ``dom0``, also does not have Internet +access. + .. note: If you attempt to directly access the network in any of these VMs, it will From 69f6a64e0d3b45a22d9d918e4230c08768c5242c Mon Sep 17 00:00:00 2001 From: Erik Moeller Date: Fri, 13 Mar 2020 12:49:56 -0700 Subject: [PATCH 7/8] Changes in response to review feedback --- ...ork.rst => troubleshooting_connection.rst} | 61 ++++++++----------- docs/admin/workstation_architecture.rst | 16 ++--- docs/index.rst | 2 +- 3 files changed, 35 insertions(+), 44 deletions(-) rename docs/admin/{troubleshooting_network.rst => troubleshooting_connection.rst} (86%) diff --git a/docs/admin/troubleshooting_network.rst b/docs/admin/troubleshooting_connection.rst similarity index 86% rename from docs/admin/troubleshooting_network.rst rename to docs/admin/troubleshooting_connection.rst index 4390e74..60418af 100644 --- a/docs/admin/troubleshooting_network.rst +++ b/docs/admin/troubleshooting_connection.rst @@ -1,9 +1,9 @@ -Troubleshooting network issues -============================== +Troubleshooting connection problems +=================================== .. include:: ../includes/top-warning.rst -Before troubleshooting network issues, we recommend reading about the +Before troubleshooting connection problems, we recommend reading about the :ref:`networking architecture ` of SecureDrop Workstation. If you are in a hurry, this guide offers quick diagnostic and remedial steps. @@ -37,6 +37,13 @@ Common causes for lost connections include fully or partly unplugged network cab lost power to networking equipment, and ISP service outages. When you see a lost connection notification, it is most likely due to one of these causes. +.. important:: + + 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 ` + overview for additional background. + If the network manager shows that you are connected to the Internet, you can verify whether your connection is working by opening a terminal in ``sys-net``: @@ -45,24 +52,18 @@ verify whether your connection is working by opening a terminal in ``sys-net``: 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``. +3. In the terminal window, type the command ``ping -c 5 google.com``. You should see a sequence of lines starting with ``64 bytes from`` and ending with the number of milliseconds it took to complete the request. If you do not see similar output, your network access may be misconfigured, or the Internet may be -wholly or partially unreachable. +wholly or partially unreachable. If using ``8.8.8.8`` instead of ``google.com`` +works, it may suggest a problem at the DNS level in your network configuration. If you have verified that you are able to connect to the Internet using ``sys-net``, but you are experiencing other connectivity issues, move on to the next step. -.. important:: - - 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 ` - overview for additional background. - Step 2: Troubleshooting login issues ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Issues logging in may not be network-related. If you are experiencing @@ -77,11 +78,12 @@ Make sure that your username, passphrase, and two-factor code are correct. 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. +extra characters and end, or subtle differences like capitalization. Note that +the spaces between words in SecureDrop passphrases are part of the passphrase. If you use the two-factor app on your phone for other websites and services, -make sure that you have selected the correct user account. +make sure that you have selected the correct user account. It should be labeled +**SecureDrop**. If you have access to a Tails-based *Journalist Workstation*, verify whether you can access SecureDrop from Tails. @@ -133,7 +135,7 @@ Internet using ``sys-net``. Now, test whether ``sys-firewall``, ``sd-whonix`` and ``sd-proxy`` are working. First, open a terminal in ``sys-firewall`` and run the ``ping google.com`` command. -You should see similar as in ``sys-net`` before. +You should see similar output as in ``sys-net`` before. Now, open a terminal in ``sd-whonix`` and run the following command: @@ -145,9 +147,10 @@ Tor connection is working. You should see the text "Congratulations. This browser is configured to use Tor." or a similar message on the terminal. -If this command fails, proceed to the next step. +If the output does not include the text "Congratulations", keep the terminal +window open and proceed to the next steps. -If the command succeeds in ``sd-whonix``, run exactly the same command in +If the command does include the expected text in ``sd-whonix``, also run it in ``sd-proxy``. If it only fails in ``sd-proxy``, your workstation may be misconfigured, or the proxy may have crashed. In that case, skip ahead to step 6. We also recommend that you contact us, so we can help identify the root cause. @@ -155,24 +158,12 @@ We also recommend that you contact us, so we can help identify the root cause. Step 5: Restart Tor ------------------- If you have narrowed down the problem to ``sd-whonix``, try restarting Tor. +You can do this from within the ``sd-whonix`` terminal using the following +command: -To do so, right-click the Tor icons in the top right corner of your Qubes -desktop. They look like this: - -**[SCREENSHOT: sdwdate-gui widget]** +``sudo systemctl restart tor`` -One of the two icons should display the option **sd-whonix**. Select that option -from the menu with your mouse, and click **Tor control panel**: - -**[SCREENSHOT: sdwdate-gui widget with Tor control panel option shown]** - -You should now see the following dialog: - -**[SCREENSHOT: Tor control panel screenshot]** - -Click **Restart Tor** in the bottom right of this dialog. You should see a -progress bar which will indicate when Tor is available again. If this does not -resolve the issue, proceed to the next step. +If this does not resolve the issue, proceed to the next step. Step 6: Restart ``sd-proxy`` and ``sd-whonix`` ---------------------------------------------- @@ -216,4 +207,4 @@ examine consolidated syslogs from all SecureDrop-related VMs in the ``sd-log`` VM. They can be found in the default user's ``~/QubesIncomingLogs`` directory. In addition, you may want to examine ``/var/log/syslog`` in ``sys-net`` and -``sys-firewall``. \ No newline at end of file +``sys-firewall``. diff --git a/docs/admin/workstation_architecture.rst b/docs/admin/workstation_architecture.rst index 5df0206..9ff5b65 100644 --- a/docs/admin/workstation_architecture.rst +++ b/docs/admin/workstation_architecture.rst @@ -29,27 +29,27 @@ the following VMs have no network access: By design, the Qubes OS host domain, ``dom0``, also does not have Internet access. -.. note: +.. note:: If you attempt to directly access the network in any of these VMs, it will not work. That is the expected behavior. 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 -VM, ``sd-proxy``, which can only access the open Internet through the Tor -network, using the separate ``sd-whonix`` VM. +replies, it can communicate through Qubes-internal Remote Procedure Calls (RPCs) +with another VM, ``sd-proxy``, which can only access the open Internet through +the Tor network, using the separate ``sd-whonix`` VM. 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. +running for the SecureDrop Client to successfully connect to the server. -.. important: +.. important:: The ``sd-whonix`` VM contains a sensitive authentication token required to access the SecureDrop API via Tor, and should not be attached to VMs that are unrelated to SecureDrop. Qubes OS ships with a Whonix service called ``sys-whonix``. When troubleshooting -network issues specific to SecureDrop, ``sys-whonix`` is only relevant during -updates of the Whonix VMs (e.g., while the preflight updater is running). \ No newline at end of file +connection issues specific to SecureDrop, ``sys-whonix`` is only relevant during +updates of the Whonix VMs (e.g., while the preflight updater is running). diff --git a/docs/index.rst b/docs/index.rst index e7e839a..33614b4 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -30,7 +30,7 @@ submitted documents with a reasonable level of security. :caption: Guide for Administrators admin/securing_workstation - admin/troubleshooting_network + admin/troubleshooting_connection admin/provisioning_usb admin/known_issues admin/workstation_architecture From 3e082f91db0de07ebbf385871b382dd6e1c083df Mon Sep 17 00:00:00 2001 From: Erik Moeller Date: Tue, 17 Mar 2020 17:50:58 -0700 Subject: [PATCH 8/8] Tighten language re: network access --- docs/admin/workstation_architecture.rst | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/docs/admin/workstation_architecture.rst b/docs/admin/workstation_architecture.rst index 9ff5b65..5b1cd5c 100644 --- a/docs/admin/workstation_architecture.rst +++ b/docs/admin/workstation_architecture.rst @@ -12,10 +12,9 @@ appropriate level of network access for each VM. For example, you could have a VM for password storage that has no network access, a work VM that is firewalled 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 -vulnerability in order to exfiltrate documents or private keys. Specifically, -the following VMs have no network access: +SecureDrop Workstation tightly controls access to the network, in order to +prevent the exfiltration of messages, replies, documents, or encryption keys by +adversaries. Specifically, the following VMs have no network access: - ``sd-app``, which runs the SecureDrop Client, and holds decrypted messages, replies, and documents.