diff --git a/docs/admin/troubleshooting_connection.rst b/docs/admin/troubleshooting_connection.rst new file mode 100644 index 0000000..60418af --- /dev/null +++ b/docs/admin/troubleshooting_connection.rst @@ -0,0 +1,210 @@ +Troubleshooting connection problems +=================================== + +.. include:: ../includes/top-warning.rst + +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. + +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, known as the *system +tray*. + +The network manager looks like this for a wired connection: + +**[SCREENSHOT: network manager wired icon]** + +It looks like this for a wireless connection: + +**[SCREENSHOT: network manager wired icon]** + +It looks like this when you are not connected to the Internet at all: + +**[SCREENSHOT: no connection icon]** + +When a network connection is lost, Qubes will display an alert like the +following: + +**[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. + +.. 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``: + +**[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 -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. 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. + +Step 2: Troubleshooting login issues +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +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:: + + 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 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. It should be labeled +**SecureDrop**. + +If you have access to a Tails-based *Journalist Workstation*, verify whether you +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 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +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`` +- ``sd-log`` +- ``sd-proxy`` +- ``sd-whonix`` +- ``sys-firewall`` +- ``sys-net`` +- ``sys-whonix`` (during updates) + +You can verify whether a VM is running or not by clicking the "Q" icon in the +system tray (top right). Only VMs that are currently running will appear in the +list: + +**[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]** + +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 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 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 output as in ``sys-net`` before. + +Now, open a terminal in ``sd-whonix`` and run the following command: + +``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 the output does not include the text "Congratulations", keep the terminal +window open and proceed to the next steps. + +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. + +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: + +``sudo systemctl restart tor`` + +If this does not resolve the issue, proceed to the next step. + +Step 6: Restart ``sd-proxy`` and ``sd-whonix`` +---------------------------------------------- +Restart ``sd-proxy`` and ``sd-whonix`` to attempt to restore connectivity: + +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`` +------------------------------------------------ + +.. 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``. diff --git a/docs/admin/troubleshooting_network.rst b/docs/admin/troubleshooting_network.rst deleted file mode 100644 index 3a378bc..0000000 --- a/docs/admin/troubleshooting_network.rst +++ /dev/null @@ -1,4 +0,0 @@ -Troubleshooting network issues -============================== - -.. include:: ../includes/top-warning.rst diff --git a/docs/admin/workstation_architecture.rst b/docs/admin/workstation_architecture.rst new file mode 100644 index 0000000..5b1cd5c --- /dev/null +++ b/docs/admin/workstation_architecture.rst @@ -0,0 +1,54 @@ +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. + +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. +- ``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. + +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 + 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 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 SecureDrop 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 +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 c3511da..33614b4 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -30,9 +30,10 @@ 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 * :ref:`genindex`