` with your specific computer model) or look it up in your computer's manual.
+
+Once you know the key to press, press your computer's power button, then repeatedly press that key until you've entered your computer's BIOS or UEFI menu. To give you and idea of what you should be looking for, we've provided a couple of example photos below.
+
+Here's an example of what the BIOS menu looks like on a ThinkPad T430:
+
+[![ThinkPad T430 BIOS menu](/attachment/doc/Thinkpad-t430-bios-main.jpg)](/attachment/doc/Thinkpad-t430-bios-main.jpg)
+
+And here's an example of what a UEFI menu looks like:
+
+[![UEFI menu](/attachment/doc/uefi.jpeg)](/attachment/doc/uefi.jpeg)
+
+Once you access your computer's BIOS or UEFI menu, you'll want to go to the "boot menu," which is where you tell your computer which devices to boot from. The goal is to tell the computer to boot from your USB drive so that you can run the Qubes installer. If your boot menu lets you select which device to boot from first, simply select your USB drive. (If you have multiple entries that all look similar to your USB drive, and you're not sure which one is correct, one option is just to try each one until it works.) If, on the other hand, your boot menu presents you with a list of boot devices in order, then you'll want to move your USB drive to the top so that the Qubes installer runs before anything else.
+
+Once you're done on the boot menu, save your changes. How you do this depends on your BIOS or UEFI, but the instructions should be displayed right there on the screen or in a nearby tab. (If you're not sure whether you've saved your changes correctly, you can always reboot your computer and go back into the boot menu to check whether it still reflects your changes.) Once your BIOS or UEFI is configured the way you want it, reboot your computer. This time, don't press any special keys. Instead, let the BIOS or UEFI load and let your computer boot from your USB drive. If you're successful in this step, after a few seconds you'll be presented with the Qubes installer screen:
+
+[![Boot screen](/attachment/doc/boot-screen.png)](/attachment/doc/boot-screen.png)
+
+From here, you can navigate the boot screen using the arrow keys on your keyboard. Pressing the "Tab" key will reveal options. You can choose one of three options:
+
+* Install Qubes OS
+* Test this media and install Qubes OS
+* Troubleshooting
+
+Select the option to test this media and install Qubes OS.
+
+
+
+
Note: If the latest stable release is not compatible with your hardware, you may wish to consider
testing a newer release.
+
+
+If the boot screen does not appear, there are several options to troubleshoot. First, try rebooting your computer. If it still loads your currently installed operating system or does not detect your installation medium, make sure the boot order is set up appropriately. The process to change the boot order varies depending on the currently installed system and the motherboard manufacturer. If **Windows 10** is installed on your machine, you may need to follow specific instructions to change the boot order. This may require an [advanced reboot](https://support.microsoft.com/en-us/help/4026206/windows-10-find-safe-mode-and-other-startup-settings).
+
+### The installer home screen
+
+On the first screen, you are asked to select the language that will be used during the installation process. When you are done, select **Continue**.
+
+[![welcome](/attachment/doc/welcome-to-qubes-os-installation-screen.png)](/attachment/doc/welcome-to-qubes-os-installation-screen.png)
+
+Prior to the next screen, a compatibility test runs to check whether IOMMU-virtualization is active or not. If the test fails, a window will pop up.
+
+[![Unsupported hardware detected](/attachment/doc/unsupported-hardware-detected.png)](/attachment/doc/unsupported-hardware-detected.png)
+
+Do not panic. It may simply indicate that IOMMU-virtualization hasn't been activated in the BIOS or UEFI. Return to the [hardware requirements](#hardware-requirements) section to learn how to activate it. If the setting is not configured correctly, it means that your hardware won't be able to leverage some Qubes security features, such as a strict isolation of the networking and USB hardware.
+
+If the test passes, you will reach the installation summary screen. The installer loads Xen right at the beginning. If you can see the installer's graphical screen, and you pass the compatibility check that runs immediately afterward, Qubes OS is likely to work on your system!
+
+Like Fedora, Qubes OS uses the Anaconda installer. Those that are familiar with RPM-based distributions should feel at home.
+
+### Installation summary
+
+
+
+ Did you know? The Qubes OS installer is completely offline. It doesn't even load any networking drivers, so there is no possibility of internet-based data leaks or attacks during the installation process.
+
+
+The Installation summary screen allows you to change how the system will be installed and configured, including localization settings. At minimum, you are required to select the storage device on which Qubes OS will be installed.
+
+[![Installation summary not ready](/attachment/doc/installation-summary-not-ready.png)](/attachment/doc/installation-summary-not-ready.png)
+
+### Localization
+
+Let's assume you wish to add a German keyboard layout. Go to Keyboard Layout, press the "Plus" symbol, search for "German" as indicated in the screenshot and press "Add". If you want it be your default language, select the "German" entry in the list and press the arrow button. Click on "Done" in the upper left corner, and you're ready to go!
+
+[![Keyboard layout selection](/attachment/doc/keyboard-layout-selection.png)](/attachment/doc/keyboard-layout-selection.png)
+
+The process to select a new language is similar to the process to select a new keyboard layout. Follow the same process in the "Language Support" entry.
+
+[![Language support selection](/attachment/doc/language-support-selection.png)](/attachment/doc/language-support-selection.png)
+
+You can have as many keyboard layout and languages as you want. Post-install, you will be able to switch between them and install others.
+
+Don't forget to select your time and date by clicking on the Time & Date entry.
+
+[![Time and date](/attachment/doc/time-and-date.png)](/attachment/doc/time-and-date.png)
+
+### Software
+
+[![Add-ons](/attachment/doc/add-ons.png)](/attachment/doc/add-ons.png)
+
+On the software selection tab, you can choose which software to install in Qubes OS. Two options are available:
+
+* **Debian:** Select this option if you would like to use [Debian](/doc/templates/debian/) qubes in addition to the default Fedora qubes.
+* **Whonix:** Select this option if you would like to use [Whonix](https://www.whonix.org/wiki/Qubes) qubes. Whonix allows you to use [Tor](https://www.torproject.org/) securely within Qubes.
+
+Whonix lets you route some or all of your network traffic through Tor for greater privacy. Depending on your threat model, you may need to install Whonix templates right away.
+
+Regardless of your choices on this screen, you will always be able to install these and other [templates](/doc/templates/) later. If you're short on disk space, you may wish to deselect these options.
+
+By default, Qubes OS comes preinstalled with the lightweight Xfce4 desktop environment. Other desktop environments will be available to you after the installation is completed, though they may not be officially supported (see [advanced topics](/doc/#advanced-topics)).
+
+Press **Done** to go back to the installation summary screen.
+
+### Installation destination
+
+Under the System section, you must choose the installation destination. Select the storage device on which you would like to install Qubes OS.
+
+
+
+ Warning: Be careful to choose the correct installation target, or you may lose data. We strongly recommended making a full backup before proceeding.
+
+
+Your installation destination can be an internal or external storage drive, such as an SSD, HDD, or USB drive. The installation destination must have a least 32 GiB of free space available.
+
+
+
+ Note: The installation destination cannot be the same as the installation medium. For example, if you're installing Qubes OS from a USB drive onto a USB drive, they must be two distinct USB drives, and they must both be plugged into your computer at the same time. (Note: This may not apply to advanced users who partition their devices appropriately.)
+
+
+Installing an operating system onto a USB drive can be a convenient way to try Qubes. However, USB drives are typically much slower than internal SSDs. We recommend a very fast USB 3.0 drive for decent performance. Please note that a minimum storage of 32 GiB is required. If you want to install Qubes OS onto a USB drive, just select the USB device as the target installation device. Bear in mind that the installation process is likely to take longer than it would on an internal storage device.
+
+[![Select storage device](/attachment/doc/select-storage-device.png)](/attachment/doc/select-storage-device.png)
+
+
+
+
Did you know? By default, Qubes OS uses
LUKS/
dm-crypt to encrypt everything except the
/boot
partition.
+
+
+As soon as you press **Done**, the installer will ask you to enter a passphrase for disk encryption. The passphrase should be complex. Make sure that your keyboard layout reflects what keyboard you are actually using. When you're finished, press **Done**.
+
+
+
+ Warning: If you forget your encryption passphrase, there is no way to recover it.
+
+
+[![Select storage passhprase](/attachment/doc/select-storage-passphrase.png)](/attachment/doc/select-storage-passphrase.png)
+
+When you're ready, press **Begin Installation**.
+
+[![Installation summary ready](/attachment/doc/installation-summary-ready.png)](/attachment/doc/installation-summary-ready.png)
+
+### Create your user account
+
+While the installation process is running, you can create your user account. This is what you'll use to log in after disk decryption and when unlocking the screen locker. This is a purely local, offline account in dom0. By design, Qubes OS is a single-user operating system, so this is just for you.
+
+Select **User Creation** to define a new user with administrator privileges and a password. Just as for the disk encryption, this password should be complex. The root account is deactivated and should remain as such.
+
+[![Account name and password](/attachment/doc/account-name-and-password.png)](/attachment/doc/account-name-and-password.png)
+
+When the installation is complete, press **Reboot**. Don't forget to remove the installation medium, or else you may end up seeing the installer boot screen again.
+
+## Post-installation
+
+### First boot
+
+If the installation was successful, you should now see the GRUB menu during the boot process.
+
+[![Grub boot menu](/attachment/doc/grub-boot-menu.png)](/attachment/doc/grub-boot-menu.png)
+
+Just after this screen, you will be asked to enter your encryption passphrase.
+
+[![Unlock storage device screen](/attachment/doc/unlock-storage-device-screen.png)](/attachment/doc/unlock-storage-device-screen.png)
+
+### Initial Setup
+
+You're almost done. Before you can start using Qubes OS, some configuration is needed.
+
+[![Initial setup menu](/attachment/doc/initial-setup-menu.png)](/attachment/doc/initial-setup-menu.png)
+
+By default, the installer will create a number of qubes (depending on the options you selected during the installation process). These are designed to give you a more ready-to-use environment from the get-go.
+
+[![Initial setup menu configuration](/attachment/doc/initial-setup-menu-configuration.png)](/attachment/doc/initial-setup-menu-configuration.png)
+
+Let's briefly go over the options:
+
+* **Create default system qubes:** These are the core components of the system, required for things like internet access.
+* **Create default application qubes:** These are how you compartmentalize your digital life. There's nothing special about the ones the installer creates. They're just suggestions that apply to most people. If you decide you don't want them, you can always delete them later, and you can always create your own.
+* **Create Whonix Gateway and Workstation qubes:** If you want to use Whonix, you should select this option.
+ * **Enabling system and template updates over the Tor anonymity network using Whonix:** If you select this option, then whenever you install or update software in dom0 or a template, the internet traffic will go through Tor.
+* **Create USB qube holding all USB controllers:** Just like the network qube for the network stack, the USB qube isolates the USB controllers.
+ * **Use sys-net qube for both networking and USB devices:** You should select this option if you rely on a USB device for network access, such as a USB modem or a USB Wi-Fi adapter.
+* **Do not configure anything:** This is for very advanced users only. If you select this option, you'll have to set everything up manually afterward.
+
+When you're satisfied with you choices, press **Done**. This configuration process may take a while, depending on the speed and compatibility of your system.
+
+After the configuration is done, you will be greeted by the login screen. Enter your password and log in.
+
+[![Login screen](/attachment/doc/login-screen.png)](/attachment/doc/login-screen.png)
+
+Congratulations, you are now ready to use Qubes OS!
+
+[![Desktop menu](/attachment/doc/desktop-menu.png)](/attachment/doc/desktop-menu.png)
+
+## Next steps
+
+### Updating
+
+Next, [update](/doc/how-to-update/) your installation to ensure you have the latest security updates. Frequently updating is one of the best ways to remain secure against new threats.
+
+### Security
+
+The Qubes OS Project occasionally issues [Qubes Security Bulletins (QSBs)](/security/qsb/) as part of the [Qubes Security Pack (qubes-secpack)](/security/pack/). It is important to make sure that you receive all QSBs in a timely manner so that you can take action to keep your system secure. (While [updating](#updating) will handle most security needs, there may be cases in which additional action from you is required.) For this reason, we strongly recommend that every Qubes user subscribe to the [qubes-announce](/support/#qubes-announce) mailing list.
+
+In addition to QSBs, the Qubes OS Project also publishes [Canaries](/security/canary/), XSA summaries, template releases and end-of-life notices, and other items of interest to Qubes users. Since these are not essential for all Qubes users to read, they are not sent to [qubes-announce](/support/#qubes-announce) in order to keep the volume on that list low. However, we expect that most users, especially novice users, will find them helpful. If you are interested in these additional items, we encourage you to subscribe to the [Qubes News RSS feed](/feed.xml) or join one of our other [venues](/support/), where these news items are also announced.
+
+For more information about Qubes OS Project security, please see the [security center](/security/).
+
+### Backups
+
+It is extremely important to make regular backups so that you don't lose your data unexpectedly. The [Qubes backup system](/doc/how-to-back-up-restore-and-migrate/) allows you to do this securely and easily.
+
+### Submit your HCL report
+
+Consider giving back to the Qubes community and helping other users by [generating and submitting a Hardware Compatibility List (HCL) report](/doc/how-to-use-the-hcl/#generating-and-submitting-new-reports).
+
+### Get Started
+
+Find out [Getting Started](/doc/getting-started/) with Qubes, check out the other [How-To Guides](/doc/#how-to-guides), and learn about [Templates](/doc/#templates).
+
+## Getting help
+
+* We work very hard to make the [documentation](/doc/) accurate, comprehensive useful and user friendly. We urge you to read it! It may very well contain the answers to your questions. (Since the documentation is a community effort, we'd also greatly appreciate your help in [improving](/doc/how-to-edit-the-documentation/) it!)
+
+* If issues arise during installation, see the [Installation Troubleshooting](/doc/installation-troubleshooting) guide.
+
+* If you don't find your answer in the documentation, please see [Help, Support, Mailing Lists, and Forum](/support/) for places to ask.
+
+* Please do **not** email individual members of the Qubes team with questions about installation or other problems. Instead, please see [Help, Support, Mailing Lists, and Forum](/support/) for appropriate places to ask questions.
diff --git a/user/downloading-installing-upgrading/installation-guide.md b/user/downloading-installing-upgrading/installation-guide.md
index 6c9361ad..7b755c34 100644
--- a/user/downloading-installing-upgrading/installation-guide.md
+++ b/user/downloading-installing-upgrading/installation-guide.md
@@ -111,19 +111,21 @@ Once you access your computer's BIOS or UEFI menu, you'll want to go to the "boo
Once you're done on the boot menu, save your changes. How you do this depends on your BIOS or UEFI, but the instructions should be displayed right there on the screen or in a nearby tab. (If you're not sure whether you've saved your changes correctly, you can always reboot your computer and go back into the boot menu to check whether it still reflects your changes.) Once your BIOS or UEFI is configured the way you want it, reboot your computer. This time, don't press any special keys. Instead, let the BIOS or UEFI load and let your computer boot from your USB drive. If you're successful in this step, after a few seconds you'll be presented with the Qubes installer screen:
-[![Boot screen](/attachment/doc/boot-screen.png)](/attachment/doc/boot-screen.png)
+[![Boot screen](/attachment/doc/boot-screen-4.2.png)](/attachment/doc/boot-screen-4.2.png)
-From here, you can navigate the boot screen using the arrow keys on your keyboard. Pressing the "Tab" key will reveal options. You can choose one of three options:
+From here, you can navigate the boot screen using the arrow keys on your keyboard. Pressing the "Tab" key will reveal options. You can choose one of five options:
* Install Qubes OS
* Test this media and install Qubes OS
-* Troubleshooting
+* Troubleshooting - verbose boot
+* Rescue a Qubes SO system
+* Install Qubes OS 4.2.1 using kernel-latest
Select the option to test this media and install Qubes OS.
-
Note: If the latest stable release is not compatible with your hardware, you may wish to consider
testing a newer release.
+
Note: If the latest stable release is not compatible with your hardware, you may wish to consider installing using the latest kernel. Be aware that this has not been as well testes as the standard kernel.
If the boot screen does not appear, there are several options to troubleshoot. First, try rebooting your computer. If it still loads your currently installed operating system or does not detect your installation medium, make sure the boot order is set up appropriately. The process to change the boot order varies depending on the currently installed system and the motherboard manufacturer. If **Windows 10** is installed on your machine, you may need to follow specific instructions to change the boot order. This may require an [advanced reboot](https://support.microsoft.com/en-us/help/4026206/windows-10-find-safe-mode-and-other-startup-settings).
@@ -132,7 +134,7 @@ If the boot screen does not appear, there are several options to troubleshoot. F
On the first screen, you are asked to select the language that will be used during the installation process. When you are done, select **Continue**.
-[![welcome](/attachment/doc/welcome-to-qubes-os-installation-screen.png)](/attachment/doc/welcome-to-qubes-os-installation-screen.png)
+[![Language selection window](/attachment/doc/welcome-to-qubes-os-installation-screen-4.2.png)](/attachment/doc/welcome-to-qubes-os-installation-screen-4.2.png)
Prior to the next screen, a compatibility test runs to check whether IOMMU-virtualization is active or not. If the test fails, a window will pop up.
@@ -153,7 +155,7 @@ Like Fedora, Qubes OS uses the Anaconda installer. Those that are familiar with
The Installation summary screen allows you to change how the system will be installed and configured, including localization settings. At minimum, you are required to select the storage device on which Qubes OS will be installed.
-[![Installation summary not ready](/attachment/doc/installation-summary-not-ready.png)](/attachment/doc/installation-summary-not-ready.png)
+[![Installation summary screen awaiting input ](/attachment/doc/installation-summary-not-ready-4.2.png)](/attachment/doc/installation-summary-not-ready-4.2.png)
### Localization
@@ -170,24 +172,6 @@ You can have as many keyboard layout and languages as you want. Post-install, yo
Don't forget to select your time and date by clicking on the Time & Date entry.
[![Time and date](/attachment/doc/time-and-date.png)](/attachment/doc/time-and-date.png)
-
-### Software
-
-[![Add-ons](/attachment/doc/add-ons.png)](/attachment/doc/add-ons.png)
-
-On the software selection tab, you can choose which software to install in Qubes OS. Two options are available:
-
-* **Debian:** Select this option if you would like to use [Debian](/doc/templates/debian/) qubes in addition to the default Fedora qubes.
-* **Whonix:** Select this option if you would like to use [Whonix](https://www.whonix.org/wiki/Qubes) qubes. Whonix allows you to use [Tor](https://www.torproject.org/) securely within Qubes.
-
-Whonix lets you route some or all of your network traffic through Tor for greater privacy. Depending on your threat model, you may need to install Whonix templates right away.
-
-Regardless of your choices on this screen, you will always be able to install these and other [templates](/doc/templates/) later. If you're short on disk space, you may wish to deselect these options.
-
-By default, Qubes OS comes preinstalled with the lightweight Xfce4 desktop environment. Other desktop environments will be available to you after the installation is completed, though they may not be officially supported (see [advanced topics](/doc/#advanced-topics)).
-
-Press **Done** to go back to the installation summary screen.
-
### Installation destination
Under the System section, you must choose the installation destination. Select the storage device on which you would like to install Qubes OS.
@@ -206,7 +190,7 @@ Your installation destination can be an internal or external storage drive, such
Installing an operating system onto a USB drive can be a convenient way to try Qubes. However, USB drives are typically much slower than internal SSDs. We recommend a very fast USB 3.0 drive for decent performance. Please note that a minimum storage of 32 GiB is required. If you want to install Qubes OS onto a USB drive, just select the USB device as the target installation device. Bear in mind that the installation process is likely to take longer than it would on an internal storage device.
-[![Select storage device](/attachment/doc/select-storage-device.png)](/attachment/doc/select-storage-device.png)
+[![Select storage device screen](/attachment/doc/select-storage-device-4.2.png)](/attachment/doc/select-storage-device-4.2.png)
@@ -220,21 +204,22 @@ As soon as you press **Done**, the installer will ask you to enter a passphrase
Warning: If you forget your encryption passphrase, there is no way to recover it.
-[![Select storage passhprase](/attachment/doc/select-storage-passphrase.png)](/attachment/doc/select-storage-passphrase.png)
-
-When you're ready, press **Begin Installation**.
-
-[![Installation summary ready](/attachment/doc/installation-summary-ready.png)](/attachment/doc/installation-summary-ready.png)
+[![Select storage passphrase](/attachment/doc/select-storage-passphrase.png)](/attachment/doc/select-storage-passphrase.png)
### Create your user account
-While the installation process is running, you can create your user account. This is what you'll use to log in after disk decryption and when unlocking the screen locker. This is a purely local, offline account in dom0. By design, Qubes OS is a single-user operating system, so this is just for you.
+Select "User Creation" to create your user account. This is what you'll use to log in after disk decryption and when unlocking the screen locker. This is a purely local, offline account in dom0. By design, Qubes OS is a single-user operating system, so this is just for you.
-Select **User Creation** to define a new user with administrator privileges and a password. Just as for the disk encryption, this password should be complex. The root account is deactivated and should remain as such.
+The new user you create has full administrator privileges and is protected by a password. Just as for the disk encryption, this password should be complex. The root account is deactivated and should remain as such.
-[![Account name and password](/attachment/doc/account-name-and-password.png)](/attachment/doc/account-name-and-password.png)
+[![Account name and password creation window. ](/attachment/doc/account-name-and-password-4.2.png)](/attachment/doc/account-name-and-password-4.2.png)
-When the installation is complete, press **Reboot**. Don't forget to remove the installation medium, or else you may end up seeing the installer boot screen again.
+### Installation
+When you have completed all the items marked with the warning icon, press **Begin Installation**.
+
+Installation can take some time.
+[![Windows showing installation complete and Reboot button. ](/attachment/doc/installation-complete-4.2.png)](/attachment/doc/installation-complete-4.2.png)
+When the installation is complete, press **Reboot System**. Don't forget to remove the installation medium, or else you may end up seeing the installer boot screen again.
## Post-installation
@@ -246,31 +231,32 @@ If the installation was successful, you should now see the GRUB menu during the
Just after this screen, you will be asked to enter your encryption passphrase.
-[![Unlock storage device screen](/attachment/doc/unlock-storage-device-screen.png)](/attachment/doc/unlock-storage-device-screen.png)
+[![Screen to enter device decryption password](/attachment/doc/unlock-storage-device-screen-4.2.png)](/attachment/doc/unlock-storage-device-screen-4.2.png)
### Initial Setup
You're almost done. Before you can start using Qubes OS, some configuration is needed.
-[![Initial setup menu](/attachment/doc/initial-setup-menu.png)](/attachment/doc/initial-setup-menu.png)
+[![Window with link for final configuration ](/attachment/doc/initial-setup-menu-4.2.png)](/attachment/doc/initial-setup-menu-4.2.png)
+Click on the item marked with the warning triangle to enter the configuration screen.
+[![Initial configuration menu](/attachment/doc/initial-setup-menu-configuration-4.2.png)](/attachment/doc/initial-setup-menu-configuration-4.2.png)
By default, the installer will create a number of qubes (depending on the options you selected during the installation process). These are designed to give you a more ready-to-use environment from the get-go.
-[![Initial setup menu configuration](/attachment/doc/initial-setup-menu-configuration.png)](/attachment/doc/initial-setup-menu-configuration.png)
-
Let's briefly go over the options:
-* **Create default system qubes:** These are the core components of the system, required for things like internet access.
+* **Templates Configuration:** Here you can decide which [templates](../templates/) you want to have installed, and which will be the default template.
+* **Create default system qubes:** These are the core components of the system, required for things like internet access. You can opt to have some created as [disposables](../glossary#disposable)
* **Create default application qubes:** These are how you compartmentalize your digital life. There's nothing special about the ones the installer creates. They're just suggestions that apply to most people. If you decide you don't want them, you can always delete them later, and you can always create your own.
-* **Create Whonix Gateway and Workstation qubes:** If you want to use Whonix, you should select this option.
- * **Enabling system and template updates over the Tor anonymity network using Whonix:** If you select this option, then whenever you install or update software in dom0 or a template, the internet traffic will go through Tor.
-* **Create USB qube holding all USB controllers:** Just like the network qube for the network stack, the USB qube isolates the USB controllers.
+* **Use a qube to hold all USB controllers:** Just like the network qube for the network stack, the USB qube isolates the USB controllers.
* **Use sys-net qube for both networking and USB devices:** You should select this option if you rely on a USB device for network access, such as a USB modem or a USB Wi-Fi adapter.
-* **Do not configure anything:** This is for very advanced users only. If you select this option, you'll have to set everything up manually afterward.
+* **Create Whonix Gateway and Workstation qubes:** If you want to use [Whonix](https://www.whonix.org/wiki/Qubes), you should select this option.
+ * **Enabling system and template updates over the Tor anonymity network using Whonix:** If you select this option, then whenever you install or update software in dom0 or a template, the internet traffic will go through Tor.
+* **Do not configure anything:** This is for very advanced users only. If you select this option, you will have to manually set up everything.
-When you're satisfied with you choices, press **Done**. This configuration process may take a while, depending on the speed and compatibility of your system.
+When you're satisfied with your choices, press **Done**. This configuration process may take a while, depending on the speed and compatibility of your system.
-After the configuration is done, you will be greeted by the login screen. Enter your password and log in.
+After configuration is done, you will be greeted by the login screen. Enter your password and log in.
[![Login screen](/attachment/doc/login-screen.png)](/attachment/doc/login-screen.png)
@@ -313,3 +299,4 @@ Find out [Getting Started](/doc/getting-started/) with Qubes, check out the othe
* If you don't find your answer in the documentation, please see [Help, Support, Mailing Lists, and Forum](/support/) for places to ask.
* Please do **not** email individual members of the Qubes team with questions about installation or other problems. Instead, please see [Help, Support, Mailing Lists, and Forum](/support/) for appropriate places to ask questions.
+
diff --git a/user/security-in-qubes/firewall.md b/user/security-in-qubes/firewall.md
index 3cb7c42b..d4597e39 100644
--- a/user/security-in-qubes/firewall.md
+++ b/user/security-in-qubes/firewall.md
@@ -66,12 +66,16 @@ Normally Qubes doesn't let the user stop a NetVM if there are other qubes runnin
But in case the NetVM stops for whatever reason (e.g. it crashes, or the user forces its shutdown via qvm-kill via terminal in Dom0), Qubes R4.x will often automatically repair the connection.
If it does not, then there is an easy way to restore the connection to the NetVM by issuing in dom0:
-` qvm-prefs netvm `
+```
+qvm-prefs netvm
+```
Normally qubes do not connect directly to the actual NetVM (sys-net by default) which has networking devices, but rather to the default sys-firewall first, and in most cases it would be the NetVM that will crash, e.g. in response to S3 sleep/restore or other issues with WiFi drivers.
In that case it is only necessary to issue the above command once, for the sys-firewall (this assumes default VM-naming used by the default Qubes installation):
-` qvm-prefs sys-firewall netvm sys-net `
+```
+qvm-prefs sys-firewall netvm sys-net
+```
Network service qubes
---------------------
@@ -304,12 +308,12 @@ nft add rule qubes custom-forward iif == "ens6" ip saddr 192.168.x.y/24 ip daddr
> Note: If you do not wish to limit the IP addresses connecting to the service, remove `ip saddr 192.168.x.y/24` from the rules
-> If you want to expose the service on multiple interfaces, repeat the steps 2 and 3 described above, for each interface.
+> If you want to expose the service on multiple interfaces, repeat the steps 2 and 3 described above, for each interface. Alternatively, you can leave out the interface completely.
Verify the rules on sys-net firewall correctly match the packets you want by looking at its counters, check for the counter lines in the chains `custom-forward` and `custom-dnat-qubeDEST`:
```
-nft list table ip qubes-firewall
+nft list table ip qubes
```
In this example, we can see 7 packets in the forward rule, and 3 packets in the dnat rule:
@@ -331,7 +335,7 @@ chain custom-dnat-qubeDEST {
telnet 192.168.x.n 443
```
-Once you have confirmed that the counters increase, store the commands used in the previous steps in `/rw/config/rc.local` so they get set on sys-net start-up:
+Once you have confirmed that the counters increase, store the commands used in the previous steps in `/rw/config/qubes-firewall-user-script` so they get set on sys-net start-up:
```
[user@sys-net user]$ sudo -i
diff --git a/user/security-in-qubes/yubi-key.md b/user/security-in-qubes/mfa.md
similarity index 60%
rename from user/security-in-qubes/yubi-key.md
rename to user/security-in-qubes/mfa.md
index a4cdfc68..3d7e7ce0 100644
--- a/user/security-in-qubes/yubi-key.md
+++ b/user/security-in-qubes/mfa.md
@@ -1,32 +1,126 @@
---
lang: en
layout: doc
-permalink: /doc/yubikey/
+permalink: /doc/mfa/
redirect_from:
- /doc/yubi-key/
- /en/doc/yubi-key/
- /doc/YubiKey/
+- /doc/yubikey/
ref: 169
-title: YubiKey
+title: Multi-factor Login
---
+
+## Multi-factor authentication within particular qubes
+
+Most use cases for the hardware tokens can be achieved exactly as described by the
+manufacturer or other instructions found online. One usually just needs to
+attach the token (e.g. YubiKey) to the corresponding app qube to get the same
+result (see the documentation on how to use [USB devices](/doc/how-to-use-usb-devices/)
+in Qubes OS accordingly). The recommended way for using CTAP in Qubes is described
+[here](https://www.qubes-os.org/doc/ctap-proxy/).
+
+## Multi-factor login for Qubes OS
+
+By default Qubes has two protection mechanisms against attackers. The first is full disk encryption and the second the user login screen / lockscreen. This article section concerns only adding multi-factor authentication to the second one.
+
+### Time-based One-time Password (TOTP)
+
+As the name implies, this generates authentication code that is time-dependent. You can save the TOTP secret in a mobile app like [FreeOTP](https://en.wikipedia.org/wiki/FreeOTP)
+and then use it as an additional factor to login to your Qubes system.
+
+> **Warning**: remember to keep backup access codes.
+
+1. Download `google-authenticator` in dom0:
+
+ ```
+ sudo qubes-dom0-update google-authenticator
+ ```
+
+2. Run google authenticator:
+
+ ```
+ google-authenticator
+ ```
+
+3. Walk through the setup instructions 2 which will also generate your QR code for your auth app of choice:
+
+ ```
+ Do you want me to update your “/home/user/.google_authenticator” file (y/n) y
+
+ Do you want to disallow multiple uses of the same authentication token? This restricts you to one login about every 30s, but it increases your chances to notice or even prevent man-in-the-middle attacks (y/n)
+
+ By default, tokens are good for 30 seconds, and to compensate for possible time-skew between the client and the server, we allow an extra token before and after the current time. If you experience problems with poor time synchronization, you can increase the window from its default size of 1:30min to about 4min. Do you want to do so (y/n)
+
+ If the computer that you are logging into isn’t hardened against brute-force login attempts, you can enable rate-limiting for the authentication module. By default, this limits attackers to no more than 3 login attempts every 30s. Do you want to enable rate-limiting (y/n)
+ ```
+
+> **Warning**: in the next session if incorrectly performed, there is the risk of locking yourself out. Before procedding ensure that you have an up-to-date backup.
+>
+> For advanced users, to make sure you can quickly recover, you can also open another loging session in a tty. To do this, you do ctrl+alt+F2 and login normally. Should anything go wrong, as long as you don't shut the computer down, you can still access this tty by entering the same key combination and reverting the changes. After you've opened this "backup" login, you can get to your graphical desktop with ctrl+alt+F1.
+
+Now we are going to add the authenticator as a login requirement:
+
+1. `sudo authselect create-profile mfa --base-on sssd`
+
+2. Edit the custom system authentication template with `sudo nanois encouraged /etc/authselect/custom/mfa/system-auth`.
+
+ Add the following line right after `auth required pam_faildelay.so delay=2000000`:
+
+ ```
+ auth required pam_google_authenticator.so
+ ```
+
+ After the change, the top of the file should look like this:
+
+ ```
+ {imply "with-smartcard" if "with-smartcard-required"}
+ auth required pam_env.so
+ auth required pam_faildelay.so delay=2000000
+ auth required pam_google_authenticator.so
+ ```
+
+3. Lastly, activate this authentication method with:
+
+ ```
+ sudo authselect select custom/mfa
+ ```
+
+Now you can test by locking the screen with ctrl+alt+l. If it was successful and you are pleased with the results, restart your computer.
+
+**Note**: When logging in. the first thing you put is the TOTP secret and then the password. This is true in the screen locker and as well as the session manager (the login window that shows right after you put the disk encryption passphrase).
+
+After this is done, its recommended to do a backup. This is because as long as you incude dom0 in the backup, your authentication code will be backed up as well.
+
+#### Troubleshooting
+
+The following assumes you haven't restarted your computer since setting up TOTP secret.
+
+1. Switch to TTY2 with ctrl+alt+F2.
+2. Revert to the original policy with:
+ ```
+ sudo authselect select sssd
+ ```
+3. Switch back to the graphical desktop with ctrl+alt+F1. You should be able to login normally (without multi-factor authentication).
+4. Change the mfa custom policy and apply it again.
+
+#### Lost TOTP / authentication device?
+
+In case you've lost your TOTP authentication device, you have two options.
+
+The first option is backup codes. When generating the TOTP secret you must have saved some recovery codes. Those can be used in place of the TOTP code, but they're discarded after use. So make sure you redo the multi-factor authentications intructions.
+
+The second option is recovery from a backup. It will work as long as you included dom0 in said backup. After restoring the dom0 backup, open a terminal in dom0 and the file should be located in `/home//home-restore-/dom0-home//.google_authenticator`.
+
+### Login with a YubiKey
+
"The YubiKey is a hardware authentication device manufactured by Yubico to
protect access to computers, networks, and online services that supports
one-time passwords (OTP), public-key cryptography, and authentication, and the
Universal 2nd Factor (U2F) and FIDO2 protocols[1] developed by the FIDO
Alliance." ([Wikipedia](https://en.wikipedia.org/wiki/YubiKey))
-## General usage in Qubes OS
-
-Most use cases for the YubiKey can be achieved exactly as described by the
-manufacturer or other instructions found online. One usually just needs to
-attach the YubiKey to the corresponding app qube to get the same result (see the
-documentation on how to use [USB devices](/doc/how-to-use-usb-devices/) in Qubes
-OS accordingly). The recommended way for using CTAP in Qubes is described
-[here](https://www.qubes-os.org/doc/ctap-proxy/).
-
-## Multi-factor login for Qubes OS
-
You can use a YubiKey to enhance the user authentication in Qubes. The following
instructions explain how to setup the YubiKey as an *additional* way to login.
@@ -45,7 +139,7 @@ during setup and b) you do not need to fear [shoulder
surfing](https://en.wikipedia.org/wiki/Shoulder_surfing_(computer_security)) so
much (i.e. by not using your standard login password in public).
-### Setup login with YubiKey
+#### Setup login with YubiKey
To use the YubiKey for multi-factor authentication you need to
@@ -90,7 +184,7 @@ All these requirements are described below, step by step.
YubiKey](https://www.qubes-os.org/doc/how-to-use-usb-devices/) to this app qube
though) or directly on the sys-usb vm.
- You need to (temporarily) install the package "yubikey-personalization-gui" and
+ You need to (temporarily) install the package "yubikey-personalization-gui" and
run it by typing `yubikey-personalization-gui` in the command line.
- In the program go to `Challenge-Response`,
@@ -154,7 +248,7 @@ these files, otherwise it will most likely not work.
7. Adjust the USB VM name in case you are using something other than the default
`sys-usb` by editing `/etc/qubes/yk-keys/yk-vm` in dom0.
-### Usage
+#### Usage
When you want to authenticate
@@ -169,7 +263,7 @@ When everything is ok, your screen will be unlocked.
In any case you can still use your normal login password, but do it in a secure
location where no one can snoop your password.
-### Optional: Enforce YubiKey Login
+#### Optional: Enforce YubiKey Login
Edit `/etc/pam.d/yubikey` (or appropriate file if you are using other screen locker program) and remove `default=ignore` so the line looks like this.
@@ -177,7 +271,7 @@ Edit `/etc/pam.d/yubikey` (or appropriate file if you are using other screen loc
auth [success=done] pam_exec.so expose_authtok quiet /usr/bin/yk-auth
```
-### Optional: Locking the screen when YubiKey is removed
+#### Optional: Locking the screen when YubiKey is removed
Look into it
You can setup your system to automatically lock the screen when you unplug your YubiKey.
diff --git a/user/templates/minimal-templates.md b/user/templates/minimal-templates.md
index 2da511ff..2e7c934e 100644
--- a/user/templates/minimal-templates.md
+++ b/user/templates/minimal-templates.md
@@ -165,6 +165,8 @@ list of packages to be installed):
- `default-mgmt-dvm`: requires `qubes-core-agent-passwordless-root` and
`qubes-mgmt-salt-vm-connector`.
+To manage fedora-39-minimal templates with salt, you may need to install `python3-urllib3` in older versions of the template. (This package is already installed in recent builds: see [discussion](https://github.com/QubesOS/qubes-issues/issues/8806).)
+
In Qubes 4.0, additional packages from the `qubes-core-agent` suite may be
needed to make the customized minimal template work properly. These packages
are:
diff --git a/user/templates/templates.md b/user/templates/templates.md
index bab15cb9..2f7ac64a 100644
--- a/user/templates/templates.md
+++ b/user/templates/templates.md
@@ -273,6 +273,15 @@ new template:
old template by clicking on the first one, holding shift, then clicking on
the last one. With multiple qubes selected, right-click on any of them,
hover your cursor over Template, then click on the new template.
+ Or in the `System` menu select `Manage templates for qubes`, select
+ any qubes using the old template and update them to the new template
+ using the drop down menu.
+
+4. **Change the template for the default-mgmt-dvm** If the old template
+ was used for management qubes, then you should change the template.
+ This is an *internal* qube which does not appear by default in the Qube manager.
+ In the `System` menu select `Manage templates for qubes`, and you will see the *default-mgmt-dvm* qube.
+ Change the template used for this disposable template to the new template.
## Advanced