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 1 commit
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
147 changes: 31 additions & 116 deletions docs/admin/reference/hardware.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,19 +10,29 @@ In order to install and use SecureDrop Workstation, you will need a Qubes-Compat
- 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.
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.

Qubes-certified laptops
~~~~~~~~~~~~~~~~~~~~~~~

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.

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

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

Lenovo X1 series laptops
------------------------
.. _thinkpad_x_series:

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:
Expand All @@ -38,11 +48,9 @@ You'll need to have a USB-to-Ethernet adapter on hand in order to :ref:`apply Qu

.. _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:
Expand All @@ -52,118 +60,25 @@ The 2nd-generation ThinkPad T14 **with an 11th-generation Intel Core processor**

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.
- Otherwise, ensure the BIOS is up-to date by following these instructions: :doc:`thinkpad_bios`.

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.

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

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

.. code-block:: sh

sudo cp /var/lib/unsafe-browser/chroot/home/clearnet/Downloads/<fileName.iso> ~amnesia/Desktop
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.

- Fix the ISO file's ownership with the command:
.. _framework_13_series:

.. code-block:: sh
Framework 13 13th generation laptop
***********************************
TK text and description here

sudo chown amnesia:amnesia ~amnesia/Desktop/<fileName.iso>

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

.. code-block:: sh

sha256sum /path/to/downloaded.iso

- Create a USB-bootable version of the ISO using the command:

.. code-block:: sh

geteltorito <path/to/CDISO> > usb-bios.iso

.. note:: To install the ``geleltorito`` utility on Debian-based systems, use the command

.. code-block:: sh

sudo apt install genisoimage

To install it on Fedora-based systems, use the command:

.. code-block:: sh

sudo dnf install geteltorito genisoimage

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

- Write the BIOS update ISO to the USB using the following command:

.. code-block:: sh

sudo dd if=usb-bios.iso of=/dev/sdX bs=1M && sync

where ``sdX`` is the device name verified above.

.. caution::

The ``dd`` command will wipe data on the targeted device. Make sure that you use the correct device name.

Once complete, remove the USB.

- Plug the USB into the ThinkPad.

- Boot the ThinkPad and follow the prompts to enter its startup and boot menus, likely via the <Enter> and <F12> keys, respectively.

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

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:
The Qubes Hardware Compatibility List (HCL)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
TK text and description here

- 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.
83 changes: 83 additions & 0 deletions docs/admin/reference/thinkpad_bios.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,83 @@
Upgrading the BIOS on Lenovo ThinkPad laptops
=============================================

.. _thinkpad_bios:

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

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

.. code-block:: sh

sudo cp /var/lib/unsafe-browser/chroot/home/clearnet/Downloads/<fileName.iso> ~amnesia/Desktop

- Fix the ISO file's ownership with the command:

.. code-block:: sh

sudo chown amnesia:amnesia ~amnesia/Desktop/<fileName.iso>

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

.. code-block:: sh

sha256sum /path/to/downloaded.iso

- Create a USB-bootable version of the ISO using the command:

.. code-block:: sh

geteltorito <path/to/CDISO> > usb-bios.iso

.. note:: To install the ``geleltorito`` utility on Debian-based systems, use the command

.. code-block:: sh

sudo apt install genisoimage

To install it on Fedora-based systems, use the command:

.. code-block:: sh

sudo dnf install geteltorito genisoimage

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

- Write the BIOS update ISO to the USB using the following command:

.. code-block:: sh

sudo dd if=usb-bios.iso of=/dev/sdX bs=1M && sync

where ``sdX`` is the device name verified above.

.. caution::

The ``dd`` command will wipe data on the targeted device. Make sure that you use the correct device name.

Once complete, remove the USB.

- Plug the USB into the ThinkPad.

- Boot the ThinkPad and follow the prompts to enter its startup and boot menus, likely via the <Enter> and <F12> keys, respectively.

- 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.
1 change: 1 addition & 0 deletions docs/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -56,6 +56,7 @@ against malware and other security risks. It is built on Qubes OS and requires a
admin/reference/troubleshooting_updates
admin/reference/provisioning_usb
admin/reference/backup
admin/reference/thinkpad_bios
Copy link
Contributor

Choose a reason for hiding this comment

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

For the sake of consistency, we should probably either have a small guide for Framework BIOS updates as well, or at least link out to their knowledgebase article on the topic: https://knowledgebase.frame.work/framework-laptop-bios-releases-S1dMQt6F

Copy link
Contributor

Choose a reason for hiding this comment

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

Er, that link was for the 11th gen Intel board specifically. Looks like each product has its own BIOS update page. We'd either need to point to https://knowledgebase.frame.work/categories/products_en-r1aUmxtrd, or consider linking to each individual page in the aforementioned small guide.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

My pref would be to link wherever possible - if that's an option I'd link from the section in the hardware reccos. Where there's a long or involved process that we have to document locally, I'd prefer to have it in a separate page.


* :ref:`genindex`
* :ref:`search`