Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Overhaul the hardware guide #224

Draft
wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

Overhaul the hardware guide #224

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/admin/install/prepare.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ To rotate passphrases for accounts, please see the `instructions <https://docs.s

Apply BIOS updates and check settings
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Before beginning the Qubes installation, make sure that your Qubes-compatible computer's BIOS is updated to the latest available version. If you're using one of the recommended ThinkPad T-series models, see the section on :ref:`thinkpad_t_series`. The process will be different for other makes and models, and can usually be found on their respective support sites.
Before beginning the Qubes installation, make sure that your Qubes-compatible computer's BIOS is updated to the latest available version. For more details about this process, see the section on :ref:`general_BIOS_update`.

Once the BIOS is up-to-date, boot into the BIOS setup utility and update its settings. Note that not all BIOS versions will support the items listed, but if available following changes are recommended:

Expand Down
140 changes: 47 additions & 93 deletions docs/admin/reference/hardware.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,108 +10,24 @@ Qubes OS hardware requirements
In order to install and use SecureDrop Workstation, you will need a Qubes-Compatible computer with the following specifications:

- 64-bit Intel or AMD processor with virtualization support
- a minimum of 16GB RAM (32GB recommended for production use)
- a minimum of 32GB RAM
- sufficient disk space for the Qubes OS base install and SecureDrop Workstation VMs (a 128GB or greater SSD is recommended)

We recommend against a device that requires an external USB keyboard for security reasons.

More information on hardware compatibility can be found on the `Qubes OS System Requirements <https://www.qubes-os.org/doc/system-requirements/>`_ page, and information on specific systems can be found via the `hardware compatibility list <https://www.qubes-os.org/hcl/>`_.

In order to print submissions, a supported non-networked printer is required. We have tested and recommend the HP LaserJet Pro M404n. More printer options will be added in future releases.

.. _thinkpad_x1_series:

Lenovo X1 series laptops
------------------------

Lenovo ThinkPad X1 Carbon (10th-generation)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The 10th-generation ThinkPad X1 Carbon **with a 12th-generation Intel Core processor** is a recommended option for the SecureDrop Workstation beginning with Qubes 4.1. If you plan to use it:

- If your laptop has come with Ubuntu preinstalled, run its **Software Updater** twice as follows:

#. to install software updates, especially for the ``fwupd`` package; and then
#. to run ``fwupd`` to update the BIOS automatically.

If **Software Updater** offers to run ``fwupd`` during step (1), decline until step (2), to make sure ``fwupd`` itself has received its latest security updates.

- Otherwise, follow the instructions below to ensure that the BIOS is up to date.

You'll need to have a USB-to-Ethernet adapter on hand in order to :ref:`apply Qubes updates <apply_dom0_updates>`, which will enable Wi-Fi and fix glitchy video rendering and cursor performance.

.. _thinkpad_t_series:

Lenovo T series laptops
-----------------------

Lenovo ThinkPad T14 (2nd-generation)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The 2nd-generation ThinkPad T14 **with an 11th-generation Intel Core processor** is a recommended option for the SecureDrop Workstation beginning with Qubes 4.1. If you plan to use it:

- If your laptop has come with Ubuntu preinstalled, run its **Software Updater** twice as follows:

#. to install software updates, especially for the ``fwupd`` package; and then
#. to run ``fwupd`` to update the BIOS automatically.

If **Software Updater** offers to run ``fwupd`` during step (1), decline until step (2), to make sure ``fwupd`` itself has received its latest security updates.

- Otherwise, follow the instructions below to ensure that the BIOS is up to date.

The Ethernet and Wi-Fi controllers may not work without one-time manual configuration, as documented in the following sections.

Ethernet controller
^^^^^^^^^^^^^^^^^^^
After Qubes starts for the first time, when ``sys-net`` fails to start, follow the instructions below for the :ref:`thinkpad_t490`, but only for the ``dom0:00_1f.6`` Ethernet device.

.. _thinkpad_t490:

Lenovo ThinkPad T490 (with 8th-generation Intel Core processor)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The ThinkPad T490 **with an 8th-generation Intel Core processor** is a recommended option for the SecureDrop Workstation. If you plan to use it, you should follow the instructions below to ensure that the BIOS is up to date and adequately configured before proceeding with the installation.


.. caution::

The versions of the T490 with 10th generation Intel Core processors are at present **untested and unsupported**. The Workstation has been tested on models 20N2002AUS & 20N20046US.

Network devices (Ethernet and Wi-Fi) will not immediately work out of the box and require a one-time manual configuration on install. After Qubes starts for the first time, ``sys-net`` will fail to start:

