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

Update hardware recommendations to include qubes-certified list #273

Merged
merged 5 commits into from
Feb 13, 2025
Merged

Update hardware recommendations to include qubes-certified list #273

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
78648b7
Refactor hardware recommendations
zenmonkeykstop Oct 25, 2024
946dec4
Don't recommend AMD processors for Qubes
nathandyer Oct 28, 2024
1359af7
Add information about the Framework 13 and the Qubes HCL
nathandyer Oct 28, 2024
917f2a5
Add Framework 13 Core Ultra Series 1 to hardware list
nathandyer Nov 8, 2024
def6b4b
Merge branch 'main' into 211-redux
nathandyer Feb 13, 2025
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: 2 additions & 0 deletions docs/admin/install/troubleshoot.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,8 @@ This is a transient error that may affect any of the SecureDrop Workstation VMs.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Transient network issues may cause an installation to fail. To work around this, verify that you have a working Internet connection, and re-run the ``sdw-admin --apply`` command.

.. _reset_pci:

"Unable to reset PCI device"
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Expand Down
184 changes: 72 additions & 112 deletions docs/admin/reference/hardware.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,164 +6,124 @@ 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
- 64-bit Intel processor with virtualization support
- 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.

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:
Choosing a laptop
-----------------
We recommend against a device that requires an external USB keyboard or other externally-connected devices, for security reasons. In practice this usually means that you should run SecureDrop Workstation on a Qubes-compatible laptop. Not all laptops support Qubes, and some may require additional customization. We recommend (in order) either a Qubes-certified laptop, one of the laptop models we use for development and testing, or a computer from the community-maintained Qubes Hardware compatibility list.

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

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.
Qubes-certified laptops are certified and tested against Qubes major releases. They must support additional security features beyond the minimal requirements above, such as the use of `coreboot <https://www.coreboot.org/>`_ in place of proprietary firmware. Where possible, we recommend that you use a Qubes-certified laptop with ``coreboot`` for SecureDrop Workstation. A full list of certified computers can be found on the `Qubes OS Certified Hardware <https://www.qubes-os.org/doc/certified-hardware/>`_ page.

- Otherwise, follow the instructions below to ensure that the BIOS is up to date.
.. note:: Some certified computers also support the use of `Heads <https://osresearch.net>`_ with ``coreboot``, for additional protection against advanced attacks during the boot process. Heads adds a layer of complexity to the overall user experience, but may make sense for you as an option if you have an expectation of those kinds of threats. If you have questions about Heads, or other hardware choices, contact us via the `SecureDrop support portal <https://support.freedom.press>`_.

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.
FPF-tested laptops
~~~~~~~~~~~~~~~~~~
In addition to Qubes-certified devices, we develop and test using Qubes-compatible laptops from other vendors. The following models may be used for SecureDrop Workstation, though some level of additional configuration may be required.

.. _thinkpad_t_series:
.. _framework_13_series:

Lenovo T series laptops
-----------------------
Framework 13 (Intel Core Ultra Series 1)
****************************************

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.
The Framework 13 laptop with an Intel Core Ultra Series 1 processor is a recommended option for the SecureDrop Workstation beginning with Qubes 4.2.

.. _thinkpad_t490:
You can either order a preassmbled system, or you can customize your build and assemble the laptop yourself once it is delivered, which is useful as either a cost-saving measure or in the event that you wish to customize the ports or internal components.

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.
Framework laptops are designed to be repairable, customizable, and user-servicable, and have grown to be a popular choice with Qubes users and SecureDrop developers.


.. 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.

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:

.. _thinkpad_bios:

Upgrading the BIOS on Lenovo ThinkPad laptops
---------------------------------------------

The instructions below assume the use of a Linux-based computer for the creation of a BIOS upgrade USB. To upgrade the BIOS:

- Locate the ThinkPad's "machine type" in its BIOS setup program:

#. Boot (or reboot) the ThinkPad and follow the prompts to enter setup, usually via the <Enter> and <F1> keys.
#. On the **Main** tab, look for the **Machine Type Model**. The first four characters, such as `20L5`, `20L6`, or `20S0`, are the machine type.

- Visit `<https://support.lenovo.com>`_ in the Linux-based computer. Type the machine type found above into the search bar, then press **Enter**.
- In the "Product Home" page, select **Drivers And Software** and choose **BIOS/UEFI**.
- Download the file called either **BIOS Update (Bootable CD)** or **BIOS Update (Utility & Bootable CD)**.
You will want to ensure you are using the latest BIOS version available. Instructions for checking the BIOS version and performing an upgrade for the Intel Core Ultra Series 1 models can be found on `this page in the Framework knowledgebase. <https://knowledgebase.frame.work/framework-laptop-bios-and-driver-releases-intel-core-ultra-series-1-H1nZQdxYR>`_

.. note::
A Tails USB can be used for the verification and conversion process described below, but the Lenovo support site blocks requests over Tor, preventing the ISO download. To work around this, either:

- download the BIOS ISO on a different computer and transfer it to Tails using a USB stick, or
- download the ISO in Tails using the Unsafe Browser as follows:

- Start Tails with an administration password set and the Unsafe Browser enabled under "Additional Settings" on the Welcome Screen.
- Open the Unsafe Browser: **Applications > Internet > Unsafe Browser** and find and download the ISO
- Note the filename, as you'll need it for subsequent steps.
- Leave the Unsafe Browser running, and open a terminal via **Applications > System Tools > Terminal**.
- Copy the ISO to the desktop with the command:
You'll want to be sure to install Qubes OS using the kernel-latest option, available from the initial boot menu (GRUB) prior to booting to the Qubes OS installer.