|screenshot_sys_net_pci_reset|
It's important that you update the BIOS of your laptop prior to installing SecureDrop Workstation. For more details about performing a BIOS update, see the section below for :ref:`general_BIOS_update`.

Open a ``dom0`` terminal via **Q > Terminal Emulator**, and run the following command to list the devices connected to the ``sys-net`` VM.

.. code-block:: sh

qvm-pci ls sys-net


This will return the two devices (Ethernet and WiFi) that are connected to ``sys-net``:

.. code-block:: sh

BACKEND:DEVID DESCRIPTION USED BY
dom0:00_14.3 Network controller: Intel Corporation sys-net
dom0:00_1f.6 Ethernet controller: Intel Corporation Ethernet Connection (5) I219-V sys-net


For both device IDs (e.g. ``dom0:00_1f.6`` and ``dom0:00_14.3``), you will need to detach and re-attach the device to ``sys-net``, then restart ``sys-net`` as follows:

.. code-block:: sh

qvm-pci detach sys-net dom0:00_14.3
qvm-pci detach sys-net dom0:00_1f.6
qvm-pci attach sys-net --persistent --option no-strict-reset=True dom0:00_14.3
qvm-pci attach sys-net --persistent --option no-strict-reset=True dom0:00_1f.6
qvm-start sys-net
More information on hardware compatibility can be found on the `Qubes OS System Requirements <https://www.qubes-os.org/doc/system-requirements/>`_ page, and information on specific systems can be found via the `hardware compatibility list <https://www.qubes-os.org/hcl/>`_.

USB drive requirements
----------------------

``sys-net`` should now start, and network devices will be functional. This change is only required once on first install. See the `Qubes documentation of this issue <https://www.qubes-os.org/doc/pci-troubleshooting/#unable-to-reset-pci-device-errors>`_ for more information.
For the installation of Qubes, and for systems that do not support automatic BIOS updates via ``fwupd``, we recommend the use of USB 3.0 drives that are at least 8GB in size.

.. |screenshot_sys_net_pci_reset| image:: ../../images/screenshot_sys_net_pci_reset.png
Printer requirements
--------------------

Lenovo ThinkPad T480
~~~~~~~~~~~~~~~~~~~~
The ThinkPad T480 is also a recommended option for SecureDrop Workstation, as it is being used by the core team for development and testing. If you plan to use it, you should follow the instructions below to ensure that the BIOS is up to date and adequately configured before proceeding with the installation:
In order to print submissions, a supported non-networked printer is required. We have tested and recommend the HP LaserJet Pro M404n. More printer options will be added in future releases.

.. _thinkpad_bios:

Expand Down Expand Up @@ -197,6 +113,44 @@ The instructions below assume the use of a Linux-based computer for the creation

- Follow the on-screen instructions to update the BIOS, including any mandatory reboots. Note that the instructions may refer to an update CD instead of your update USB.

.. _general_BIOS_update:

Generalized BIOS Update Instructions
-------------------------------------

Automatic BIOS Updates
^^^^^^^^^^^^^^^^^^^^^^

Ubuntu
######

If your laptop has Ubuntu preinstalled, run its **Software Updater** twice as follows:

#. to install software updates, especially for the ``fwupd`` package; and then
#. to run ``fwupd`` to update the BIOS automatically.

If **Software Updater** offers to run ``fwupd`` during step (1), decline until step (2), to make sure ``fwupd`` itself has received its latest security updates.

- Otherwise, follow the instructions below to manually perform a BIOS update.

Other Linux
###########

If your laptop has another Linux distribution installed, use the built-in software manager (such as GNOME Software or KDE Discover) to update the available software. Most modern distributions include ``fwupd`` by default. If not, you can install the package using your preferred software manager.

Once ``fwupd`` is installed, you can install available updates by running:

.. code-block:: sh

fwupdmgr refresh
fwupdmgr update


Manual BIOS Updates
^^^^^^^^^^^^^^^^^^^
If your laptop is not supported by ``fwupd``, you will need to consult the manual for your specific make and model to determine how to manually apply a BIOS update. The process will likely include downloading an update file, verifying its integrity, copying it to a USB drive, and then accessing an update menu within the BIOS settings. If you have a Thinkpad, refer to our instructions for :ref:`thinkpad_bios`.


USB-C ports
-----------
If you intend to use USB-C ports, please note that our recommended BIOS settings will disable dual USB-C/Thunderbolt ports (recognizable by the Thunderbolt logo next to the port). The T480, for example, includes two USB-C ports, `specified <https://psref.lenovo.com/syspool/Sys/PDF/ThinkPad/ThinkPad_T480/ThinkPad_T480_Spec.PDF>`__ as follows:
Expand Down