.. code-block:: sh
Framework 13 (13th-generation)
******************************

sudo cp /var/lib/unsafe-browser/chroot/home/clearnet/Downloads/<fileName.iso> ~amnesia/Desktop
The Framework 13 laptop with a 13th generation Intel processor is a recommended option for the SecureDrop Workstation beginning with Qubes 4.2.

- Fix the ISO file's ownership with the command:
You can either order a preassmbled system, or you can customize your build and assemble the laptop yourself once it is delivered, which is useful as either a cost-saving measure or in the event that you wish to customize the ports or internal components.

.. code-block:: sh
Framework laptops are designed to be repairable, customizable, and user-servicable, and have grown to be a popular choice with Qubes users and SecureDrop developers.

sudo chown amnesia:amnesia ~amnesia/Desktop/<fileName.iso>
You will want to ensure you are using the latest BIOS version available. Instructions for checking the BIOS version and performing an upgrade for the 13th generation models can be found `here in the Framework knowledgebase. <https://knowledgebase.frame.work/framework-laptop-bios-and-driver-releases-13th-gen-intel-core-BkQBvKWr3>`_

- Verify the checksum of the downloaded ISO file using the following command, comparing it against the checksum in the file listing above:
.. _thinkpad_x_series:

.. code-block:: sh
Lenovo ThinkPad X1 Carbon (10th-generation)
*******************************************

sha256sum /path/to/downloaded.iso
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:

- Create a USB-bootable version of the ISO using the command:
- If your laptop has come with Ubuntu preinstalled, run its **Software Updater** twice as follows:

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

geteltorito <path/to/CDISO> > usb-bios.iso
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.

.. note:: To install the ``geleltorito`` utility on Debian-based systems, use the command
- Otherwise, follow the instructions below to ensure that the BIOS is up to date.

.. code-block:: sh
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.

sudo apt install genisoimage
.. _thinkpad_t_series:

To install it on Fedora-based systems, use the command:
Lenovo ThinkPad T14 (2nd-generation)
************************************

.. code-block:: sh
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:

sudo dnf install geteltorito genisoimage
- If your laptop has come with Ubuntu preinstalled, run its **Software Updater** twice as follows:

- Plug in a USB and check its device name with the ``lsblk`` command - use the root device name below, not a partition (eg. ``/dev/sdc`` instead of ``/dev/sdc1``).
#. to install software updates, especially for the ``fwupd`` package; and then
#. to run ``fwupd`` to update the BIOS automatically.

- Write the BIOS update ISO to the USB using the following command:
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.

.. code-block:: sh
- Otherwise, ensure the BIOS is up-to date by following these instructions: :doc:`thinkpad_bios`.

sudo dd if=usb-bios.iso of=/dev/sdX bs=1M && sync
The Ethernet and Wi-Fi controllers may not work without one-time manual configuration, as documented in the following sections.

where ``sdX`` is the device name verified above.
Ethernet controller
^^^^^^^^^^^^^^^^^^^
After Qubes starts for the first time, when ``sys-net`` fails to start, follow the troubleshooting instructions for :ref:`reset_pci`, but only for the ``dom0:00_1f.6`` Ethernet device.

.. caution::
The Qubes Hardware Compatibility List (HCL)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The ``dd`` command will wipe data on the targeted device. Make sure that you use the correct device name.
The `Qubes Hardware Compatibility List (HCL) <https://www.qubes-os.org/hcl/>`_
is a community-maintained list of hardware that has been tested by Qubes users.
It consists of individual reports generated and submitted by Qubes users across
the world. Anyone can attempt to install Qubes on their computer, then report
back on whether or not it can be installed, if there are any issues, and overall,
what the experience is like.

Once complete, remove the USB.
There are some benefits to this list:

- Plug the USB into the ThinkPad.
* A much wider selection of hardware is tested, because anyone can contribute to the list
* There are sometimes multiple reports for a particular system, which lets you compare and feel confident the results are consistent
* It tells you exactly what is and isn't working within the system, so you can decide if a device you own will function well enough to suit your needs
* Devices get tested across many different configurations and Qubes versions

- Boot the ThinkPad and follow the prompts to enter its startup and boot menus, likely via the <Enter> and <F12> keys, respectively.
However, there are some things to consider:

- 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.
* Reports are not verified for their accuracy by either the Qubes team or Freedom of the Press Foundation
* Reports correspond to a specific Qubes OS version, and may not reflect breaking changes or expanded hardware support in the most recent Qubes OS version

USB-C ports
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Was the decision to remove the section on USB-C ports because this information is no longer applicable, or because it's too in-the-weeds?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Bit of both - it references 8th-gen T480s so n/a, and if it is caused by bios settings in install section it can probably be a note there.

-----------
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:
For the best experience, we recommend choosing a Qubes-certified laptop, or a
laptop that we have directly tested (in that order); however, if none of those
suit your needs, or if you want to see if your existing hardware might be
Qubes compatible, the HCL is a good choice.

- 1 x USB 3.1 Gen 1 Type-C (Power Delivery, DisplayPort, Data transfer)
- 1 x USB 3.1 Gen 2 Type-C / Intel Thunderbolt 3 (Power Delivery, DisplayPort, Data transfer)
Choosing a printer
------------------
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.

The first of these ports will continue to function as a USB-C port. After disabling Thunderbolt, the second port can no longer be used for Thunderbolt or for USB-C data transfer, but it can still be used for power delivery (i.e. to plug in your AC adapter). If you are unsure about the features of your laptop's USB-C ports, or if you are using a different make or model, please consult the technical specifications of your laptop for further information.
Loading