From 2713aefdea22bf44b19058fc9de5e1a1e77fb026 Mon Sep 17 00:00:00 2001 From: Neowutran Date: Sun, 10 May 2020 09:43:49 +0200 Subject: [PATCH 001/663] [Kali] remove obsolete section (r3.0, katoolin) --- external/os-guides/pentesting/kali.md | 546 ++++---------------------- 1 file changed, 70 insertions(+), 476 deletions(-) diff --git a/external/os-guides/pentesting/kali.md b/external/os-guides/pentesting/kali.md index 09a7bda7db..cb182c54de 100644 --- a/external/os-guides/pentesting/kali.md +++ b/external/os-guides/pentesting/kali.md @@ -19,291 +19,6 @@ redirect_from: - Kali Linux distribution is a rolling distribution based constantly on Debian testing release, so it always will have newer software base than available in Qubes OS debian template. Keep in mind that it may result in problems (especially in regard to package dependency) not covered by this tutorial. -## Qubes 3.2 - -### How to Create a Kali Linux VM - -This guide is being created to give guidance on ways in which you could create a [Kali Linux][kali] penetration testing VM (qube) in Qubes OS. - -Kali Linux is the most widely used penetration testing Linux distribution. - -There are multiple ways to create a Kali Linux VM: - - 1. Create a HVM and use the official ISO to install the system or convert a [Virtual Image][kali-vbox]. Explained [here](#hvm3_2). - 2. Clone the Qubes OS latest Debian template image and turn it into a Kali Linux distribution: - - using [katoolin]. Explained [here](#katoolin3_2). - - manually. Explained [here](#templatevm-from-debian3_2). - -### Kali Linux HVM - -1. Download the Kali installation DVD - -2. Create a new HVM - -3. Start the HVM with attached CD/DVD - - [user@dom0 ~]$ qvm-start --cdrom :/home/user/Downloads/.iso - -### Debian based Kali Template with Katoolin - -**Note:** The prompt on each line indicates where each command should be entered (`@dom0`, `@debian-` or `@kali`). - -1. (Optional) Check for latest Debian stable template and install it (if not already done) - - [user@dom0 ~]$ sudo qubes-dom0-update --action="search all" qubes-template-debian - [user@dom0 ~]$ sudo qubes-dom0-update - -2. Start, update and close your latest Debian template - - [user@dom0 ~]$ qvm-start debian- - [user@dom0 ~]$ qvm-run -a debian- gnome-terminal - [user@debian- ~]$ sudo apt-get update - [user@debian- ~]$ sudo apt-get upgrade - [user@dom0 ~]$ qvm-shutdown debian- - -3. Clone `debian-` template (two options) - - 1. Via Qubes VM Manager - - ![Clone Debian Template](/attachment/wiki/Kali/clone-kali.png) - - 2. Via command line - - [user@dom0 ~]$ qvm-clone debian- kali - -4. Check the name of currently used repository in `/etc/apt/sources.list` and current testing [Debian release][Debian-releases]. Update repository list accordingly - - [user@kali ~]$ sudo sed -i 's///g' /etc/apt/sources.list - [user@kali ~]$ sudo sed -i 's///g' /etc/apt/sources.list.d/qubes-r.list - - e.g. in this example we update `stretch` stable repository to `buster` testing repository - - [user@kali ~]$ sudo sed -i 's/stretch/buster/g' /etc/apt/sources.list - [user@kali ~]$ sudo sed -i 's/stretch/buster/g' /etc/apt/sources.list.d/qubes-r.list - -5. Upgrade `kali` template to latest Debian testing release - - [user@kali ~]$ sudo apt-get update - [user@kali ~]$ sudo apt-get dist-upgrade - [user@kali ~]$ sudo apt-get autoremove - - **Note:** During execution of a `dist-upgrade` command read carefully list of packages to be removed. - If it contains `qubes-*` packages, terminate operation and try to resolve `qubes-*` packages missing dependencies first. - -6. Install Katoolin and add Kali Linux repositories - - 1. Install Katoolin - - [user@kali ~]$ sudo apt-get install git - [user@kali ~]$ git clone https://github.com/LionSec/katoolin.git - [user@kali ~]$ sudo cp katoolin/katoolin.py /usr/bin/katoolin - [user@kali ~]$ sudo chmod +x /usr/bin/katoolin - [user@kali ~]$ rm -rf katoolin - - 2. Add Kali Linux repositories - - - start katoolin - - [user@kali ~]$ sudo katoolin - - - select 'Add Kali repositories & Update' - - 1) Add Kali repositories & Update - 2) View Categories - 3) Install classicmenu indicator - 4) Install Kali menu - 5) Help - - kat > 1 - - ![Add Kali repositories and Update menu](/attachment/wiki/Kali/katoolin-add-update-repo-menu.png) - - - select 'Add kali linux repositories' - - 1) Add kali linux repositories - 2) Update - 3) Remove all kali linux repositories - 4) View the contents of sources.list file - - What do you want to do ?> 1 - - ![Add Kali repositories](/attachment/wiki/Kali/katoolin-add-repos-menu.png) - - - update Kali repositories - - - 1) Add kali linux repositories - 2) Update - 3) Remove all kali linux repositories - 4) View the contents of sources.list file - - What do you want to do ?> 2 - - - quit katoolin by pressing `CRTL` + `c` keys - - What do you want to do ?> ^CShutdown requested...Goodbye... - -7. Clean up and update `kali` template - - [user@kali ~]$ sudo apt-get dist-upgrade - [user@kali ~]$ sudo apt-get autoremove - -8. Shut down `kali` template - - [user@kali ~]$ sudo shutdown -h now - -9. Start image - - [user@dom0 ~]$ qvm-start kali - -10. Install tools - - **Note** [Resize the template disk image][qubes-resize-disk-image] to at least 20GB if you plan on installing all packages from Kali distribution. - - 1. View Categories - - - start katoolin - - [user@kali ~]$ sudo katoolin - - - select `2) View Categories` - - 2. Select the categories/tools you want to install - - - For more information on how to use Katoolin see [How to Auto Install All Kali Linux Tools Using “Katoolin” on Debian/Ubuntu][katoolin-howto]. - - - **Note:** The `all` option does not work for `Information Gathering`, `Web Apps`, `Forensic Tools`, `Reverse Engineering` and `Extra`. - -11. Create a AppVMs based on the `kali` template - - - (Optional) Attach necessary devices - -### Kali Linux TemplateVM from a Debian template - -This section will explain how to create your own [Kali] Linux TemplateVM based -on a current stable Debian TemplateVM. The basic idea is to personalize the -template with all the tools needed, and then spin up isolated AppVMs based on -the template. - -The steps can be summarised as: - -1. Install Qubes stable Debian template -2. Upgrade the template to Debian testing release -3. Install Kali Linux through the ``kali-linux-full`` package -4. Use the template to build AppVM so that you can maintain isolation between - e.g. pentesting jobs - -#### Get Kali Linux GPG key - -**CAUTION:** Before proceeding, please carefully read [On Digital Signatures and Key Verification][qubes-verifying-signatures]. -This website cannot guarantee that any PGP key you download from the Internet is authentic. -Always obtain a trusted key fingerprint via other channels, and always check any key you download against your trusted copy of the fingerprint. - -This step is required since by (security) default a TemplateVM do not have a -direct Internet connectivity. Users understanding the risks of enabling such -access can change this configuration in firewall settings for the TemplateVM. - -**Note:** The prompt on each line indicates where each command should be entered -(`@dom0`, `@kali-rolling`, `@xxxx-dvm` or `@debian-`). - -1. Retrive the Kali Linux GPG key using a DispVM. - - [user@xxxx-dvm ~]$ gpg --keyserver hkp://keys.gnupg.net --recv-key 44C6513A8E4FB3D30875F758ED444FF07D8D0BF6 - [user@xxxx-dvm ~]$ gpg --list-keys --with-fingerprint 44C6513A8E4FB3D30875F758ED444FF07D8D0BF6 - [user@xxxx-dvm ~]$ gpg --export --armor 44C6513A8E4FB3D30875F758ED444FF07D8D0BF6 > kali-key.asc - -2. **DO NOT TURN OFF** the DispVM, the `kali-key.asc` file will be copied to - the Kali Linux template in a further step. - -3. Make sure the key is the authentic Kali key. - See the [Kali website] for further advice and instructions on verification. - -#### Create a Kali Linux (rolling) template - -These instructions will show you how to upgrade a Debian TemplateVM to Kali Linux. - -1. (Optional) Check for latest Debian stable template and install it (if not already done) - - [user@dom0 ~]$ sudo qubes-dom0-update --action="search all" qubes-template-debian - [user@dom0 ~]$ sudo qubes-dom0-update - -2. Start, update and close your latest Debian template - - [user@dom0 ~]$ qvm-start debian- - [user@dom0 ~]$ qvm-run -a debian- gnome-terminal - [user@debian- ~]$ sudo apt-get update - [user@debian- ~]$ sudo apt-get upgrade - [user@dom0 ~]$ qvm-shutdown debian- - -3. Clone `debian-X` template - - [user@dom0 ~]$ qvm-clone debian- kali-rolling - -4. Check the name of currently used repository in `/etc/apt/sources.list` and current testing [Debian release][Debian-releases]. Update repository list accordingly - - [user@kali-rolling ~]$ sudo sed -i 's///g' /etc/apt/sources.list - [user@kali-rolling ~]$ sudo sed -i 's///g' /etc/apt/sources.list.d/qubes-r.list - - e.g. in this example we update `stretch` stable repository to `buster` testing repository - - [user@kali-rolling ~]$ sudo sed -i 's/stretch/buster/g' /etc/apt/sources.list - [user@kali-rolling ~]$ sudo sed -i 's/stretch/buster/g' /etc/apt/sources.list.d/qubes-r.list - -5. Upgrade `kali-rolling` template to latest Debian testing release - - [user@kali-rolling ~]$ sudo apt-get update - [user@kali-rolling ~]$ sudo apt-get dist-upgrade - [user@kali-rolling ~]$ sudo apt-get autoremove - -**Note:** During execution of a `dist-upgrade` command read carefully list of packages to be removed. If it contains `qubes-*` packages, terminate operation and try to resolve `qubes-*` packages missing dependencies first. - -6. Copy the Kali GPG key from the DispVM to the new template: - - [user@xxxx-dvm ~]$ qvm-copy-to-vm kali-rolling kali-key.asc - - The DispVM can now be turned off. - -7. Add the Kali GPG key to the list of keys trusted to authenticate packages: - - [user@kali-rolling ~]$ cat /home/user/QubesIncoming/dispXXX/kali-key.asc | sudo apt-key add - - - This command should return `OK` on a line by itself. - -8. Attempt the upgrade process in the new template. - - [user@kali-rolling ~]$ sudo cat < /etc/apt/sources.list.d/kali.list - # Kali Linux repository - deb http://http.kali.org/kali kali-rolling main non-free contrib - EOF - [user@kali-rolling ~]$ sudo apt-get update - [user@kali-rolling ~]$ sudo apt-get dist-upgrade - [user@kali-rolling ~]$ sudo apt-get autoremove - -9. Shut down the new template. - - [user@dom0 ~]$ qvm-shutdown kali-rolling - -10. Ensure a terminal can be opened in the new template. - - [user@dom0 ~]$ qvm-run -a kali-rolling gnome-terminal - -#### Install the Kali tools - -At this point you should have a working template and you can install the tools you need. - -1. [Resize the template disk image][qubes-resize-disk-image] if you plan on installing the full Kali distribution. For example to install `kali-linux-full` you must **grow** the size of the VM system from 10GB to at least 20GB. - -2. Install Kali Linux tools: - - [user@kali-rolling ~]$ sudo apt-get install kali-linux-full - -3. (Optional) Customise the template's home directory (e.g. install your licensed copy of Burp Suite Professional) - -#### Use the template - -The template is ready to be used. You can now spin up AppVMs based on the `kali-rolling` template. - - ## Qubes 4.0 ### How to Create a Kali Linux VM @@ -327,137 +42,9 @@ There are multiple ways to create a Kali Linux VM: 3. Start the HVM with attached CD/DVD - [user@dom0 ~]$ qvm-start --cdrom :/home/user/Downloads/.iso - -### Debian based Kali Template with Katoolin - -**Note:** The prompt on each line indicates where each command should be entered (`@dom0`, `@debian-` or `@kali`). - -1. (Optional) Check for latest Debian stable template and install it (if not already done) - - [user@dom0 ~]$ sudo qubes-dom0-update --action="search all" qubes-template-debian - [user@dom0 ~]$ sudo qubes-dom0-update - -2. Start, update and close your latest Debian template - - [user@dom0 ~]$ qvm-start debian- - [user@dom0 ~]$ qvm-run -a debian- gnome-terminal - [user@debian- ~]$ sudo apt-get update - [user@debian- ~]$ sudo apt-get upgrade - [user@dom0 ~]$ qvm-shutdown debian- - -3. Clone `debian-` template (two options) - - 1. Via Qubes VM Manager - - ![Clone Debian Template](/attachment/wiki/Kali/clone-kali.png) - - 2. Via command line - - [user@dom0 ~]$ qvm-clone debian- kali - -4. Check the name of currently used repository in `/etc/apt/sources.list` and current testing [Debian release][Debian-releases]. Update repository list accordingly. - - [user@kali ~]$ sudo sed -i 's///g' /etc/apt/sources.list - [user@kali ~]$ sudo sed -i 's///g' /etc/apt/sources.list.d/qubes-r.list - - e.g. in this example we update `stretch` stable repository to `buster` testing repository - - [user@kali ~]$ sudo sed -i 's/stretch/buster/g' /etc/apt/sources.list - [user@kali ~]$ sudo sed -i 's/stretch/buster/g' /etc/apt/sources.list.d/qubes-r.list - -For installation based on Debian 10 stable, please note that the security repository of Debian testing has [recently been renamed][Debian-security-naming-convention] from `/update` to `-security`. To account for that change, execute the following command. - - [user@kali ~]$ sudo sed -i 's/bullseye\/updates/bullseye-security/g' /etc/apt/sources.list - -5. Upgrade `kali` template to latest Debian testing release - - [user@kali ~]$ sudo apt-get update - [user@kali ~]$ sudo apt-get dist-upgrade - [user@kali ~]$ sudo apt-get autoremove - - **Note:** During execution of a `dist-upgrade` command read carefully list of packages to be removed. - If it contains `qubes-*` packages, terminate operation and try to resolve `qubes-*` packages missing dependencies first. - -6. Install Katoolin and add Kali Linux repositories - - 1. Install Katoolin - - [user@kali ~]$ sudo apt-get install git - [user@kali ~]$ git clone https://github.com/LionSec/katoolin.git - [user@kali ~]$ sudo cp katoolin/katoolin.py /usr/bin/katoolin - [user@kali ~]$ sudo chmod +x /usr/bin/katoolin - [user@kali ~]$ rm -rf katoolin - - 2. Add Kali Linux repositories - - - start katoolin - - [user@kali ~]$ sudo katoolin - - - select 'Add Kali repositories & Update' - - 1) Add Kali repositories & Update - 2) View Categories - 3) Install classicmenu indicator - 4) Install Kali menu - 5) Help - - kat > 1 - - ![Add Kali repositories and Update menu](/attachment/wiki/Kali/katoolin-add-update-repo-menu.png) - - - select 'Add kali linux repositories' - - 1) Add kali linux repositories - 2) Update - 3) Remove all kali linux repositories - 4) View the contents of sources.list file - - What do you want to do ?> 1 - - ![Add Kali repositories](/attachment/wiki/Kali/katoolin-add-repos-menu.png) - - - update Kali repositories - - - 1) Add kali linux repositories - 2) Update - 3) Remove all kali linux repositories - 4) View the contents of sources.list file - - What do you want to do ?> 2 - - - quit katoolin by pressing `CRTL` + `c` keys - - What do you want to do ?> ^CShutdown requested...Goodbye... - -7. Clean up and update `kali` template - - [user@kali ~]$ sudo apt-get dist-upgrade - [user@kali ~]$ sudo apt-get autoremove - -8. Install tools - - **Note** [Resize the template disk image][qubes-resize-disk-image] to at least 20GB if you plan on installing all packages from Kali distribution. - - 1. View Categories - - - start katoolin - - [user@kali ~]$ sudo katoolin - - - select `2) View Categories` - - 2. Select the categories/tools you want to install - - - For more information on how to use Katoolin see [How to Auto Install All Kali Linux Tools Using “Katoolin” on Debian/Ubuntu][katoolin-howto]. - - - **Note:** The `all` option does not work for `Information Gathering`, `Web Apps`, `Forensic Tools`, `Reverse Engineering` and `Extra`. - -9. Create a AppVMs based on the `kali` template - - - (Optional) Attach necessary devices +```shell_session +$ qvm-start --cdrom :/home/user/Downloads/.iso +``` ### Kali Linux TemplateVM from a Debian template @@ -470,9 +57,8 @@ The steps can be summarised as: 1. Install Qubes stable Debian template 2. Upgrade the template to Debian testing release -3. Install Kali Linux through the ``kali-linux-full`` package -4. Use the template to build AppVM so that you can maintain isolation between - e.g. pentesting jobs +3. Add the Kali repository +4. Update the template #### Get Kali Linux GPG key @@ -484,14 +70,13 @@ This step is required since by (security) default a TemplateVM do not have a direct Internet connectivity. Users understanding the risks of enabling such access can change this configuration in firewall settings for the TemplateVM. -**Note:** The prompt on each line indicates where each command should be entered -(`@dom0`, `@kali-rolling`, `@xxxx-dvm` or `@debian-`). - 1. Retrive the Kali Linux GPG key using a DispVM. - [user@xxxx-dvm ~]$ gpg --keyserver hkp://keys.gnupg.net --recv-key 44C6513A8E4FB3D30875F758ED444FF07D8D0BF6 - [user@xxxx-dvm ~]$ gpg --list-keys --with-fingerprint 44C6513A8E4FB3D30875F758ED444FF07D8D0BF6 - [user@xxxx-dvm ~]$ gpg --export --armor 44C6513A8E4FB3D30875F758ED444FF07D8D0BF6 > kali-key.asc +```shell_session +$ gpg --keyserver hkp://keys.gnupg.net --recv-key 44C6513A8E4FB3D30875F758ED444FF07D8D0BF6 +$ gpg --list-keys --with-fingerprint 44C6513A8E4FB3D30875F758ED444FF07D8D0BF6 +$ gpg --export --armor 44C6513A8E4FB3D30875F758ED444FF07D8D0BF6 > kali-key.asc +``` 2. **DO NOT TURN OFF** the DispVM, the `kali-key.asc` file will be copied to the Kali Linux template in a further step. @@ -505,85 +90,94 @@ These instructions will show you how to upgrade a Debian TemplateVM to Kali Linu 1. (Optional) Check for latest Debian stable template and install it (if not already done) - [user@dom0 ~]$ sudo qubes-dom0-update --action="search all" qubes-template-debian - [user@dom0 ~]$ sudo qubes-dom0-update +```shell_session +$ sudo qubes-dom0-update --action="search all" qubes-template-debian +$ sudo qubes-dom0-update +``` + +2. Start your latest Debian template + +```shell_session +$ qvm-start debian- +$ qvm-run -a debian- gnome-terminal +``` + +3. Update it + +4. And then close it -2. Start, update and close your latest Debian template +```shell_session +$ qvm-shutdown debian- +``` - [user@dom0 ~]$ qvm-start debian- - [user@dom0 ~]$ qvm-run -a debian- gnome-terminal - [user@debian- ~]$ sudo apt-get update - [user@debian- ~]$ sudo apt-get upgrade - [user@dom0 ~]$ qvm-shutdown debian- +5. Clone `debian-X` template -3. Clone `debian-X` template +```shell_session +$ qvm-clone debian- kali-rolling +``` - [user@dom0 ~]$ qvm-clone debian- kali-rolling +6. Check the name of currently used repository in `/etc/apt/sources.list` and current testing [Debian release][Debian-releases]. Update repository list accordingly -4. Check the name of currently used repository in `/etc/apt/sources.list` and current testing [Debian release][Debian-releases]. Update repository list accordingly +```shell_session +# sed -i 's///g' /etc/apt/sources.list +# sed -i 's///g' /etc/apt/sources.list.d/qubes-r.list +``` - [user@kali-rolling ~]$ sudo sed -i 's///g' /etc/apt/sources.list - [user@kali-rolling ~]$ sudo sed -i 's///g' /etc/apt/sources.list.d/qubes-r.list - - e.g. in this example we update `stretch` stable repository to `buster` testing repository - - [user@kali-rolling ~]$ sudo sed -i 's/stretch/buster/g' /etc/apt/sources.list - [user@kali-rolling ~]$ sudo sed -i 's/stretch/buster/g' /etc/apt/sources.list.d/qubes-r.list +e.g. in this example we update `buster` stable repository to `bullseye` testing repository + + +```shell_session +# sed -i 's/buster/bullseye/g' /etc/apt/sources.list +# sed -i 's/buster/bullseye/g' /etc/apt/sources.list.d/qubes-r.list +``` For installation based on Debian 10 stable, please note that the security repository of Debian testing has [recently been renamed][Debian-security-naming-convention] from `/update` to `-security`. To account for that change, execute the following command. - [user@kali ~]$ sudo sed -i 's/bullseye\/updates/bullseye-security/g' /etc/apt/sources.list +```shell_session +# sed -i 's/bullseye\/updates/bullseye-security/g' /etc/apt/sources.list +``` -5. Upgrade `kali-rolling` template to latest Debian testing release +5. Update the template - [user@kali-rolling ~]$ sudo apt-get update - [user@kali-rolling ~]$ sudo apt-get dist-upgrade - [user@kali-rolling ~]$ sudo apt-get autoremove - -**Note:** During execution of a `dist-upgrade` command read carefully list of packages to be removed. If it contains `qubes-*` packages, terminate operation and try to resolve `qubes-*` packages missing dependencies first. +**Note:** During execution of the update, read carefully list of packages to be removed. If it contains `qubes-*` packages, terminate operation and try to resolve `qubes-*` packages missing dependencies first. 6. Copy the Kali GPG key from the DispVM to the new template: - - [user@xxxx-dvm ~]$ qvm-copy kali-key.asc + +```shell_session +$ qvm-copy kali-key.asc +``` The DispVM can now be turned off. 7. Add the Kali GPG key to the list of keys trusted to authenticate packages: - [user@kali-rolling ~]$ cat /home/user/QubesIncoming/dispXXX/kali-key.asc | sudo apt-key add - +```shell_session +# cat /home/user/QubesIncoming/dispXXX/kali-key.asc | apt-key add - +``` This command should return `OK` on a line by itself. -8. Attempt the upgrade process in the new template. +8. Add the Kali repository - [user@kali-rolling ~]$ sudo cat < /etc/apt/sources.list.d/kali.list - # Kali Linux repository - deb http://http.kali.org/kali kali-rolling main non-free contrib - EOF - [user@kali-rolling ~]$ sudo apt-get update - [user@kali-rolling ~]$ sudo apt-get dist-upgrade - [user@kali-rolling ~]$ sudo apt-get autoremove +```shell_session +# cat < /etc/apt/sources.list.d/kali.list +# Kali Linux repository +deb https://http.kali.org/kali kali-rolling main non-free contrib +EOF +``` -9. Ensure a terminal can be opened in the new template. +9. Update the template - [user@dom0 ~]$ qvm-run -a kali-rolling gnome-terminal +10. Ensure a terminal can be opened in the new template. + +```shell_session +$ qvm-run -a kali-rolling gnome-terminal +``` #### Install the Kali tools At this point you should have a working template and you can install the tools you need. - -1. [Resize the template disk image][qubes-resize-disk-image] if you plan on installing the full Kali distribution. For example to install `kali-linux-full` you must **grow** the size of the VM system from 10GB to at least 20GB. - -2. Install Kali Linux tools: - - [user@kali-rolling ~]$ sudo apt-get install kali-linux-full - -3. (Optional) Customise the template's home directory (e.g. install your licensed copy of Burp Suite Professional) - -#### Use the template - -The template is ready to be used. You can now spin up AppVMs based on the `kali-rolling` template. - +Keep in mind that the tools you will install can easily take more than 10GB, [so you will need to **grow** the size of the VM1][qubes-resize-disk-image] ### Alternative Options to Kali Linux From 96ccb0582a5025fde42f85c75d9b7a47ff9da2d0 Mon Sep 17 00:00:00 2001 From: Neowutran Date: Sun, 10 May 2020 10:09:53 +0200 Subject: [PATCH 002/663] [Kali] add positive and negative points for each methods --- external/os-guides/pentesting/kali.md | 92 ++++++++++----------------- 1 file changed, 35 insertions(+), 57 deletions(-) diff --git a/external/os-guides/pentesting/kali.md b/external/os-guides/pentesting/kali.md index cb182c54de..940cf5d8d7 100644 --- a/external/os-guides/pentesting/kali.md +++ b/external/os-guides/pentesting/kali.md @@ -6,52 +6,32 @@ redirect_from: - /doc/kali/ --- -# How to create a Kali Linux VM - -## Warnings - -- The installation scripts and provided tools may have bugs, be vulnerable to Man in the Middle (MitM) attacks or other vulnerabilities. - -- Adding additional repositories or tools for installing software extends your trust to those tool providers. - -- Please keep in mind that using such a VM or VM's based on the template for security and privacy critical tasks is not recommended. - -- Kali Linux distribution is a rolling distribution based constantly on Debian testing release, so it always will have newer software base than available in Qubes OS debian template. Keep in mind that it may result in problems (especially in regard to package dependency) not covered by this tutorial. - - -## Qubes 4.0 - -### How to Create a Kali Linux VM - -This guide is being created to give guidance on ways in which you could create a [Kali Linux][kali] penetration testing VM (qube) in Qubes OS. - -Kali Linux is the most widely used penetration testing Linux distribution. - -There are multiple ways to create a Kali Linux VM: - - 1. Create a HVM and use the official ISO to install the system or convert a [Virtual Image][kali-vbox]. Explained [here](#hvm4_0). - 2. Clone the Qubes OS latest Debian template image and turn it into a Kali Linux distribution: - - using [katoolin]. Explained [here](#katoolin4_0). - - manually. Explained [here](#templatevm-from-debian4_0). - -### Kali Linux HVM +How to create a Kali Linux VM +=============================== +Warnings +-------------- +* The installation scripts and provided tools may have bugs, be vulnerable to Man in the Middle (MitM) attacks or other vulnerabilities. +* Adding additional repositories or tools for installing software extends your trust to those tool providers. +* Please keep in mind that using such a VM or VM's based on the template for security and privacy critical tasks is not recommended. +* Kali Linux distribution is a rolling distribution based constantly on Debian testing release, so it always will have newer software base than available in Qubes OS debian template. Keep in mind that it may result in problems (especially in regard to package dependency) not covered by this tutorial. + +From the official ISO file +================================================== +Only use this method if you want to have the full Kali GUI (desktop, fancy menus, ...), it come at the cost of much greater resources consumption. 1. Download the Kali installation DVD - 2. Create a new HVM - 3. Start the HVM with attached CD/DVD - ```shell_session $ qvm-start --cdrom :/home/user/Downloads/.iso ``` -### Kali Linux TemplateVM from a Debian template +From a Debian template +================================================================ +This is the recommanded method. +Easier to maintain and less demanding on resources, but you won't have the full Kali GUI. -This section will explain how to create your own [Kali] Linux TemplateVM based -on a current stable Debian TemplateVM. The basic idea is to personalize the -template with all the tools needed, and then spin up isolated AppVMs based on -the template. +If you need to install custom kernel modules (wifi drivers, ...) you need use the kernel provided by Kali instead of the kernel provided by Qubes, see [Managing VM Kernel][managing-vm-kernel] The steps can be summarised as: @@ -60,8 +40,8 @@ The steps can be summarised as: 3. Add the Kali repository 4. Update the template -#### Get Kali Linux GPG key - +Get Kali Linux GPG key +----------------------- **CAUTION:** Before proceeding, please carefully read [On Digital Signatures and Key Verification][qubes-verifying-signatures]. This website cannot guarantee that any PGP key you download from the Internet is authentic. Always obtain a trusted key fingerprint via other channels, and always check any key you download against your trusted copy of the fingerprint. @@ -70,7 +50,7 @@ This step is required since by (security) default a TemplateVM do not have a direct Internet connectivity. Users understanding the risks of enabling such access can change this configuration in firewall settings for the TemplateVM. -1. Retrive the Kali Linux GPG key using a DispVM. +1. Retrive the Kali Linux GPG key using a DisposableVM. ```shell_session $ gpg --keyserver hkp://keys.gnupg.net --recv-key 44C6513A8E4FB3D30875F758ED444FF07D8D0BF6 @@ -78,14 +58,14 @@ $ gpg --list-keys --with-fingerprint 44C6513A8E4FB3D30875F758ED444FF07D8D0BF6 $ gpg --export --armor 44C6513A8E4FB3D30875F758ED444FF07D8D0BF6 > kali-key.asc ``` -2. **DO NOT TURN OFF** the DispVM, the `kali-key.asc` file will be copied to +2. **DO NOT TURN OFF** the DisposableVM, the `kali-key.asc` file will be copied to the Kali Linux template in a further step. 3. Make sure the key is the authentic Kali key. See the [Kali website] for further advice and instructions on verification. -#### Create a Kali Linux (rolling) template - +Create a Kali Linux (rolling) template +---------------------------------------- These instructions will show you how to upgrade a Debian TemplateVM to Kali Linux. 1. (Optional) Check for latest Debian stable template and install it (if not already done) @@ -125,7 +105,6 @@ $ qvm-clone debian- kali-rolling e.g. in this example we update `buster` stable repository to `bullseye` testing repository - ```shell_session # sed -i 's/buster/bullseye/g' /etc/apt/sources.list # sed -i 's/buster/bullseye/g' /etc/apt/sources.list.d/qubes-r.list @@ -141,13 +120,13 @@ For installation based on Debian 10 stable, please note that the security reposi **Note:** During execution of the update, read carefully list of packages to be removed. If it contains `qubes-*` packages, terminate operation and try to resolve `qubes-*` packages missing dependencies first. -6. Copy the Kali GPG key from the DispVM to the new template: +6. Copy the Kali GPG key from the DisposableVM to the new template: ```shell_session $ qvm-copy kali-key.asc ``` - The DispVM can now be turned off. + The DisposableVM can now be turned off. 7. Add the Kali GPG key to the list of keys trusted to authenticate packages: @@ -174,21 +153,20 @@ EOF $ qvm-run -a kali-rolling gnome-terminal ``` -#### Install the Kali tools - +Install the Kali tools +------------------------------ At this point you should have a working template and you can install the tools you need. -Keep in mind that the tools you will install can easily take more than 10GB, [so you will need to **grow** the size of the VM1][qubes-resize-disk-image] +Keep in mind that the tools you will install can easily take more than 10GB, [so you will need to **grow** the size of the VM][qubes-resize-disk-image] -### Alternative Options to Kali Linux - - * [PenTester Framework][PTF], with [PTF Qubes OS guide][qubes-ptf] - * BlackArch Linux, with [BA Qubes OS guide][qubes-blackarch] - * [KATOOLIN][katoolin-howto] - * more on the [Penetration Testing page][qubes-pentesting] +Alternative Options to Kali Linux +=================================== +* [PenTester Framework][PTF], with [PTF Qubes OS guide][qubes-ptf] +* BlackArch Linux, with [BA Qubes OS guide][qubes-blackarch] +* more on the [Penetration Testing page][qubes-pentesting] -## Notes - +Notes +============= Thanks to the people in [the discussion thread](https://github.com/QubesOS/qubes-issues/issues/1981). [qubes-verifying-signatures]: /security/verifying-signatures/ From f0bdc96de9232086b4bdde7f8bd98d6b876caaf3 Mon Sep 17 00:00:00 2001 From: Neowutran Date: Sun, 10 May 2020 10:14:13 +0200 Subject: [PATCH 003/663] [Kali] fix link --- external/os-guides/pentesting/kali.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/external/os-guides/pentesting/kali.md b/external/os-guides/pentesting/kali.md index 940cf5d8d7..dd86944749 100644 --- a/external/os-guides/pentesting/kali.md +++ b/external/os-guides/pentesting/kali.md @@ -31,7 +31,7 @@ From a Debian template This is the recommanded method. Easier to maintain and less demanding on resources, but you won't have the full Kali GUI. -If you need to install custom kernel modules (wifi drivers, ...) you need use the kernel provided by Kali instead of the kernel provided by Qubes, see [Managing VM Kernel][managing-vm-kernel] +If you need to install custom kernel modules (wifi drivers, ...) you need use the kernel provided by Kali instead of the kernel provided by Qubes, see [Managing VM Kernel](/doc/managing-vm-kernel/) The steps can be summarised as: From c9254236d60805487e6215e76c7812b9e5bd9842 Mon Sep 17 00:00:00 2001 From: Neowutran Date: Sun, 10 May 2020 10:34:23 +0200 Subject: [PATCH 004/663] [Kali] fix typos --- external/os-guides/pentesting/kali.md | 39 ++++++++++++++------------- 1 file changed, 20 insertions(+), 19 deletions(-) diff --git a/external/os-guides/pentesting/kali.md b/external/os-guides/pentesting/kali.md index dd86944749..3be86c867b 100644 --- a/external/os-guides/pentesting/kali.md +++ b/external/os-guides/pentesting/kali.md @@ -12,14 +12,15 @@ Warnings -------------- * The installation scripts and provided tools may have bugs, be vulnerable to Man in the Middle (MitM) attacks or other vulnerabilities. * Adding additional repositories or tools for installing software extends your trust to those tool providers. -* Please keep in mind that using such a VM or VM's based on the template for security and privacy critical tasks is not recommended. -* Kali Linux distribution is a rolling distribution based constantly on Debian testing release, so it always will have newer software base than available in Qubes OS debian template. Keep in mind that it may result in problems (especially in regard to package dependency) not covered by this tutorial. +* Please keep in mind that using such template for security and privacy critical tasks is not recommended. +* Kali Linux distribution is a rolling distribution constantly based on Debian testing release, so it will always have a newer software base than available in Qubes OS Debian template. Keep in mind that it may result in problems (especially in regard to package dependency) not covered by this tutorial. From the official ISO file ================================================== -Only use this method if you want to have the full Kali GUI (desktop, fancy menus, ...), it come at the cost of much greater resources consumption. +Only use this method if you want the full Kali GUI (desktop, fancy menus, etc.). +It comes at the cost of much greater resources consumption. -1. Download the Kali installation DVD +1. Download the Kali ISO 2. Create a new HVM 3. Start the HVM with attached CD/DVD ```shell_session @@ -28,12 +29,12 @@ $ qvm-start --cdrom :/home/user/Downloads/.iso From a Debian template ================================================================ -This is the recommanded method. -Easier to maintain and less demanding on resources, but you won't have the full Kali GUI. +This is the recommended method. +Easier to maintain and less demanding on resources, but you won’t have the full Kali GUI. -If you need to install custom kernel modules (wifi drivers, ...) you need use the kernel provided by Kali instead of the kernel provided by Qubes, see [Managing VM Kernel](/doc/managing-vm-kernel/) +If you need to install custom kernel modules (wifi drivers, …) you need to use the kernel provided by Kali instead of the kernel provided by Qubes, see [Managing VM Kernel.](/doc/managing-vm-kernel/) -The steps can be summarised as: +The steps can be summarized as: 1. Install Qubes stable Debian template 2. Upgrade the template to Debian testing release @@ -43,14 +44,14 @@ The steps can be summarised as: Get Kali Linux GPG key ----------------------- **CAUTION:** Before proceeding, please carefully read [On Digital Signatures and Key Verification][qubes-verifying-signatures]. -This website cannot guarantee that any PGP key you download from the Internet is authentic. -Always obtain a trusted key fingerprint via other channels, and always check any key you download against your trusted copy of the fingerprint. +This website cannot guarantee that any GPG key you download from the Internet is authentic. +Always obtain a trusted key fingerprint via other channels, and always check key you download against your trusted copy of the fingerprint. -This step is required since by (security) default a TemplateVM do not have a +This step is required since by (security) default TemplateVM do not have a direct Internet connectivity. Users understanding the risks of enabling such access can change this configuration in firewall settings for the TemplateVM. -1. Retrive the Kali Linux GPG key using a DisposableVM. +1. Retrieve the Kali Linux GPG key using a DisposableVM. ```shell_session $ gpg --keyserver hkp://keys.gnupg.net --recv-key 44C6513A8E4FB3D30875F758ED444FF07D8D0BF6 @@ -59,7 +60,7 @@ $ gpg --export --armor 44C6513A8E4FB3D30875F758ED444FF07D8D0BF6 > kali-key.asc ``` 2. **DO NOT TURN OFF** the DisposableVM, the `kali-key.asc` file will be copied to - the Kali Linux template in a further step. + the Kali Linux template for a further step. 3. Make sure the key is the authentic Kali key. See the [Kali website] for further advice and instructions on verification. @@ -68,11 +69,11 @@ Create a Kali Linux (rolling) template ---------------------------------------- These instructions will show you how to upgrade a Debian TemplateVM to Kali Linux. -1. (Optional) Check for latest Debian stable template and install it (if not already done) +1. (Optional) Check for latest Debian stable templates and install it (if not already done) ```shell_session -$ sudo qubes-dom0-update --action="search all" qubes-template-debian -$ sudo qubes-dom0-update +# qubes-dom0-update --action="search all" qubes-template-debian +# qubes-dom0-update ``` 2. Start your latest Debian template @@ -118,7 +119,7 @@ For installation based on Debian 10 stable, please note that the security reposi 5. Update the template -**Note:** During execution of the update, read carefully list of packages to be removed. If it contains `qubes-*` packages, terminate operation and try to resolve `qubes-*` packages missing dependencies first. +**Note:** During execution of the update, carefully read list of packages to be removed. If it contains `qubes-*` packages, terminate operation and try to resolve `qubes-*` packages missing dependencies first. 6. Copy the Kali GPG key from the DisposableVM to the new template: @@ -134,7 +135,7 @@ $ qvm-copy kali-key.asc # cat /home/user/QubesIncoming/dispXXX/kali-key.asc | apt-key add - ``` - This command should return `OK` on a line by itself. + This command should return: "`OK".` 8. Add the Kali repository @@ -156,7 +157,7 @@ $ qvm-run -a kali-rolling gnome-terminal Install the Kali tools ------------------------------ At this point you should have a working template and you can install the tools you need. -Keep in mind that the tools you will install can easily take more than 10GB, [so you will need to **grow** the size of the VM][qubes-resize-disk-image] +Keep in mind that the tools you will install can easily take more than 10 GB, [so you will need to **grow** the size of the VM.][qubes-resize-disk-image] Alternative Options to Kali Linux =================================== From 62ba561d3cc0a5875cf17592632166f8bf081a52 Mon Sep 17 00:00:00 2001 From: Neowutran Date: Sun, 10 May 2020 10:36:03 +0200 Subject: [PATCH 005/663] [Kali] fix typos --- external/os-guides/pentesting/kali.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/external/os-guides/pentesting/kali.md b/external/os-guides/pentesting/kali.md index 3be86c867b..0868321556 100644 --- a/external/os-guides/pentesting/kali.md +++ b/external/os-guides/pentesting/kali.md @@ -135,7 +135,7 @@ $ qvm-copy kali-key.asc # cat /home/user/QubesIncoming/dispXXX/kali-key.asc | apt-key add - ``` - This command should return: "`OK".` + This command should return: `OK`. 8. Add the Kali repository From 8e5e9011761ec8503b31acd2df0c2b19c1b1fff0 Mon Sep 17 00:00:00 2001 From: Neowutran Date: Tue, 19 May 2020 18:31:04 +0200 Subject: [PATCH 006/663] [Kali] minor fix --- external/os-guides/pentesting/kali.md | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/external/os-guides/pentesting/kali.md b/external/os-guides/pentesting/kali.md index 0868321556..d0ff9451b8 100644 --- a/external/os-guides/pentesting/kali.md +++ b/external/os-guides/pentesting/kali.md @@ -12,8 +12,8 @@ Warnings -------------- * The installation scripts and provided tools may have bugs, be vulnerable to Man in the Middle (MitM) attacks or other vulnerabilities. * Adding additional repositories or tools for installing software extends your trust to those tool providers. -* Please keep in mind that using such template for security and privacy critical tasks is not recommended. -* Kali Linux distribution is a rolling distribution constantly based on Debian testing release, so it will always have a newer software base than available in Qubes OS Debian template. Keep in mind that it may result in problems (especially in regard to package dependency) not covered by this tutorial. +* Please keep in mind that using such a template for security and privacy critical tasks is not recommended. +* Kali Linux distribution is a rolling distribution based on Debian testing release, so it will always have a newer software base than available in the Qubes OS Debian template. Keep in mind that this may result in problems (especially in regard to package dependencies) not covered by this tutorial. From the official ISO file ================================================== @@ -41,17 +41,17 @@ The steps can be summarized as: 3. Add the Kali repository 4. Update the template -Get Kali Linux GPG key +Get Kali Linux PGP key ----------------------- **CAUTION:** Before proceeding, please carefully read [On Digital Signatures and Key Verification][qubes-verifying-signatures]. -This website cannot guarantee that any GPG key you download from the Internet is authentic. -Always obtain a trusted key fingerprint via other channels, and always check key you download against your trusted copy of the fingerprint. +This website cannot guarantee that any PGP key you download from the Internet is authentic. +Always obtain a trusted key fingerprint via other channels, and always check any key you download against your trusted copy of the fingerprint. This step is required since by (security) default TemplateVM do not have a direct Internet connectivity. Users understanding the risks of enabling such access can change this configuration in firewall settings for the TemplateVM. -1. Retrieve the Kali Linux GPG key using a DisposableVM. +1. Retrieve the Kali Linux PGP key using a DisposableVM. ```shell_session $ gpg --keyserver hkp://keys.gnupg.net --recv-key 44C6513A8E4FB3D30875F758ED444FF07D8D0BF6 @@ -59,7 +59,7 @@ $ gpg --list-keys --with-fingerprint 44C6513A8E4FB3D30875F758ED444FF07D8D0BF6 $ gpg --export --armor 44C6513A8E4FB3D30875F758ED444FF07D8D0BF6 > kali-key.asc ``` -2. **DO NOT TURN OFF** the DisposableVM, the `kali-key.asc` file will be copied to +2. **DO NOT TURN OFF** the DisposableVM, the `kali-key.asc` file will be copied in the Kali Linux template for a further step. 3. Make sure the key is the authentic Kali key. @@ -69,14 +69,14 @@ Create a Kali Linux (rolling) template ---------------------------------------- These instructions will show you how to upgrade a Debian TemplateVM to Kali Linux. -1. (Optional) Check for latest Debian stable templates and install it (if not already done) +1. (Optional) Check for latest Debian stable template and install it (if not already done) ```shell_session # qubes-dom0-update --action="search all" qubes-template-debian # qubes-dom0-update ``` -2. Start your latest Debian template +2. Start your Debian template ```shell_session $ qvm-start debian- @@ -114,14 +114,14 @@ e.g. in this example we update `buster` stable repository to `bullseye` testing For installation based on Debian 10 stable, please note that the security repository of Debian testing has [recently been renamed][Debian-security-naming-convention] from `/update` to `-security`. To account for that change, execute the following command. ```shell_session -# sed -i 's/bullseye\/updates/bullseye-security/g' /etc/apt/sources.list +# sed -i 's%bullseye/updates%bullseye-security%g' /etc/apt/sources.list ``` 5. Update the template **Note:** During execution of the update, carefully read list of packages to be removed. If it contains `qubes-*` packages, terminate operation and try to resolve `qubes-*` packages missing dependencies first. -6. Copy the Kali GPG key from the DisposableVM to the new template: +6. Copy the Kali PGP key from the DisposableVM to the new template: ```shell_session $ qvm-copy kali-key.asc @@ -129,7 +129,7 @@ $ qvm-copy kali-key.asc The DisposableVM can now be turned off. -7. Add the Kali GPG key to the list of keys trusted to authenticate packages: +7. Add the Kali PGP key to the list of keys trusted to authenticate packages: ```shell_session # cat /home/user/QubesIncoming/dispXXX/kali-key.asc | apt-key add - @@ -157,7 +157,7 @@ $ qvm-run -a kali-rolling gnome-terminal Install the Kali tools ------------------------------ At this point you should have a working template and you can install the tools you need. -Keep in mind that the tools you will install can easily take more than 10 GB, [so you will need to **grow** the size of the VM.][qubes-resize-disk-image] +Keep in mind that the tools you will install can easily take more than 10 GB, [so you will need to **grow** the size of the VM system storage.][qubes-resize-disk-image] Alternative Options to Kali Linux =================================== From 0112dc772ebf3a100b8e894cd7f1a95531e38203 Mon Sep 17 00:00:00 2001 From: Neowutran Date: Sat, 23 May 2020 19:29:04 +0200 Subject: [PATCH 007/663] [Kali] migitagion against dependency hell between Qubes repository and Kali repository --- external/os-guides/pentesting/kali.md | 56 ++++++++------------------- 1 file changed, 17 insertions(+), 39 deletions(-) diff --git a/external/os-guides/pentesting/kali.md b/external/os-guides/pentesting/kali.md index d0ff9451b8..b74af7b2dd 100644 --- a/external/os-guides/pentesting/kali.md +++ b/external/os-guides/pentesting/kali.md @@ -37,7 +37,7 @@ If you need to install custom kernel modules (wifi drivers, …) you need to use The steps can be summarized as: 1. Install Qubes stable Debian template -2. Upgrade the template to Debian testing release +2. Add `testing` and `securitytesting` Qubes repositories 3. Add the Kali repository 4. Update the template @@ -45,7 +45,8 @@ Get Kali Linux PGP key ----------------------- **CAUTION:** Before proceeding, please carefully read [On Digital Signatures and Key Verification][qubes-verifying-signatures]. This website cannot guarantee that any PGP key you download from the Internet is authentic. -Always obtain a trusted key fingerprint via other channels, and always check any key you download against your trusted copy of the fingerprint. +In order to obtain a trusted fingerprint, check its value against multiple sources. +Then, check the keys you download against your trusted fingerprint. This step is required since by (security) default TemplateVM do not have a direct Internet connectivity. Users understanding the risks of enabling such @@ -54,7 +55,7 @@ access can change this configuration in firewall settings for the TemplateVM. 1. Retrieve the Kali Linux PGP key using a DisposableVM. ```shell_session -$ gpg --keyserver hkp://keys.gnupg.net --recv-key 44C6513A8E4FB3D30875F758ED444FF07D8D0BF6 +$ gpg --keyserver hkps://keys.gnupg.net --recv-key 44C6513A8E4FB3D30875F758ED444FF07D8D0BF6 $ gpg --list-keys --with-fingerprint 44C6513A8E4FB3D30875F758ED444FF07D8D0BF6 $ gpg --export --armor 44C6513A8E4FB3D30875F758ED444FF07D8D0BF6 > kali-key.asc ``` @@ -76,52 +77,30 @@ These instructions will show you how to upgrade a Debian TemplateVM to Kali Linu # qubes-dom0-update ``` -2. Start your Debian template - -```shell_session -$ qvm-start debian- -$ qvm-run -a debian- gnome-terminal -``` - -3. Update it - -4. And then close it - -```shell_session -$ qvm-shutdown debian- -``` - -5. Clone `debian-X` template +2. Clone `debian-X` template ```shell_session $ qvm-clone debian- kali-rolling ``` -6. Check the name of currently used repository in `/etc/apt/sources.list` and current testing [Debian release][Debian-releases]. Update repository list accordingly +3. Check the name of currently used repository in `/etc/apt/sources.list.d/qubes-r.list` and current testing [Debian release][Debian-releases]. Update repository list accordingly ```shell_session -# sed -i 's///g' /etc/apt/sources.list # sed -i 's///g' /etc/apt/sources.list.d/qubes-r.list ``` e.g. in this example we update `buster` stable repository to `bullseye` testing repository ```shell_session -# sed -i 's/buster/bullseye/g' /etc/apt/sources.list # sed -i 's/buster/bullseye/g' /etc/apt/sources.list.d/qubes-r.list ``` - -For installation based on Debian 10 stable, please note that the security repository of Debian testing has [recently been renamed][Debian-security-naming-convention] from `/update` to `-security`. To account for that change, execute the following command. - -```shell_session -# sed -i 's%bullseye/updates%bullseye-security%g' /etc/apt/sources.list -``` -5. Update the template +4. Enable the QubesOS `testing` and `securitytesting` repositories -**Note:** During execution of the update, carefully read list of packages to be removed. If it contains `qubes-*` packages, terminate operation and try to resolve `qubes-*` packages missing dependencies first. +In `/etc/apt/sources.list.d/qubes-r.list`, enable the 'testing' and 'securitytesting' repository. +We do that to reduce the 'dependency hell' between Qubes repository and Kali repository. -6. Copy the Kali PGP key from the DisposableVM to the new template: +5. Copy the Kali PGP key from the DisposableVM to the new template: ```shell_session $ qvm-copy kali-key.asc @@ -129,7 +108,7 @@ $ qvm-copy kali-key.asc The DisposableVM can now be turned off. -7. Add the Kali PGP key to the list of keys trusted to authenticate packages: +6. Add the Kali PGP key to the list of keys trusted to authenticate packages: ```shell_session # cat /home/user/QubesIncoming/dispXXX/kali-key.asc | apt-key add - @@ -137,18 +116,17 @@ $ qvm-copy kali-key.asc This command should return: `OK`. -8. Add the Kali repository +7. Replace Debian repositories with Kali repository ```shell_session -# cat < /etc/apt/sources.list.d/kali.list -# Kali Linux repository -deb https://http.kali.org/kali kali-rolling main non-free contrib -EOF +# echo 'deb https://http.kali.org/kali kali-rolling main non-free contrib' > /etc/apt/sources.list ``` -9. Update the template +8. Update the template + +**Note:** During execution of the update, carefully read list of packages to be removed. If it contains `qubes-vm-dependencies` package, terminate operation and try to resolve missing dependencies first. For other `qubes-*` packages, it is up to you to decide if you need them. -10. Ensure a terminal can be opened in the new template. +9. Ensure a terminal can be opened in the new template. ```shell_session $ qvm-run -a kali-rolling gnome-terminal From aa066d24fc44a4629da8ed38f664855a0ff86695 Mon Sep 17 00:00:00 2001 From: Neowutran Date: Sat, 23 May 2020 20:34:07 +0200 Subject: [PATCH 008/663] [Kali] fix wrong tag for spellchecker --- external/os-guides/pentesting/kali.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/external/os-guides/pentesting/kali.md b/external/os-guides/pentesting/kali.md index b74af7b2dd..2bd0720b3c 100644 --- a/external/os-guides/pentesting/kali.md +++ b/external/os-guides/pentesting/kali.md @@ -97,7 +97,7 @@ e.g. in this example we update `buster` stable repository to `bullseye` testing 4. Enable the QubesOS `testing` and `securitytesting` repositories -In `/etc/apt/sources.list.d/qubes-r.list`, enable the 'testing' and 'securitytesting' repository. +In `/etc/apt/sources.list.d/qubes-r.list`, enable the `testing` and `securitytesting` repository. We do that to reduce the 'dependency hell' between Qubes repository and Kali repository. 5. Copy the Kali PGP key from the DisposableVM to the new template: From d872d88ea72b8edd5ac4403d8103a5e051d41106 Mon Sep 17 00:00:00 2001 From: dd Date: Sat, 4 Jul 2020 05:53:51 +0200 Subject: [PATCH 009/663] add lang attribute with default en value in docs, pages, news index, 404, updated counter (added lang attribute with default en value in docs, pages, news index, 404, updated counter) --- developer/building/development-workflow.md | 4 +++- developer/building/qubes-builder-details.md | 4 +++- developer/building/qubes-builder.md | 4 +++- developer/building/qubes-iso-building.md | 4 +++- developer/code/code-signing.md | 5 +++-- developer/code/coding-style.md | 4 +++- developer/code/license.md | 4 +++- developer/code/source-code.md | 4 +++- developer/debugging/automated-tests.md | 5 +++-- developer/debugging/mount-lvm-image.md | 4 +++- developer/debugging/profiling.md | 4 +++- developer/debugging/safe-remote-ttys.md | 5 +++-- developer/debugging/test-bench.md | 4 +++- developer/debugging/vm-interface.md | 4 +++- developer/debugging/windows-debugging.md | 4 +++- developer/general/devel-books.md | 4 +++- developer/general/doc-guidelines.md | 5 +++-- developer/general/gsoc.md | 4 +++- developer/general/gsod.md | 4 +++- developer/general/join.md | 7 ++++--- developer/general/package-contributions.md | 4 +++- developer/general/style-guide.md | 4 +++- developer/general/usability-ux.md | 4 +++- developer/releases/1.0/release-notes.md | 5 +++-- developer/releases/2.0/release-notes.md | 4 +++- developer/releases/3.0/release-notes.md | 5 +++-- developer/releases/3.0/schedule.md | 4 +++- developer/releases/3.1/release-notes.md | 4 +++- developer/releases/3.1/schedule.md | 4 +++- developer/releases/3.2/release-notes.md | 4 +++- developer/releases/3.2/schedule.md | 4 +++- developer/releases/4.0/release-notes.md | 4 +++- developer/releases/4.0/schedule.md | 4 +++- developer/releases/notes.md | 5 +++-- developer/releases/schedules.md | 5 +++-- developer/releases/todo.md | 4 +++- developer/services/admin-api.md | 4 +++- developer/services/dom0-secure-updates.md | 4 +++- developer/services/dvm-impl.md | 4 +++- developer/services/qfilecopy.md | 4 +++- developer/services/qfileexchgd.md | 5 +++-- developer/services/qmemman.md | 5 +++-- developer/services/qrexec-internals.md | 4 +++- developer/services/qrexec-socket-services.md | 4 +++- developer/services/qrexec.md | 5 +++-- developer/services/qrexec2.md | 4 +++- developer/system/architecture.md | 4 +++- developer/system/audio.md | 5 +++-- developer/system/gui.md | 4 +++- developer/system/networking.md | 5 +++-- developer/system/security-critical-code.md | 5 +++-- developer/system/storage-pools.md | 6 ++++-- developer/system/system-doc.md | 5 +++-- developer/system/template-implementation.md | 4 +++- doc.md | 6 ++++-- .../building-archlinux-template.md | 4 +++- .../building-non-fedora-template.md | 4 +++- .../building-guides/building-whonix-template.md | 6 +++--- .../configuration-guides/change-time-zone.md | 5 +++-- external/configuration-guides/disk-trim.md | 4 +++- external/configuration-guides/external-audio.md | 4 +++- external/configuration-guides/fetchmail.md | 4 +++- external/configuration-guides/multiboot.md | 4 +++- external/configuration-guides/multimedia.md | 5 +++-- external/configuration-guides/mutt.md | 4 +++- .../network-bridge-support.md | 4 +++- .../configuration-guides/network-printer.md | 5 +++-- external/configuration-guides/postfix.md | 4 +++- external/configuration-guides/rxvt.md | 4 +++- .../configuration-guides/tips-and-tricks.md | 5 +++-- external/configuration-guides/vpn.md | 4 +++- external/configuration-guides/w3m.md | 4 +++- external/configuration-guides/zfs.md | 5 +++-- external/customization-guides/dark-theme.md | 4 +++- .../fedora-minimal-template-customization.md | 4 +++- .../language-localization.md | 4 +++- .../removing-templatevm-packages.md | 4 +++- .../windows-template-customization.md | 4 +++- external/os-guides/centos.md | 6 +++--- external/os-guides/linux-hvm-tips.md | 4 +++- external/os-guides/netbsd.md | 4 +++- external/os-guides/pentesting.md | 4 +++- external/os-guides/pentesting/blackarch.md | 4 +++- external/os-guides/pentesting/kali.md | 5 +++-- external/os-guides/pentesting/ptf.md | 4 +++- external/os-guides/ubuntu.md | 4 +++- external/os-guides/windows/windows-tools.md | 5 +++-- external/os-guides/windows/windows-vm.md | 6 +++--- .../anonymizing-your-mac-address.md | 4 +++- external/privacy-guides/signal.md | 4 +++- external/privacy-guides/tails.md | 4 +++- external/privacy-guides/torvm.md | 4 +++- external/privacy-guides/whonix.md | 5 +++-- .../multifactor-authentication.md | 4 +++- external/security-guides/security-guidelines.md | 5 +++-- external/security-guides/split-bitcoin.md | 5 +++-- .../troubleshooting/install-nvidia-driver.md | 4 +++- .../intel-igfx-troubleshooting.md | 6 ++++-- .../troubleshooting/macbook-troubleshooting.md | 4 +++- .../troubleshooting/nvidia-troubleshooting.md | 5 +++-- external/troubleshooting/out-of-memory.md | 5 +++-- external/troubleshooting/remove-vm-manually.md | 5 +++-- external/troubleshooting/sony-vaio-tinkering.md | 4 +++- .../troubleshooting/thinkpad-troubleshooting.md | 5 +++-- .../updating-debian-and-whonix.md | 4 +++- .../troubleshooting/wireless-troubleshooting.md | 4 +++- introduction/code-of-conduct.md | 4 +++- introduction/contributing.md | 5 +++-- introduction/experts.md | 4 +++- introduction/faq.md | 4 +++- introduction/intro.md | 4 +++- introduction/reporting-bugs.md | 5 +++-- introduction/screenshots.md | 5 +++-- introduction/statistics.md | 7 ++++--- introduction/support.md | 5 +++-- introduction/video-tours.html | 4 +++- project-security/canaries.md | 5 +++-- project-security/canary-checklist.md | 5 +++-- project-security/canary-template.md | 5 +++-- .../security-bulletins-checklist.md | 5 +++-- project-security/security-bulletins-template.md | 5 +++-- project-security/security-bulletins.md | 7 ++++--- project-security/security-goals.md | 4 +++- project-security/security-pack.md | 5 +++-- project-security/security.md | 8 ++++---- project-security/verifying-signatures.md | 5 +++-- project-security/xsa.md | 5 +++-- user/advanced-configuration/awesome.md | 6 +++--- user/advanced-configuration/bind-dirs.md | 4 +++- user/advanced-configuration/config-files.md | 8 +++++--- .../disposablevm-customization.md | 5 +++-- .../advanced-configuration/gui-configuration.md | 6 ++++-- user/advanced-configuration/i3.md | 9 +++++---- user/advanced-configuration/kde.md | 4 +++- .../managing-vm-kernel.md | 5 +++-- .../mount-from-other-os.md | 6 +++--- .../newer-hardware-troubleshooting.md | 5 +++-- .../advanced-configuration/resize-disk-image.md | 9 +++------ user/advanced-configuration/rpc-policy.md | 5 +++-- user/advanced-configuration/salt.md | 4 +++- .../advanced-configuration/secondary-storage.md | 5 +++-- .../uefi-troubleshooting.md | 4 +++- user/advanced-configuration/usb-qubes.md | 5 +++-- .../common-tasks/backup-emergency-restore-v2.md | 4 +++- .../common-tasks/backup-emergency-restore-v3.md | 5 +++-- .../common-tasks/backup-emergency-restore-v4.md | 5 +++-- user/common-tasks/backup-restore.md | 5 +++-- user/common-tasks/block-devices.md | 5 +++-- user/common-tasks/copy-from-dom0.md | 5 +++-- user/common-tasks/copy-paste.md | 5 +++-- user/common-tasks/copying-files.md | 4 +++- user/common-tasks/device-handling.md | 5 +++-- user/common-tasks/disposablevm.md | 4 +++- user/common-tasks/full-screen-mode.md | 4 +++- user/common-tasks/getting-started.md | 4 +++- user/common-tasks/managing-appvm-shortcuts.md | 5 +++-- user/common-tasks/optical-discs.md | 9 +++++---- user/common-tasks/pci-devices.md | 5 +++-- user/common-tasks/software-update-dom0.md | 5 +++-- user/common-tasks/software-update-domu.md | 5 +++-- user/common-tasks/updating-qubes-os.md | 4 +++- user/common-tasks/usb-devices.md | 4 +++- user/common-tasks/volume-backup-revert.md | 6 ++++-- .../custom-install.md | 7 ++++--- .../download-mirrors.md | 4 +++- .../install-security.md | 5 +++-- .../installation-guide.md | 5 +++-- .../live-usb.md | 4 +++- .../supported-versions.md | 5 +++-- .../downloading-installing-upgrading/testing.md | 5 +++-- .../upgrade/upgrade-to-r2.md | 4 +++- .../upgrade/upgrade-to-r2b1.md | 5 +++-- .../upgrade/upgrade-to-r2b2.md | 4 +++- .../upgrade/upgrade-to-r2b3.md | 4 +++- .../upgrade/upgrade-to-r3.0.md | 4 +++- .../upgrade/upgrade-to-r3.1.md | 5 +++-- .../upgrade/upgrade-to-r3.2.md | 6 +++--- .../upgrade/upgrade-to-r4.0.md | 5 +++-- .../upgrade/upgrade.md | 5 +++-- .../version-scheme.md | 4 +++- user/hardware/certified-hardware.md | 11 ++++++----- user/hardware/hardware-testing.md | 5 +++-- user/hardware/hcl.html | 6 ++++-- user/hardware/hcl.md | 5 +++-- user/hardware/system-requirements.md | 5 +++-- user/managing-os/debian/debian-upgrade.md | 5 +++-- user/managing-os/debian/debian.md | 5 +++-- user/managing-os/fedora/fedora-upgrade.md | 5 +++-- user/managing-os/fedora/fedora-xfce.md | 5 +++-- user/managing-os/fedora/fedora.md | 4 +++- user/managing-os/minimal-templates.md | 5 +++-- user/managing-os/reinstall-template.md | 5 +++-- user/managing-os/standalone-and-hvm.md | 5 +++-- user/managing-os/templates.md | 4 +++- user/managing-os/windows.md | 6 +++--- user/reference/glossary.md | 5 +++-- user/reference/qubes-service.md | 5 +++-- user/reference/research.md | 4 +++- user/reference/tools.md | 17 +++++++++-------- user/security-in-qubes/anti-evil-maid.md | 5 +++-- user/security-in-qubes/data-leaks.md | 4 +++- .../device-handling-security.md | 5 +++-- user/security-in-qubes/firewall.md | 4 +++- user/security-in-qubes/split-gpg.md | 4 +++- user/security-in-qubes/u2f-proxy.md | 5 +++-- user/security-in-qubes/vm-sudo.md | 4 +++- user/security-in-qubes/yubi-key.md | 4 +++- 207 files changed, 647 insertions(+), 343 deletions(-) diff --git a/developer/building/development-workflow.md b/developer/building/development-workflow.md index 3f9b2fcd4a..3e801aa07f 100644 --- a/developer/building/development-workflow.md +++ b/developer/building/development-workflow.md @@ -1,11 +1,13 @@ --- +lang: en layout: doc -title: Development Workflow permalink: /doc/development-workflow/ redirect_from: - /en/doc/development-workflow/ - /doc/DevelopmentWorkflow/ - /wiki/DevelopmentWorkflow/ +ref: 66 +title: Development Workflow --- Development Workflow diff --git a/developer/building/qubes-builder-details.md b/developer/building/qubes-builder-details.md index f1f85b3e7e..3677eba2d1 100644 --- a/developer/building/qubes-builder-details.md +++ b/developer/building/qubes-builder-details.md @@ -1,11 +1,13 @@ --- +lang: en layout: doc -title: Qubes Builder Details permalink: /doc/qubes-builder-details/ redirect_from: - /en/doc/qubes-builder-details/ - /doc/QubesBuilderDetails/ - /wiki/QubesBuilderDetails/ +ref: 65 +title: Qubes Builder Details --- [QubesBuilder](/doc/qubes-builder/) "API" diff --git a/developer/building/qubes-builder.md b/developer/building/qubes-builder.md index 1fa88418c4..a65852cfc4 100644 --- a/developer/building/qubes-builder.md +++ b/developer/building/qubes-builder.md @@ -1,11 +1,13 @@ --- +lang: en layout: doc -title: Qubes Builder permalink: /doc/qubes-builder/ redirect_from: - /en/doc/qubes-builder/ - /doc/QubesBuilder/ - /wiki/QubesBuilder/ +ref: 64 +title: Qubes Builder --- **Note: See [ISO building instructions](/doc/qubes-iso-building/) for a streamlined overview on how to use the build system.** diff --git a/developer/building/qubes-iso-building.md b/developer/building/qubes-iso-building.md index e25d1975b7..c6a249a372 100644 --- a/developer/building/qubes-iso-building.md +++ b/developer/building/qubes-iso-building.md @@ -1,6 +1,6 @@ --- +lang: en layout: doc -title: Qubes ISO Building permalink: /doc/qubes-iso-building/ redirect_from: - /doc/qubes-r3-building/ @@ -8,6 +8,8 @@ redirect_from: - /en/doc/qubes-iso-building/ - /doc/QubesR3Building/ - /wiki/QubesR3Building/ +ref: 63 +title: Qubes ISO Building --- Building Qubes OS ISO diff --git a/developer/code/code-signing.md b/developer/code/code-signing.md index e826561e7f..56675970cc 100644 --- a/developer/code/code-signing.md +++ b/developer/code/code-signing.md @@ -1,7 +1,9 @@ --- +lang: en layout: doc -title: Code Signing permalink: /doc/code-signing/ +ref: 51 +title: Code Signing --- Code Signing @@ -214,4 +216,3 @@ Enigmail is a security addon for the Mozilla Thunderbird email client that allow [signature-checker]: https://github.com/marmarek/signature-checker [GitHub New GPG key]: https://github.com/settings/gpg/new [GitHub SSH GPG keys page]: https://github.com/settings/keys - diff --git a/developer/code/coding-style.md b/developer/code/coding-style.md index f37e2b9071..e8ae5445ae 100644 --- a/developer/code/coding-style.md +++ b/developer/code/coding-style.md @@ -1,12 +1,14 @@ --- +lang: en layout: doc -title: Coding Style permalink: /doc/coding-style/ redirect_from: - /en/doc/coding-style/ - /doc/CodingStyle/ - /wiki/CodingStyle/ - /trac/wiki/CodingStyle/ +ref: 53 +title: Coding Style --- Coding Guidelines for Qubes Developers diff --git a/developer/code/license.md b/developer/code/license.md index 1a7879a2f9..ae4ba67abf 100644 --- a/developer/code/license.md +++ b/developer/code/license.md @@ -1,11 +1,13 @@ --- +lang: en layout: doc -title: License permalink: /doc/license/ redirect_from: - /en/doc/license/ - /doc/QubesLicensing/ - /wiki/QubesLicensing/ +ref: 52 +title: License --- Qubes OS License diff --git a/developer/code/source-code.md b/developer/code/source-code.md index 6f1f531b13..5b6adef565 100644 --- a/developer/code/source-code.md +++ b/developer/code/source-code.md @@ -1,11 +1,13 @@ --- +lang: en layout: doc -title: Source Code permalink: /doc/source-code/ redirect_from: - /en/doc/source-code/ - /doc/SourceCode/ - /wiki/SourceCode/ +ref: 54 +title: Source Code --- Qubes Source Code Repositories diff --git a/developer/debugging/automated-tests.md b/developer/debugging/automated-tests.md index 2fa9e6b8a2..467cb4dade 100644 --- a/developer/debugging/automated-tests.md +++ b/developer/debugging/automated-tests.md @@ -1,10 +1,12 @@ --- +lang: en layout: doc -title: Automated Tests permalink: /doc/automated-tests/ redirect_from: - /en/doc/automated-tests/ - /doc/AutomatedTests/ +ref: 45 +title: Automated Tests --- Automated Tests @@ -219,4 +221,3 @@ Thanks to an anonymous donor, our openQA system is hosted in a datacenter on har [unittest]: https://docs.python.org/2/library/unittest.html [OpenQA]: http://open.qa/ - diff --git a/developer/debugging/mount-lvm-image.md b/developer/debugging/mount-lvm-image.md index ca9f090131..65615feb0b 100644 --- a/developer/debugging/mount-lvm-image.md +++ b/developer/debugging/mount-lvm-image.md @@ -1,7 +1,9 @@ --- +lang: en layout: doc -title: Mount LVM image permalink: /doc/mount-lvm-image/ +ref: 46 +title: Mount LVM image --- # How to mount LVM image diff --git a/developer/debugging/profiling.md b/developer/debugging/profiling.md index e20e3208f4..69d5149194 100644 --- a/developer/debugging/profiling.md +++ b/developer/debugging/profiling.md @@ -1,11 +1,13 @@ --- +lang: en layout: doc -title: Profiling permalink: /doc/profiling/ redirect_from: - /en/doc/profiling/ - /doc/Profiling/ - /wiki/Profiling/ +ref: 48 +title: Profiling --- Profiling diff --git a/developer/debugging/safe-remote-ttys.md b/developer/debugging/safe-remote-ttys.md index 0568df6dd5..f385505b7e 100644 --- a/developer/debugging/safe-remote-ttys.md +++ b/developer/debugging/safe-remote-ttys.md @@ -1,10 +1,11 @@ --- +lang: en layout: doc -title: Safe Remote Dom0 Terminals permalink: /doc/safe-remote-ttys/ redirect_from: - /en/doc/safe-remote-ttys/ -- /doc/safe-remote-ttys/ +ref: 49 +title: Safe Remote Dom0 Terminals --- Safe Remote Dom0 Terminals diff --git a/developer/debugging/test-bench.md b/developer/debugging/test-bench.md index 6f2a9019e6..bd631900d6 100644 --- a/developer/debugging/test-bench.md +++ b/developer/debugging/test-bench.md @@ -1,11 +1,13 @@ --- +lang: en layout: doc -title: Test Bench permalink: /doc/test-bench/ redirect_from: - /en/doc/test-bench/ - /doc/TestBench/ - /wiki/TestBench/ +ref: 44 +title: Test Bench --- Test bench for Dom0 diff --git a/developer/debugging/vm-interface.md b/developer/debugging/vm-interface.md index 7a79f3871f..bbe5dffc57 100644 --- a/developer/debugging/vm-interface.md +++ b/developer/debugging/vm-interface.md @@ -1,12 +1,14 @@ --- +lang: en layout: doc -title: VM Configuration Interface permalink: /doc/vm-interface/ redirect_from: - /en/doc/vm-interface/ - /doc/VMInterface/ - /doc/SystemDoc/VMInterface/ - /wiki/SystemDoc/VMInterface/ +ref: 47 +title: VM Configuration Interface --- VM Configuration Interface diff --git a/developer/debugging/windows-debugging.md b/developer/debugging/windows-debugging.md index d1b2dd186e..93846db32c 100644 --- a/developer/debugging/windows-debugging.md +++ b/developer/debugging/windows-debugging.md @@ -1,11 +1,13 @@ --- +lang: en layout: doc -title: Windows Debugging permalink: /doc/windows-debugging/ redirect_from: - /en/doc/windows-debugging/ - /doc/WindowsDebugging/ - /wiki/WindowsDebugging/ +ref: 50 +title: Windows Debugging --- Debugging Windows HVMs diff --git a/developer/general/devel-books.md b/developer/general/devel-books.md index 4284b89323..6d57eff907 100644 --- a/developer/general/devel-books.md +++ b/developer/general/devel-books.md @@ -1,11 +1,13 @@ --- +lang: en layout: doc -title: Developer Books permalink: /doc/devel-books/ redirect_from: - /en/doc/devel-books/ - /doc/DevelBooks/ - /wiki/DevelBooks/ +ref: 32 +title: Developer Books --- Below is a list of various books that might be useful in learning some basics needed for Qubes development. diff --git a/developer/general/doc-guidelines.md b/developer/general/doc-guidelines.md index bea00fecdd..8220956b83 100644 --- a/developer/general/doc-guidelines.md +++ b/developer/general/doc-guidelines.md @@ -1,11 +1,13 @@ --- +lang: en layout: doc -title: Documentation Guidelines permalink: /doc/doc-guidelines/ redirect_from: - /en/doc/doc-guidelines/ - /wiki/DocStyle/ - /doc/DocStyle/ +ref: 30 +title: Documentation Guidelines --- Documentation Guidelines @@ -305,4 +307,3 @@ Please try to write good commit messages, according to the [git-commit]: /doc/coding-style/#commit-message-guidelines [render the site locally]: https://github.com/QubesOS/qubesos.github.io#instructions [qubes-attachment]: https://github.com/QubesOS/qubes-attachment - diff --git a/developer/general/gsoc.md b/developer/general/gsoc.md index 3241fcfb29..0af12965bf 100644 --- a/developer/general/gsoc.md +++ b/developer/general/gsoc.md @@ -1,8 +1,10 @@ --- +lang: en layout: sidebar -title: Google Summer of Code permalink: /gsoc/ redirect_from: /GSoC/ +ref: 33 +title: Google Summer of Code --- 2020 Google Summer of Code diff --git a/developer/general/gsod.md b/developer/general/gsod.md index cc4ab7efd8..43b54d2fb1 100644 --- a/developer/general/gsod.md +++ b/developer/general/gsod.md @@ -1,7 +1,9 @@ --- +lang: en layout: sidebar -title: Google Season of Docs permalink: /gsod/ +ref: 28 +title: Google Season of Docs --- # 2020 Google Season of Docs diff --git a/developer/general/join.md b/developer/general/join.md index ef195556bf..3988f474c6 100644 --- a/developer/general/join.md +++ b/developer/general/join.md @@ -1,7 +1,9 @@ --- +lang: en layout: sidebar -title: Join permalink: /join/ +ref: 26 +title: Join --- Joining the Qubes OS Team @@ -9,5 +11,4 @@ Joining the Qubes OS Team The Qubes OS Project does not currently have any open positions. This page will be updated when open positions become available. -In the meantime, there are many different ways you can [contribute to the Qubes OS project](/doc/contributing/). - +In the meantime, there are many different ways you can [contribute to the Qubes OS project](/doc/contributing/). diff --git a/developer/general/package-contributions.md b/developer/general/package-contributions.md index bc52aae536..f22efd2cd0 100644 --- a/developer/general/package-contributions.md +++ b/developer/general/package-contributions.md @@ -1,7 +1,9 @@ --- +lang: en layout: doc -title: Package Contributions permalink: /doc/package-contributions/ +ref: 29 +title: Package Contributions --- Package Contributions diff --git a/developer/general/style-guide.md b/developer/general/style-guide.md index 795a0c5e9d..9635690f26 100644 --- a/developer/general/style-guide.md +++ b/developer/general/style-guide.md @@ -1,7 +1,9 @@ --- +lang: en layout: doc -title: Style-guide permalink: /doc/style-guide/ +ref: 27 +title: Style-guide --- Style Guide diff --git a/developer/general/usability-ux.md b/developer/general/usability-ux.md index d703ec76e3..9cf64b4ba0 100644 --- a/developer/general/usability-ux.md +++ b/developer/general/usability-ux.md @@ -1,7 +1,9 @@ --- +lang: en layout: doc -title: Usability & UX permalink: /doc/usability-ux/ +ref: 31 +title: Usability & UX --- Usability & UX diff --git a/developer/releases/1.0/release-notes.md b/developer/releases/1.0/release-notes.md index 74b125ff50..780b738f03 100644 --- a/developer/releases/1.0/release-notes.md +++ b/developer/releases/1.0/release-notes.md @@ -1,9 +1,11 @@ --- +lang: en layout: doc -title: Qubes R1.0 Release Notes permalink: /doc/releases/1.0/release-notes/ redirect_from: - /en/doc/releases/1.0/release-notes/ +ref: 18 +title: Qubes R1.0 Release Notes --- Qubes R1.0 Release Notes @@ -53,4 +55,3 @@ If you have Qubes Beta 3 currently installed on your system, you must reinstall ~~~ qvm-backup-restore --replace-template=fedora-15-x64:fedora-17-x64 ~~~ - diff --git a/developer/releases/2.0/release-notes.md b/developer/releases/2.0/release-notes.md index c1d01f4161..8a9027e372 100644 --- a/developer/releases/2.0/release-notes.md +++ b/developer/releases/2.0/release-notes.md @@ -1,9 +1,11 @@ --- +lang: en layout: doc -title: Qubes R2.0 Release Notes permalink: /doc/releases/2.0/release-notes/ redirect_from: - /en/doc/releases/2.0/release-notes/ +ref: 25 +title: Qubes R2.0 Release Notes --- Qubes R2.0 Release Notes diff --git a/developer/releases/3.0/release-notes.md b/developer/releases/3.0/release-notes.md index ec3d030d0a..95d677a120 100644 --- a/developer/releases/3.0/release-notes.md +++ b/developer/releases/3.0/release-notes.md @@ -1,9 +1,11 @@ --- +lang: en layout: doc -title: Qubes R3.0 Release Notes permalink: /doc/releases/3.0/release-notes/ redirect_from: - /en/doc/releases/3.0/release-notes/ +ref: 19 +title: Qubes R3.0 Release Notes --- Qubes R3.0 Release Notes @@ -64,4 +66,3 @@ If you are using Qubes R3.0rc1, R3.0rc2 or R3.0rc3, just install system updates, The easiest and safest way to upgrade to Qubes R3.0 is to install it from scratch and use [qubes backup and restore tools](/doc/backup-restore/) for migrating of all of the user VMs. Users of Qubes R2 can upgrade using [experimental procedure](/doc/upgrade-to-r3.0/). - diff --git a/developer/releases/3.0/schedule.md b/developer/releases/3.0/schedule.md index 403895f6d9..9f13d461f9 100644 --- a/developer/releases/3.0/schedule.md +++ b/developer/releases/3.0/schedule.md @@ -1,9 +1,11 @@ --- +lang: en layout: doc -title: Qubes R3.0 Release Schedule permalink: /doc/releases/3.0/schedule/ redirect_from: - /en/doc/releases/3.0/schedule/ +ref: 20 +title: Qubes R3.0 Release Schedule --- Qubes R3.0 Release Schedule diff --git a/developer/releases/3.1/release-notes.md b/developer/releases/3.1/release-notes.md index 160d1b9003..85dc042792 100644 --- a/developer/releases/3.1/release-notes.md +++ b/developer/releases/3.1/release-notes.md @@ -1,7 +1,9 @@ --- +lang: en layout: doc -title: Qubes R3.1 release notes permalink: /doc/releases/3.1/release-notes/ +ref: 16 +title: Qubes R3.1 release notes --- Qubes R3.1 release notes diff --git a/developer/releases/3.1/schedule.md b/developer/releases/3.1/schedule.md index ede408ed8f..46dfe8b44c 100644 --- a/developer/releases/3.1/schedule.md +++ b/developer/releases/3.1/schedule.md @@ -1,9 +1,11 @@ --- +lang: en layout: doc -title: Qubes R3.1 Release Schedule permalink: /doc/releases/3.1/schedule/ redirect_from: - /en/doc/releases/3.1/schedule/ +ref: 17 +title: Qubes R3.1 Release Schedule --- Qubes R3.1 Release Schedule diff --git a/developer/releases/3.2/release-notes.md b/developer/releases/3.2/release-notes.md index 2411915387..b411a6c666 100644 --- a/developer/releases/3.2/release-notes.md +++ b/developer/releases/3.2/release-notes.md @@ -1,7 +1,9 @@ --- +lang: en layout: doc -title: Qubes R3.2 release notes permalink: /doc/releases/3.2/release-notes/ +ref: 21 +title: Qubes R3.2 release notes --- Qubes R3.2 release notes diff --git a/developer/releases/3.2/schedule.md b/developer/releases/3.2/schedule.md index 05dc5599b4..5fc3fdd5fc 100644 --- a/developer/releases/3.2/schedule.md +++ b/developer/releases/3.2/schedule.md @@ -1,9 +1,11 @@ --- +lang: en layout: doc -title: Qubes R3.2 Release Schedule permalink: /doc/releases/3.2/schedule/ redirect_from: - /en/doc/releases/3.2/schedule/ +ref: 22 +title: Qubes R3.2 Release Schedule --- Qubes R3.2 Release Schedule diff --git a/developer/releases/4.0/release-notes.md b/developer/releases/4.0/release-notes.md index 3033692423..0e4e1d5842 100644 --- a/developer/releases/4.0/release-notes.md +++ b/developer/releases/4.0/release-notes.md @@ -1,7 +1,9 @@ --- +lang: en layout: doc -title: Qubes R4.0 release notes permalink: /doc/releases/4.0/release-notes/ +ref: 23 +title: Qubes R4.0 release notes --- Qubes R4.0 release notes diff --git a/developer/releases/4.0/schedule.md b/developer/releases/4.0/schedule.md index ca2a3c5ce5..29e0a5866e 100644 --- a/developer/releases/4.0/schedule.md +++ b/developer/releases/4.0/schedule.md @@ -1,9 +1,11 @@ --- +lang: en layout: doc -title: Qubes R4.0 Release Schedule permalink: /doc/releases/4.0/schedule/ redirect_from: - /en/doc/releases/4.0/schedule/ +ref: 24 +title: Qubes R4.0 Release Schedule --- Qubes R4.0 Release Schedule diff --git a/developer/releases/notes.md b/developer/releases/notes.md index cb1119f9db..0a6f9f02d8 100644 --- a/developer/releases/notes.md +++ b/developer/releases/notes.md @@ -1,7 +1,9 @@ --- +lang: en layout: doc -title: Release Notes permalink: /doc/releases/notes/ +ref: 13 +title: Release Notes --- Release Notes @@ -13,4 +15,3 @@ Release Notes * [Qubes R3.1 release notes](/doc/releases/3.1/release-notes/) * [Qubes R3.2 release notes](/doc/releases/3.2/release-notes/) * [Qubes R4.0 release notes](/doc/releases/4.0/release-notes/) - diff --git a/developer/releases/schedules.md b/developer/releases/schedules.md index 50c6824cdb..2e5257ec2f 100644 --- a/developer/releases/schedules.md +++ b/developer/releases/schedules.md @@ -1,7 +1,9 @@ --- +lang: en layout: doc -title: Release Schedules permalink: /doc/releases/schedules/ +ref: 15 +title: Release Schedules --- Release Schedules @@ -11,4 +13,3 @@ Release Schedules * [Qubes R3.1 release schedule](/doc/releases/3.1/schedule/) * [Qubes R3.2 release schedule](/doc/releases/3.2/schedule/) * [Qubes R4.0 release schedule](/doc/releases/4.0/schedule/) - diff --git a/developer/releases/todo.md b/developer/releases/todo.md index e9a9539989..28b5fc53df 100644 --- a/developer/releases/todo.md +++ b/developer/releases/todo.md @@ -1,9 +1,11 @@ --- +lang: en layout: doc -title: Release Checklist permalink: /doc/releases/todo/ redirect_from: - /en/doc/releases/todo/ +ref: 14 +title: Release Checklist --- Release Checklist diff --git a/developer/services/admin-api.md b/developer/services/admin-api.md index cdfcc65567..57d6f1c0d0 100644 --- a/developer/services/admin-api.md +++ b/developer/services/admin-api.md @@ -1,12 +1,14 @@ --- +lang: en layout: doc-full -title: Admin API permalink: /doc/admin-api/ redirect_from: - /doc/mgmt/ - /doc/mgmt1/ - /doc/mgmt-architecture/ - /doc/admin-api-architecture/ +ref: 36 +title: Admin API --- # Qubes OS Admin API diff --git a/developer/services/dom0-secure-updates.md b/developer/services/dom0-secure-updates.md index 805df16c98..1902fa5f5f 100644 --- a/developer/services/dom0-secure-updates.md +++ b/developer/services/dom0-secure-updates.md @@ -1,11 +1,13 @@ --- +lang: en layout: doc -title: Dom0 Secure Updates permalink: /doc/dom0-secure-updates/ redirect_from: - /en/doc/dom0-secure-updates/ - /doc/Dom0SecureUpdates/ - /wiki/Dom0SecureUpdates/ +ref: 43 +title: Dom0 Secure Updates --- Qubes Dom0 secure update procedure diff --git a/developer/services/dvm-impl.md b/developer/services/dvm-impl.md index 72139f3e2e..dbda0cef08 100644 --- a/developer/services/dvm-impl.md +++ b/developer/services/dvm-impl.md @@ -1,11 +1,13 @@ --- +lang: en layout: doc -title: DVMimpl permalink: /doc/dvm-impl/ redirect_from: - /en/doc/dvm-impl/ - /doc/DVMimpl/ - /wiki/DVMimpl/ +ref: 34 +title: DVMimpl --- DisposableVM implementation in Qubes diff --git a/developer/services/qfilecopy.md b/developer/services/qfilecopy.md index 60c3cb3493..4f4260e0cd 100644 --- a/developer/services/qfilecopy.md +++ b/developer/services/qfilecopy.md @@ -1,11 +1,13 @@ --- +lang: en layout: doc -title: Qfilecopy permalink: /doc/qfilecopy/ redirect_from: - /en/doc/qfilecopy/ - /doc/Qfilecopy/ - /wiki/Qfilecopy/ +ref: 35 +title: Qfilecopy --- InterVM file copy design diff --git a/developer/services/qfileexchgd.md b/developer/services/qfileexchgd.md index dc6167c38c..934ae0836c 100644 --- a/developer/services/qfileexchgd.md +++ b/developer/services/qfileexchgd.md @@ -1,11 +1,13 @@ --- +lang: en layout: doc -title: Qfileexchgd permalink: /doc/qfileexchgd/ redirect_from: - /en/doc/qfileexchgd/ - /doc/Qfileexchgd/ - /wiki/Qfileexchgd/ +ref: 40 +title: Qfileexchgd --- **This mechanism is obsolete as of Qubes Beta 1!** @@ -54,4 +56,3 @@ In order to minimize attack surface presented by necessity to process virtual pe 2. *qfilexchgd* sees that "send" argument=="disposable", and creates a new DisposableVM by calling */usr/lib/qubes/qubes\_restore*. It adds the new DisposableVM to qubesDB via qvm\_collection.add\_new\_disposablevm. Then it attaches the virtual pendrive (previously attached as `/dev/xvdg` at AppVM1) as `/dev/xvdh` in DisposableVM. 3. In DisposableVM, *qubes\_add\_pendrive\_script* sees non-zero `qubes_transaction_seq` key in xenstore, and instead processing the virtual pendrive as in the case of normal copy, treats it as DVM transaction (a request, because we run in DisposableVM). It retrieves the body of the file passed in `/dev/xvdh`, copies to /tmp, and runs *mime-open* utility to open appropriate executable to edit it. When *mime-open* returns, if the file was modified, it is sent back to AppVM1 (by writing "send AppVM1 SEQ" to `device/qpen` xenstore key). Then DisposableVM destroys itself. 4. In AppVM1, a new `/dev/xvdh` appears (because DisposableVM has sent it). *qubes\_add\_pendrive\_script* sees non-zero `qubes_transaction_seq` key, and treats it as DVM transaction (a response, because we run in AppVM, not DisposableVM). It retrieves the filename from `/home/user/.dvm/SEQ`, and copies data from `/dev/xvdh` to it. - diff --git a/developer/services/qmemman.md b/developer/services/qmemman.md index 356ddbf503..1d61bc09ed 100644 --- a/developer/services/qmemman.md +++ b/developer/services/qmemman.md @@ -1,11 +1,13 @@ --- +lang: en layout: doc -title: Qmemman permalink: /doc/qmemman/ redirect_from: - /en/doc/qmemman/ - /doc/Qmemman/ - /wiki/Qmemman/ +ref: 41 +title: Qmemman --- qmemman, Qubes memory manager @@ -74,4 +76,3 @@ Whenever *qmemman* is asked to return X megabytes of memory to Xen free pool, th 3. shrink donors, proportionally to their `prefmem`, so that X MB should become free 4. wait BALOON\_DELAY (0.1s) 5. if some domain have not given back any memory, remove it from the donors list, and go to step 2, unless we already did MAX\_TRIES (20) iterations (then return error). - diff --git a/developer/services/qrexec-internals.md b/developer/services/qrexec-internals.md index 37d6ffcc8d..6771482d78 100644 --- a/developer/services/qrexec-internals.md +++ b/developer/services/qrexec-internals.md @@ -1,12 +1,14 @@ --- +lang: en layout: doc -title: "Qrexec: Qubes RPC internals" permalink: /doc/qrexec-internals/ redirect_from: - /doc/qrexec3-implementation/ - /en/doc/qrexec3-implementation/ - /doc/Qrexec3Implementation/ - /wiki/Qrexec3Implementation/ +ref: 39 +title: 'Qrexec: Qubes RPC internals' --- # Qubes RPC internals diff --git a/developer/services/qrexec-socket-services.md b/developer/services/qrexec-socket-services.md index a98045ebcd..f6a8275042 100644 --- a/developer/services/qrexec-socket-services.md +++ b/developer/services/qrexec-socket-services.md @@ -1,7 +1,9 @@ --- +lang: en layout: doc -title: "Qrexec: Socket-based services" permalink: /doc/qrexec-socket-services/ +ref: 42 +title: 'Qrexec: Socket-based services' --- # Qrexec: Socket-based services diff --git a/developer/services/qrexec.md b/developer/services/qrexec.md index dcf2575000..0b74ca3aae 100644 --- a/developer/services/qrexec.md +++ b/developer/services/qrexec.md @@ -1,16 +1,17 @@ --- +lang: en layout: doc -title: "Qrexec: secure communication across domains" permalink: /doc/qrexec/ redirect_from: - /en/doc/qrexec3/ - /doc/Qrexec3/ - /doc/qrexec3/ - /wiki/Qrexec3/ -- /doc/qrexec/ - /en/doc/qrexec/ - /doc/Qrexec/ - /wiki/Qrexec/ +ref: 37 +title: 'Qrexec: secure communication across domains' --- # Qrexec: secure communication across domains diff --git a/developer/services/qrexec2.md b/developer/services/qrexec2.md index 1f5f3c480b..20dff90c81 100644 --- a/developer/services/qrexec2.md +++ b/developer/services/qrexec2.md @@ -1,12 +1,14 @@ --- +lang: en layout: doc -title: Qrexec2 permalink: /doc/qrexec2/ redirect_from: - /doc/qrexec2-implementation/ - /en/doc/qrexec2-implementation/ - /doc/Qrexec2Implementation/ - /wiki/Qrexec2Implementation/ +ref: 38 +title: Qrexec2 --- # Command execution in VMs # diff --git a/developer/system/architecture.md b/developer/system/architecture.md index 5d02408ec4..5e6d41bb71 100644 --- a/developer/system/architecture.md +++ b/developer/system/architecture.md @@ -1,12 +1,14 @@ --- +lang: en layout: doc -title: Architecture permalink: /doc/architecture/ redirect_from: - /doc/qubes-architecture/ - /en/doc/qubes-architecture/ - /doc/QubesArchitecture/ - /wiki/QubesArchitecture/ +ref: 56 +title: Architecture --- Qubes Architecture Overview diff --git a/developer/system/audio.md b/developer/system/audio.md index 05c69bab61..63de31983b 100644 --- a/developer/system/audio.md +++ b/developer/system/audio.md @@ -1,7 +1,9 @@ --- +lang: en layout: doc -title: Audio Virtualization permalink: /doc/audio-virtualization/ +ref: 60 +title: Audio Virtualization --- Audio Virtualization @@ -68,4 +70,3 @@ The current status is written into QubesDB at `/audio-input/VMNAME` (where `VMNA The lack of a key means that the `pacat-simple-vchan` for a given VM is not running. In either version, it is exposed to the user as device of class `mic`, which can be attached to a VM (for example, using the `qvm-device mic` command). - diff --git a/developer/system/gui.md b/developer/system/gui.md index 8e17e8276d..d4eba90def 100644 --- a/developer/system/gui.md +++ b/developer/system/gui.md @@ -1,12 +1,14 @@ --- +lang: en layout: doc -title: GUI permalink: /doc/gui/ redirect_from: - /en/doc/gui/ - /en/doc/gui-docs/ - /doc/GUIdocs/ - /wiki/GUIdocs/ +ref: 61 +title: GUI --- Qubes GUI protocol diff --git a/developer/system/networking.md b/developer/system/networking.md index cde78adee2..936744602b 100644 --- a/developer/system/networking.md +++ b/developer/system/networking.md @@ -1,12 +1,14 @@ --- +lang: en layout: doc -title: Networking permalink: /doc/networking/ redirect_from: - /doc/qubes-net/ - /en/doc/qubes-net/ - /doc/QubesNet/ - /wiki/QubesNet/ +ref: 59 +title: Networking --- VM network in Qubes @@ -68,4 +70,3 @@ Besides enabling IPv6 forwarding, standard Qubes firewall can be used to limit w Currently only IPv4 DNS servers are configured, regardless of `ipv6` feature state. It is done this way to avoid reconfiguring all connected qubes whenever IPv6 DNS becomes available or not. Configuring qubes to always use IPv6 DNS and only fallback to IPv4 may result in relatively long timeouts and poor usability. But note that DNS using IPv4 does not prevent to return IPv6 addresses. In practice this is only a problem for IPv6-only networks. - diff --git a/developer/system/security-critical-code.md b/developer/system/security-critical-code.md index 9c6ccab627..9adf926be9 100644 --- a/developer/system/security-critical-code.md +++ b/developer/system/security-critical-code.md @@ -1,12 +1,14 @@ --- +lang: en layout: doc -title: Security-critical Code permalink: /doc/security-critical-code/ redirect_from: - /en/doc/security-critical-code/ - /doc/SecurityCriticalCode/ - /wiki/SecurityCriticalCode/ - /trac/wiki/SecurityCriticalCode/ +ref: 55 +title: Security-critical Code --- Security-critical Code in Qubes OS @@ -78,4 +80,3 @@ This software is signed by Fedora distribution keys, so it is also critical that [Qubes Security Goals]: /security/goals/ [Fedora Project]: https://getfedora.org/ [Understanding and Preventing Data Leaks]: /doc/data-leaks/ - diff --git a/developer/system/storage-pools.md b/developer/system/storage-pools.md index 8886f406f2..70c30d3d3b 100644 --- a/developer/system/storage-pools.md +++ b/developer/system/storage-pools.md @@ -1,7 +1,9 @@ --- +lang: en layout: doc -title: Storage Pools permalink: /doc/storage-pools/ +ref: 57 +title: Storage Pools --- Storage Pools in Qubes @@ -50,4 +52,4 @@ argument to `qvm-create` to have the VM images stored in pool `foo`. See also `qvm-create --help`. While the current API is not as clean and beautiful as the R4 API, it allows -you to write your own storage drivers e.g. for Btrfs today. +you to write your own storage drivers e.g. for Btrfs today. diff --git a/developer/system/system-doc.md b/developer/system/system-doc.md index 110e7fb7e2..1bdaa99703 100644 --- a/developer/system/system-doc.md +++ b/developer/system/system-doc.md @@ -1,6 +1,6 @@ --- +lang: en layout: doc -title: System Documentation permalink: /doc/system-doc/ redirect_from: - /en/doc/system-doc/ @@ -8,5 +8,6 @@ redirect_from: - /wiki/SystemDoc/ redirect_to: - /doc/#developer-documentation +ref: 62 +title: System Documentation --- - diff --git a/developer/system/template-implementation.md b/developer/system/template-implementation.md index 0f3209105e..b1bd137444 100644 --- a/developer/system/template-implementation.md +++ b/developer/system/template-implementation.md @@ -1,11 +1,13 @@ --- +lang: en layout: doc -title: Template Implementation permalink: /doc/template-implementation/ redirect_from: - /en/doc/template-implementation/ - /doc/TemplateImplementation/ - /wiki/TemplateImplementation/ +ref: 58 +title: Template Implementation --- Overview of VM block devices diff --git a/doc.md b/doc.md index df16c6ed0a..f76a61e2eb 100644 --- a/doc.md +++ b/doc.md @@ -1,6 +1,6 @@ --- +lang: en layout: doc-index -title: Documentation permalink: /doc/ redirect_from: - /en/doc/ @@ -12,7 +12,10 @@ redirect_from: - /en/help/ - /en/community/ - /community/ +ref: 12 +title: Documentation --- + ## Table of Contents 1. [Introduction](#introduction) 2. [Project Security](#project-security) @@ -304,4 +307,3 @@ Unofficial, third-party documentation from the Qubes community and others. * [Building the Archlinux Template](/doc/building-archlinux-template/) * [Building the Whonix Templates](/doc/building-whonix-template/) * [How to compile kernels for dom0](https://groups.google.com/d/topic/qubes-users/yBeUJPwKwHM/discussion) - diff --git a/external/building-guides/building-archlinux-template.md b/external/building-guides/building-archlinux-template.md index 0f996223c7..21d85c3f14 100644 --- a/external/building-guides/building-archlinux-template.md +++ b/external/building-guides/building-archlinux-template.md @@ -1,11 +1,13 @@ --- +lang: en layout: doc -title: Building Archlinux Template permalink: /doc/building-archlinux-template/ redirect_from: - /en/doc/building-archlinux-template/ - /doc/BuildingArchlinuxTemplate/ - /wiki/BuildingArchlinuxTemplate/ +ref: 116 +title: Building Archlinux Template --- Archlinux template building instructions diff --git a/external/building-guides/building-non-fedora-template.md b/external/building-guides/building-non-fedora-template.md index b8e409f0f9..99e752e9df 100644 --- a/external/building-guides/building-non-fedora-template.md +++ b/external/building-guides/building-non-fedora-template.md @@ -1,11 +1,13 @@ --- +lang: en layout: doc -title: Building Non-Fedora Template permalink: /doc/building-non-fedora-template/ redirect_from: - /en/doc/building-non-fedora-template/ - /doc/BuildingNonFedoraTemplate/ - /wiki/BuildingNonFedoraTemplate/ +ref: 117 +title: Building Non-Fedora Template --- Building a TemplateVM for a new OS diff --git a/external/building-guides/building-whonix-template.md b/external/building-guides/building-whonix-template.md index 423487b1dc..4ee9f4ff7e 100644 --- a/external/building-guides/building-whonix-template.md +++ b/external/building-guides/building-whonix-template.md @@ -1,9 +1,11 @@ --- +lang: en layout: doc -title: Building Whonix Templates permalink: /doc/building-whonix-template/ redirect_from: - /en/doc/building-whonix-template/ +ref: 115 +title: Building Whonix Templates --- ## Building Whonix Templates @@ -90,5 +92,3 @@ sudo dnf install qubes-template-whonix-ws-4.0.0-201802250145.noarch.rpm ~~~ And you are done! - - diff --git a/external/configuration-guides/change-time-zone.md b/external/configuration-guides/change-time-zone.md index 48463178f1..7bdd5f8635 100644 --- a/external/configuration-guides/change-time-zone.md +++ b/external/configuration-guides/change-time-zone.md @@ -1,7 +1,9 @@ --- +lang: en layout: doc -title: Changing your Time Zone permalink: /doc/change-time-zone/ +ref: 109 +title: Changing your Time Zone --- # Changing your Time Zone # @@ -33,4 +35,3 @@ Europe/Berlin: Network time on: no NTP synchronized: no RTC in local TZ: no - diff --git a/external/configuration-guides/disk-trim.md b/external/configuration-guides/disk-trim.md index e1fe258333..66b7afdc14 100644 --- a/external/configuration-guides/disk-trim.md +++ b/external/configuration-guides/disk-trim.md @@ -1,11 +1,13 @@ --- +lang: en layout: doc -title: Disk TRIM permalink: /doc/disk-trim/ redirect_from: - /en/doc/disk-trim/ - /doc/DiskTRIM/ - /wiki/DiskTRIM/ +ref: 104 +title: Disk TRIM --- Disk Trim diff --git a/external/configuration-guides/external-audio.md b/external/configuration-guides/external-audio.md index b50c6a753b..029c9d6f40 100644 --- a/external/configuration-guides/external-audio.md +++ b/external/configuration-guides/external-audio.md @@ -1,11 +1,13 @@ --- +lang: en layout: doc -title: External Audio permalink: /doc/external-audio/ redirect_from: - /en/doc/external-audio/ - /doc/ExternalAudio/ - /wiki/ExternalAudio/ +ref: 100 +title: External Audio --- Using External Audio Devices diff --git a/external/configuration-guides/fetchmail.md b/external/configuration-guides/fetchmail.md index 25bd4ab68b..3b0b953a3c 100644 --- a/external/configuration-guides/fetchmail.md +++ b/external/configuration-guides/fetchmail.md @@ -1,11 +1,13 @@ --- +lang: en layout: doc -title: Fetchmail permalink: /doc/fetchmail/ redirect_from: - /en/doc/fetchmail/ - /doc/Fetchmail/ - /wiki/Fetchmail/ +ref: 114 +title: Fetchmail --- Fetchmail diff --git a/external/configuration-guides/multiboot.md b/external/configuration-guides/multiboot.md index d85f3cfb6a..ce411572c7 100644 --- a/external/configuration-guides/multiboot.md +++ b/external/configuration-guides/multiboot.md @@ -1,7 +1,9 @@ --- +lang: en layout: doc -title: Multibooting permalink: /doc/multiboot/ +ref: 112 +title: Multibooting --- Multibooting Qubes diff --git a/external/configuration-guides/multimedia.md b/external/configuration-guides/multimedia.md index 43fdedcafb..6167dedf33 100644 --- a/external/configuration-guides/multimedia.md +++ b/external/configuration-guides/multimedia.md @@ -1,11 +1,13 @@ --- +lang: en layout: doc -title: How to Make a Multimedia TemplateVM permalink: /doc/multimedia/ redirect_from: - /en/doc/multimedia/ - /doc/Multimedia/ - /wiki/Multimedia/ +ref: 105 +title: How to Make a Multimedia TemplateVM --- How to Make a Multimedia TemplateVM @@ -237,4 +239,3 @@ Create a Multimedia AppVM The last step is to create a multimedia AppVM (named "my-multimedia" here) based on the new multimedia template. `qvm-create --template t-multimedia --label orange my-multimedia` - diff --git a/external/configuration-guides/mutt.md b/external/configuration-guides/mutt.md index 6118a3d2cd..464190bf2b 100644 --- a/external/configuration-guides/mutt.md +++ b/external/configuration-guides/mutt.md @@ -1,11 +1,13 @@ --- +lang: en layout: doc -title: Mutt permalink: /doc/mutt/ redirect_from: - /en/doc/mutt/ - /doc/Mutt/ - /wiki/Mutt/ +ref: 106 +title: Mutt --- Mutt diff --git a/external/configuration-guides/network-bridge-support.md b/external/configuration-guides/network-bridge-support.md index 822d991f0e..d703aa96a7 100644 --- a/external/configuration-guides/network-bridge-support.md +++ b/external/configuration-guides/network-bridge-support.md @@ -1,11 +1,13 @@ --- +lang: en layout: doc -title: Network Bridge Support permalink: /doc/network-bridge-support/ redirect_from: - /en/doc/network-bridge-support/ - /doc/NetworkBridgeSupport/ - /wiki/NetworkBridgeSupport/ +ref: 113 +title: Network Bridge Support --- Network Bridge Support (EXPERIMENTAL and UNSUPPORTED) diff --git a/external/configuration-guides/network-printer.md b/external/configuration-guides/network-printer.md index f5d7ef9f78..180a44a439 100644 --- a/external/configuration-guides/network-printer.md +++ b/external/configuration-guides/network-printer.md @@ -1,11 +1,13 @@ --- +lang: en layout: doc -title: Network Printer permalink: /doc/network-printer/ redirect_from: - /en/doc/network-printer/ - /doc/NetworkPrinter/ - /wiki/NetworkPrinter/ +ref: 108 +title: Network Printer --- Configuring a network printer for Qubes AppVMs @@ -52,4 +54,3 @@ Steps to configure a network printer in a template VM If it doesn't then probably the AppVM doesn't have networking access to the printer -- in that case adjust the firewall settings for that AppVM in Qubes Manager. Also, make sure that the AppVM gets restarted after the template was shutdown. 5. Alternatively if you do not want to modify the firewall rules of the template VM (that have security scope) you can simply shut down the template VM without trying to print the test page (which will not work), start or restart an AppVM based on the template and test printing there. - diff --git a/external/configuration-guides/postfix.md b/external/configuration-guides/postfix.md index 7a142f3784..327ff4ae56 100644 --- a/external/configuration-guides/postfix.md +++ b/external/configuration-guides/postfix.md @@ -1,11 +1,13 @@ --- +lang: en layout: doc -title: Postfix permalink: /doc/postfix/ redirect_from: - /en/doc/postfix/ - /doc/Postfix/ - /wiki/Postfix/ +ref: 107 +title: Postfix --- Postfix diff --git a/external/configuration-guides/rxvt.md b/external/configuration-guides/rxvt.md index aa0c0bbcc4..259e1dab40 100644 --- a/external/configuration-guides/rxvt.md +++ b/external/configuration-guides/rxvt.md @@ -1,11 +1,13 @@ --- +lang: en layout: doc -title: Rxvt permalink: /doc/rxvt/ redirect_from: - /en/doc/rxvt/ - /doc/Rxvt/ - /wiki/Rxvt/ +ref: 103 +title: Rxvt --- Rxvt diff --git a/external/configuration-guides/tips-and-tricks.md b/external/configuration-guides/tips-and-tricks.md index f937b32d30..2e6d5e3655 100644 --- a/external/configuration-guides/tips-and-tricks.md +++ b/external/configuration-guides/tips-and-tricks.md @@ -1,7 +1,9 @@ --- +lang: en layout: doc -title: Tips and Tricks permalink: /doc/tips-and-tricks/ +ref: 110 +title: Tips and Tricks --- Tips and Tricks @@ -52,4 +54,3 @@ Start the Windows TemplateVM (which has no user data), install/upgrade apps; the This applies also to any TemplateBasedVM relative to its parent TemplateVM, but the privacy risk is especially high in the case of Windows. Credit: [Joanna Rutkovska](https://twitter.com/rootkovska/status/832571372085850112) - diff --git a/external/configuration-guides/vpn.md b/external/configuration-guides/vpn.md index 45227fdba9..1285b17ada 100644 --- a/external/configuration-guides/vpn.md +++ b/external/configuration-guides/vpn.md @@ -1,12 +1,14 @@ --- +lang: en layout: doc -title: VPN permalink: /doc/vpn/ redirect_from: - /doc/privacy/vpn/ - /en/doc/vpn/ - /doc/VPN/ - /wiki/VPN/ +ref: 102 +title: VPN --- How To make a VPN Gateway in Qubes diff --git a/external/configuration-guides/w3m.md b/external/configuration-guides/w3m.md index 5511adb357..79943f65ba 100644 --- a/external/configuration-guides/w3m.md +++ b/external/configuration-guides/w3m.md @@ -1,11 +1,13 @@ --- +lang: en layout: doc -title: Reducing the fingerprint of the text-based web browser w3m permalink: /doc/w3m/ redirect_from: - /en/doc/mutt/ - /doc/W3m/ - /wiki/W3m/ +ref: 101 +title: Reducing the fingerprint of the text-based web browser w3m --- Reducing the fingerprint of the text-based web browser w3m diff --git a/external/configuration-guides/zfs.md b/external/configuration-guides/zfs.md index 931d459a56..1261c231f4 100644 --- a/external/configuration-guides/zfs.md +++ b/external/configuration-guides/zfs.md @@ -1,11 +1,13 @@ --- +lang: en layout: doc -title: ZFS permalink: /doc/zfs/ redirect_from: - /en/doc/zfs/ - /doc/ZFS/ - /wiki/ZFS/ +ref: 111 +title: ZFS --- ZFS in Qubes @@ -194,4 +196,3 @@ Further Reading - [http://www.open-zfs.org](http://www.open-zfs.org) - [http://zfsonlinux.org](http://zfsonlinux.org) - diff --git a/external/customization-guides/dark-theme.md b/external/customization-guides/dark-theme.md index b469aeacc8..5c1751900b 100644 --- a/external/customization-guides/dark-theme.md +++ b/external/customization-guides/dark-theme.md @@ -1,7 +1,9 @@ --- +lang: en layout: doc -title: Dark Theme in Dom0 and DomU permalink: /doc/dark-theme/ +ref: 74 +title: Dark Theme in Dom0 and DomU --- Dark Theme in Dom0 diff --git a/external/customization-guides/fedora-minimal-template-customization.md b/external/customization-guides/fedora-minimal-template-customization.md index d4280f2452..7c9d61a687 100644 --- a/external/customization-guides/fedora-minimal-template-customization.md +++ b/external/customization-guides/fedora-minimal-template-customization.md @@ -1,8 +1,10 @@ --- +lang: en layout: doc -title: Fedora Minimal Template Customization permalink: /doc/fedora-minimal-template-customization/ redirect_from: /en/doc/fedora-minimal-template-customization/ +ref: 76 +title: Fedora Minimal Template Customization --- FEDORA Packages Recommendations diff --git a/external/customization-guides/language-localization.md b/external/customization-guides/language-localization.md index 79c22558af..b402e2b925 100644 --- a/external/customization-guides/language-localization.md +++ b/external/customization-guides/language-localization.md @@ -1,11 +1,13 @@ --- +lang: en layout: doc -title: Language Localization permalink: /doc/language-localization/ redirect_from: - /en/doc/language-localization/ - /doc/LanguageLocalization/ - /wiki/LanguageLocalization/ +ref: 73 +title: Language Localization --- Language Localization diff --git a/external/customization-guides/removing-templatevm-packages.md b/external/customization-guides/removing-templatevm-packages.md index 9739981a7b..0ce6bf89a2 100644 --- a/external/customization-guides/removing-templatevm-packages.md +++ b/external/customization-guides/removing-templatevm-packages.md @@ -1,7 +1,9 @@ --- +lang: en layout: doc -title: Removing TemplateVM Packages permalink: /doc/removing-templatevm-packages/ +ref: 75 +title: Removing TemplateVM Packages --- # Removing TemplateVM Packages diff --git a/external/customization-guides/windows-template-customization.md b/external/customization-guides/windows-template-customization.md index ecaffa23fd..1de6237138 100644 --- a/external/customization-guides/windows-template-customization.md +++ b/external/customization-guides/windows-template-customization.md @@ -1,8 +1,10 @@ --- +lang: en layout: doc -title: Windows Template Customization permalink: /doc/windows-template-customization/ redirect_from: /en/doc/windows-template-customization/ +ref: 72 +title: Windows Template Customization --- Disable/Uninstall unnecessary features/services diff --git a/external/os-guides/centos.md b/external/os-guides/centos.md index 5b1c9d6721..64324e0edd 100644 --- a/external/os-guides/centos.md +++ b/external/os-guides/centos.md @@ -1,7 +1,9 @@ --- +lang: en layout: doc -title: CentOS Template permalink: /doc/templates/centos/ +ref: 81 +title: CentOS Template --- # CentOS Template @@ -32,5 +34,3 @@ After a fresh install, we recommend to [Update the TemplateVM](/doc/software-upd [switch]: /doc/templates/#switching [reinstall]: /doc/reinstall-template/ [uninstall]: /doc/templates/#uninstalling - - diff --git a/external/os-guides/linux-hvm-tips.md b/external/os-guides/linux-hvm-tips.md index c1c99fa382..7d0514a0ac 100644 --- a/external/os-guides/linux-hvm-tips.md +++ b/external/os-guides/linux-hvm-tips.md @@ -1,11 +1,13 @@ --- +lang: en layout: doc -title: Linux HVM Tips permalink: /doc/linux-hvm-tips/ redirect_from: - /en/doc/linux-hvm-tips/ - /doc/LinuxHVMTips/ - /wiki/LinuxHVMTips/ +ref: 82 +title: Linux HVM Tips --- Tips for Linux in HVM domain diff --git a/external/os-guides/netbsd.md b/external/os-guides/netbsd.md index 8b655ec296..b5d39b6f70 100644 --- a/external/os-guides/netbsd.md +++ b/external/os-guides/netbsd.md @@ -1,7 +1,9 @@ --- +lang: en layout: doc -title: How to Create a NetBSD VM permalink: /doc/netbsd/ +ref: 84 +title: How to Create a NetBSD VM --- How to Create a NetBSD VM diff --git a/external/os-guides/pentesting.md b/external/os-guides/pentesting.md index 56d79260e9..def8d5764b 100644 --- a/external/os-guides/pentesting.md +++ b/external/os-guides/pentesting.md @@ -1,7 +1,9 @@ --- +lang: en layout: doc -title: Penetration Testing permalink: /doc/pentesting/ +ref: 83 +title: Penetration Testing --- **Legal notice:** diff --git a/external/os-guides/pentesting/blackarch.md b/external/os-guides/pentesting/blackarch.md index b0f06be253..bc378a2f16 100644 --- a/external/os-guides/pentesting/blackarch.md +++ b/external/os-guides/pentesting/blackarch.md @@ -1,9 +1,11 @@ --- +lang: en layout: doc -title: How to Create a BlackArch VM permalink: /doc/pentesting/blackarch/ redirect_from: - /doc/blackarch/ +ref: 88 +title: How to Create a BlackArch VM --- **General reminder:** diff --git a/external/os-guides/pentesting/kali.md b/external/os-guides/pentesting/kali.md index 09a7bda7db..48eb74ceb7 100644 --- a/external/os-guides/pentesting/kali.md +++ b/external/os-guides/pentesting/kali.md @@ -1,9 +1,11 @@ --- +lang: en layout: doc -title: How to create a Kali Linux VM permalink: /doc/pentesting/kali/ redirect_from: - /doc/kali/ +ref: 87 +title: How to create a Kali Linux VM --- # How to create a Kali Linux VM @@ -616,4 +618,3 @@ Thanks to the people in [the discussion thread](https://github.com/QubesOS/qubes [Debian-releases]: https://www.debian.org/releases/ [Debian-security-naming-convention]: https://www.mail-archive.com/debian-security@lists.debian.org/msg41223.html - diff --git a/external/os-guides/pentesting/ptf.md b/external/os-guides/pentesting/ptf.md index badc085ba3..08fb544819 100644 --- a/external/os-guides/pentesting/ptf.md +++ b/external/os-guides/pentesting/ptf.md @@ -1,9 +1,11 @@ --- +lang: en layout: doc -title: How to create Penetration Testers Framework (PTF) VM permalink: /doc/pentesting/ptf/ redirect_from: - /doc/ptf/ +ref: 89 +title: How to create Penetration Testers Framework (PTF) VM --- **General reminder:** diff --git a/external/os-guides/ubuntu.md b/external/os-guides/ubuntu.md index 5bf691a57b..200e565f4b 100644 --- a/external/os-guides/ubuntu.md +++ b/external/os-guides/ubuntu.md @@ -1,12 +1,14 @@ --- +lang: en layout: doc -title: Ubuntu Template permalink: /doc/templates/ubuntu/ redirect_from: - /doc/ubuntu/ - /en/doc/templates/ubuntu/ - /doc/Templates/Ubuntu/ - /wiki/Templates/Ubuntu/ +ref: 80 +title: Ubuntu Template --- Ubuntu template(s) diff --git a/external/os-guides/windows/windows-tools.md b/external/os-guides/windows/windows-tools.md index 50678ac1b5..c37fea6824 100644 --- a/external/os-guides/windows/windows-tools.md +++ b/external/os-guides/windows/windows-tools.md @@ -1,6 +1,6 @@ --- +lang: en layout: doc -title: Qubes Windows Tools permalink: /doc/windows-tools/ redirect_from: - /doc/windows-appvms/ @@ -12,6 +12,8 @@ redirect_from: - /doc/WindowsTools3/ - /doc/WindowsTools/ - /wiki/WindowsTools/ +ref: 86 +title: Qubes Windows Tools --- Qubes Windows Tools @@ -256,4 +258,3 @@ When we publish new QWT version (which is announced on `qubes-users` Google Grou `qubes-dom0-update --enablerepo=qubes-dom0-current-testing qubes-windows-tools` That command will download a new QWT .iso from the testing repository. It goes without saying that you should **backup your VMs** before installing anything from testing repos. - diff --git a/external/os-guides/windows/windows-vm.md b/external/os-guides/windows/windows-vm.md index 74ea761c03..28945ec90b 100644 --- a/external/os-guides/windows/windows-vm.md +++ b/external/os-guides/windows/windows-vm.md @@ -1,10 +1,11 @@ --- +lang: en layout: doc -title: Installing a Windows VM permalink: /doc/windows-vm/ +ref: 85 +title: Installing a Windows VM --- - Installing a Windows VM ======================= @@ -250,4 +251,3 @@ Further customization --------------------- Please see the [Customizing Windows 7 templates](/doc/windows-template-customization/) page (despite the focus on preparing the VM for use as a template, most of the instructions are independent from how the VM will be used - ie. TemplateVM or StandaloneVM). - diff --git a/external/privacy-guides/anonymizing-your-mac-address.md b/external/privacy-guides/anonymizing-your-mac-address.md index 448e2a644b..eb26c2fcc7 100644 --- a/external/privacy-guides/anonymizing-your-mac-address.md +++ b/external/privacy-guides/anonymizing-your-mac-address.md @@ -1,9 +1,11 @@ --- +lang: en layout: doc -title: Anonymizing your MAC Address permalink: /doc/anonymizing-your-mac-address/ redirect_from: - /doc/randomizing-your-mac-address/ +ref: 67 +title: Anonymizing your MAC Address --- Anonymizing your MAC Address diff --git a/external/privacy-guides/signal.md b/external/privacy-guides/signal.md index b63788558e..9e810588fb 100644 --- a/external/privacy-guides/signal.md +++ b/external/privacy-guides/signal.md @@ -1,7 +1,9 @@ --- +lang: en layout: doc -title: Signal permalink: /doc/signal/ +ref: 70 +title: Signal --- Signal diff --git a/external/privacy-guides/tails.md b/external/privacy-guides/tails.md index be209018f6..872d10eb02 100644 --- a/external/privacy-guides/tails.md +++ b/external/privacy-guides/tails.md @@ -1,9 +1,11 @@ --- +lang: en layout: doc -title: Running Tails in Qubes permalink: /doc/tails/ redirect_from: - /doc/running-tails +ref: 71 +title: Running Tails in Qubes --- Running Tails in Qubes diff --git a/external/privacy-guides/torvm.md b/external/privacy-guides/torvm.md index d04de0f182..b677161416 100644 --- a/external/privacy-guides/torvm.md +++ b/external/privacy-guides/torvm.md @@ -1,6 +1,6 @@ --- +lang: en layout: doc -title: TorVM permalink: /doc/torvm/ redirect_from: - /doc/privacy/torvm/ @@ -8,6 +8,8 @@ redirect_from: - /doc/TorVM/ - /doc/UserDoc/TorVM/ - /wiki/UserDoc/TorVM/ +ref: 68 +title: TorVM --- Known issues: diff --git a/external/privacy-guides/whonix.md b/external/privacy-guides/whonix.md index 7835d4c863..25a59fea90 100644 --- a/external/privacy-guides/whonix.md +++ b/external/privacy-guides/whonix.md @@ -1,6 +1,6 @@ --- +lang: en layout: doc -title: Whonix for Privacy & Anonymity permalink: /doc/whonix/ redirect_from: - /doc/privacy/whonix/ @@ -16,6 +16,8 @@ redirect_from: - /doc/privacy/uninstall-whonix/ - /doc/whonix/update/ - /doc/privacy/updating-whonix/ +ref: 69 +title: Whonix for Privacy & Anonymity --- Whonix for Privacy & Anonymity @@ -55,4 +57,3 @@ Note: To install Whonix in Qubes, you must [install Qubes](/doc/installation-gui * [Whonix Support](https://www.whonix.org/wiki/Support) - General Whonix, Debian, Tor, etc... related issues * [Whonix Qubes Forum](https://forums.whonix.org/c/qubes) - Whonix specific issues - diff --git a/external/security-guides/multifactor-authentication.md b/external/security-guides/multifactor-authentication.md index 9d074666a5..c5dc7b5fb6 100644 --- a/external/security-guides/multifactor-authentication.md +++ b/external/security-guides/multifactor-authentication.md @@ -1,10 +1,12 @@ --- +lang: en layout: doc -title: Multifactor Authentication permalink: /doc/multifactor-authentication/ redirect_from: - /en/doc/multifactor-authentication/ - /doc/Multi-factorAuthentication/ +ref: 78 +title: Multifactor Authentication --- Using Multi-factor Authentication with Qubes diff --git a/external/security-guides/security-guidelines.md b/external/security-guides/security-guidelines.md index 4a85d552fd..89cf38449a 100644 --- a/external/security-guides/security-guidelines.md +++ b/external/security-guides/security-guidelines.md @@ -1,11 +1,13 @@ --- +lang: en layout: doc -title: Security Guidelines permalink: /doc/security-guidelines/ redirect_from: - /en/doc/security-guidelines/ - /doc/SecurityGuidelines/ - /wiki/SecurityGuidelines/ +ref: 79 +title: Security Guidelines --- Security Guidelines @@ -163,4 +165,3 @@ TemplateBasedVM Directories changes in the parent TemplateVM. * See [here](/doc/templates) for more detail and version specific information. - diff --git a/external/security-guides/split-bitcoin.md b/external/security-guides/split-bitcoin.md index 3665a7e7ea..375bea49ad 100644 --- a/external/security-guides/split-bitcoin.md +++ b/external/security-guides/split-bitcoin.md @@ -1,7 +1,9 @@ --- +lang: en layout: doc -title: Split Bitcoin permalink: /doc/split-bitcoin/ +ref: 77 +title: Split Bitcoin --- How to Set Up a Split Bitcoin Wallet in Qubes @@ -49,4 +51,3 @@ Important Notes [inter-VM clipboard]: /doc/copy-paste/ [inter-VM file copy]: /doc/copying-files/ - diff --git a/external/troubleshooting/install-nvidia-driver.md b/external/troubleshooting/install-nvidia-driver.md index 97b8826930..6df99f808a 100644 --- a/external/troubleshooting/install-nvidia-driver.md +++ b/external/troubleshooting/install-nvidia-driver.md @@ -1,11 +1,13 @@ --- +lang: en layout: doc -title: How to Install an Nvidia Driver permalink: /doc/install-nvidia-driver/ redirect_from: - /en/doc/install-nvidia-driver/ - /doc/InstallNvidiaDriver/ - /wiki/InstallNvidiaDriver/ +ref: 96 +title: How to Install an Nvidia Driver --- # Nvidia proprietary driver installation diff --git a/external/troubleshooting/intel-igfx-troubleshooting.md b/external/troubleshooting/intel-igfx-troubleshooting.md index 03014ebb3f..6a620312bf 100644 --- a/external/troubleshooting/intel-igfx-troubleshooting.md +++ b/external/troubleshooting/intel-igfx-troubleshooting.md @@ -1,8 +1,11 @@ --- +lang: en layout: doc -title: Intel Integrated Graphics Troubleshooting permalink: /doc/intel-igfx-troubleshooting/ +ref: 90 +title: Intel Integrated Graphics Troubleshooting --- + # Intel Integrated Graphics Troubleshooting # ## Software Rendering or Video Lags @@ -62,4 +65,3 @@ Edit the startup parameters for Xen: 3. Add to the line `options` the setting `iommu=no-igfx`, save and quit 1 [↩](#a1-1) - diff --git a/external/troubleshooting/macbook-troubleshooting.md b/external/troubleshooting/macbook-troubleshooting.md index 5743a67b4d..2aef629a7d 100644 --- a/external/troubleshooting/macbook-troubleshooting.md +++ b/external/troubleshooting/macbook-troubleshooting.md @@ -1,7 +1,9 @@ --- +lang: en layout: doc -title: Apple MacBook Troubleshooting permalink: /doc/macbook-troubleshooting/ +ref: 99 +title: Apple MacBook Troubleshooting --- Apple MacBook Troubleshooting diff --git a/external/troubleshooting/nvidia-troubleshooting.md b/external/troubleshooting/nvidia-troubleshooting.md index af54891a9e..9a17c23dee 100644 --- a/external/troubleshooting/nvidia-troubleshooting.md +++ b/external/troubleshooting/nvidia-troubleshooting.md @@ -1,11 +1,13 @@ --- +lang: en layout: doc -title: Nvidia Troubleshooting permalink: /doc/nvidia-troubleshooting/ redirect_from: - /en/doc/nvidia-troubleshooting/ - /doc/NvidiaTroubleshooting/ - /wiki/NvidiaTroubleshooting/ +ref: 91 +title: Nvidia Troubleshooting --- NVidia Troubleshooting Guide @@ -156,4 +158,3 @@ You'll have to do the following to make this change persistent, so that it will ~~~ sudo grub2-mkconfig -o /boot/grub2/grub.cfg ~~~ - diff --git a/external/troubleshooting/out-of-memory.md b/external/troubleshooting/out-of-memory.md index 869da99335..9e889e7e84 100644 --- a/external/troubleshooting/out-of-memory.md +++ b/external/troubleshooting/out-of-memory.md @@ -1,11 +1,13 @@ --- +lang: en layout: doc -title: Out of Memory permalink: /doc/out-of-memory/ redirect_from: - /en/doc/out-of-memory/ - /doc/OutOfmemory/ - /wiki/OutOfmemory/ +ref: 97 +title: Out of Memory --- VMs (especially templates) use pre-allocated space. The default private storage max size is 2 GB, but it's very easy to increase as needed. If the disk is completely full, you will get an `Out of disk space` error that may crash your system because Dom0 does not have enough disk space to work. So it's good practice to regularly check disk space usage with the command `df -h` in dom0 terminal. @@ -43,4 +45,3 @@ In any case you'll need some disk space to start the VM. Check `df -h` output if ~~~ 4. Remove some unneeded files in dom0 home (if you have any, most likely not). - diff --git a/external/troubleshooting/remove-vm-manually.md b/external/troubleshooting/remove-vm-manually.md index fbc1c145b8..b6756cb71e 100644 --- a/external/troubleshooting/remove-vm-manually.md +++ b/external/troubleshooting/remove-vm-manually.md @@ -1,7 +1,9 @@ --- +lang: en layout: doc -title: How to Remove VMs Manually permalink: /doc/remove-vm-manually/ +ref: 92 +title: How to Remove VMs Manually --- How to Remove VMs Manually @@ -33,4 +35,3 @@ When a template is marked as 'installed by package manager', but cannot be unins [normal method]: /doc/templates/#uninstalling - diff --git a/external/troubleshooting/sony-vaio-tinkering.md b/external/troubleshooting/sony-vaio-tinkering.md index 022e8bfa55..f44bb33060 100644 --- a/external/troubleshooting/sony-vaio-tinkering.md +++ b/external/troubleshooting/sony-vaio-tinkering.md @@ -1,11 +1,13 @@ --- +lang: en layout: doc -title: Sony Vaio Tinkering permalink: /doc/sony-vaio-tinkering/ redirect_from: - /en/doc/sony-vaio-tinkering/ - /doc/SonyVaioTinkering/ - /wiki/SonyVaioTinkering/ +ref: 93 +title: Sony Vaio Tinkering --- Instructions for getting your Sony Vaio Z laptop working with Qubes/Linux diff --git a/external/troubleshooting/thinkpad-troubleshooting.md b/external/troubleshooting/thinkpad-troubleshooting.md index c4e94a5aec..03bca9e69b 100644 --- a/external/troubleshooting/thinkpad-troubleshooting.md +++ b/external/troubleshooting/thinkpad-troubleshooting.md @@ -1,6 +1,6 @@ --- +lang: en layout: doc -title: Lenovo ThinkPad Troubleshooting permalink: /doc/thinkpad-troubleshooting/ redirect_from: - /doc/thinkpad_x201/ @@ -11,6 +11,8 @@ redirect_from: - /en/doc/lenovo450-tinkering/ - /doc/Lenovo450Tinkering/ - /wiki/Lenovo450Tinkering/ +ref: 95 +title: Lenovo ThinkPad Troubleshooting --- # Lenovo ThinkPad Troubleshooting # @@ -91,4 +93,3 @@ Lenovo 450 uses UEFI, so some settings are needed to get Qubes (or Fedora) to bo 5. Install Qubes ... and now enjoy :) These settings may be needed also in other UEFI computers. - diff --git a/external/troubleshooting/updating-debian-and-whonix.md b/external/troubleshooting/updating-debian-and-whonix.md index 39091d1fbf..9c7cbee76b 100644 --- a/external/troubleshooting/updating-debian-and-whonix.md +++ b/external/troubleshooting/updating-debian-and-whonix.md @@ -1,7 +1,9 @@ --- +lang: en layout: doc -title: Updating Debian and Whonix permalink: /doc/troubleshooting/updating-debian-and-whonix/ +ref: 98 +title: Updating Debian and Whonix --- Updating Debian and Whonix diff --git a/external/troubleshooting/wireless-troubleshooting.md b/external/troubleshooting/wireless-troubleshooting.md index 9c8ea33de5..f0e9daa3a2 100644 --- a/external/troubleshooting/wireless-troubleshooting.md +++ b/external/troubleshooting/wireless-troubleshooting.md @@ -1,9 +1,11 @@ --- +lang: en layout: doc -title: Wireless Troubleshooting permalink: /doc/wireless-troubleshooting/ redirect_from: - /en/doc/wireless-troubleshooting/ +ref: 94 +title: Wireless Troubleshooting --- Wireless Troubleshooting Guide diff --git a/introduction/code-of-conduct.md b/introduction/code-of-conduct.md index f4c0d835d4..b57d5436d1 100644 --- a/introduction/code-of-conduct.md +++ b/introduction/code-of-conduct.md @@ -1,7 +1,9 @@ --- +lang: en layout: default -title: Code of Conduct permalink: /code-of-conduct/ +ref: 118 +title: Code of Conduct --- ## Introduction diff --git a/introduction/contributing.md b/introduction/contributing.md index 9326f797e4..4091f2164d 100644 --- a/introduction/contributing.md +++ b/introduction/contributing.md @@ -1,11 +1,13 @@ --- +lang: en layout: doc -title: Contributing to the Qubes OS Project permalink: /doc/contributing/ redirect_from: - /en/doc/contributing/ - /doc/ContributingHowto/ - /wiki/ContributingHowto/ +ref: 125 +title: Contributing to the Qubes OS Project --- How to Contribute to the Qubes OS Project @@ -79,4 +81,3 @@ be grateful to [receive your patch][patch]. [qubes-devel]: /support/#qubes-devel [Community-Developed Feature Tracker]: /qubes-issues/ [Qubes download mirror]: /downloads/mirrors/ - diff --git a/introduction/experts.md b/introduction/experts.md index 29ec32dac4..e508aa47af 100644 --- a/introduction/experts.md +++ b/introduction/experts.md @@ -1,7 +1,9 @@ --- +lang: en layout: home -title: Experts permalink: /experts/ +ref: 119 +title: Experts ---
diff --git a/introduction/faq.md b/introduction/faq.md index 4ca3addef5..5eb3af5937 100644 --- a/introduction/faq.md +++ b/introduction/faq.md @@ -1,6 +1,6 @@ --- +lang: en layout: sidebar -title: Frequently Asked Questions permalink: /faq/ redirect_from: - /doc/user-faq/ @@ -11,6 +11,8 @@ redirect_from: - /en/doc/devel-faq/ - /doc/DevelFaq/ - /wiki/DevelFaq/ +ref: 124 +title: Frequently Asked Questions --- # Frequently Asked Questions diff --git a/introduction/intro.md b/introduction/intro.md index 18e3cb2b7e..6925762f36 100644 --- a/introduction/intro.md +++ b/introduction/intro.md @@ -1,6 +1,6 @@ --- +lang: en layout: intro -title: An Introduction to Qubes OS permalink: /intro/ redirect_from: - /tour/ @@ -8,6 +8,8 @@ redirect_from: - /tour/#what-is-qubes-os - /about/ - /en/about/ +ref: 126 +title: An Introduction to Qubes OS --- What is Qubes OS? diff --git a/introduction/reporting-bugs.md b/introduction/reporting-bugs.md index 7f9a57a4db..215b49ab5a 100644 --- a/introduction/reporting-bugs.md +++ b/introduction/reporting-bugs.md @@ -1,6 +1,6 @@ --- +lang: en layout: doc -title: Reporting bugs and other issues permalink: /doc/reporting-bugs/ redirect_from: - /en/doc/reporting-bugs/ @@ -11,6 +11,8 @@ redirect_from: - /bugs/ - /bug-report/ - /bug-reports/ +ref: 121 +title: Reporting bugs and other issues --- # Reporting bugs and other issues # @@ -144,4 +146,3 @@ If the issue is closed without one of these specific resolutions, then it means, [Contributing Code]: /doc/contributing/#contributing-code [Package Contributions]: /doc/package-contributions/ [Documentation Guidelines]: /doc/doc-guidelines/ - diff --git a/introduction/screenshots.md b/introduction/screenshots.md index 0f15d5f671..dba5583bf7 100644 --- a/introduction/screenshots.md +++ b/introduction/screenshots.md @@ -1,11 +1,13 @@ --- +lang: en layout: default -title: Screenshots permalink: /screenshots/ redirect_from: - /media/ - /doc/QubesScreenshots/ - /wiki/QubesScreenshots/ +ref: 123 +title: Screenshots --- Select Qubes OS Screenshots @@ -120,4 +122,3 @@ The following screenshots, [courtesy of Qubes user nalu](https://groups.google.c [![r3rc1-nalu-desktop-3.png](/attachment/wiki/QubesScreenshots/r3rc1-nalu-desktop-3.png)](/attachment/wiki/QubesScreenshots/r3rc1-nalu-desktop-3.png) [![r3rc1-nalu-desktop-4.png](/attachment/wiki/QubesScreenshots/r3rc1-nalu-desktop-4.png)](/attachment/wiki/QubesScreenshots/r3rc1-nalu-desktop-4.png) - diff --git a/introduction/statistics.md b/introduction/statistics.md index e46e155dda..84c1b65833 100644 --- a/introduction/statistics.md +++ b/introduction/statistics.md @@ -1,9 +1,11 @@ --- +lang: en layout: default -title: Statistics permalink: /statistics/ -redirect_from: +redirect_from: - /counter/ +ref: 127 +title: Statistics ---
@@ -67,4 +69,3 @@ The source code is available [here][source-code]. [TorDNSEL's exit lists]: https://metrics.torproject.org/collector.html#type-tordnsel [raw-data]: https://tools.qubes-os.org/counter/stats.json [source-code]: https://github.com/woju/qubes-stats - diff --git a/introduction/support.md b/introduction/support.md index 5e16e1bdb5..afd5b67254 100644 --- a/introduction/support.md +++ b/introduction/support.md @@ -1,6 +1,6 @@ --- +lang: en layout: sidebar -title: Help, Support, and Mailing Lists permalink: /support/ redirect_from: - /help/ @@ -11,6 +11,8 @@ redirect_from: - /doc/qubes-lists/ - /doc/QubesLists/ - /wiki/QubesLists/ +ref: 122 +title: Help, Support, and Mailing Lists --- # Help, Support, and Mailing Lists # @@ -386,4 +388,3 @@ The following unofficial chat channels are maintained by the community: [Transifex]: https://www.transifex.com/otf/qubes/ [issue tracker]: /doc/reporting-bugs/ [searching the issue tracker]: /doc/reporting-bugs/#search-tips - diff --git a/introduction/video-tours.html b/introduction/video-tours.html index 4ea7dacd8e..412d0d96ef 100644 --- a/introduction/video-tours.html +++ b/introduction/video-tours.html @@ -1,7 +1,9 @@ --- +lang: en layout: default -title: Video Tours of Qubes OS permalink: /video-tours/ +ref: 120 +title: Video Tours of Qubes OS ---
diff --git a/project-security/canaries.md b/project-security/canaries.md index c82eeefe6d..547a1187b5 100644 --- a/project-security/canaries.md +++ b/project-security/canaries.md @@ -1,8 +1,10 @@ --- +lang: en layout: doc -title: Canaries permalink: /security/canaries/ redirect_from: /doc/canaries/ +ref: 208 +title: Canaries --- Qubes Canaries @@ -24,4 +26,3 @@ Qubes Canaries are published through the [Qubes Security Pack](/security/pack/). {% endfor %} - diff --git a/project-security/canary-checklist.md b/project-security/canary-checklist.md index 487a8ba313..707817a3f0 100644 --- a/project-security/canary-checklist.md +++ b/project-security/canary-checklist.md @@ -1,7 +1,9 @@ --- +lang: en layout: doc -title: Canary Checklist permalink: /security/canaries/checklist/ +ref: 216 +title: Canary Checklist --- Canary Checklist @@ -21,4 +23,3 @@ Announcement * Send the content of the news post to the appropriate [mailing lists](/support/) * Share link to news post on social media * Set a reminder for the next canary - diff --git a/project-security/canary-template.md b/project-security/canary-template.md index 3aac7badff..3e62c7591c 100644 --- a/project-security/canary-template.md +++ b/project-security/canary-template.md @@ -1,8 +1,10 @@ --- +lang: en layout: doc -title: Canary Template permalink: /security/canaries/template/ redirect_from: /doc/canaries/template/ +ref: 212 +title: Canary Template --- Canary Template @@ -58,4 +60,3 @@ Footnotes ``` ~~~ - diff --git a/project-security/security-bulletins-checklist.md b/project-security/security-bulletins-checklist.md index 03ba223460..dc1d3b76e8 100644 --- a/project-security/security-bulletins-checklist.md +++ b/project-security/security-bulletins-checklist.md @@ -1,8 +1,10 @@ --- +lang: en layout: doc -title: Security Bulletin Checklist permalink: /security/bulletins/checklist/ redirect_from: /doc/security-bulletins/checklist/ +ref: 215 +title: Security Bulletin Checklist --- Security Bulletin Checklist @@ -23,4 +25,3 @@ Announcement * Publish a [news post](/news/) using the [QSB Template](/security/bulletins/template/) * Send the content of the news post to the appropriate [mailing lists](/support/) * Share link to news post on social media - diff --git a/project-security/security-bulletins-template.md b/project-security/security-bulletins-template.md index f6d41ba694..dca3981dc5 100644 --- a/project-security/security-bulletins-template.md +++ b/project-security/security-bulletins-template.md @@ -1,8 +1,10 @@ --- +lang: en layout: doc -title: Security Bulletin Template permalink: /security/bulletins/template/ redirect_from: /doc/security-bulletins/template/ +ref: 209 +title: Security Bulletin Template --- Security Bulletin Template @@ -80,4 +82,3 @@ https://www.qubes-os.org/security/ ``` ~~~ - diff --git a/project-security/security-bulletins.md b/project-security/security-bulletins.md index 3f77c8910b..33cda87f5d 100644 --- a/project-security/security-bulletins.md +++ b/project-security/security-bulletins.md @@ -1,13 +1,15 @@ --- +lang: en layout: doc -title: Qubes Security Bulletins permalink: /security/bulletins/ -redirect_from: +redirect_from: - /doc/security-bulletins/ - /en/doc/security-bulletins/ - /doc/SecurityBulletins/ - /wiki/SecurityBulletins/ - /trac/wiki/SecurityBulletins/ +ref: 218 +title: Qubes Security Bulletins --- Qubes Security Bulletins (QSBs) @@ -29,4 +31,3 @@ Qubes Security Bulletins (QSBs) are published through the [Qubes Security Pack]( {% endfor %} - diff --git a/project-security/security-goals.md b/project-security/security-goals.md index 8e0581a5c5..2829eabe06 100644 --- a/project-security/security-goals.md +++ b/project-security/security-goals.md @@ -1,12 +1,14 @@ --- +lang: en layout: doc -title: Security Goals permalink: /security/goals/ redirect_from: - /doc/security-goals/ - /en/doc/security-goals/ - /doc/SecurityGoals/ - /wiki/SecurityGoals/ +ref: 210 +title: Security Goals --- Qubes Security Goals diff --git a/project-security/security-pack.md b/project-security/security-pack.md index e2363bc1cf..8394dc6e17 100644 --- a/project-security/security-pack.md +++ b/project-security/security-pack.md @@ -1,6 +1,6 @@ --- +lang: en layout: doc -title: Security Pack permalink: /security/pack/ redirect_from: - /doc/security-pack/ @@ -13,6 +13,8 @@ redirect_from: - /doc/qsp/ - /doc/sec-pack/ - /doc/secpack/ +ref: 213 +title: Security Pack --- Qubes Security Pack @@ -258,4 +260,3 @@ The same procedures can be applied to any directory or file in the signatures) are provided to ensure that the system is robust (e.g., against a potential failure in Git tag-based verification) and to give users more options to verify the files. - diff --git a/project-security/security.md b/project-security/security.md index 25eb0c829f..4c1f035aa2 100644 --- a/project-security/security.md +++ b/project-security/security.md @@ -1,8 +1,8 @@ --- +lang: en layout: doc -title: Security permalink: /security/ -redirect_from: +redirect_from: - /en/security/ - /en/doc/security/ - /en/doc/qubes-security/ @@ -12,6 +12,8 @@ redirect_from: - /doc/SecurityPage/ - /wiki/SecurityPage/ - /trac/wiki/SecurityPage/ +ref: 217 +title: Security --- Qubes OS Project Security Center @@ -87,5 +89,3 @@ Please see [Why and How to Verify Signatures] for information about how to verif [Joanna Rutkowska]: /team/#joanna-rutkowska [emeritus, canaries only]: /news/2018/11/05/qubes-security-team-update/ [Updating Qubes OS]: /doc/updating-qubes-os/ - - diff --git a/project-security/verifying-signatures.md b/project-security/verifying-signatures.md index 486402597a..573cc4d1e6 100644 --- a/project-security/verifying-signatures.md +++ b/project-security/verifying-signatures.md @@ -1,12 +1,14 @@ --- +lang: en layout: doc -title: Verifying Signatures permalink: /security/verifying-signatures/ redirect_from: - /doc/verifying-signatures/ - /en/doc/verifying-signatures/ - /doc/VerifyingSignatures/ - /wiki/VerifyingSignatures/ +ref: 211 +title: Verifying Signatures --- On Digital Signatures and Key Verification @@ -457,4 +459,3 @@ If you still have a question, please address it to the [qubes-users mailing list [GPG documentation]: https://www.gnupg.org/documentation/ [qubes-users mailing list]: /support/#qubes-users [except dom0]: https://github.com/QubesOS/qubes-issues/issues/2544 - diff --git a/project-security/xsa.md b/project-security/xsa.md index 6341cf6a66..d0cbce0094 100644 --- a/project-security/xsa.md +++ b/project-security/xsa.md @@ -1,7 +1,9 @@ --- +lang: en layout: doc -title: Xen Security Advisory (XSA) Tracker permalink: /security/xsa/ +ref: 214 +title: Xen Security Advisory (XSA) Tracker --- Xen Security Advisory (XSA) Tracker @@ -111,4 +113,3 @@ Tracker [DoS]: https://en.wikipedia.org/wiki/Denial-of-service_attack [Xen Security Policy]: https://www.xenproject.org/security-policy.html [Statistics]: #statistics - diff --git a/user/advanced-configuration/awesome.md b/user/advanced-configuration/awesome.md index 4f95505c93..e0dc1555e6 100644 --- a/user/advanced-configuration/awesome.md +++ b/user/advanced-configuration/awesome.md @@ -1,10 +1,11 @@ --- +lang: en layout: doc -title: awesome permalink: /doc/awesome/ redirect_from: - /en/doc/awesome/ -- /doc/awesome/ +ref: 179 +title: awesome --- # Using awesome in dom0 @@ -184,4 +185,3 @@ client.disconnect_signal("request::tag", ewmh.tag) ``` The signal names may change across awesome versions. - diff --git a/user/advanced-configuration/bind-dirs.md b/user/advanced-configuration/bind-dirs.md index 75b046c12d..1edb902cfe 100644 --- a/user/advanced-configuration/bind-dirs.md +++ b/user/advanced-configuration/bind-dirs.md @@ -1,9 +1,11 @@ --- +lang: en layout: doc -title: How to make any file in a TemplateBasedVM persistent using bind-dirs permalink: /doc/bind-dirs/ redirect_from: - /en/doc/bind-dirs/ +ref: 186 +title: How to make any file in a TemplateBasedVM persistent using bind-dirs --- # How to make any file in a TemplateBasedVM persistent using bind-dirs # diff --git a/user/advanced-configuration/config-files.md b/user/advanced-configuration/config-files.md index 501618aadd..2b668a6bc3 100644 --- a/user/advanced-configuration/config-files.md +++ b/user/advanced-configuration/config-files.md @@ -1,12 +1,14 @@ --- +lang: en layout: doc -title: Config Files permalink: /doc/config-files/ redirect_from: - /en/doc/config-files/ - /doc/ConfigFiles/ -- "/doc/UserDoc/ConfigFiles/" -- "/wiki/UserDoc/ConfigFiles/" +- /doc/UserDoc/ConfigFiles/ +- /wiki/UserDoc/ConfigFiles/ +ref: 180 +title: Config Files --- Configuration Files diff --git a/user/advanced-configuration/disposablevm-customization.md b/user/advanced-configuration/disposablevm-customization.md index 49558bf244..370dc9bc14 100644 --- a/user/advanced-configuration/disposablevm-customization.md +++ b/user/advanced-configuration/disposablevm-customization.md @@ -1,6 +1,6 @@ --- +lang: en layout: doc -title: DisposableVM Customization permalink: /doc/disposablevm-customization/ redirect_from: - /doc/dispvm-customization/ @@ -8,6 +8,8 @@ redirect_from: - /doc/DispVMCustomization/ - /doc/UserDoc/DispVMCustomization/ - /wiki/UserDoc/DispVMCustomization/ +ref: 174 +title: DisposableVM Customization --- # DisposableVM Customization @@ -317,4 +319,3 @@ You can then delete the DisposableVM Template: If you still encounter the issue, you may have forgot to clean an entry. Looking at the system logs will help you: [user@dom0 ~]$ journalctl | tail - diff --git a/user/advanced-configuration/gui-configuration.md b/user/advanced-configuration/gui-configuration.md index 5ae0f5f2e3..d804ac40c6 100644 --- a/user/advanced-configuration/gui-configuration.md +++ b/user/advanced-configuration/gui-configuration.md @@ -1,9 +1,11 @@ --- +lang: en layout: doc -title: GUI Configuration and Troubleshooting permalink: /doc/gui-configuration-and-troubleshooting/ redirect_from: - - /doc/gui-configuration/ +- /doc/gui-configuration/ +ref: 184 +title: GUI Configuration and Troubleshooting --- # GUI Configuration and Troubleshooting diff --git a/user/advanced-configuration/i3.md b/user/advanced-configuration/i3.md index f170a04a79..88ac3226f6 100644 --- a/user/advanced-configuration/i3.md +++ b/user/advanced-configuration/i3.md @@ -1,12 +1,13 @@ --- +lang: en layout: doc -title: i3 permalink: /doc/i3/ redirect_from: - /en/doc/i3/ -- /doc/i3/ -- "/doc/UserDoc/i3/" -- "/wiki/UserDoc/i3/" +- /doc/UserDoc/i3/ +- /wiki/UserDoc/i3/ +ref: 183 +title: i3 --- # i3 installation in dom0 diff --git a/user/advanced-configuration/kde.md b/user/advanced-configuration/kde.md index bdc54928aa..1aa1e59d9f 100644 --- a/user/advanced-configuration/kde.md +++ b/user/advanced-configuration/kde.md @@ -1,8 +1,10 @@ --- +lang: en layout: doc -title: KDE permalink: /doc/kde/ redirect_from: /en/doc/kde/ +ref: 176 +title: KDE --- Using KDE in dom0 diff --git a/user/advanced-configuration/managing-vm-kernel.md b/user/advanced-configuration/managing-vm-kernel.md index 42dbd75d60..b658e586e4 100644 --- a/user/advanced-configuration/managing-vm-kernel.md +++ b/user/advanced-configuration/managing-vm-kernel.md @@ -1,9 +1,11 @@ --- +lang: en layout: doc -title: Managing VM kernel permalink: /doc/managing-vm-kernel/ redirect_from: - /en/doc/managing-vm-kernel/ +ref: 173 +title: Managing VM kernel --- VM kernel managed by dom0 @@ -364,4 +366,3 @@ You can always set the kernel back to some dom0-provided value to fix a VM kerne [dom0-kernel-upgrade]: /doc/software-update-dom0/#kernel-upgrade - diff --git a/user/advanced-configuration/mount-from-other-os.md b/user/advanced-configuration/mount-from-other-os.md index 64160df958..894fca86b1 100644 --- a/user/advanced-configuration/mount-from-other-os.md +++ b/user/advanced-configuration/mount-from-other-os.md @@ -1,11 +1,13 @@ --- +lang: en layout: doc -title: Mounting and Decrypting Qubes Partitions from Outside Qubes permalink: /doc/mount-from-other-os/ redirect_from: - /en/doc/mount-from-other-os/ - /doc/MountFromOtherOs/ - /wiki/MountFromOtherOs/ +ref: 175 +title: Mounting and Decrypting Qubes Partitions from Outside Qubes --- Mount and Decrypt Qubes Partition from Outside Qubes @@ -93,5 +95,3 @@ Thes steps must occur either in an AppVM or using recovery media. 1. Unmount any disks that were accessed. 2. Rename the VG back to qubes\_dom0 using the command `vgrename other_install qubes_dom0`. - - diff --git a/user/advanced-configuration/newer-hardware-troubleshooting.md b/user/advanced-configuration/newer-hardware-troubleshooting.md index 4ed30ba82d..8e13cde861 100644 --- a/user/advanced-configuration/newer-hardware-troubleshooting.md +++ b/user/advanced-configuration/newer-hardware-troubleshooting.md @@ -1,7 +1,9 @@ --- +lang: en layout: doc -title: Troubleshooting newer hardware permalink: /doc/newer-hardware-troubleshooting/ +ref: 172 +title: Troubleshooting newer hardware --- Troubleshooting newer hardware @@ -26,4 +28,3 @@ If `uname -r` reports a higher version number, then you've successfully booted w [dom0-kernel-upgrade]: /doc/software-update-dom0/#kernel-upgrade - diff --git a/user/advanced-configuration/resize-disk-image.md b/user/advanced-configuration/resize-disk-image.md index 7a74132e91..c332f16095 100644 --- a/user/advanced-configuration/resize-disk-image.md +++ b/user/advanced-configuration/resize-disk-image.md @@ -1,6 +1,6 @@ --- +lang: en layout: doc -title: Resize Disk Image permalink: /doc/resize-disk-image/ redirect_from: - /en/doc/resize-disk-image/ @@ -9,6 +9,8 @@ redirect_from: - /doc/ResizeRootDiskImage/ - /wiki/ResizeDiskImage/ - /wiki/ResizeRootDiskImage/ +ref: 182 +title: Resize Disk Image --- Resizing Disk Images @@ -108,8 +110,3 @@ sudo lvresize --size 1024M /dev/qubes_dom0/vm-qube1-private If you have a SSD see [here][fstrim] for information on using fstrim. [fstrim]: /doc/disk-trim - - - - - diff --git a/user/advanced-configuration/rpc-policy.md b/user/advanced-configuration/rpc-policy.md index fe516f5a64..5887fd9854 100644 --- a/user/advanced-configuration/rpc-policy.md +++ b/user/advanced-configuration/rpc-policy.md @@ -1,7 +1,9 @@ --- +lang: en layout: doc -title: RPC Policies permalink: /doc/rpc-policy/ +ref: 178 +title: RPC Policies --- RPC Policies @@ -58,4 +60,3 @@ Further details about how this system works can be found in [Qrexec: command exe For more information, see the bulletin [here](https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-038-2018.txt).*) [qrexec3]: /doc/qrexec3/ - diff --git a/user/advanced-configuration/salt.md b/user/advanced-configuration/salt.md index dfb890afeb..8cc34fbef5 100644 --- a/user/advanced-configuration/salt.md +++ b/user/advanced-configuration/salt.md @@ -1,7 +1,9 @@ --- +lang: en layout: doc -title: Management stack permalink: /doc/salt/ +ref: 185 +title: Management stack --- # Management Infrastructure diff --git a/user/advanced-configuration/secondary-storage.md b/user/advanced-configuration/secondary-storage.md index 52aeb3fb38..fbc41e026c 100644 --- a/user/advanced-configuration/secondary-storage.md +++ b/user/advanced-configuration/secondary-storage.md @@ -1,11 +1,13 @@ --- +lang: en layout: doc -title: Secondary Storage permalink: /doc/secondary-storage/ redirect_from: - /en/doc/secondary-storage/ - /doc/SecondaryStorage/ - /wiki/SecondaryStorage/ +ref: 187 +title: Secondary Storage --- Storing AppVMs on Secondary Drives @@ -90,4 +92,3 @@ By default VMs will be created on the main Qubes disk (i.e. a small SSD), to cre [Qubes Backup]: /doc/BackupRestore/ [TemplateVM]: /doc/Templates/ - diff --git a/user/advanced-configuration/uefi-troubleshooting.md b/user/advanced-configuration/uefi-troubleshooting.md index d93906ff58..a6f4810444 100644 --- a/user/advanced-configuration/uefi-troubleshooting.md +++ b/user/advanced-configuration/uefi-troubleshooting.md @@ -1,7 +1,9 @@ --- +lang: en layout: doc -title: UEFI Troubleshooting permalink: /doc/uefi-troubleshooting/ +ref: 177 +title: UEFI Troubleshooting --- Troubleshooting UEFI related problems diff --git a/user/advanced-configuration/usb-qubes.md b/user/advanced-configuration/usb-qubes.md index 8a75ab5382..cffcc1bbbe 100644 --- a/user/advanced-configuration/usb-qubes.md +++ b/user/advanced-configuration/usb-qubes.md @@ -1,6 +1,6 @@ --- +lang: en layout: doc -title: USB Qubes permalink: /doc/usb-qubes/ redirect_from: - /doc/usbvm/ @@ -8,6 +8,8 @@ redirect_from: - /doc/USBVM/ - /wiki/USBVM/ - /doc/sys-usb/ +ref: 181 +title: USB Qubes --- # USB Qubes # @@ -205,4 +207,3 @@ The procedure to hide all USB controllers from dom0 is as follows: [hiding USB controllers from dom0]: #how-to-hide-all-usb-controllers-from-dom0 [AEM]: /doc/anti-evil-maid/ [create a USB qube]: #creating-and-using-a-usb-qube - diff --git a/user/common-tasks/backup-emergency-restore-v2.md b/user/common-tasks/backup-emergency-restore-v2.md index 159607f78f..6946a431bf 100644 --- a/user/common-tasks/backup-emergency-restore-v2.md +++ b/user/common-tasks/backup-emergency-restore-v2.md @@ -1,10 +1,12 @@ --- +lang: en layout: doc -title: Emergency Backup Recovery (v2) permalink: /doc/backup-emergency-restore-v2/ redirect_from: - /en/doc/backup-emergency-restore-v2/ - /doc/BackupEmergencyRestoreV2/ +ref: 207 +title: Emergency Backup Recovery (v2) --- Emergency Backup Recovery without Qubes (v2) diff --git a/user/common-tasks/backup-emergency-restore-v3.md b/user/common-tasks/backup-emergency-restore-v3.md index c2774ee9a5..664686d387 100644 --- a/user/common-tasks/backup-emergency-restore-v3.md +++ b/user/common-tasks/backup-emergency-restore-v3.md @@ -1,10 +1,12 @@ --- +lang: en layout: doc -title: Emergency Backup Recovery (v3) permalink: /doc/backup-emergency-restore-v3/ redirect_from: - /en/doc/backup-emergency-restore-v3/ - /doc/BackupEmergencyRestoreV3/ +ref: 201 +title: Emergency Backup Recovery (v3) --- Emergency Backup Recovery without Qubes (v3) @@ -137,4 +139,3 @@ any GNU/Linux system with the following procedure. repository: https://github.com/QubesOS/qubes-doc.git - diff --git a/user/common-tasks/backup-emergency-restore-v4.md b/user/common-tasks/backup-emergency-restore-v4.md index ec9731d406..ed65fb38dc 100644 --- a/user/common-tasks/backup-emergency-restore-v4.md +++ b/user/common-tasks/backup-emergency-restore-v4.md @@ -1,10 +1,12 @@ --- +lang: en layout: doc -title: Emergency Backup Recovery (v4) permalink: /doc/backup-emergency-restore-v4/ redirect_from: - /en/doc/backup-emergency-restore-v4/ - /doc/BackupEmergencyRestoreV4/ +ref: 192 +title: Emergency Backup Recovery (v4) --- Emergency Backup Recovery without Qubes (v4) @@ -192,4 +194,3 @@ Emergency Recovery Instructions [get and verify the Release 4 Signing Key]: https://www.qubes-os.org/security/verifying-signatures/#2-get-the-release-signing-key [Emergency Backup Recovery without Qubes (v2)]: https://www.qubes-os.org/doc/backup-emergency-restore-v2/ [Emergency Backup Recovery without Qubes (v3)]: https://www.qubes-os.org/doc/backup-emergency-restore-v3/ - diff --git a/user/common-tasks/backup-restore.md b/user/common-tasks/backup-restore.md index 94a5575f14..be1ab06a91 100644 --- a/user/common-tasks/backup-restore.md +++ b/user/common-tasks/backup-restore.md @@ -1,11 +1,13 @@ --- +lang: en layout: doc -title: Backup, Restoration, and Migration permalink: /doc/backup-restore/ redirect_from: - /en/doc/backup-restore/ - /doc/BackupRestore/ - /wiki/BackupRestore/ +ref: 199 +title: Backup, Restoration, and Migration --- Qubes Backup, Restoration, and Migration @@ -137,4 +139,3 @@ Notes * For the technical details of the backup system, please refer to [this thread](https://groups.google.com/d/topic/qubes-devel/TQr_QcXIVww/discussion). * If working with symlinks, note the issues described in [this thread](https://groups.google.com/d/topic/qubes-users/EITd1kBHD30/discussion). - diff --git a/user/common-tasks/block-devices.md b/user/common-tasks/block-devices.md index 460aa625c3..f2511af10c 100644 --- a/user/common-tasks/block-devices.md +++ b/user/common-tasks/block-devices.md @@ -1,12 +1,14 @@ --- +lang: en layout: doc -title: Block (Storage) Devices permalink: /doc/block-devices/ redirect_from: - /doc/stick-mounting/ - /en/doc/stick-mounting/ - /doc/StickMounting/ - /wiki/StickMounting/ +ref: 193 +title: Block (Storage) Devices --- # Block (Storage) Devices # @@ -242,4 +244,3 @@ This option accepts `cdrom` and `disk`, default is `disk`. [losetup]: https://linux.die.net/man/8/losetup [USB]:/doc/usb-devices/ [1082]: https://github.com/QubesOS/qubes-issues/issues/1082 - diff --git a/user/common-tasks/copy-from-dom0.md b/user/common-tasks/copy-from-dom0.md index 67c8fe8982..e34473eb4e 100644 --- a/user/common-tasks/copy-from-dom0.md +++ b/user/common-tasks/copy-from-dom0.md @@ -1,12 +1,14 @@ --- +lang: en layout: doc -title: Copying from (and to) dom0 permalink: /doc/copy-from-dom0/ redirect_from: - /doc/copy-to-dom0/ - /en/doc/copy-to-dom0/ - /doc/CopyToDomZero/ - /wiki/CopyToDomZero/ +ref: 198 +title: Copying from (and to) dom0 --- Copying from (and to) dom0 @@ -72,4 +74,3 @@ Note that you can use the same method to copy files from dom0 to VMs (if, for so ~~~ cat /path/to/file_in_dom0 | qvm-run --pass-io 'cat > /path/to/file_name_in_appvm' ~~~ - diff --git a/user/common-tasks/copy-paste.md b/user/common-tasks/copy-paste.md index e2d7baebbb..c679f3a9e2 100644 --- a/user/common-tasks/copy-paste.md +++ b/user/common-tasks/copy-paste.md @@ -1,11 +1,13 @@ --- +lang: en layout: doc -title: Copy and Paste permalink: /doc/copy-paste/ redirect_from: - /en/doc/copy-paste/ - /doc/CopyPaste/ - /wiki/CopyPaste/ +ref: 196 +title: Copy and Paste --- Copy and Paste between domains @@ -81,4 +83,3 @@ VMs need to be restarted in order for changes in `/etc/qubes/guid.conf` to take [RPC policy]: /doc/rpc-policy/ - diff --git a/user/common-tasks/copying-files.md b/user/common-tasks/copying-files.md index 21688795bf..3b92ded157 100644 --- a/user/common-tasks/copying-files.md +++ b/user/common-tasks/copying-files.md @@ -1,11 +1,13 @@ --- +lang: en layout: doc -title: Copying Files between qubes permalink: /doc/copying-files/ redirect_from: - /en/doc/copying-files/ - /doc/CopyingFiles/ - /wiki/CopyingFiles/ +ref: 191 +title: Copying Files between qubes --- Copying files and folders between qubes diff --git a/user/common-tasks/device-handling.md b/user/common-tasks/device-handling.md index 82cd6458f3..d6d5efea27 100644 --- a/user/common-tasks/device-handling.md +++ b/user/common-tasks/device-handling.md @@ -1,12 +1,14 @@ --- +lang: en layout: doc -title: Device Handling permalink: /doc/device-handling/ redirect_from: - /doc/external-device-mount-point/ - /en/doc/external-device-mount-point/ - /doc/ExternalDeviceMountPoint/ - /wiki/ExternalDeviceMountPoint/ +ref: 188 +title: Device Handling --- # Device Handling # @@ -168,4 +170,3 @@ If no specific `sourceVM:deviceID` combination is given, *all devices of that DE [device manager icon]: /attachment/wiki/Devices/media-removable.png [eject icon]: /attachment/wiki/Devices/media-eject.png [i4692]: https://github.com/QubesOS/qubes-issues/issues/4692 - diff --git a/user/common-tasks/disposablevm.md b/user/common-tasks/disposablevm.md index f59be63f46..3047dc4b58 100644 --- a/user/common-tasks/disposablevm.md +++ b/user/common-tasks/disposablevm.md @@ -1,12 +1,14 @@ --- +lang: en layout: doc -title: DisposableVMs permalink: /doc/disposablevm/ redirect_from: - /doc/dispvm/ - /en/doc/dispvm/ - /doc/DisposableVms/ - /wiki/DisposableVMs/ +ref: 203 +title: DisposableVMs --- # DisposableVMs # diff --git a/user/common-tasks/full-screen-mode.md b/user/common-tasks/full-screen-mode.md index 1ec7f8fa0c..e88d1aeffb 100644 --- a/user/common-tasks/full-screen-mode.md +++ b/user/common-tasks/full-screen-mode.md @@ -1,11 +1,13 @@ --- +lang: en layout: doc -title: Full Screen Mode permalink: /doc/full-screen-mode/ redirect_from: - /en/doc/full-screen-mode/ - /doc/FullScreenMode/ - /wiki/FullScreenMode/ +ref: 205 +title: Full Screen Mode --- Enabling Full Screen Mode for select VMs diff --git a/user/common-tasks/getting-started.md b/user/common-tasks/getting-started.md index db10e49b2a..720616d043 100644 --- a/user/common-tasks/getting-started.md +++ b/user/common-tasks/getting-started.md @@ -1,12 +1,14 @@ --- +lang: en layout: default -title: Get Started permalink: /getting-started/ redirect_from: - /doc/getting-started/ - /en/doc/getting-started/ - /doc/GettingStarted/ - /wiki/GettingStarted/ +ref: 190 +title: Get Started --- After [installing Qubes](/doc/installation-guide/), let's cover some basic concepts. diff --git a/user/common-tasks/managing-appvm-shortcuts.md b/user/common-tasks/managing-appvm-shortcuts.md index e098e514fc..13c0698866 100644 --- a/user/common-tasks/managing-appvm-shortcuts.md +++ b/user/common-tasks/managing-appvm-shortcuts.md @@ -1,11 +1,13 @@ --- +lang: en layout: doc -title: Managing AppVm Shortcuts permalink: /doc/managing-appvm-shortcuts/ redirect_from: - /en/doc/managing-appvm-shortcuts/ - /doc/ManagingAppVmShortcuts/ - /wiki/ManagingAppVmShortcuts/ +ref: 202 +title: Managing AppVm Shortcuts --- Managing shortcuts to applications in AppVMs @@ -115,4 +117,3 @@ Actual command lines for the menu shortcuts involve `qvm-run` command which star Examples: `qvm-run -q -a --service -- %VMNAME% qubes.StartApp+7-Zip-7-Zip_File_Manager` or `qvm-run -q -a --service -- %VMNAME% qubes.StartApp+firefox` Note that you can create a shortcut that points to a .desktop file in your AppVM with e.g. `qvm-run -q -a --service -- personal qubes.StartApp+firefox`. - diff --git a/user/common-tasks/optical-discs.md b/user/common-tasks/optical-discs.md index d8fb6f91d1..3e65f0a6a6 100644 --- a/user/common-tasks/optical-discs.md +++ b/user/common-tasks/optical-discs.md @@ -1,10 +1,12 @@ --- +lang: en layout: doc -title: Optical Discs permalink: /doc/optical-discs/ redirect_from: - - /doc/recording-optical-discs/ - - /en/doc/recording-optical-discs/ +- /doc/recording-optical-discs/ +- /en/doc/recording-optical-discs/ +ref: 204 +title: Optical Discs --- Optical Discs @@ -22,4 +24,3 @@ To access an optical disc via USB follow the [typical procedure for attaching a Typically this would be `sr0`. For example, if `sys-usb` has device `3-2` attached to the `work` qube's `sr0`, you would mount it with `mount /dev/sr0 /mnt/removable`. You could also write to a disc with `wodim -v dev=/dev/sr0 -eject /home/user/Qubes.iso`. - diff --git a/user/common-tasks/pci-devices.md b/user/common-tasks/pci-devices.md index e84b0ea724..66b36cc0d8 100644 --- a/user/common-tasks/pci-devices.md +++ b/user/common-tasks/pci-devices.md @@ -1,12 +1,14 @@ --- +lang: en layout: doc -title: PCI Devices permalink: /doc/pci-devices/ redirect_from: - /doc/assigning-devices/ - /en/doc/assigning-devices/ - /doc/AssigningDevices/ - /wiki/AssigningDevices/ +ref: 197 +title: PCI Devices --- # PCI Devices # @@ -171,4 +173,3 @@ or [ml1]: https://groups.google.com/group/qubes-devel/browse_thread/thread/631c4a3a9d1186e3 [ml2]: https://groups.google.com/forum/#!topic/qubes-users/Fs94QAc3vQI [PCI passthrough]: https://wiki.xen.org/wiki/Xen_PCI_Passthrough - diff --git a/user/common-tasks/software-update-dom0.md b/user/common-tasks/software-update-dom0.md index 5f4aaa743d..6ce0a24f16 100644 --- a/user/common-tasks/software-update-dom0.md +++ b/user/common-tasks/software-update-dom0.md @@ -1,11 +1,13 @@ --- +lang: en layout: doc -title: Installing and updating software in dom0 permalink: /doc/software-update-dom0/ redirect_from: - /en/doc/software-update-dom0/ - /doc/SoftwareUpdateDom0/ - /wiki/SoftwareUpdateDom0/ +ref: 194 +title: Installing and updating software in dom0 --- # Installing and updating software in dom0 @@ -219,4 +221,3 @@ For example: sys-whonix. [testing]: /doc/testing/ [troubleshooting newer hardware]: /doc/newer-hardware-troubleshooting/ [Managing VM kernel]: /doc/managing-vm-kernel/ - diff --git a/user/common-tasks/software-update-domu.md b/user/common-tasks/software-update-domu.md index 6be06e59d9..9fc9e6a270 100644 --- a/user/common-tasks/software-update-domu.md +++ b/user/common-tasks/software-update-domu.md @@ -1,12 +1,14 @@ --- +lang: en layout: doc -title: Installing and updating software in domUs permalink: /doc/software-update-domu/ redirect_from: - /doc/software-update-vm/ - /en/doc/software-update-vm/ - /doc/SoftwareUpdateVM/ - /wiki/SoftwareUpdateVM/ +ref: 189 +title: Installing and updating software in domUs --- # Installing and updating software in domUs @@ -311,4 +313,3 @@ Note that the app will autostart only when the AppVM starts. If you would like t [RPM Fusion]: http://rpmfusion.org/ [service framework]: /doc/qubes-service/ [How to Reinstall a TemplateVM]: /doc/reinstall-template/ - diff --git a/user/common-tasks/updating-qubes-os.md b/user/common-tasks/updating-qubes-os.md index 8bc45f2883..179f47c563 100644 --- a/user/common-tasks/updating-qubes-os.md +++ b/user/common-tasks/updating-qubes-os.md @@ -1,7 +1,9 @@ --- +lang: en layout: doc -title: Updating Qubes OS permalink: /doc/updating-qubes-os/ +ref: 200 +title: Updating Qubes OS --- Updating Qubes OS diff --git a/user/common-tasks/usb-devices.md b/user/common-tasks/usb-devices.md index bd250daaa7..83abcf1f1a 100644 --- a/user/common-tasks/usb-devices.md +++ b/user/common-tasks/usb-devices.md @@ -1,9 +1,11 @@ --- +lang: en layout: doc -title: USB Devices permalink: /doc/usb-devices/ redirect_from: - /doc/usb/ +ref: 195 +title: USB Devices --- # USB Devices # diff --git a/user/common-tasks/volume-backup-revert.md b/user/common-tasks/volume-backup-revert.md index 48a4a42e75..741af055d9 100644 --- a/user/common-tasks/volume-backup-revert.md +++ b/user/common-tasks/volume-backup-revert.md @@ -1,11 +1,13 @@ --- +lang: en layout: doc -title: Volume Backup and Revert permalink: /doc/volume-backup-revert/ redirect_from: - /en/doc/volume-backup-revert/ - /doc/VolumeBackupRevert/ - /wiki/VolumeBackupRevert/ +ref: 206 +title: Volume Backup and Revert --- Qubes Volume Backup and Revert @@ -42,4 +44,4 @@ With the VM stopped, you may revert to an older snapshot of the private volume from the the above list of "Available revisions (for revert)", where the last item on the list with the largest integer is the most recent snapshot: - qvm-volume revert vmname:private \ No newline at end of file + qvm-volume revert vmname:private diff --git a/user/downloading-installing-upgrading/custom-install.md b/user/downloading-installing-upgrading/custom-install.md index a443c385e9..01fdc5312e 100644 --- a/user/downloading-installing-upgrading/custom-install.md +++ b/user/downloading-installing-upgrading/custom-install.md @@ -1,9 +1,11 @@ --- +lang: en layout: doc -title: Custom Installation permalink: /doc/custom-install/ redirect_from: - - /doc/encryption-config/ +- /doc/encryption-config/ +ref: 152 +title: Custom Installation --- # Custom Installation @@ -156,4 +158,3 @@ Boot into the Qubes installer, then press `ctrl`+`alt`+`F2` to get a virtual con [cryptsetup-faq]: https://gitlab.com/cryptsetup/cryptsetup/wikis/FrequentlyAskedQuestions [dm-crypt]: https://wiki.archlinux.org/index.php/dm-crypt/Device_encryption [tomb-238]: https://github.com/dyne/Tomb/issues/238 - diff --git a/user/downloading-installing-upgrading/download-mirrors.md b/user/downloading-installing-upgrading/download-mirrors.md index 79f45b59bf..2b70612b21 100644 --- a/user/downloading-installing-upgrading/download-mirrors.md +++ b/user/downloading-installing-upgrading/download-mirrors.md @@ -1,7 +1,9 @@ --- +lang: en layout: sidebar -title: Download Mirrors permalink: /downloads/mirrors/ +ref: 148 +title: Download Mirrors --- Qubes Download Mirrors diff --git a/user/downloading-installing-upgrading/install-security.md b/user/downloading-installing-upgrading/install-security.md index 377d408141..c3dd8bb20d 100644 --- a/user/downloading-installing-upgrading/install-security.md +++ b/user/downloading-installing-upgrading/install-security.md @@ -1,11 +1,13 @@ --- +lang: en layout: doc -title: Installation Security permalink: /doc/install-security/ redirect_from: - /en/doc/install-security/ - /doc/InstallSecurity/ - /wiki/InstallSecurity/ +ref: 149 +title: Installation Security --- # Installation Security Considerations # @@ -85,4 +87,3 @@ switch might be the option. [solutions]: https://www.dwheeler.com/trusting-trust/ [USB qube]: /doc/usb-qubes/#creating-and-using-a-usb-qube [BadUSB]: https://srlabs.de/badusb/ - diff --git a/user/downloading-installing-upgrading/installation-guide.md b/user/downloading-installing-upgrading/installation-guide.md index 58ed9d553f..0c8962c083 100644 --- a/user/downloading-installing-upgrading/installation-guide.md +++ b/user/downloading-installing-upgrading/installation-guide.md @@ -1,6 +1,6 @@ --- +lang: en layout: doc -title: Installation Guide permalink: /doc/installation-guide/ redirect_from: - /en/doc/installation-guide/ @@ -14,6 +14,8 @@ redirect_from: - /doc/InstallationGuideR2rc2/ - /doc/InstallationGuideR3.0rc1/ - /doc/InstallationGuideR3.0rc2/ +ref: 153 +title: Installation Guide --- Installation Guide @@ -348,4 +350,3 @@ Getting Help [improving]: /doc/doc-guidelines/ [mailing lists]: /support/ [help]: /help/ - diff --git a/user/downloading-installing-upgrading/live-usb.md b/user/downloading-installing-upgrading/live-usb.md index 23c73316f3..1f9fe5c34a 100644 --- a/user/downloading-installing-upgrading/live-usb.md +++ b/user/downloading-installing-upgrading/live-usb.md @@ -1,7 +1,9 @@ --- +lang: en layout: doc -title: Live USB permalink: /doc/live-usb/ +ref: 150 +title: Live USB --- Qubes Live USB (alpha) diff --git a/user/downloading-installing-upgrading/supported-versions.md b/user/downloading-installing-upgrading/supported-versions.md index ffe0dcf1de..601134c211 100644 --- a/user/downloading-installing-upgrading/supported-versions.md +++ b/user/downloading-installing-upgrading/supported-versions.md @@ -1,7 +1,9 @@ --- +lang: en layout: doc -title: Supported Versions permalink: /doc/supported-versions/ +ref: 154 +title: Supported Versions --- # Supported Versions @@ -143,4 +145,3 @@ We aim to announce both types of events one month in advance in order to remind [debian-eol]: https://wiki.debian.org/DebianReleases [Whonix]: /doc/whonix/ [Whonix Project]: https://www.whonix.org/ - diff --git a/user/downloading-installing-upgrading/testing.md b/user/downloading-installing-upgrading/testing.md index 9c64638419..3a80f4156d 100644 --- a/user/downloading-installing-upgrading/testing.md +++ b/user/downloading-installing-upgrading/testing.md @@ -1,7 +1,9 @@ --- +lang: en layout: doc -title: Testing New Releases and Updates permalink: /doc/testing/ +ref: 147 +title: Testing New Releases and Updates --- Testing New Releases and Updates @@ -61,4 +63,3 @@ If you [report a bug] in a package that is in a testing repository, please refer [updates-status]: https://github.com/QubesOS/updates-status/issues [report a bug]: /doc/reporting-bugs/ [Providing Feedback]: #providing-feedback - diff --git a/user/downloading-installing-upgrading/upgrade/upgrade-to-r2.md b/user/downloading-installing-upgrading/upgrade/upgrade-to-r2.md index 18e827f0ad..e3eddde0b9 100644 --- a/user/downloading-installing-upgrading/upgrade/upgrade-to-r2.md +++ b/user/downloading-installing-upgrading/upgrade/upgrade-to-r2.md @@ -1,12 +1,14 @@ --- +lang: en layout: doc -title: Upgrading to R2 permalink: /doc/upgrade-to-r2/ redirect_from: - /en/doc/upgrade-to-r2/ - /doc/UpgradeToR2/ - /doc/UpgradeToR2rc1/ - /wiki/UpgradeToR2rc1/ +ref: 156 +title: Upgrading to R2 --- Upgrading Qubes R2 Beta 3 to R2 diff --git a/user/downloading-installing-upgrading/upgrade/upgrade-to-r2b1.md b/user/downloading-installing-upgrading/upgrade/upgrade-to-r2b1.md index ef8e9bfb86..ec5cea491d 100644 --- a/user/downloading-installing-upgrading/upgrade/upgrade-to-r2b1.md +++ b/user/downloading-installing-upgrading/upgrade/upgrade-to-r2b1.md @@ -1,11 +1,13 @@ --- +lang: en layout: doc -title: Upgrading to R2B1 permalink: /doc/upgrade-to-r2b1/ redirect_from: - /en/doc/upgrade-to-r2b1/ - /doc/UpgradeToR2B1/ - /wiki/UpgradeToR2B1/ +ref: 163 +title: Upgrading to R2B1 --- Upgrading Qubes R1 to R2 Beta 1 @@ -74,4 +76,3 @@ Be sure to do steps described in this section after *all* your template and stan ~~~ 4. Reboot your system. Please note that if you use Anti Evil Maid, then it won't be able to unseal the passphrase this time, because the Xen, kernel, and initramfs binaries have changed. Once the system boots up again, you could reseal your Anti Evil Maid's passphrase to the new configuration. Please consult Anti Evil Maid documentation for explanation on how to do that. - diff --git a/user/downloading-installing-upgrading/upgrade/upgrade-to-r2b2.md b/user/downloading-installing-upgrading/upgrade/upgrade-to-r2b2.md index a3d37ee9a5..674ddc5509 100644 --- a/user/downloading-installing-upgrading/upgrade/upgrade-to-r2b2.md +++ b/user/downloading-installing-upgrading/upgrade/upgrade-to-r2b2.md @@ -1,11 +1,13 @@ --- +lang: en layout: doc -title: Upgrading to R2B2 permalink: /doc/upgrade-to-r2b2/ redirect_from: - /en/doc/upgrade-to-r2b2/ - /doc/UpgradeToR2B2/ - /wiki/UpgradeToR2B2/ +ref: 160 +title: Upgrading to R2B2 --- Upgrading Qubes R1 to R2 (beta2) diff --git a/user/downloading-installing-upgrading/upgrade/upgrade-to-r2b3.md b/user/downloading-installing-upgrading/upgrade/upgrade-to-r2b3.md index c5079adb56..df30ef3e93 100644 --- a/user/downloading-installing-upgrading/upgrade/upgrade-to-r2b3.md +++ b/user/downloading-installing-upgrading/upgrade/upgrade-to-r2b3.md @@ -1,11 +1,13 @@ --- +lang: en layout: doc -title: Upgrading to R2B3 permalink: /doc/upgrade-to-r2b3/ redirect_from: - /en/doc/upgrade-to-r2b3/ - /doc/UpgradeToR2B3/ - /wiki/UpgradeToR2B3/ +ref: 157 +title: Upgrading to R2B3 --- Upgrading Qubes R2 Beta 2 to R2 Beta 3 diff --git a/user/downloading-installing-upgrading/upgrade/upgrade-to-r3.0.md b/user/downloading-installing-upgrading/upgrade/upgrade-to-r3.0.md index bc43ba2f3c..7a181ab878 100644 --- a/user/downloading-installing-upgrading/upgrade/upgrade-to-r3.0.md +++ b/user/downloading-installing-upgrading/upgrade/upgrade-to-r3.0.md @@ -1,11 +1,13 @@ --- +lang: en layout: doc -title: Upgrading to R3.0 permalink: /doc/upgrade-to-r3.0/ redirect_from: - /en/doc/upgrade-to-r3.0/ - /doc/UpgradeToR3.0/ - /doc/UpgradeToR3.0rc1/ +ref: 159 +title: Upgrading to R3.0 --- Upgrading Qubes R2 to R3.0 diff --git a/user/downloading-installing-upgrading/upgrade/upgrade-to-r3.1.md b/user/downloading-installing-upgrading/upgrade/upgrade-to-r3.1.md index e858c6b779..2a95131d39 100644 --- a/user/downloading-installing-upgrading/upgrade/upgrade-to-r3.1.md +++ b/user/downloading-installing-upgrading/upgrade/upgrade-to-r3.1.md @@ -1,11 +1,13 @@ --- +lang: en layout: doc -title: Upgrading to R3.1 permalink: /doc/upgrade-to-r3.1/ redirect_from: - /en/doc/upgrade-to-r3.1/ - /doc/UpgradeToR3.1/ - /doc/UpgradeToR3.1rc1/ +ref: 155 +title: Upgrading to R3.1 --- Upgrading Qubes R3.0 to R3.1 @@ -114,4 +116,3 @@ Once you have upgraded dom0, you can install new templates from Qubes R3.1 repositories, in particular the new default Fedora 23 template: sudo qubes-dom0-update qubes-template-fedora-23 - diff --git a/user/downloading-installing-upgrading/upgrade/upgrade-to-r3.2.md b/user/downloading-installing-upgrading/upgrade/upgrade-to-r3.2.md index c391dfe8c1..7c0501e2ae 100644 --- a/user/downloading-installing-upgrading/upgrade/upgrade-to-r3.2.md +++ b/user/downloading-installing-upgrading/upgrade/upgrade-to-r3.2.md @@ -1,11 +1,13 @@ --- +lang: en layout: doc -title: Upgrading to R3.2 permalink: /doc/upgrade-to-r3.2/ redirect_from: - /en/doc/upgrade-to-r3.2/ - /doc/UpgradeToR3.2/ - /doc/UpgradeToR3.2rc1/ +ref: 161 +title: Upgrading to R3.2 --- Upgrading Qubes R3.1 to R3.2 @@ -163,5 +165,3 @@ In order to do that, please see the sudo rm -f /etc/apt/sources.list.d/qubes-r3-upgrade.list 6. Shut down the template VM. - - diff --git a/user/downloading-installing-upgrading/upgrade/upgrade-to-r4.0.md b/user/downloading-installing-upgrading/upgrade/upgrade-to-r4.0.md index e3006c4426..1bb8ed4191 100644 --- a/user/downloading-installing-upgrading/upgrade/upgrade-to-r4.0.md +++ b/user/downloading-installing-upgrading/upgrade/upgrade-to-r4.0.md @@ -1,11 +1,13 @@ --- +lang: en layout: doc -title: Upgrading to R4.0 permalink: /doc/upgrade-to-r4.0/ redirect_from: - /en/doc/upgrade-to-r4.0/ - /doc/UpgradeToR4.0/ - /doc/UpgradeToR4.0rc1/ +ref: 162 +title: Upgrading to R4.0 --- Upgrading Qubes R3.2 to R4.0 @@ -118,4 +120,3 @@ Please see [Supported Versions](/doc/supported-versions/) for information on sup * [Upgrading Fedora TemplateVMs](/doc/templates/fedora/#upgrading) * [Upgrading Debian TemplateVMs](/doc/templates/debian/#upgrading) * [Updating Whonix TemplateVMs](https://www.whonix.org/wiki/Qubes/Update) - diff --git a/user/downloading-installing-upgrading/upgrade/upgrade.md b/user/downloading-installing-upgrading/upgrade/upgrade.md index 5c32fc82cb..e48414d09a 100644 --- a/user/downloading-installing-upgrading/upgrade/upgrade.md +++ b/user/downloading-installing-upgrading/upgrade/upgrade.md @@ -1,7 +1,9 @@ --- +lang: en layout: doc -title: Upgrade Guides permalink: /doc/upgrade/ +ref: 158 +title: Upgrade Guides --- Qubes OS Upgrade Guides @@ -21,4 +23,3 @@ If you're just looking to update your system while staying on the same version, [Updating Qubes OS]: /doc/updating-qubes-os/ - diff --git a/user/downloading-installing-upgrading/version-scheme.md b/user/downloading-installing-upgrading/version-scheme.md index c055d1e5f0..cb829c0d19 100644 --- a/user/downloading-installing-upgrading/version-scheme.md +++ b/user/downloading-installing-upgrading/version-scheme.md @@ -1,11 +1,13 @@ --- +lang: en layout: doc -title: Version Scheme permalink: /doc/version-scheme/ redirect_from: - /en/doc/version-scheme/ - /doc/VersionScheme/ - /wiki/VersionScheme/ +ref: 151 +title: Version Scheme --- Version Scheme diff --git a/user/hardware/certified-hardware.md b/user/hardware/certified-hardware.md index aba20086c6..0982e7d09e 100644 --- a/user/hardware/certified-hardware.md +++ b/user/hardware/certified-hardware.md @@ -1,11 +1,13 @@ --- +lang: en layout: doc -title: Certified Hardware permalink: /doc/certified-hardware/ redirect_from: - - /doc/hardware/ - - /doc/certified-laptops/ - - /hardware-certification/ +- /doc/hardware/ +- /doc/certified-laptops/ +- /hardware-certification/ +ref: 144 +title: Certified Hardware --- # Certified Hardware @@ -118,4 +120,3 @@ If you are interested in having your hardware certified, please [contact us]. [Insurgo PrivacyBeast X230]: https://insurgo.ca/produit/qubesos-certified-privacybeast_x230-reasonably-secured-laptop/ [privacybeast announcement]: /news/2019/07/18/insurgo-privacybeast-qubes-certification/ [NitroPad X230]: https://shop.nitrokey.com/shop/product/nitropad-x230-67 - diff --git a/user/hardware/hardware-testing.md b/user/hardware/hardware-testing.md index 9b7093b947..c25703c7c4 100644 --- a/user/hardware/hardware-testing.md +++ b/user/hardware/hardware-testing.md @@ -1,7 +1,9 @@ --- +lang: en layout: doc -title: Hardware Testing permalink: /doc/hardware-testing/ +ref: 145 +title: Hardware Testing --- # Hardware Testing @@ -41,4 +43,3 @@ Note: The Lenovo X and T series are similar enough to assume similar compatibili [Qubes Certified Hardware]: /doc/certified-hardware/ [Hardware Compatibility List (HCL)]: /hcl/ - diff --git a/user/hardware/hcl.html b/user/hardware/hcl.html index 216676a9f9..27fa9476e2 100644 --- a/user/hardware/hcl.html +++ b/user/hardware/hcl.html @@ -1,9 +1,11 @@ --- +lang: en layout: full -title: Hardware Compatibility List (HCL) -permalink: /hcl/ model: all +permalink: /hcl/ redirect_from: /compatible-hardware/ +ref: 143 +title: Hardware Compatibility List (HCL) ---
diff --git a/user/hardware/hcl.md b/user/hardware/hcl.md index 5b9b656296..addb2bc615 100644 --- a/user/hardware/hcl.md +++ b/user/hardware/hcl.md @@ -1,6 +1,6 @@ --- +lang: en layout: doc -title: Hardware Compatibility List (HCL) permalink: /doc/hcl/ redirect_from: - /en/doc/hcl/ @@ -8,6 +8,8 @@ redirect_from: - /wiki/HCL/ - /wiki/HCLR1/ - /wiki/HCL-R2B2/ +ref: 146 +title: Hardware Compatibility List (HCL) --- Hardware Compatibility List (HCL) for All Qubes OS Releases @@ -50,4 +52,3 @@ Please consider sending the **HCL Support Files** `.cpio.gz` file as well. To ge [Certified Hardware]: /doc/certified-hardware/ [Hardware Testing]: /doc/hardware-testing/ - diff --git a/user/hardware/system-requirements.md b/user/hardware/system-requirements.md index 4a0007fece..01a03f9c3b 100644 --- a/user/hardware/system-requirements.md +++ b/user/hardware/system-requirements.md @@ -1,12 +1,14 @@ --- +lang: en layout: doc -title: System Requirements permalink: /doc/system-requirements/ redirect_from: - /system-requirements/ - /en/doc/system-requirements/ - /doc/SystemRequirements/ - /wiki/SystemRequirements/ +ref: 142 +title: System Requirements --- # System Requirements # @@ -101,4 +103,3 @@ redirect_from: [AMD-Vi (aka AMD IOMMU)]: https://en.wikipedia.org/wiki/X86_virtualization#I.2FO_MMU_virtualization_.28AMD-Vi_and_Intel_VT-d.29 [EPT]: https://en.wikipedia.org/wiki/Second_Level_Address_Translation#Extended_Page_Tables [RVI]: https://en.wikipedia.org/wiki/Second_Level_Address_Translation#Rapid_Virtualization_Indexing - diff --git a/user/managing-os/debian/debian-upgrade.md b/user/managing-os/debian/debian-upgrade.md index 828c102c15..2e6e374bd1 100644 --- a/user/managing-os/debian/debian-upgrade.md +++ b/user/managing-os/debian/debian-upgrade.md @@ -1,6 +1,6 @@ --- +lang: en layout: doc -title: Upgrading Debian TemplateVMs permalink: /doc/template/debian/upgrade/ redirect_from: - /doc/template/debian/upgrade-8-to-9/ @@ -8,6 +8,8 @@ redirect_from: - /en/doc/debian-template-upgrade-8/ - /doc/DebianTemplateUpgrade8/ - /wiki/DebianTemplateUpgrade8/ +ref: 133 +title: Upgrading Debian TemplateVMs --- # Upgrading Debian TemplateVMs @@ -161,4 +163,3 @@ We strongly recommend against using any Debian release that has reached [end-of- [StandaloneVM]: /doc/standalone-and-hvm/ [template-notes]: /doc/templates/#important-notes [5055]: https://github.com/QubesOS/qubes-issues/issues/5055 - diff --git a/user/managing-os/debian/debian.md b/user/managing-os/debian/debian.md index 236c2d8e1f..e2fb779794 100644 --- a/user/managing-os/debian/debian.md +++ b/user/managing-os/debian/debian.md @@ -1,12 +1,14 @@ --- +lang: en layout: doc -title: The Debian TemplateVM permalink: /doc/templates/debian/ redirect_from: - /doc/debian/ - /en/doc/templates/debian/ - /doc/Templates/Debian/ - /wiki/Templates/Debian/ +ref: 134 +title: The Debian TemplateVM --- # The Debian TemplateVM @@ -124,4 +126,3 @@ One solution is to add a dummy interface to allow the package to install correct [Upgrading Debian TemplateVMs]: /doc/template/debian/upgrade/ [5149]: https://github.com/QubesOS/qubes-issues/issues/5149 [install]: /doc/templates/#installing - diff --git a/user/managing-os/fedora/fedora-upgrade.md b/user/managing-os/fedora/fedora-upgrade.md index 51d5449f8f..7b3c95a602 100644 --- a/user/managing-os/fedora/fedora-upgrade.md +++ b/user/managing-os/fedora/fedora-upgrade.md @@ -1,6 +1,6 @@ --- +lang: en layout: doc -title: Upgrading Fedora TemplateVMs permalink: /doc/template/fedora/upgrade/ redirect_from: - /doc/template/fedora/upgrade-26-to-27/ @@ -19,6 +19,8 @@ redirect_from: - /doc/FedoraTemplateUpgrade28/ - /wiki/FedoraTemplateUpgrade28/ - /doc/template/fedora/upgrade-29-to-30/ +ref: 137 +title: Upgrading Fedora TemplateVMs --- # Upgrading Fedora TemplateVMs @@ -210,4 +212,3 @@ In this case, you have several options: [StandaloneVM]: /doc/standalone-and-hvm/ [template-notes]: /doc/templates/#important-notes [5055]: https://github.com/QubesOS/qubes-issues/issues/5055 - diff --git a/user/managing-os/fedora/fedora-xfce.md b/user/managing-os/fedora/fedora-xfce.md index 5a758ee94c..5c7c52a80a 100644 --- a/user/managing-os/fedora/fedora-xfce.md +++ b/user/managing-os/fedora/fedora-xfce.md @@ -1,7 +1,9 @@ --- +lang: en layout: doc -title: The Fedora Xfce TemplateVM permalink: /doc/templates/fedora-xfce/ +ref: 135 +title: The Fedora Xfce TemplateVM --- The Fedora Xfce TemplateVM @@ -29,4 +31,3 @@ To upgrade your Fedora TemplateVM, please see [Upgrading Fedora TemplateVMs]. [Upgrading Fedora TemplateVMs]: /doc/template/fedora/upgrade/ [How to Reinstall a TemplateVM]: /doc/reinstall-template/ - diff --git a/user/managing-os/fedora/fedora.md b/user/managing-os/fedora/fedora.md index 46212d4ceb..5157fa5fa2 100644 --- a/user/managing-os/fedora/fedora.md +++ b/user/managing-os/fedora/fedora.md @@ -1,7 +1,9 @@ --- +lang: en layout: doc -title: The Fedora TemplateVM permalink: /doc/templates/fedora/ +ref: 136 +title: The Fedora TemplateVM --- # The Fedora TemplateVM diff --git a/user/managing-os/minimal-templates.md b/user/managing-os/minimal-templates.md index 5fc22520d0..34580d9cd1 100644 --- a/user/managing-os/minimal-templates.md +++ b/user/managing-os/minimal-templates.md @@ -1,6 +1,6 @@ --- +lang: en layout: doc -title: Minimal TemplateVMs permalink: /doc/templates/minimal/ redirect_from: - /doc/templates/fedora-minimal/ @@ -9,6 +9,8 @@ redirect_from: - /doc/Templates/FedoraMinimal/ - /wiki/Templates/FedoraMinimal/ - /doc/templates/debian-minimal/ +ref: 132 +title: Minimal TemplateVMs --- # Minimal TemplateVMs @@ -217,4 +219,3 @@ You could, of course, use `qubes-vm-recommended` to automatically install many o [testing]: /doc/testing/ [customization]: /doc/fedora-minimal-template-customization/ [Passwordless Root Access in VMs]: /doc/vm-sudo/ - diff --git a/user/managing-os/reinstall-template.md b/user/managing-os/reinstall-template.md index 632e6648a5..2d97a1cd41 100644 --- a/user/managing-os/reinstall-template.md +++ b/user/managing-os/reinstall-template.md @@ -1,9 +1,11 @@ --- +lang: en layout: doc -title: How to Reinstall a TemplateVM permalink: /doc/reinstall-template/ redirect_from: - /doc/whonix/reinstall/ +ref: 128 +title: How to Reinstall a TemplateVM --- How to Reinstall a TemplateVM @@ -82,4 +84,3 @@ If you want to reinstall more than one TemplateVM, repeat these instructions for [TemplateVM]: /doc/templates/ - diff --git a/user/managing-os/standalone-and-hvm.md b/user/managing-os/standalone-and-hvm.md index c539310c9a..4990ca7e68 100644 --- a/user/managing-os/standalone-and-hvm.md +++ b/user/managing-os/standalone-and-hvm.md @@ -1,6 +1,6 @@ --- +lang: en layout: doc -title: StandaloneVMs and HVMs permalink: /doc/standalone-and-hvm/ redirect_from: - /doc/hvm/ @@ -8,6 +8,8 @@ redirect_from: - /en/doc/hvm-create/ - /doc/HvmCreate/ - /wiki/HvmCreate/ +ref: 130 +title: StandaloneVMs and HVMs --- # StandaloneVMs and HVMs @@ -338,4 +340,3 @@ Other documents related to HVM: - [Windows VMs](/doc/windows-vm/) - [LinuxHVMTips](/doc/linux-hvm-tips/) - diff --git a/user/managing-os/templates.md b/user/managing-os/templates.md index b092dc93a1..ab2414a42f 100644 --- a/user/managing-os/templates.md +++ b/user/managing-os/templates.md @@ -1,12 +1,14 @@ --- +lang: en layout: doc -title: TemplateVMs permalink: /doc/templates/ redirect_from: - /doc/template/ - /en/doc/templates/ - /doc/Templates/ - /wiki/Templates/ +ref: 131 +title: TemplateVMs --- # TemplateVMs diff --git a/user/managing-os/windows.md b/user/managing-os/windows.md index dd84825177..c1585fd74c 100644 --- a/user/managing-os/windows.md +++ b/user/managing-os/windows.md @@ -1,7 +1,9 @@ --- +lang: en layout: doc -title: Windows VMs permalink: /doc/windows/ +ref: 129 +title: Windows VMs --- Windows VMs in Qubes OS @@ -17,5 +19,3 @@ For more information about Windows VMs in Qubes OS, please see the specific guid * [Installing and Using Windows-based VMs](/doc/windows-vm/) * [Installing and Using Qubes Windows Tools](/doc/windows-tools/) * [Issue #3585 - Installation and know limitations of Qubes Windows Tools in Qubes R4.0](https://github.com/QubesOS/qubes-issues/issues/3585) - - diff --git a/user/reference/glossary.md b/user/reference/glossary.md index ac263e21dc..7bb719989b 100644 --- a/user/reference/glossary.md +++ b/user/reference/glossary.md @@ -1,11 +1,13 @@ --- +lang: en layout: doc -title: Glossary permalink: /doc/glossary/ redirect_from: - /en/doc/glossary/ - /doc/Glossary/ - /wiki/Glossary/ +ref: 140 +title: Glossary --- Glossary of Qubes Terminology @@ -194,4 +196,3 @@ Qubes Windows Tools are a set of programs and drivers that provide integration o QWT ---- An abbreviation of Qubes [Windows Tools](#windows-tools). - diff --git a/user/reference/qubes-service.md b/user/reference/qubes-service.md index 11d362a8d1..03f114300b 100644 --- a/user/reference/qubes-service.md +++ b/user/reference/qubes-service.md @@ -1,11 +1,13 @@ --- +lang: en layout: doc -title: Qubes Service permalink: /doc/qubes-service/ redirect_from: - /en/doc/qubes-service/ - /doc/QubesService/ - /wiki/QubesService/ +ref: 138 +title: Qubes Service --- Usage documentation is in the `qvm-service` man page. There are also described predefined services. @@ -21,4 +23,3 @@ ConditionPathExists=/var/run/qubes-service/ ~~~ This will cause the service to be started only when you enable it with `qvm-service` for this VM. - diff --git a/user/reference/research.md b/user/reference/research.md index bf8163f11b..ac9441903d 100644 --- a/user/reference/research.md +++ b/user/reference/research.md @@ -1,12 +1,14 @@ --- +lang: en layout: default -title: Research permalink: /research/ redirect_from: - /doc/qubes-research/ - /en/doc/qubes-research/ - /doc/QubesResearch/ - /wiki/QubesResearch/ +ref: 139 +title: Research --- Here are links to various research papers, projects, and blog posts that relate diff --git a/user/reference/tools.md b/user/reference/tools.md index b6bf39ec99..49d868f426 100644 --- a/user/reference/tools.md +++ b/user/reference/tools.md @@ -1,14 +1,16 @@ --- +lang: en layout: doc -title: Command-Line Tools permalink: /doc/tools/ redirect_from: - - /doc/tools/4.0/ - - /doc/tools/4.0/dom0/ - - /doc/tools/4.0/domU/ - - /doc/tools/3.2/ - - /doc/tools/3.2/dom0/ - - /doc/tools/3.2/domU/ +- /doc/tools/4.0/ +- /doc/tools/4.0/dom0/ +- /doc/tools/4.0/domU/ +- /doc/tools/3.2/ +- /doc/tools/3.2/dom0/ +- /doc/tools/3.2/domU/ +ref: 141 +title: Command-Line Tools --- Command-Line Tools @@ -28,4 +30,3 @@ DomU * [qvm-open-in-dvm](https://github.com/QubesOS/qubes-core-agent-linux/blob/master/doc/vm-tools/qvm-open-in-dvm.rst) * [qvm-open-in-vm](https://github.com/QubesOS/qubes-core-agent-linux/blob/master/doc/vm-tools/qvm-open-in-vm.rst) * [qvm-run-vm](https://github.com/QubesOS/qubes-core-agent-linux/blob/master/doc/vm-tools/qvm-run-vm.rst) - diff --git a/user/security-in-qubes/anti-evil-maid.md b/user/security-in-qubes/anti-evil-maid.md index af1c6936e1..45ece579a8 100644 --- a/user/security-in-qubes/anti-evil-maid.md +++ b/user/security-in-qubes/anti-evil-maid.md @@ -1,11 +1,13 @@ --- +lang: en layout: doc -title: Anti Evil Maid (AEM) permalink: /doc/anti-evil-maid/ redirect_from: - /en/doc/anti-evil-maid/ - /doc/AntiEvilMaid/ - /wiki/AntiEvilMaid/ +ref: 164 +title: Anti Evil Maid (AEM) --- Installing and Using Anti Evil Maid (AEM) with Qubes OS @@ -60,4 +62,3 @@ Known issues - USB 3.0 isn't supported yet - [AEM is not compatible with having an SSD cache](https://groups.google.com/d/msgid/qubes-users/70021590-fb3a-4f95-9ce5-4b340530ddbf%40petaramesh.org) - diff --git a/user/security-in-qubes/data-leaks.md b/user/security-in-qubes/data-leaks.md index ed5383a39d..7d0ca805d5 100644 --- a/user/security-in-qubes/data-leaks.md +++ b/user/security-in-qubes/data-leaks.md @@ -1,11 +1,13 @@ --- +lang: en layout: doc -title: Data Leaks permalink: /doc/data-leaks/ redirect_from: - /en/doc/data-leaks/ - /doc/DataLeaks/ - /wiki/DataLeaks/ +ref: 171 +title: Data Leaks --- Understanding and Preventing Data Leaks diff --git a/user/security-in-qubes/device-handling-security.md b/user/security-in-qubes/device-handling-security.md index 8a414e6e91..2b9036bbf4 100644 --- a/user/security-in-qubes/device-handling-security.md +++ b/user/security-in-qubes/device-handling-security.md @@ -1,7 +1,9 @@ --- +lang: en layout: doc -title: Device Handling Security permalink: /doc/device-handling-security/ +ref: 170 +title: Device Handling Security --- # Device Handling Security # @@ -86,4 +88,3 @@ Support for [two factor authentication][qubes u2f proxy] was recently added, tho [side channel attack]: https://en.wikipedia.org/wiki/Side-channel_attack [Xen PCI Passthrough: PV guests and PCI quirks]: https://wiki.xenproject.org/wiki/Xen_PCI_Passthrough#PV_guests_and_PCI_quirks [Software Attacks on Intel VT-d]: https://invisiblethingslab.com/resources/2011/Software%20Attacks%20on%20Intel%20VT-d.pdf - diff --git a/user/security-in-qubes/firewall.md b/user/security-in-qubes/firewall.md index 17e305b0b3..ece41f0767 100644 --- a/user/security-in-qubes/firewall.md +++ b/user/security-in-qubes/firewall.md @@ -1,12 +1,14 @@ --- +lang: en layout: doc -title: The Qubes Firewall permalink: /doc/firewall/ redirect_from: - /doc/qubes-firewall/ - /en/doc/qubes-firewall/ - /doc/QubesFirewall/ - /wiki/QubesFirewall/ +ref: 166 +title: The Qubes Firewall --- The Qubes Firewall diff --git a/user/security-in-qubes/split-gpg.md b/user/security-in-qubes/split-gpg.md index a62a9d4d38..60dc3d6906 100644 --- a/user/security-in-qubes/split-gpg.md +++ b/user/security-in-qubes/split-gpg.md @@ -1,6 +1,6 @@ --- +lang: en layout: doc -title: Split GPG permalink: /doc/split-gpg/ redirect_from: - /en/doc/split-gpg/ @@ -12,6 +12,8 @@ redirect_from: - /doc/OpenPGP/ - /doc/UserDoc/OpenPGP/ - /wiki/UserDoc/OpenPGP/ +ref: 168 +title: Split GPG --- # Qubes Split GPG # diff --git a/user/security-in-qubes/u2f-proxy.md b/user/security-in-qubes/u2f-proxy.md index efcddc0983..fbbabefab9 100644 --- a/user/security-in-qubes/u2f-proxy.md +++ b/user/security-in-qubes/u2f-proxy.md @@ -1,7 +1,9 @@ --- +lang: en layout: doc -title: The Qubes U2F Proxy permalink: /doc/u2f-proxy/ +ref: 167 +title: The Qubes U2F Proxy --- # The Qubes U2F Proxy @@ -135,4 +137,3 @@ As always, please [report any bugs you encounter]. [report any bugs you encounter]: /doc/reporting-bugs/ [ff-u2f-addon]: https://addons.mozilla.org/en-US/firefox/addon/u2f-support-add-on/?src=api [qubes-devel]: /support/#qubes-devel - diff --git a/user/security-in-qubes/vm-sudo.md b/user/security-in-qubes/vm-sudo.md index c15996a4cc..8ff1c40dd0 100644 --- a/user/security-in-qubes/vm-sudo.md +++ b/user/security-in-qubes/vm-sudo.md @@ -1,11 +1,13 @@ --- +lang: en layout: doc -title: Passwordless Root Access in VMs permalink: /doc/vm-sudo/ redirect_from: - /en/doc/vm-sudo/ - /doc/VMSudo/ - /wiki/VMSudo/ +ref: 165 +title: Passwordless Root Access in VMs --- Passwordless Root Access in VMs diff --git a/user/security-in-qubes/yubi-key.md b/user/security-in-qubes/yubi-key.md index a2a23b69eb..93085ec399 100644 --- a/user/security-in-qubes/yubi-key.md +++ b/user/security-in-qubes/yubi-key.md @@ -1,10 +1,12 @@ --- +lang: en layout: doc -title: YubiKey in Qubes permalink: /doc/yubi-key/ redirect_from: - /en/doc/yubi-key/ - /doc/YubiKey/ +ref: 169 +title: YubiKey in Qubes --- Using YubiKey to Qubes authentication From e20f59174e430325191d8eb94f5de6f5b7f39f66 Mon Sep 17 00:00:00 2001 From: dd Date: Sat, 4 Jul 2020 19:34:57 +0200 Subject: [PATCH 010/663] renamed user, external, developer documentations folders --- .../building/development-workflow.md | 0 .../building/qubes-builder-details.md | 0 {developer => developer-documentation}/building/qubes-builder.md | 0 .../building/qubes-iso-building.md | 0 {developer => developer-documentation}/code/code-signing.md | 0 {developer => developer-documentation}/code/coding-style.md | 0 {developer => developer-documentation}/code/license.md | 0 {developer => developer-documentation}/code/source-code.md | 0 .../debugging/automated-tests.md | 0 .../debugging/mount-lvm-image.md | 0 {developer => developer-documentation}/debugging/profiling.md | 0 .../debugging/safe-remote-ttys.md | 0 {developer => developer-documentation}/debugging/test-bench.md | 0 {developer => developer-documentation}/debugging/vm-interface.md | 0 .../debugging/windows-debugging.md | 0 {developer => developer-documentation}/general/devel-books.md | 0 {developer => developer-documentation}/general/doc-guidelines.md | 0 {developer => developer-documentation}/general/gsoc.md | 0 {developer => developer-documentation}/general/gsod.md | 0 {developer => developer-documentation}/general/join.md | 0 .../general/package-contributions.md | 0 {developer => developer-documentation}/general/style-guide.md | 0 {developer => developer-documentation}/general/usability-ux.md | 0 .../releases/1.0/release-notes.md | 0 .../releases/2.0/release-notes.md | 0 .../releases/3.0/release-notes.md | 0 {developer => developer-documentation}/releases/3.0/schedule.md | 0 .../releases/3.1/release-notes.md | 0 {developer => developer-documentation}/releases/3.1/schedule.md | 0 .../releases/3.2/release-notes.md | 0 {developer => developer-documentation}/releases/3.2/schedule.md | 0 .../releases/4.0/release-notes.md | 0 {developer => developer-documentation}/releases/4.0/schedule.md | 0 {developer => developer-documentation}/releases/notes.md | 0 {developer => developer-documentation}/releases/schedules.md | 0 {developer => developer-documentation}/releases/todo.md | 0 {developer => developer-documentation}/services/admin-api.md | 0 .../services/dom0-secure-updates.md | 0 {developer => developer-documentation}/services/dvm-impl.md | 0 {developer => developer-documentation}/services/qfilecopy.md | 0 {developer => developer-documentation}/services/qfileexchgd.md | 0 {developer => developer-documentation}/services/qmemman.md | 0 .../services/qrexec-internals.md | 0 .../services/qrexec-socket-services.md | 0 {developer => developer-documentation}/services/qrexec.md | 0 {developer => developer-documentation}/services/qrexec2.md | 0 {developer => developer-documentation}/system/architecture.md | 0 {developer => developer-documentation}/system/audio.md | 0 {developer => developer-documentation}/system/gui.md | 0 {developer => developer-documentation}/system/networking.md | 0 .../system/security-critical-code.md | 0 {developer => developer-documentation}/system/storage-pools.md | 0 {developer => developer-documentation}/system/system-doc.md | 0 .../system/template-implementation.md | 0 .../building-guides/building-archlinux-template.md | 0 .../building-guides/building-non-fedora-template.md | 0 .../building-guides/building-whonix-template.md | 0 .../configuration-guides/change-time-zone.md | 0 .../configuration-guides/disk-trim.md | 0 .../configuration-guides/external-audio.md | 0 .../configuration-guides/fetchmail.md | 0 .../configuration-guides/multiboot.md | 0 .../configuration-guides/multimedia.md | 0 {external => external-documentation}/configuration-guides/mutt.md | 0 .../configuration-guides/network-bridge-support.md | 0 .../configuration-guides/network-printer.md | 0 .../configuration-guides/postfix.md | 0 {external => external-documentation}/configuration-guides/rxvt.md | 0 .../configuration-guides/tips-and-tricks.md | 0 {external => external-documentation}/configuration-guides/vpn.md | 0 {external => external-documentation}/configuration-guides/w3m.md | 0 {external => external-documentation}/configuration-guides/zfs.md | 0 .../customization-guides/dark-theme.md | 0 .../customization-guides/fedora-minimal-template-customization.md | 0 .../customization-guides/language-localization.md | 0 .../customization-guides/removing-templatevm-packages.md | 0 .../customization-guides/windows-template-customization.md | 0 {external => external-documentation}/os-guides/centos.md | 0 {external => external-documentation}/os-guides/linux-hvm-tips.md | 0 {external => external-documentation}/os-guides/netbsd.md | 0 {external => external-documentation}/os-guides/pentesting.md | 0 .../os-guides/pentesting/blackarch.md | 0 {external => external-documentation}/os-guides/pentesting/kali.md | 0 {external => external-documentation}/os-guides/pentesting/ptf.md | 0 {external => external-documentation}/os-guides/ubuntu.md | 0 .../os-guides/windows/windows-tools.md | 0 .../os-guides/windows/windows-vm.md | 0 .../privacy-guides/anonymizing-your-mac-address.md | 0 {external => external-documentation}/privacy-guides/signal.md | 0 {external => external-documentation}/privacy-guides/tails.md | 0 {external => external-documentation}/privacy-guides/torvm.md | 0 {external => external-documentation}/privacy-guides/whonix.md | 0 .../security-guides/multifactor-authentication.md | 0 .../security-guides/security-guidelines.md | 0 .../security-guides/split-bitcoin.md | 0 .../troubleshooting/install-nvidia-driver.md | 0 .../troubleshooting/intel-igfx-troubleshooting.md | 0 .../troubleshooting/macbook-troubleshooting.md | 0 .../troubleshooting/nvidia-troubleshooting.md | 0 .../troubleshooting/out-of-memory.md | 0 .../troubleshooting/remove-vm-manually.md | 0 .../troubleshooting/sony-vaio-tinkering.md | 0 .../troubleshooting/thinkpad-troubleshooting.md | 0 .../troubleshooting/updating-debian-and-whonix.md | 0 .../troubleshooting/wireless-troubleshooting.md | 0 {user => user-documentation}/advanced-configuration/awesome.md | 0 {user => user-documentation}/advanced-configuration/bind-dirs.md | 0 .../advanced-configuration/config-files.md | 0 .../advanced-configuration/disposablevm-customization.md | 0 .../advanced-configuration/gui-configuration.md | 0 {user => user-documentation}/advanced-configuration/i3.md | 0 {user => user-documentation}/advanced-configuration/kde.md | 0 .../advanced-configuration/managing-vm-kernel.md | 0 .../advanced-configuration/mount-from-other-os.md | 0 .../advanced-configuration/newer-hardware-troubleshooting.md | 0 .../advanced-configuration/resize-disk-image.md | 0 {user => user-documentation}/advanced-configuration/rpc-policy.md | 0 {user => user-documentation}/advanced-configuration/salt.md | 0 .../advanced-configuration/secondary-storage.md | 0 .../advanced-configuration/uefi-troubleshooting.md | 0 {user => user-documentation}/advanced-configuration/usb-qubes.md | 0 .../common-tasks/backup-emergency-restore-v2.md | 0 .../common-tasks/backup-emergency-restore-v3.md | 0 .../common-tasks/backup-emergency-restore-v4.md | 0 {user => user-documentation}/common-tasks/backup-restore.md | 0 {user => user-documentation}/common-tasks/block-devices.md | 0 {user => user-documentation}/common-tasks/copy-from-dom0.md | 0 {user => user-documentation}/common-tasks/copy-paste.md | 0 {user => user-documentation}/common-tasks/copying-files.md | 0 {user => user-documentation}/common-tasks/device-handling.md | 0 {user => user-documentation}/common-tasks/disposablevm.md | 0 {user => user-documentation}/common-tasks/full-screen-mode.md | 0 {user => user-documentation}/common-tasks/getting-started.md | 0 .../common-tasks/managing-appvm-shortcuts.md | 0 {user => user-documentation}/common-tasks/optical-discs.md | 0 {user => user-documentation}/common-tasks/pci-devices.md | 0 {user => user-documentation}/common-tasks/software-update-dom0.md | 0 {user => user-documentation}/common-tasks/software-update-domu.md | 0 {user => user-documentation}/common-tasks/updating-qubes-os.md | 0 {user => user-documentation}/common-tasks/usb-devices.md | 0 {user => user-documentation}/common-tasks/volume-backup-revert.md | 0 .../downloading-installing-upgrading/custom-install.md | 0 .../downloading-installing-upgrading/download-mirrors.md | 0 .../downloading-installing-upgrading/install-security.md | 0 .../downloading-installing-upgrading/installation-guide.md | 0 .../downloading-installing-upgrading/live-usb.md | 0 .../downloading-installing-upgrading/supported-versions.md | 0 .../downloading-installing-upgrading/testing.md | 0 .../downloading-installing-upgrading/upgrade/upgrade-to-r2.md | 0 .../downloading-installing-upgrading/upgrade/upgrade-to-r2b1.md | 0 .../downloading-installing-upgrading/upgrade/upgrade-to-r2b2.md | 0 .../downloading-installing-upgrading/upgrade/upgrade-to-r2b3.md | 0 .../downloading-installing-upgrading/upgrade/upgrade-to-r3.0.md | 0 .../downloading-installing-upgrading/upgrade/upgrade-to-r3.1.md | 0 .../downloading-installing-upgrading/upgrade/upgrade-to-r3.2.md | 0 .../downloading-installing-upgrading/upgrade/upgrade-to-r4.0.md | 0 .../downloading-installing-upgrading/upgrade/upgrade.md | 0 .../downloading-installing-upgrading/version-scheme.md | 0 {user => user-documentation}/hardware/certified-hardware.md | 0 {user => user-documentation}/hardware/hardware-testing.md | 0 {user => user-documentation}/hardware/hcl.html | 0 {user => user-documentation}/hardware/hcl.md | 0 {user => user-documentation}/hardware/system-requirements.md | 0 {user => user-documentation}/managing-os/debian/debian-upgrade.md | 0 {user => user-documentation}/managing-os/debian/debian.md | 0 {user => user-documentation}/managing-os/fedora/fedora-upgrade.md | 0 {user => user-documentation}/managing-os/fedora/fedora-xfce.md | 0 {user => user-documentation}/managing-os/fedora/fedora.md | 0 {user => user-documentation}/managing-os/minimal-templates.md | 0 {user => user-documentation}/managing-os/reinstall-template.md | 0 {user => user-documentation}/managing-os/standalone-and-hvm.md | 0 {user => user-documentation}/managing-os/templates.md | 0 {user => user-documentation}/managing-os/windows.md | 0 {user => user-documentation}/reference/glossary.md | 0 {user => user-documentation}/reference/qubes-service.md | 0 {user => user-documentation}/reference/research.md | 0 {user => user-documentation}/reference/tools.md | 0 {user => user-documentation}/security-in-qubes/anti-evil-maid.md | 0 {user => user-documentation}/security-in-qubes/data-leaks.md | 0 .../security-in-qubes/device-handling-security.md | 0 {user => user-documentation}/security-in-qubes/firewall.md | 0 {user => user-documentation}/security-in-qubes/split-gpg.md | 0 {user => user-documentation}/security-in-qubes/u2f-proxy.md | 0 {user => user-documentation}/security-in-qubes/vm-sudo.md | 0 {user => user-documentation}/security-in-qubes/yubi-key.md | 0 185 files changed, 0 insertions(+), 0 deletions(-) rename {developer => developer-documentation}/building/development-workflow.md (100%) rename {developer => developer-documentation}/building/qubes-builder-details.md (100%) rename {developer => developer-documentation}/building/qubes-builder.md (100%) rename {developer => developer-documentation}/building/qubes-iso-building.md (100%) rename {developer => developer-documentation}/code/code-signing.md (100%) rename {developer => developer-documentation}/code/coding-style.md (100%) rename {developer => developer-documentation}/code/license.md (100%) rename {developer => developer-documentation}/code/source-code.md (100%) rename {developer => developer-documentation}/debugging/automated-tests.md (100%) rename {developer => developer-documentation}/debugging/mount-lvm-image.md (100%) rename {developer => developer-documentation}/debugging/profiling.md (100%) rename {developer => developer-documentation}/debugging/safe-remote-ttys.md (100%) rename {developer => developer-documentation}/debugging/test-bench.md (100%) rename {developer => developer-documentation}/debugging/vm-interface.md (100%) rename {developer => developer-documentation}/debugging/windows-debugging.md (100%) rename {developer => developer-documentation}/general/devel-books.md (100%) rename {developer => developer-documentation}/general/doc-guidelines.md (100%) rename {developer => developer-documentation}/general/gsoc.md (100%) rename {developer => developer-documentation}/general/gsod.md (100%) rename {developer => developer-documentation}/general/join.md (100%) rename {developer => developer-documentation}/general/package-contributions.md (100%) rename {developer => developer-documentation}/general/style-guide.md (100%) rename {developer => developer-documentation}/general/usability-ux.md (100%) rename {developer => developer-documentation}/releases/1.0/release-notes.md (100%) rename {developer => developer-documentation}/releases/2.0/release-notes.md (100%) rename {developer => developer-documentation}/releases/3.0/release-notes.md (100%) rename {developer => developer-documentation}/releases/3.0/schedule.md (100%) rename {developer => developer-documentation}/releases/3.1/release-notes.md (100%) rename {developer => developer-documentation}/releases/3.1/schedule.md (100%) rename {developer => developer-documentation}/releases/3.2/release-notes.md (100%) rename {developer => developer-documentation}/releases/3.2/schedule.md (100%) rename {developer => developer-documentation}/releases/4.0/release-notes.md (100%) rename {developer => developer-documentation}/releases/4.0/schedule.md (100%) rename {developer => developer-documentation}/releases/notes.md (100%) rename {developer => developer-documentation}/releases/schedules.md (100%) rename {developer => developer-documentation}/releases/todo.md (100%) rename {developer => developer-documentation}/services/admin-api.md (100%) rename {developer => developer-documentation}/services/dom0-secure-updates.md (100%) rename {developer => developer-documentation}/services/dvm-impl.md (100%) rename {developer => developer-documentation}/services/qfilecopy.md (100%) rename {developer => developer-documentation}/services/qfileexchgd.md (100%) rename {developer => developer-documentation}/services/qmemman.md (100%) rename {developer => developer-documentation}/services/qrexec-internals.md (100%) rename {developer => developer-documentation}/services/qrexec-socket-services.md (100%) rename {developer => developer-documentation}/services/qrexec.md (100%) rename {developer => developer-documentation}/services/qrexec2.md (100%) rename {developer => developer-documentation}/system/architecture.md (100%) rename {developer => developer-documentation}/system/audio.md (100%) rename {developer => developer-documentation}/system/gui.md (100%) rename {developer => developer-documentation}/system/networking.md (100%) rename {developer => developer-documentation}/system/security-critical-code.md (100%) rename {developer => developer-documentation}/system/storage-pools.md (100%) rename {developer => developer-documentation}/system/system-doc.md (100%) rename {developer => developer-documentation}/system/template-implementation.md (100%) rename {external => external-documentation}/building-guides/building-archlinux-template.md (100%) rename {external => external-documentation}/building-guides/building-non-fedora-template.md (100%) rename {external => external-documentation}/building-guides/building-whonix-template.md (100%) rename {external => external-documentation}/configuration-guides/change-time-zone.md (100%) rename {external => external-documentation}/configuration-guides/disk-trim.md (100%) rename {external => external-documentation}/configuration-guides/external-audio.md (100%) rename {external => external-documentation}/configuration-guides/fetchmail.md (100%) rename {external => external-documentation}/configuration-guides/multiboot.md (100%) rename {external => external-documentation}/configuration-guides/multimedia.md (100%) rename {external => external-documentation}/configuration-guides/mutt.md (100%) rename {external => external-documentation}/configuration-guides/network-bridge-support.md (100%) rename {external => external-documentation}/configuration-guides/network-printer.md (100%) rename {external => external-documentation}/configuration-guides/postfix.md (100%) rename {external => external-documentation}/configuration-guides/rxvt.md (100%) rename {external => external-documentation}/configuration-guides/tips-and-tricks.md (100%) rename {external => external-documentation}/configuration-guides/vpn.md (100%) rename {external => external-documentation}/configuration-guides/w3m.md (100%) rename {external => external-documentation}/configuration-guides/zfs.md (100%) rename {external => external-documentation}/customization-guides/dark-theme.md (100%) rename {external => external-documentation}/customization-guides/fedora-minimal-template-customization.md (100%) rename {external => external-documentation}/customization-guides/language-localization.md (100%) rename {external => external-documentation}/customization-guides/removing-templatevm-packages.md (100%) rename {external => external-documentation}/customization-guides/windows-template-customization.md (100%) rename {external => external-documentation}/os-guides/centos.md (100%) rename {external => external-documentation}/os-guides/linux-hvm-tips.md (100%) rename {external => external-documentation}/os-guides/netbsd.md (100%) rename {external => external-documentation}/os-guides/pentesting.md (100%) rename {external => external-documentation}/os-guides/pentesting/blackarch.md (100%) rename {external => external-documentation}/os-guides/pentesting/kali.md (100%) rename {external => external-documentation}/os-guides/pentesting/ptf.md (100%) rename {external => external-documentation}/os-guides/ubuntu.md (100%) rename {external => external-documentation}/os-guides/windows/windows-tools.md (100%) rename {external => external-documentation}/os-guides/windows/windows-vm.md (100%) rename {external => external-documentation}/privacy-guides/anonymizing-your-mac-address.md (100%) rename {external => external-documentation}/privacy-guides/signal.md (100%) rename {external => external-documentation}/privacy-guides/tails.md (100%) rename {external => external-documentation}/privacy-guides/torvm.md (100%) rename {external => external-documentation}/privacy-guides/whonix.md (100%) rename {external => external-documentation}/security-guides/multifactor-authentication.md (100%) rename {external => external-documentation}/security-guides/security-guidelines.md (100%) rename {external => external-documentation}/security-guides/split-bitcoin.md (100%) rename {external => external-documentation}/troubleshooting/install-nvidia-driver.md (100%) rename {external => external-documentation}/troubleshooting/intel-igfx-troubleshooting.md (100%) rename {external => external-documentation}/troubleshooting/macbook-troubleshooting.md (100%) rename {external => external-documentation}/troubleshooting/nvidia-troubleshooting.md (100%) rename {external => external-documentation}/troubleshooting/out-of-memory.md (100%) rename {external => external-documentation}/troubleshooting/remove-vm-manually.md (100%) rename {external => external-documentation}/troubleshooting/sony-vaio-tinkering.md (100%) rename {external => external-documentation}/troubleshooting/thinkpad-troubleshooting.md (100%) rename {external => external-documentation}/troubleshooting/updating-debian-and-whonix.md (100%) rename {external => external-documentation}/troubleshooting/wireless-troubleshooting.md (100%) rename {user => user-documentation}/advanced-configuration/awesome.md (100%) rename {user => user-documentation}/advanced-configuration/bind-dirs.md (100%) rename {user => user-documentation}/advanced-configuration/config-files.md (100%) rename {user => user-documentation}/advanced-configuration/disposablevm-customization.md (100%) rename {user => user-documentation}/advanced-configuration/gui-configuration.md (100%) rename {user => user-documentation}/advanced-configuration/i3.md (100%) rename {user => user-documentation}/advanced-configuration/kde.md (100%) rename {user => user-documentation}/advanced-configuration/managing-vm-kernel.md (100%) rename {user => user-documentation}/advanced-configuration/mount-from-other-os.md (100%) rename {user => user-documentation}/advanced-configuration/newer-hardware-troubleshooting.md (100%) rename {user => user-documentation}/advanced-configuration/resize-disk-image.md (100%) rename {user => user-documentation}/advanced-configuration/rpc-policy.md (100%) rename {user => user-documentation}/advanced-configuration/salt.md (100%) rename {user => user-documentation}/advanced-configuration/secondary-storage.md (100%) rename {user => user-documentation}/advanced-configuration/uefi-troubleshooting.md (100%) rename {user => user-documentation}/advanced-configuration/usb-qubes.md (100%) rename {user => user-documentation}/common-tasks/backup-emergency-restore-v2.md (100%) rename {user => user-documentation}/common-tasks/backup-emergency-restore-v3.md (100%) rename {user => user-documentation}/common-tasks/backup-emergency-restore-v4.md (100%) rename {user => user-documentation}/common-tasks/backup-restore.md (100%) rename {user => user-documentation}/common-tasks/block-devices.md (100%) rename {user => user-documentation}/common-tasks/copy-from-dom0.md (100%) rename {user => user-documentation}/common-tasks/copy-paste.md (100%) rename {user => user-documentation}/common-tasks/copying-files.md (100%) rename {user => user-documentation}/common-tasks/device-handling.md (100%) rename {user => user-documentation}/common-tasks/disposablevm.md (100%) rename {user => user-documentation}/common-tasks/full-screen-mode.md (100%) rename {user => user-documentation}/common-tasks/getting-started.md (100%) rename {user => user-documentation}/common-tasks/managing-appvm-shortcuts.md (100%) rename {user => user-documentation}/common-tasks/optical-discs.md (100%) rename {user => user-documentation}/common-tasks/pci-devices.md (100%) rename {user => user-documentation}/common-tasks/software-update-dom0.md (100%) rename {user => user-documentation}/common-tasks/software-update-domu.md (100%) rename {user => user-documentation}/common-tasks/updating-qubes-os.md (100%) rename {user => user-documentation}/common-tasks/usb-devices.md (100%) rename {user => user-documentation}/common-tasks/volume-backup-revert.md (100%) rename {user => user-documentation}/downloading-installing-upgrading/custom-install.md (100%) rename {user => user-documentation}/downloading-installing-upgrading/download-mirrors.md (100%) rename {user => user-documentation}/downloading-installing-upgrading/install-security.md (100%) rename {user => user-documentation}/downloading-installing-upgrading/installation-guide.md (100%) rename {user => user-documentation}/downloading-installing-upgrading/live-usb.md (100%) rename {user => user-documentation}/downloading-installing-upgrading/supported-versions.md (100%) rename {user => user-documentation}/downloading-installing-upgrading/testing.md (100%) rename {user => user-documentation}/downloading-installing-upgrading/upgrade/upgrade-to-r2.md (100%) rename {user => user-documentation}/downloading-installing-upgrading/upgrade/upgrade-to-r2b1.md (100%) rename {user => user-documentation}/downloading-installing-upgrading/upgrade/upgrade-to-r2b2.md (100%) rename {user => user-documentation}/downloading-installing-upgrading/upgrade/upgrade-to-r2b3.md (100%) rename {user => user-documentation}/downloading-installing-upgrading/upgrade/upgrade-to-r3.0.md (100%) rename {user => user-documentation}/downloading-installing-upgrading/upgrade/upgrade-to-r3.1.md (100%) rename {user => user-documentation}/downloading-installing-upgrading/upgrade/upgrade-to-r3.2.md (100%) rename {user => user-documentation}/downloading-installing-upgrading/upgrade/upgrade-to-r4.0.md (100%) rename {user => user-documentation}/downloading-installing-upgrading/upgrade/upgrade.md (100%) rename {user => user-documentation}/downloading-installing-upgrading/version-scheme.md (100%) rename {user => user-documentation}/hardware/certified-hardware.md (100%) rename {user => user-documentation}/hardware/hardware-testing.md (100%) rename {user => user-documentation}/hardware/hcl.html (100%) rename {user => user-documentation}/hardware/hcl.md (100%) rename {user => user-documentation}/hardware/system-requirements.md (100%) rename {user => user-documentation}/managing-os/debian/debian-upgrade.md (100%) rename {user => user-documentation}/managing-os/debian/debian.md (100%) rename {user => user-documentation}/managing-os/fedora/fedora-upgrade.md (100%) rename {user => user-documentation}/managing-os/fedora/fedora-xfce.md (100%) rename {user => user-documentation}/managing-os/fedora/fedora.md (100%) rename {user => user-documentation}/managing-os/minimal-templates.md (100%) rename {user => user-documentation}/managing-os/reinstall-template.md (100%) rename {user => user-documentation}/managing-os/standalone-and-hvm.md (100%) rename {user => user-documentation}/managing-os/templates.md (100%) rename {user => user-documentation}/managing-os/windows.md (100%) rename {user => user-documentation}/reference/glossary.md (100%) rename {user => user-documentation}/reference/qubes-service.md (100%) rename {user => user-documentation}/reference/research.md (100%) rename {user => user-documentation}/reference/tools.md (100%) rename {user => user-documentation}/security-in-qubes/anti-evil-maid.md (100%) rename {user => user-documentation}/security-in-qubes/data-leaks.md (100%) rename {user => user-documentation}/security-in-qubes/device-handling-security.md (100%) rename {user => user-documentation}/security-in-qubes/firewall.md (100%) rename {user => user-documentation}/security-in-qubes/split-gpg.md (100%) rename {user => user-documentation}/security-in-qubes/u2f-proxy.md (100%) rename {user => user-documentation}/security-in-qubes/vm-sudo.md (100%) rename {user => user-documentation}/security-in-qubes/yubi-key.md (100%) diff --git a/developer/building/development-workflow.md b/developer-documentation/building/development-workflow.md similarity index 100% rename from developer/building/development-workflow.md rename to developer-documentation/building/development-workflow.md diff --git a/developer/building/qubes-builder-details.md b/developer-documentation/building/qubes-builder-details.md similarity index 100% rename from developer/building/qubes-builder-details.md rename to developer-documentation/building/qubes-builder-details.md diff --git a/developer/building/qubes-builder.md b/developer-documentation/building/qubes-builder.md similarity index 100% rename from developer/building/qubes-builder.md rename to developer-documentation/building/qubes-builder.md diff --git a/developer/building/qubes-iso-building.md b/developer-documentation/building/qubes-iso-building.md similarity index 100% rename from developer/building/qubes-iso-building.md rename to developer-documentation/building/qubes-iso-building.md diff --git a/developer/code/code-signing.md b/developer-documentation/code/code-signing.md similarity index 100% rename from developer/code/code-signing.md rename to developer-documentation/code/code-signing.md diff --git a/developer/code/coding-style.md b/developer-documentation/code/coding-style.md similarity index 100% rename from developer/code/coding-style.md rename to developer-documentation/code/coding-style.md diff --git a/developer/code/license.md b/developer-documentation/code/license.md similarity index 100% rename from developer/code/license.md rename to developer-documentation/code/license.md diff --git a/developer/code/source-code.md b/developer-documentation/code/source-code.md similarity index 100% rename from developer/code/source-code.md rename to developer-documentation/code/source-code.md diff --git a/developer/debugging/automated-tests.md b/developer-documentation/debugging/automated-tests.md similarity index 100% rename from developer/debugging/automated-tests.md rename to developer-documentation/debugging/automated-tests.md diff --git a/developer/debugging/mount-lvm-image.md b/developer-documentation/debugging/mount-lvm-image.md similarity index 100% rename from developer/debugging/mount-lvm-image.md rename to developer-documentation/debugging/mount-lvm-image.md diff --git a/developer/debugging/profiling.md b/developer-documentation/debugging/profiling.md similarity index 100% rename from developer/debugging/profiling.md rename to developer-documentation/debugging/profiling.md diff --git a/developer/debugging/safe-remote-ttys.md b/developer-documentation/debugging/safe-remote-ttys.md similarity index 100% rename from developer/debugging/safe-remote-ttys.md rename to developer-documentation/debugging/safe-remote-ttys.md diff --git a/developer/debugging/test-bench.md b/developer-documentation/debugging/test-bench.md similarity index 100% rename from developer/debugging/test-bench.md rename to developer-documentation/debugging/test-bench.md diff --git a/developer/debugging/vm-interface.md b/developer-documentation/debugging/vm-interface.md similarity index 100% rename from developer/debugging/vm-interface.md rename to developer-documentation/debugging/vm-interface.md diff --git a/developer/debugging/windows-debugging.md b/developer-documentation/debugging/windows-debugging.md similarity index 100% rename from developer/debugging/windows-debugging.md rename to developer-documentation/debugging/windows-debugging.md diff --git a/developer/general/devel-books.md b/developer-documentation/general/devel-books.md similarity index 100% rename from developer/general/devel-books.md rename to developer-documentation/general/devel-books.md diff --git a/developer/general/doc-guidelines.md b/developer-documentation/general/doc-guidelines.md similarity index 100% rename from developer/general/doc-guidelines.md rename to developer-documentation/general/doc-guidelines.md diff --git a/developer/general/gsoc.md b/developer-documentation/general/gsoc.md similarity index 100% rename from developer/general/gsoc.md rename to developer-documentation/general/gsoc.md diff --git a/developer/general/gsod.md b/developer-documentation/general/gsod.md similarity index 100% rename from developer/general/gsod.md rename to developer-documentation/general/gsod.md diff --git a/developer/general/join.md b/developer-documentation/general/join.md similarity index 100% rename from developer/general/join.md rename to developer-documentation/general/join.md diff --git a/developer/general/package-contributions.md b/developer-documentation/general/package-contributions.md similarity index 100% rename from developer/general/package-contributions.md rename to developer-documentation/general/package-contributions.md diff --git a/developer/general/style-guide.md b/developer-documentation/general/style-guide.md similarity index 100% rename from developer/general/style-guide.md rename to developer-documentation/general/style-guide.md diff --git a/developer/general/usability-ux.md b/developer-documentation/general/usability-ux.md similarity index 100% rename from developer/general/usability-ux.md rename to developer-documentation/general/usability-ux.md diff --git a/developer/releases/1.0/release-notes.md b/developer-documentation/releases/1.0/release-notes.md similarity index 100% rename from developer/releases/1.0/release-notes.md rename to developer-documentation/releases/1.0/release-notes.md diff --git a/developer/releases/2.0/release-notes.md b/developer-documentation/releases/2.0/release-notes.md similarity index 100% rename from developer/releases/2.0/release-notes.md rename to developer-documentation/releases/2.0/release-notes.md diff --git a/developer/releases/3.0/release-notes.md b/developer-documentation/releases/3.0/release-notes.md similarity index 100% rename from developer/releases/3.0/release-notes.md rename to developer-documentation/releases/3.0/release-notes.md diff --git a/developer/releases/3.0/schedule.md b/developer-documentation/releases/3.0/schedule.md similarity index 100% rename from developer/releases/3.0/schedule.md rename to developer-documentation/releases/3.0/schedule.md diff --git a/developer/releases/3.1/release-notes.md b/developer-documentation/releases/3.1/release-notes.md similarity index 100% rename from developer/releases/3.1/release-notes.md rename to developer-documentation/releases/3.1/release-notes.md diff --git a/developer/releases/3.1/schedule.md b/developer-documentation/releases/3.1/schedule.md similarity index 100% rename from developer/releases/3.1/schedule.md rename to developer-documentation/releases/3.1/schedule.md diff --git a/developer/releases/3.2/release-notes.md b/developer-documentation/releases/3.2/release-notes.md similarity index 100% rename from developer/releases/3.2/release-notes.md rename to developer-documentation/releases/3.2/release-notes.md diff --git a/developer/releases/3.2/schedule.md b/developer-documentation/releases/3.2/schedule.md similarity index 100% rename from developer/releases/3.2/schedule.md rename to developer-documentation/releases/3.2/schedule.md diff --git a/developer/releases/4.0/release-notes.md b/developer-documentation/releases/4.0/release-notes.md similarity index 100% rename from developer/releases/4.0/release-notes.md rename to developer-documentation/releases/4.0/release-notes.md diff --git a/developer/releases/4.0/schedule.md b/developer-documentation/releases/4.0/schedule.md similarity index 100% rename from developer/releases/4.0/schedule.md rename to developer-documentation/releases/4.0/schedule.md diff --git a/developer/releases/notes.md b/developer-documentation/releases/notes.md similarity index 100% rename from developer/releases/notes.md rename to developer-documentation/releases/notes.md diff --git a/developer/releases/schedules.md b/developer-documentation/releases/schedules.md similarity index 100% rename from developer/releases/schedules.md rename to developer-documentation/releases/schedules.md diff --git a/developer/releases/todo.md b/developer-documentation/releases/todo.md similarity index 100% rename from developer/releases/todo.md rename to developer-documentation/releases/todo.md diff --git a/developer/services/admin-api.md b/developer-documentation/services/admin-api.md similarity index 100% rename from developer/services/admin-api.md rename to developer-documentation/services/admin-api.md diff --git a/developer/services/dom0-secure-updates.md b/developer-documentation/services/dom0-secure-updates.md similarity index 100% rename from developer/services/dom0-secure-updates.md rename to developer-documentation/services/dom0-secure-updates.md diff --git a/developer/services/dvm-impl.md b/developer-documentation/services/dvm-impl.md similarity index 100% rename from developer/services/dvm-impl.md rename to developer-documentation/services/dvm-impl.md diff --git a/developer/services/qfilecopy.md b/developer-documentation/services/qfilecopy.md similarity index 100% rename from developer/services/qfilecopy.md rename to developer-documentation/services/qfilecopy.md diff --git a/developer/services/qfileexchgd.md b/developer-documentation/services/qfileexchgd.md similarity index 100% rename from developer/services/qfileexchgd.md rename to developer-documentation/services/qfileexchgd.md diff --git a/developer/services/qmemman.md b/developer-documentation/services/qmemman.md similarity index 100% rename from developer/services/qmemman.md rename to developer-documentation/services/qmemman.md diff --git a/developer/services/qrexec-internals.md b/developer-documentation/services/qrexec-internals.md similarity index 100% rename from developer/services/qrexec-internals.md rename to developer-documentation/services/qrexec-internals.md diff --git a/developer/services/qrexec-socket-services.md b/developer-documentation/services/qrexec-socket-services.md similarity index 100% rename from developer/services/qrexec-socket-services.md rename to developer-documentation/services/qrexec-socket-services.md diff --git a/developer/services/qrexec.md b/developer-documentation/services/qrexec.md similarity index 100% rename from developer/services/qrexec.md rename to developer-documentation/services/qrexec.md diff --git a/developer/services/qrexec2.md b/developer-documentation/services/qrexec2.md similarity index 100% rename from developer/services/qrexec2.md rename to developer-documentation/services/qrexec2.md diff --git a/developer/system/architecture.md b/developer-documentation/system/architecture.md similarity index 100% rename from developer/system/architecture.md rename to developer-documentation/system/architecture.md diff --git a/developer/system/audio.md b/developer-documentation/system/audio.md similarity index 100% rename from developer/system/audio.md rename to developer-documentation/system/audio.md diff --git a/developer/system/gui.md b/developer-documentation/system/gui.md similarity index 100% rename from developer/system/gui.md rename to developer-documentation/system/gui.md diff --git a/developer/system/networking.md b/developer-documentation/system/networking.md similarity index 100% rename from developer/system/networking.md rename to developer-documentation/system/networking.md diff --git a/developer/system/security-critical-code.md b/developer-documentation/system/security-critical-code.md similarity index 100% rename from developer/system/security-critical-code.md rename to developer-documentation/system/security-critical-code.md diff --git a/developer/system/storage-pools.md b/developer-documentation/system/storage-pools.md similarity index 100% rename from developer/system/storage-pools.md rename to developer-documentation/system/storage-pools.md diff --git a/developer/system/system-doc.md b/developer-documentation/system/system-doc.md similarity index 100% rename from developer/system/system-doc.md rename to developer-documentation/system/system-doc.md diff --git a/developer/system/template-implementation.md b/developer-documentation/system/template-implementation.md similarity index 100% rename from developer/system/template-implementation.md rename to developer-documentation/system/template-implementation.md diff --git a/external/building-guides/building-archlinux-template.md b/external-documentation/building-guides/building-archlinux-template.md similarity index 100% rename from external/building-guides/building-archlinux-template.md rename to external-documentation/building-guides/building-archlinux-template.md diff --git a/external/building-guides/building-non-fedora-template.md b/external-documentation/building-guides/building-non-fedora-template.md similarity index 100% rename from external/building-guides/building-non-fedora-template.md rename to external-documentation/building-guides/building-non-fedora-template.md diff --git a/external/building-guides/building-whonix-template.md b/external-documentation/building-guides/building-whonix-template.md similarity index 100% rename from external/building-guides/building-whonix-template.md rename to external-documentation/building-guides/building-whonix-template.md diff --git a/external/configuration-guides/change-time-zone.md b/external-documentation/configuration-guides/change-time-zone.md similarity index 100% rename from external/configuration-guides/change-time-zone.md rename to external-documentation/configuration-guides/change-time-zone.md diff --git a/external/configuration-guides/disk-trim.md b/external-documentation/configuration-guides/disk-trim.md similarity index 100% rename from external/configuration-guides/disk-trim.md rename to external-documentation/configuration-guides/disk-trim.md diff --git a/external/configuration-guides/external-audio.md b/external-documentation/configuration-guides/external-audio.md similarity index 100% rename from external/configuration-guides/external-audio.md rename to external-documentation/configuration-guides/external-audio.md diff --git a/external/configuration-guides/fetchmail.md b/external-documentation/configuration-guides/fetchmail.md similarity index 100% rename from external/configuration-guides/fetchmail.md rename to external-documentation/configuration-guides/fetchmail.md diff --git a/external/configuration-guides/multiboot.md b/external-documentation/configuration-guides/multiboot.md similarity index 100% rename from external/configuration-guides/multiboot.md rename to external-documentation/configuration-guides/multiboot.md diff --git a/external/configuration-guides/multimedia.md b/external-documentation/configuration-guides/multimedia.md similarity index 100% rename from external/configuration-guides/multimedia.md rename to external-documentation/configuration-guides/multimedia.md diff --git a/external/configuration-guides/mutt.md b/external-documentation/configuration-guides/mutt.md similarity index 100% rename from external/configuration-guides/mutt.md rename to external-documentation/configuration-guides/mutt.md diff --git a/external/configuration-guides/network-bridge-support.md b/external-documentation/configuration-guides/network-bridge-support.md similarity index 100% rename from external/configuration-guides/network-bridge-support.md rename to external-documentation/configuration-guides/network-bridge-support.md diff --git a/external/configuration-guides/network-printer.md b/external-documentation/configuration-guides/network-printer.md similarity index 100% rename from external/configuration-guides/network-printer.md rename to external-documentation/configuration-guides/network-printer.md diff --git a/external/configuration-guides/postfix.md b/external-documentation/configuration-guides/postfix.md similarity index 100% rename from external/configuration-guides/postfix.md rename to external-documentation/configuration-guides/postfix.md diff --git a/external/configuration-guides/rxvt.md b/external-documentation/configuration-guides/rxvt.md similarity index 100% rename from external/configuration-guides/rxvt.md rename to external-documentation/configuration-guides/rxvt.md diff --git a/external/configuration-guides/tips-and-tricks.md b/external-documentation/configuration-guides/tips-and-tricks.md similarity index 100% rename from external/configuration-guides/tips-and-tricks.md rename to external-documentation/configuration-guides/tips-and-tricks.md diff --git a/external/configuration-guides/vpn.md b/external-documentation/configuration-guides/vpn.md similarity index 100% rename from external/configuration-guides/vpn.md rename to external-documentation/configuration-guides/vpn.md diff --git a/external/configuration-guides/w3m.md b/external-documentation/configuration-guides/w3m.md similarity index 100% rename from external/configuration-guides/w3m.md rename to external-documentation/configuration-guides/w3m.md diff --git a/external/configuration-guides/zfs.md b/external-documentation/configuration-guides/zfs.md similarity index 100% rename from external/configuration-guides/zfs.md rename to external-documentation/configuration-guides/zfs.md diff --git a/external/customization-guides/dark-theme.md b/external-documentation/customization-guides/dark-theme.md similarity index 100% rename from external/customization-guides/dark-theme.md rename to external-documentation/customization-guides/dark-theme.md diff --git a/external/customization-guides/fedora-minimal-template-customization.md b/external-documentation/customization-guides/fedora-minimal-template-customization.md similarity index 100% rename from external/customization-guides/fedora-minimal-template-customization.md rename to external-documentation/customization-guides/fedora-minimal-template-customization.md diff --git a/external/customization-guides/language-localization.md b/external-documentation/customization-guides/language-localization.md similarity index 100% rename from external/customization-guides/language-localization.md rename to external-documentation/customization-guides/language-localization.md diff --git a/external/customization-guides/removing-templatevm-packages.md b/external-documentation/customization-guides/removing-templatevm-packages.md similarity index 100% rename from external/customization-guides/removing-templatevm-packages.md rename to external-documentation/customization-guides/removing-templatevm-packages.md diff --git a/external/customization-guides/windows-template-customization.md b/external-documentation/customization-guides/windows-template-customization.md similarity index 100% rename from external/customization-guides/windows-template-customization.md rename to external-documentation/customization-guides/windows-template-customization.md diff --git a/external/os-guides/centos.md b/external-documentation/os-guides/centos.md similarity index 100% rename from external/os-guides/centos.md rename to external-documentation/os-guides/centos.md diff --git a/external/os-guides/linux-hvm-tips.md b/external-documentation/os-guides/linux-hvm-tips.md similarity index 100% rename from external/os-guides/linux-hvm-tips.md rename to external-documentation/os-guides/linux-hvm-tips.md diff --git a/external/os-guides/netbsd.md b/external-documentation/os-guides/netbsd.md similarity index 100% rename from external/os-guides/netbsd.md rename to external-documentation/os-guides/netbsd.md diff --git a/external/os-guides/pentesting.md b/external-documentation/os-guides/pentesting.md similarity index 100% rename from external/os-guides/pentesting.md rename to external-documentation/os-guides/pentesting.md diff --git a/external/os-guides/pentesting/blackarch.md b/external-documentation/os-guides/pentesting/blackarch.md similarity index 100% rename from external/os-guides/pentesting/blackarch.md rename to external-documentation/os-guides/pentesting/blackarch.md diff --git a/external/os-guides/pentesting/kali.md b/external-documentation/os-guides/pentesting/kali.md similarity index 100% rename from external/os-guides/pentesting/kali.md rename to external-documentation/os-guides/pentesting/kali.md diff --git a/external/os-guides/pentesting/ptf.md b/external-documentation/os-guides/pentesting/ptf.md similarity index 100% rename from external/os-guides/pentesting/ptf.md rename to external-documentation/os-guides/pentesting/ptf.md diff --git a/external/os-guides/ubuntu.md b/external-documentation/os-guides/ubuntu.md similarity index 100% rename from external/os-guides/ubuntu.md rename to external-documentation/os-guides/ubuntu.md diff --git a/external/os-guides/windows/windows-tools.md b/external-documentation/os-guides/windows/windows-tools.md similarity index 100% rename from external/os-guides/windows/windows-tools.md rename to external-documentation/os-guides/windows/windows-tools.md diff --git a/external/os-guides/windows/windows-vm.md b/external-documentation/os-guides/windows/windows-vm.md similarity index 100% rename from external/os-guides/windows/windows-vm.md rename to external-documentation/os-guides/windows/windows-vm.md diff --git a/external/privacy-guides/anonymizing-your-mac-address.md b/external-documentation/privacy-guides/anonymizing-your-mac-address.md similarity index 100% rename from external/privacy-guides/anonymizing-your-mac-address.md rename to external-documentation/privacy-guides/anonymizing-your-mac-address.md diff --git a/external/privacy-guides/signal.md b/external-documentation/privacy-guides/signal.md similarity index 100% rename from external/privacy-guides/signal.md rename to external-documentation/privacy-guides/signal.md diff --git a/external/privacy-guides/tails.md b/external-documentation/privacy-guides/tails.md similarity index 100% rename from external/privacy-guides/tails.md rename to external-documentation/privacy-guides/tails.md diff --git a/external/privacy-guides/torvm.md b/external-documentation/privacy-guides/torvm.md similarity index 100% rename from external/privacy-guides/torvm.md rename to external-documentation/privacy-guides/torvm.md diff --git a/external/privacy-guides/whonix.md b/external-documentation/privacy-guides/whonix.md similarity index 100% rename from external/privacy-guides/whonix.md rename to external-documentation/privacy-guides/whonix.md diff --git a/external/security-guides/multifactor-authentication.md b/external-documentation/security-guides/multifactor-authentication.md similarity index 100% rename from external/security-guides/multifactor-authentication.md rename to external-documentation/security-guides/multifactor-authentication.md diff --git a/external/security-guides/security-guidelines.md b/external-documentation/security-guides/security-guidelines.md similarity index 100% rename from external/security-guides/security-guidelines.md rename to external-documentation/security-guides/security-guidelines.md diff --git a/external/security-guides/split-bitcoin.md b/external-documentation/security-guides/split-bitcoin.md similarity index 100% rename from external/security-guides/split-bitcoin.md rename to external-documentation/security-guides/split-bitcoin.md diff --git a/external/troubleshooting/install-nvidia-driver.md b/external-documentation/troubleshooting/install-nvidia-driver.md similarity index 100% rename from external/troubleshooting/install-nvidia-driver.md rename to external-documentation/troubleshooting/install-nvidia-driver.md diff --git a/external/troubleshooting/intel-igfx-troubleshooting.md b/external-documentation/troubleshooting/intel-igfx-troubleshooting.md similarity index 100% rename from external/troubleshooting/intel-igfx-troubleshooting.md rename to external-documentation/troubleshooting/intel-igfx-troubleshooting.md diff --git a/external/troubleshooting/macbook-troubleshooting.md b/external-documentation/troubleshooting/macbook-troubleshooting.md similarity index 100% rename from external/troubleshooting/macbook-troubleshooting.md rename to external-documentation/troubleshooting/macbook-troubleshooting.md diff --git a/external/troubleshooting/nvidia-troubleshooting.md b/external-documentation/troubleshooting/nvidia-troubleshooting.md similarity index 100% rename from external/troubleshooting/nvidia-troubleshooting.md rename to external-documentation/troubleshooting/nvidia-troubleshooting.md diff --git a/external/troubleshooting/out-of-memory.md b/external-documentation/troubleshooting/out-of-memory.md similarity index 100% rename from external/troubleshooting/out-of-memory.md rename to external-documentation/troubleshooting/out-of-memory.md diff --git a/external/troubleshooting/remove-vm-manually.md b/external-documentation/troubleshooting/remove-vm-manually.md similarity index 100% rename from external/troubleshooting/remove-vm-manually.md rename to external-documentation/troubleshooting/remove-vm-manually.md diff --git a/external/troubleshooting/sony-vaio-tinkering.md b/external-documentation/troubleshooting/sony-vaio-tinkering.md similarity index 100% rename from external/troubleshooting/sony-vaio-tinkering.md rename to external-documentation/troubleshooting/sony-vaio-tinkering.md diff --git a/external/troubleshooting/thinkpad-troubleshooting.md b/external-documentation/troubleshooting/thinkpad-troubleshooting.md similarity index 100% rename from external/troubleshooting/thinkpad-troubleshooting.md rename to external-documentation/troubleshooting/thinkpad-troubleshooting.md diff --git a/external/troubleshooting/updating-debian-and-whonix.md b/external-documentation/troubleshooting/updating-debian-and-whonix.md similarity index 100% rename from external/troubleshooting/updating-debian-and-whonix.md rename to external-documentation/troubleshooting/updating-debian-and-whonix.md diff --git a/external/troubleshooting/wireless-troubleshooting.md b/external-documentation/troubleshooting/wireless-troubleshooting.md similarity index 100% rename from external/troubleshooting/wireless-troubleshooting.md rename to external-documentation/troubleshooting/wireless-troubleshooting.md diff --git a/user/advanced-configuration/awesome.md b/user-documentation/advanced-configuration/awesome.md similarity index 100% rename from user/advanced-configuration/awesome.md rename to user-documentation/advanced-configuration/awesome.md diff --git a/user/advanced-configuration/bind-dirs.md b/user-documentation/advanced-configuration/bind-dirs.md similarity index 100% rename from user/advanced-configuration/bind-dirs.md rename to user-documentation/advanced-configuration/bind-dirs.md diff --git a/user/advanced-configuration/config-files.md b/user-documentation/advanced-configuration/config-files.md similarity index 100% rename from user/advanced-configuration/config-files.md rename to user-documentation/advanced-configuration/config-files.md diff --git a/user/advanced-configuration/disposablevm-customization.md b/user-documentation/advanced-configuration/disposablevm-customization.md similarity index 100% rename from user/advanced-configuration/disposablevm-customization.md rename to user-documentation/advanced-configuration/disposablevm-customization.md diff --git a/user/advanced-configuration/gui-configuration.md b/user-documentation/advanced-configuration/gui-configuration.md similarity index 100% rename from user/advanced-configuration/gui-configuration.md rename to user-documentation/advanced-configuration/gui-configuration.md diff --git a/user/advanced-configuration/i3.md b/user-documentation/advanced-configuration/i3.md similarity index 100% rename from user/advanced-configuration/i3.md rename to user-documentation/advanced-configuration/i3.md diff --git a/user/advanced-configuration/kde.md b/user-documentation/advanced-configuration/kde.md similarity index 100% rename from user/advanced-configuration/kde.md rename to user-documentation/advanced-configuration/kde.md diff --git a/user/advanced-configuration/managing-vm-kernel.md b/user-documentation/advanced-configuration/managing-vm-kernel.md similarity index 100% rename from user/advanced-configuration/managing-vm-kernel.md rename to user-documentation/advanced-configuration/managing-vm-kernel.md diff --git a/user/advanced-configuration/mount-from-other-os.md b/user-documentation/advanced-configuration/mount-from-other-os.md similarity index 100% rename from user/advanced-configuration/mount-from-other-os.md rename to user-documentation/advanced-configuration/mount-from-other-os.md diff --git a/user/advanced-configuration/newer-hardware-troubleshooting.md b/user-documentation/advanced-configuration/newer-hardware-troubleshooting.md similarity index 100% rename from user/advanced-configuration/newer-hardware-troubleshooting.md rename to user-documentation/advanced-configuration/newer-hardware-troubleshooting.md diff --git a/user/advanced-configuration/resize-disk-image.md b/user-documentation/advanced-configuration/resize-disk-image.md similarity index 100% rename from user/advanced-configuration/resize-disk-image.md rename to user-documentation/advanced-configuration/resize-disk-image.md diff --git a/user/advanced-configuration/rpc-policy.md b/user-documentation/advanced-configuration/rpc-policy.md similarity index 100% rename from user/advanced-configuration/rpc-policy.md rename to user-documentation/advanced-configuration/rpc-policy.md diff --git a/user/advanced-configuration/salt.md b/user-documentation/advanced-configuration/salt.md similarity index 100% rename from user/advanced-configuration/salt.md rename to user-documentation/advanced-configuration/salt.md diff --git a/user/advanced-configuration/secondary-storage.md b/user-documentation/advanced-configuration/secondary-storage.md similarity index 100% rename from user/advanced-configuration/secondary-storage.md rename to user-documentation/advanced-configuration/secondary-storage.md diff --git a/user/advanced-configuration/uefi-troubleshooting.md b/user-documentation/advanced-configuration/uefi-troubleshooting.md similarity index 100% rename from user/advanced-configuration/uefi-troubleshooting.md rename to user-documentation/advanced-configuration/uefi-troubleshooting.md diff --git a/user/advanced-configuration/usb-qubes.md b/user-documentation/advanced-configuration/usb-qubes.md similarity index 100% rename from user/advanced-configuration/usb-qubes.md rename to user-documentation/advanced-configuration/usb-qubes.md diff --git a/user/common-tasks/backup-emergency-restore-v2.md b/user-documentation/common-tasks/backup-emergency-restore-v2.md similarity index 100% rename from user/common-tasks/backup-emergency-restore-v2.md rename to user-documentation/common-tasks/backup-emergency-restore-v2.md diff --git a/user/common-tasks/backup-emergency-restore-v3.md b/user-documentation/common-tasks/backup-emergency-restore-v3.md similarity index 100% rename from user/common-tasks/backup-emergency-restore-v3.md rename to user-documentation/common-tasks/backup-emergency-restore-v3.md diff --git a/user/common-tasks/backup-emergency-restore-v4.md b/user-documentation/common-tasks/backup-emergency-restore-v4.md similarity index 100% rename from user/common-tasks/backup-emergency-restore-v4.md rename to user-documentation/common-tasks/backup-emergency-restore-v4.md diff --git a/user/common-tasks/backup-restore.md b/user-documentation/common-tasks/backup-restore.md similarity index 100% rename from user/common-tasks/backup-restore.md rename to user-documentation/common-tasks/backup-restore.md diff --git a/user/common-tasks/block-devices.md b/user-documentation/common-tasks/block-devices.md similarity index 100% rename from user/common-tasks/block-devices.md rename to user-documentation/common-tasks/block-devices.md diff --git a/user/common-tasks/copy-from-dom0.md b/user-documentation/common-tasks/copy-from-dom0.md similarity index 100% rename from user/common-tasks/copy-from-dom0.md rename to user-documentation/common-tasks/copy-from-dom0.md diff --git a/user/common-tasks/copy-paste.md b/user-documentation/common-tasks/copy-paste.md similarity index 100% rename from user/common-tasks/copy-paste.md rename to user-documentation/common-tasks/copy-paste.md diff --git a/user/common-tasks/copying-files.md b/user-documentation/common-tasks/copying-files.md similarity index 100% rename from user/common-tasks/copying-files.md rename to user-documentation/common-tasks/copying-files.md diff --git a/user/common-tasks/device-handling.md b/user-documentation/common-tasks/device-handling.md similarity index 100% rename from user/common-tasks/device-handling.md rename to user-documentation/common-tasks/device-handling.md diff --git a/user/common-tasks/disposablevm.md b/user-documentation/common-tasks/disposablevm.md similarity index 100% rename from user/common-tasks/disposablevm.md rename to user-documentation/common-tasks/disposablevm.md diff --git a/user/common-tasks/full-screen-mode.md b/user-documentation/common-tasks/full-screen-mode.md similarity index 100% rename from user/common-tasks/full-screen-mode.md rename to user-documentation/common-tasks/full-screen-mode.md diff --git a/user/common-tasks/getting-started.md b/user-documentation/common-tasks/getting-started.md similarity index 100% rename from user/common-tasks/getting-started.md rename to user-documentation/common-tasks/getting-started.md diff --git a/user/common-tasks/managing-appvm-shortcuts.md b/user-documentation/common-tasks/managing-appvm-shortcuts.md similarity index 100% rename from user/common-tasks/managing-appvm-shortcuts.md rename to user-documentation/common-tasks/managing-appvm-shortcuts.md diff --git a/user/common-tasks/optical-discs.md b/user-documentation/common-tasks/optical-discs.md similarity index 100% rename from user/common-tasks/optical-discs.md rename to user-documentation/common-tasks/optical-discs.md diff --git a/user/common-tasks/pci-devices.md b/user-documentation/common-tasks/pci-devices.md similarity index 100% rename from user/common-tasks/pci-devices.md rename to user-documentation/common-tasks/pci-devices.md diff --git a/user/common-tasks/software-update-dom0.md b/user-documentation/common-tasks/software-update-dom0.md similarity index 100% rename from user/common-tasks/software-update-dom0.md rename to user-documentation/common-tasks/software-update-dom0.md diff --git a/user/common-tasks/software-update-domu.md b/user-documentation/common-tasks/software-update-domu.md similarity index 100% rename from user/common-tasks/software-update-domu.md rename to user-documentation/common-tasks/software-update-domu.md diff --git a/user/common-tasks/updating-qubes-os.md b/user-documentation/common-tasks/updating-qubes-os.md similarity index 100% rename from user/common-tasks/updating-qubes-os.md rename to user-documentation/common-tasks/updating-qubes-os.md diff --git a/user/common-tasks/usb-devices.md b/user-documentation/common-tasks/usb-devices.md similarity index 100% rename from user/common-tasks/usb-devices.md rename to user-documentation/common-tasks/usb-devices.md diff --git a/user/common-tasks/volume-backup-revert.md b/user-documentation/common-tasks/volume-backup-revert.md similarity index 100% rename from user/common-tasks/volume-backup-revert.md rename to user-documentation/common-tasks/volume-backup-revert.md diff --git a/user/downloading-installing-upgrading/custom-install.md b/user-documentation/downloading-installing-upgrading/custom-install.md similarity index 100% rename from user/downloading-installing-upgrading/custom-install.md rename to user-documentation/downloading-installing-upgrading/custom-install.md diff --git a/user/downloading-installing-upgrading/download-mirrors.md b/user-documentation/downloading-installing-upgrading/download-mirrors.md similarity index 100% rename from user/downloading-installing-upgrading/download-mirrors.md rename to user-documentation/downloading-installing-upgrading/download-mirrors.md diff --git a/user/downloading-installing-upgrading/install-security.md b/user-documentation/downloading-installing-upgrading/install-security.md similarity index 100% rename from user/downloading-installing-upgrading/install-security.md rename to user-documentation/downloading-installing-upgrading/install-security.md diff --git a/user/downloading-installing-upgrading/installation-guide.md b/user-documentation/downloading-installing-upgrading/installation-guide.md similarity index 100% rename from user/downloading-installing-upgrading/installation-guide.md rename to user-documentation/downloading-installing-upgrading/installation-guide.md diff --git a/user/downloading-installing-upgrading/live-usb.md b/user-documentation/downloading-installing-upgrading/live-usb.md similarity index 100% rename from user/downloading-installing-upgrading/live-usb.md rename to user-documentation/downloading-installing-upgrading/live-usb.md diff --git a/user/downloading-installing-upgrading/supported-versions.md b/user-documentation/downloading-installing-upgrading/supported-versions.md similarity index 100% rename from user/downloading-installing-upgrading/supported-versions.md rename to user-documentation/downloading-installing-upgrading/supported-versions.md diff --git a/user/downloading-installing-upgrading/testing.md b/user-documentation/downloading-installing-upgrading/testing.md similarity index 100% rename from user/downloading-installing-upgrading/testing.md rename to user-documentation/downloading-installing-upgrading/testing.md diff --git a/user/downloading-installing-upgrading/upgrade/upgrade-to-r2.md b/user-documentation/downloading-installing-upgrading/upgrade/upgrade-to-r2.md similarity index 100% rename from user/downloading-installing-upgrading/upgrade/upgrade-to-r2.md rename to user-documentation/downloading-installing-upgrading/upgrade/upgrade-to-r2.md diff --git a/user/downloading-installing-upgrading/upgrade/upgrade-to-r2b1.md b/user-documentation/downloading-installing-upgrading/upgrade/upgrade-to-r2b1.md similarity index 100% rename from user/downloading-installing-upgrading/upgrade/upgrade-to-r2b1.md rename to user-documentation/downloading-installing-upgrading/upgrade/upgrade-to-r2b1.md diff --git a/user/downloading-installing-upgrading/upgrade/upgrade-to-r2b2.md b/user-documentation/downloading-installing-upgrading/upgrade/upgrade-to-r2b2.md similarity index 100% rename from user/downloading-installing-upgrading/upgrade/upgrade-to-r2b2.md rename to user-documentation/downloading-installing-upgrading/upgrade/upgrade-to-r2b2.md diff --git a/user/downloading-installing-upgrading/upgrade/upgrade-to-r2b3.md b/user-documentation/downloading-installing-upgrading/upgrade/upgrade-to-r2b3.md similarity index 100% rename from user/downloading-installing-upgrading/upgrade/upgrade-to-r2b3.md rename to user-documentation/downloading-installing-upgrading/upgrade/upgrade-to-r2b3.md diff --git a/user/downloading-installing-upgrading/upgrade/upgrade-to-r3.0.md b/user-documentation/downloading-installing-upgrading/upgrade/upgrade-to-r3.0.md similarity index 100% rename from user/downloading-installing-upgrading/upgrade/upgrade-to-r3.0.md rename to user-documentation/downloading-installing-upgrading/upgrade/upgrade-to-r3.0.md diff --git a/user/downloading-installing-upgrading/upgrade/upgrade-to-r3.1.md b/user-documentation/downloading-installing-upgrading/upgrade/upgrade-to-r3.1.md similarity index 100% rename from user/downloading-installing-upgrading/upgrade/upgrade-to-r3.1.md rename to user-documentation/downloading-installing-upgrading/upgrade/upgrade-to-r3.1.md diff --git a/user/downloading-installing-upgrading/upgrade/upgrade-to-r3.2.md b/user-documentation/downloading-installing-upgrading/upgrade/upgrade-to-r3.2.md similarity index 100% rename from user/downloading-installing-upgrading/upgrade/upgrade-to-r3.2.md rename to user-documentation/downloading-installing-upgrading/upgrade/upgrade-to-r3.2.md diff --git a/user/downloading-installing-upgrading/upgrade/upgrade-to-r4.0.md b/user-documentation/downloading-installing-upgrading/upgrade/upgrade-to-r4.0.md similarity index 100% rename from user/downloading-installing-upgrading/upgrade/upgrade-to-r4.0.md rename to user-documentation/downloading-installing-upgrading/upgrade/upgrade-to-r4.0.md diff --git a/user/downloading-installing-upgrading/upgrade/upgrade.md b/user-documentation/downloading-installing-upgrading/upgrade/upgrade.md similarity index 100% rename from user/downloading-installing-upgrading/upgrade/upgrade.md rename to user-documentation/downloading-installing-upgrading/upgrade/upgrade.md diff --git a/user/downloading-installing-upgrading/version-scheme.md b/user-documentation/downloading-installing-upgrading/version-scheme.md similarity index 100% rename from user/downloading-installing-upgrading/version-scheme.md rename to user-documentation/downloading-installing-upgrading/version-scheme.md diff --git a/user/hardware/certified-hardware.md b/user-documentation/hardware/certified-hardware.md similarity index 100% rename from user/hardware/certified-hardware.md rename to user-documentation/hardware/certified-hardware.md diff --git a/user/hardware/hardware-testing.md b/user-documentation/hardware/hardware-testing.md similarity index 100% rename from user/hardware/hardware-testing.md rename to user-documentation/hardware/hardware-testing.md diff --git a/user/hardware/hcl.html b/user-documentation/hardware/hcl.html similarity index 100% rename from user/hardware/hcl.html rename to user-documentation/hardware/hcl.html diff --git a/user/hardware/hcl.md b/user-documentation/hardware/hcl.md similarity index 100% rename from user/hardware/hcl.md rename to user-documentation/hardware/hcl.md diff --git a/user/hardware/system-requirements.md b/user-documentation/hardware/system-requirements.md similarity index 100% rename from user/hardware/system-requirements.md rename to user-documentation/hardware/system-requirements.md diff --git a/user/managing-os/debian/debian-upgrade.md b/user-documentation/managing-os/debian/debian-upgrade.md similarity index 100% rename from user/managing-os/debian/debian-upgrade.md rename to user-documentation/managing-os/debian/debian-upgrade.md diff --git a/user/managing-os/debian/debian.md b/user-documentation/managing-os/debian/debian.md similarity index 100% rename from user/managing-os/debian/debian.md rename to user-documentation/managing-os/debian/debian.md diff --git a/user/managing-os/fedora/fedora-upgrade.md b/user-documentation/managing-os/fedora/fedora-upgrade.md similarity index 100% rename from user/managing-os/fedora/fedora-upgrade.md rename to user-documentation/managing-os/fedora/fedora-upgrade.md diff --git a/user/managing-os/fedora/fedora-xfce.md b/user-documentation/managing-os/fedora/fedora-xfce.md similarity index 100% rename from user/managing-os/fedora/fedora-xfce.md rename to user-documentation/managing-os/fedora/fedora-xfce.md diff --git a/user/managing-os/fedora/fedora.md b/user-documentation/managing-os/fedora/fedora.md similarity index 100% rename from user/managing-os/fedora/fedora.md rename to user-documentation/managing-os/fedora/fedora.md diff --git a/user/managing-os/minimal-templates.md b/user-documentation/managing-os/minimal-templates.md similarity index 100% rename from user/managing-os/minimal-templates.md rename to user-documentation/managing-os/minimal-templates.md diff --git a/user/managing-os/reinstall-template.md b/user-documentation/managing-os/reinstall-template.md similarity index 100% rename from user/managing-os/reinstall-template.md rename to user-documentation/managing-os/reinstall-template.md diff --git a/user/managing-os/standalone-and-hvm.md b/user-documentation/managing-os/standalone-and-hvm.md similarity index 100% rename from user/managing-os/standalone-and-hvm.md rename to user-documentation/managing-os/standalone-and-hvm.md diff --git a/user/managing-os/templates.md b/user-documentation/managing-os/templates.md similarity index 100% rename from user/managing-os/templates.md rename to user-documentation/managing-os/templates.md diff --git a/user/managing-os/windows.md b/user-documentation/managing-os/windows.md similarity index 100% rename from user/managing-os/windows.md rename to user-documentation/managing-os/windows.md diff --git a/user/reference/glossary.md b/user-documentation/reference/glossary.md similarity index 100% rename from user/reference/glossary.md rename to user-documentation/reference/glossary.md diff --git a/user/reference/qubes-service.md b/user-documentation/reference/qubes-service.md similarity index 100% rename from user/reference/qubes-service.md rename to user-documentation/reference/qubes-service.md diff --git a/user/reference/research.md b/user-documentation/reference/research.md similarity index 100% rename from user/reference/research.md rename to user-documentation/reference/research.md diff --git a/user/reference/tools.md b/user-documentation/reference/tools.md similarity index 100% rename from user/reference/tools.md rename to user-documentation/reference/tools.md diff --git a/user/security-in-qubes/anti-evil-maid.md b/user-documentation/security-in-qubes/anti-evil-maid.md similarity index 100% rename from user/security-in-qubes/anti-evil-maid.md rename to user-documentation/security-in-qubes/anti-evil-maid.md diff --git a/user/security-in-qubes/data-leaks.md b/user-documentation/security-in-qubes/data-leaks.md similarity index 100% rename from user/security-in-qubes/data-leaks.md rename to user-documentation/security-in-qubes/data-leaks.md diff --git a/user/security-in-qubes/device-handling-security.md b/user-documentation/security-in-qubes/device-handling-security.md similarity index 100% rename from user/security-in-qubes/device-handling-security.md rename to user-documentation/security-in-qubes/device-handling-security.md diff --git a/user/security-in-qubes/firewall.md b/user-documentation/security-in-qubes/firewall.md similarity index 100% rename from user/security-in-qubes/firewall.md rename to user-documentation/security-in-qubes/firewall.md diff --git a/user/security-in-qubes/split-gpg.md b/user-documentation/security-in-qubes/split-gpg.md similarity index 100% rename from user/security-in-qubes/split-gpg.md rename to user-documentation/security-in-qubes/split-gpg.md diff --git a/user/security-in-qubes/u2f-proxy.md b/user-documentation/security-in-qubes/u2f-proxy.md similarity index 100% rename from user/security-in-qubes/u2f-proxy.md rename to user-documentation/security-in-qubes/u2f-proxy.md diff --git a/user/security-in-qubes/vm-sudo.md b/user-documentation/security-in-qubes/vm-sudo.md similarity index 100% rename from user/security-in-qubes/vm-sudo.md rename to user-documentation/security-in-qubes/vm-sudo.md diff --git a/user/security-in-qubes/yubi-key.md b/user-documentation/security-in-qubes/yubi-key.md similarity index 100% rename from user/security-in-qubes/yubi-key.md rename to user-documentation/security-in-qubes/yubi-key.md From 3f48f8901b2ea97361771e4049470b298f1bc29e Mon Sep 17 00:00:00 2001 From: dd Date: Sat, 4 Jul 2020 21:02:44 +0200 Subject: [PATCH 011/663] Indexed documentation table of contents via index.yml, layout changed --- doc.md | 291 --------------------------------------------------------- 1 file changed, 291 deletions(-) diff --git a/doc.md b/doc.md index f76a61e2eb..5a59386e6f 100644 --- a/doc.md +++ b/doc.md @@ -16,294 +16,3 @@ ref: 12 title: Documentation --- -## Table of Contents -1. [Introduction](#introduction) -2. [Project Security](#project-security) -3. [User Documentation](#user-documentation) - 3.1. [Choosing Your Hardware](#choosing-your-hardware) - 3.2. [Downloading, Installing, and Upgrading Qubes](#downloading-installing-and-upgrading-qubes) - 3.3. [Common Tasks](#common-tasks) - 3.4. [Managing Operating Systems within Qubes](#managing-operating-systems-within-qubes) - 3.5. [Security in Qubes](#security-in-qubes) - 3.6. [Advanced Configuration](#advanced-configuration) - 3.7. [Reference Pages](#reference-pages) -4. [Developer Documentation](#developer-documentation) - 4.1. [General](#general) - 4.2. [Code](#code) - 4.3. [System](#system) - 4.4. [Services](#services) - 4.5. [Debugging](#debugging) - 4.6. [Building](#building) - 4.7. [Releases](#releases) -5. [External Documentation](#external-documentation) - 5.1. [Operating System Guides](#operating-system-guides) - 5.2. [Security Guides](#security-guides) - 5.3. [Privacy Guides](#privacy-guides) - 5.4. [Configuration Guides](#configuration-guides) - 5.5. [Customization Guides](#customization-guides) - 5.6. [Troubleshooting](#troubleshooting) - 5.7. [Building Guides](#building-guides) - -## Introduction - - * [What is Qubes OS?](/intro/) - * [Video Tours](/video-tours/) - * [Screenshots](/screenshots/) - * [User FAQ](/faq/#users) - * [Reporting Bugs and Other Issues](/doc/reporting-bugs/) - * [Help, Support, and Mailing Lists](/support/) - * [How to Contribute](/doc/contributing/) - -## Project Security - - * [Security Center](/security/) - * [Security FAQ](/faq/#general--security) - * [Security Pack](/security/pack/) - * [Security Bulletins](/security/bulletins/) - * [Canaries](/security/canaries/) - * [Xen Security Advisory (XSA) Tracker](/security/xsa/) - * [Verifying Signatures](/security/verifying-signatures/) - * [Qubes PGP Keys](https://keys.qubes-os.org/keys/) - - -## User Documentation - -Core documentation for Qubes users. - -### Choosing Your Hardware - - * [System Requirements](/doc/system-requirements/) - * [Certified Hardware](/doc/certified-hardware/) - * [Hardware Compatibility List (HCL)](/hcl/) - * [Hardware Testing](/doc/hardware-testing/) - -### Downloading, Installing, and Upgrading Qubes - - * [Downloads](/downloads/) - * [Installation Guide](/doc/installation-guide/) - * [Upgrade Guides](/doc/upgrade/) - * [Supported Versions](/doc/supported-versions/) - * [Version Scheme](/doc/version-scheme/) - * [Testing New Releases and Updates](/doc/testing/) - -### Common Tasks - - * [Getting Started](/getting-started/) - * [Copying and Pasting Text Between Domains](/doc/copy-paste/) - * [Copying and Moving Files Between Domains](/doc/copying-files/) - * [Copying from (and to) Dom0](/doc/copy-from-dom0/) - * [Updating Qubes OS](/doc/updating-qubes-os/) - * [Installing and Updating Software in Dom0](/doc/software-update-dom0/) - * [Installing and Updating Software in DomUs](/doc/software-update-domu/) - * [Backup, Restoration, and Migration](/doc/backup-restore/) - * [Volume Backup and Revert](/doc/volume-backup-revert/) - * [DisposableVMs](/doc/disposablevm/) - * [Block (or Storage) Devices](/doc/block-devices/) - * [USB Devices](/doc/usb-devices) - * [PCI Devices](/doc/pci-devices/) - * [Device Handling](/doc/device-handling/) - * [Optical Discs](/doc/optical-discs/) - * [Application Shortcuts](/doc/managing-appvm-shortcuts/) - * [Fullscreen Mode](/doc/full-screen-mode/) - -### Managing Operating Systems within Qubes - - * [TemplateVMs](/doc/templates/) - * [Fedora](/doc/templates/fedora/) - * [Debian](/doc/templates/debian/) - * [Minimal TemplateVMs](/doc/templates/minimal/) - * [Windows](/doc/windows/) - * [StandaloneVMs and HVMs](/doc/standalone-and-hvm/) - -### Security in Qubes - - * [Qubes Firewall](/doc/firewall/) - * [Understanding and Preventing Data Leaks](/doc/data-leaks/) - * [Passwordless Root Access in VMs](/doc/vm-sudo/) - * [Device Handling Security](/doc/device-handling-security/) - * [Anti Evil Maid](/doc/anti-evil-maid/) - * [Split GPG](/doc/split-gpg/) - * [U2F Proxy](/doc/u2f-proxy/) - * [YubiKey](/doc/yubi-key/) - -### Advanced Configuration - - * [Configuration Files](/doc/config-files/) - * [Storing AppVMs on Secondary Drives](/doc/secondary-storage/) - * [RPC Policies](/doc/rpc-policy/) - * [USB Qubes](/doc/usb-qubes/) - * [Managing VM Kernels](/doc/managing-vm-kernel/) - * [Salt Management Stack](/doc/salt/) - * [DisposableVM Customization](/doc/disposablevm-customization/) - * [Making Any File Persistent Using `bind-dirs`](/doc/bind-dirs/) - * [GUI Configuration](/doc/gui-configuration/) - * [Resizing Disk Images](/doc/resize-disk-image/) - * [Troubleshooting UEFI](/doc/uefi-troubleshooting/) - * [Troubleshooting Newer Hardware](/doc/newer-hardware-troubleshooting/) - * [Mounting and Decrypting Qubes Partitions from Outside Qubes](/doc/mount-from-other-os/) - * [KDE](/doc/kde/) - * [i3 Window Manager](/doc/i3/) - * [awesome Window Manager](/doc/awesome/) - -### Reference Pages - - * [Command-line Tools](/doc/tools/) - * [Glossary](/doc/glossary/) - * [Qubes Service Framework](/doc/qubes-service/) - * [Command Execution in VMs (and Qubes RPC)](/doc/qrexec/) - * [Deprecated Documentation](https://github.com/QubesOS/qubesos.github.io#deprecated-documentation) - - -## Developer Documentation - -Core documentation for Qubes developers and advanced users. - -### General - - * [Developer FAQ](/faq/#developers) - * [Package Contributions](/doc/package-contributions/) - * [Documentation Guidelines](/doc/doc-guidelines/) - * [Community-Developed Feature Tracker](/qubes-issues/) - * [Google Summer of Code](/gsoc/) - * [Google Season of Docs](/gsod/) - * [Books for Developers](/doc/devel-books/) - * [Style Guide](/doc/style-guide/) - * [Usability & UX](/doc/usability-ux/) - -### Code - - * [Source Code](/doc/source-code/) - * [Software License](/doc/license/) - * [Coding Guidelines](/doc/coding-style/) - * [Code Signing](/doc/code-signing/) - -### System - - * [Qubes OS Architecture Overview](/doc/architecture/) - * [Qubes OS Architecture Spec v0.3 [PDF]](/attachment/wiki/QubesArchitecture/arch-spec-0.3.pdf) - * [Security-critical Code in Qubes OS](/doc/security-critical-code/) - * [Qubes Core Admin](https://dev.qubes-os.org/projects/core-admin/en/latest/) - * [Qubes Core Admin Client](https://dev.qubes-os.org/projects/core-admin-client/en/latest/) - * [Qubes Admin API](/news/2017/06/27/qubes-admin-api/) - * [Qubes Core Stack](/news/2017/10/03/core3/) - * [Qubes GUI virtualization protocol](/doc/gui/) - * [Networking in Qubes](/doc/networking/) - * [Implementation of template sharing and updating](/doc/template-implementation/) - * [Storage Pools](/doc/storage-pools/) - * [Audio virtualization](/doc/audio-virtualization/) - -### Services - - * [Inter-domain file copying](/doc/qfilecopy/) (deprecates [`qfileexchgd`](/doc/qfileexchgd/)) - * [Dynamic memory management in Qubes](/doc/qmemman/) - * [Implementation of DisposableVMs](/doc/dvm-impl/) - * [Dom0 secure update mechanism](/doc/dom0-secure-updates/) - * [Qrexec: secure communication across domains](/doc/qrexec/) - * [Qrexec: Qubes RPC internals](/doc/qrexec-internals/) - * [Qrexec: Socket-based services](/doc/qrexec-socket-services/) - -### Debugging - - * [Profiling python code](/doc/profiling/) - * [Test environment in separate machine for automatic tests](/doc/test-bench/) - * [Automated tests](/doc/automated-tests/) - * [VM-dom0 internal configuration interface](/doc/vm-interface/) - * [Debugging Windows VMs](/doc/windows-debugging/) - * [Safe Remote Dom0 Terminals](/doc/safe-remote-ttys/) - * [Mount LVM Image](/doc/mount-lvm-image/) - -### Building - - * [Building Qubes](/doc/qubes-builder/) (["API" Details](/doc/qubes-builder-details/)) - * [Development Workflow](/doc/development-workflow/) - * [Building Qubes OS ISO](/doc/qubes-iso-building/) - * [Qubes Template Configuration Files](https://github.com/QubesOS/qubes-template-configs) - -### Releases - - * [Release notes](/doc/releases/notes/) - * [Release schedules](/doc/releases/schedules/) - * [Release checklist](/doc/releases/todo/) - - -## External Documentation - -Unofficial, third-party documentation from the Qubes community and others. - - * [Qubes Community Documentation](https://github.com/Qubes-Community/Contents/tree/master/docs) - -### Operating System Guides - - * [Template: Ubuntu](/doc/templates/ubuntu/) - * [Template: Whonix](/doc/whonix/) - * [Pentesting](/doc/pentesting/) - * [Pentesting: BlackArch](/doc/pentesting/blackarch/) - * [Pentesting: Kali](/doc/pentesting/kali/) - * [Pentesting: PTF](/doc/pentesting/ptf/) - * [Tips for Using Linux in an HVM](/doc/linux-hvm-tips/) - * [Creating a NetBSD VM](/doc/netbsd/) - -### Security Guides - - * [Security Guidelines](/doc/security-guidelines/) - * [Using Multi-factor Authentication with Qubes](/doc/multifactor-authentication/) - * [How to Set Up a Split Bitcoin Wallet in Qubes](/doc/split-bitcoin/) - * [Split dm-crypt](https://github.com/rustybird/qubes-split-dm-crypt) - * [Split SSH](https://kushaldas.in/posts/using-split-ssh-in-qubesos-4-0.html) - * [Using OnlyKey with Qubes OS](https://docs.crp.to/qubes.html) - -### Privacy Guides - - * [Whonix for Privacy & Anonymity](/doc/whonix/) - * [Running Tails in Qubes](/doc/tails/) - * [Anonymizing your MAC Address](/doc/anonymizing-your-mac-address/) - * [Signal](/doc/signal/) - * [Reducing the fingerprint of the text-based web browser w3m](/doc/w3m/) - -### Configuration Guides - - * [Qubes Tips and Tricks](/doc/tips-and-tricks/) - * [How to set up a ProxyVM as a VPN Gateway](/doc/vpn/) - * [Multibooting](/doc/multiboot/) - * [Changing your Time Zone](/doc/change-time-zone/) - * [Installing ZFS in Qubes](/doc/zfs/) - * [Mutt Guide](/doc/mutt/) - * [Postfix Guide](/doc/postfix/) - * [Fetchmail Guide](/doc/fetchmail/) - * [Creating Custom NetVMs and ProxyVMs](https://theinvisiblethings.blogspot.com/2011/09/playing-with-qubes-networking-for-fun.html) - * [How to make proxy for individual tcp connection from networkless VM](https://groups.google.com/group/qubes-devel/msg/4ca950ab6d7cd11a) - * [Adding Bridge Support to the NetVM (EXPERIMENTAL)](/doc/network-bridge-support/) - * [Enabling TRIM for SSD disks](/doc/disk-trim/) - * [Configuring a Network Printer](/doc/network-printer/) - * [Using External Audio Devices](/doc/external-audio/) - * [Rxvt Guide](/doc/rxvt/) - * [Adding SSD storage cache](https://groups.google.com/d/msgid/qubes-users/a08359c9-9eb0-4d1a-ad92-a8a9bc676ea6%40googlegroups.com) - * [How to Make a Multimedia TemplateVM](/doc/multimedia/) - -### Customization Guides - - * [Customizing Fedora minimal templates](/doc/fedora-minimal-template-customization/) - * [Customizing Windows 7 templates](/doc/windows-template-customization/) - * [Language Localization](/doc/language-localization/) - * [Dark Theme in Dom0 and DomU](/doc/dark-theme/) - * [Safely Removing TemplateVM Packages (Example: Thunderbird)](/doc/removing-templatevm-packages/) - -### Troubleshooting - - * [Home directory is out of disk space error](/doc/out-of-memory/) - * [Installing on system with new AMD GPU (missing firmware problem)](https://groups.google.com/group/qubes-devel/browse_thread/thread/e27a57b0eda62f76) - * [How to install an Nvidia driver in dom0](/doc/install-nvidia-driver/) - * [Nvidia troubleshooting guide](/doc/nvidia-troubleshooting/) - * [Lenovo ThinkPad Troubleshooting](/doc/thinkpad-troubleshooting/) - * [Apple MacBook Troubleshooting](/doc/macbook-troubleshooting/) - * [Getting Sony Vaio Z laptop to work with Qubes](/doc/sony-vaio-tinkering/) - * [Fixing wireless on suspend & resume](/doc/wireless-troubleshooting/) - * [How to remove VMs manually](/doc/remove-vm-manually/) - * [Intel Integrated Graphics Troubleshooting](/doc/intel-igfx-troubleshooting/) - -### Building Guides - - * [Building a TemplateVM based on a new OS (ArchLinux example)](/doc/building-non-fedora-template/) - * [Building the Archlinux Template](/doc/building-archlinux-template/) - * [Building the Whonix Templates](/doc/building-whonix-template/) - * [How to compile kernels for dom0](https://groups.google.com/d/topic/qubes-users/yBeUJPwKwHM/discussion) From a77928c1ab7f77bb6f2bcac2627b74fc26aca8ab Mon Sep 17 00:00:00 2001 From: dd Date: Sat, 4 Jul 2020 22:55:34 +0200 Subject: [PATCH 012/663] add experts layout --- introduction/experts.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/introduction/experts.md b/introduction/experts.md index e508aa47af..d2aec9d145 100644 --- a/introduction/experts.md +++ b/introduction/experts.md @@ -1,6 +1,6 @@ --- lang: en -layout: home +layout: experts permalink: /experts/ ref: 119 title: Experts From 5afa8cf342c1dbe166816899b91f9d82df677396 Mon Sep 17 00:00:00 2001 From: dd Date: Sat, 4 Jul 2020 23:18:22 +0200 Subject: [PATCH 013/663] removed problematic dots with underscores in files' and dirs' names, renamed hcl.md to avoid conflict with hcl.html, reason: transifex config --- developer-documentation/releases/{1.0 => 1_0}/release-notes.md | 0 developer-documentation/releases/{2.0 => 2_0}/release-notes.md | 0 developer-documentation/releases/{3.0 => 3_0}/release-notes.md | 0 developer-documentation/releases/{3.0 => 3_0}/schedule.md | 0 developer-documentation/releases/{3.1 => 3_1}/release-notes.md | 0 developer-documentation/releases/{3.1 => 3_1}/schedule.md | 0 developer-documentation/releases/{3.2 => 3_2}/release-notes.md | 0 developer-documentation/releases/{3.2 => 3_2}/schedule.md | 0 developer-documentation/releases/{4.0 => 4_0}/release-notes.md | 0 developer-documentation/releases/{4.0 => 4_0}/schedule.md | 0 .../upgrade/{upgrade-to-r3.0.md => upgrade-to-r3_0.md} | 0 .../upgrade/{upgrade-to-r3.1.md => upgrade-to-r3_1.md} | 0 .../upgrade/{upgrade-to-r3.2.md => upgrade-to-r3_2.md} | 0 .../upgrade/{upgrade-to-r4.0.md => upgrade-to-r4_0.md} | 0 user-documentation/hardware/{hcl.md => hcl_md.md} | 0 15 files changed, 0 insertions(+), 0 deletions(-) rename developer-documentation/releases/{1.0 => 1_0}/release-notes.md (100%) rename developer-documentation/releases/{2.0 => 2_0}/release-notes.md (100%) rename developer-documentation/releases/{3.0 => 3_0}/release-notes.md (100%) rename developer-documentation/releases/{3.0 => 3_0}/schedule.md (100%) rename developer-documentation/releases/{3.1 => 3_1}/release-notes.md (100%) rename developer-documentation/releases/{3.1 => 3_1}/schedule.md (100%) rename developer-documentation/releases/{3.2 => 3_2}/release-notes.md (100%) rename developer-documentation/releases/{3.2 => 3_2}/schedule.md (100%) rename developer-documentation/releases/{4.0 => 4_0}/release-notes.md (100%) rename developer-documentation/releases/{4.0 => 4_0}/schedule.md (100%) rename user-documentation/downloading-installing-upgrading/upgrade/{upgrade-to-r3.0.md => upgrade-to-r3_0.md} (100%) rename user-documentation/downloading-installing-upgrading/upgrade/{upgrade-to-r3.1.md => upgrade-to-r3_1.md} (100%) rename user-documentation/downloading-installing-upgrading/upgrade/{upgrade-to-r3.2.md => upgrade-to-r3_2.md} (100%) rename user-documentation/downloading-installing-upgrading/upgrade/{upgrade-to-r4.0.md => upgrade-to-r4_0.md} (100%) rename user-documentation/hardware/{hcl.md => hcl_md.md} (100%) diff --git a/developer-documentation/releases/1.0/release-notes.md b/developer-documentation/releases/1_0/release-notes.md similarity index 100% rename from developer-documentation/releases/1.0/release-notes.md rename to developer-documentation/releases/1_0/release-notes.md diff --git a/developer-documentation/releases/2.0/release-notes.md b/developer-documentation/releases/2_0/release-notes.md similarity index 100% rename from developer-documentation/releases/2.0/release-notes.md rename to developer-documentation/releases/2_0/release-notes.md diff --git a/developer-documentation/releases/3.0/release-notes.md b/developer-documentation/releases/3_0/release-notes.md similarity index 100% rename from developer-documentation/releases/3.0/release-notes.md rename to developer-documentation/releases/3_0/release-notes.md diff --git a/developer-documentation/releases/3.0/schedule.md b/developer-documentation/releases/3_0/schedule.md similarity index 100% rename from developer-documentation/releases/3.0/schedule.md rename to developer-documentation/releases/3_0/schedule.md diff --git a/developer-documentation/releases/3.1/release-notes.md b/developer-documentation/releases/3_1/release-notes.md similarity index 100% rename from developer-documentation/releases/3.1/release-notes.md rename to developer-documentation/releases/3_1/release-notes.md diff --git a/developer-documentation/releases/3.1/schedule.md b/developer-documentation/releases/3_1/schedule.md similarity index 100% rename from developer-documentation/releases/3.1/schedule.md rename to developer-documentation/releases/3_1/schedule.md diff --git a/developer-documentation/releases/3.2/release-notes.md b/developer-documentation/releases/3_2/release-notes.md similarity index 100% rename from developer-documentation/releases/3.2/release-notes.md rename to developer-documentation/releases/3_2/release-notes.md diff --git a/developer-documentation/releases/3.2/schedule.md b/developer-documentation/releases/3_2/schedule.md similarity index 100% rename from developer-documentation/releases/3.2/schedule.md rename to developer-documentation/releases/3_2/schedule.md diff --git a/developer-documentation/releases/4.0/release-notes.md b/developer-documentation/releases/4_0/release-notes.md similarity index 100% rename from developer-documentation/releases/4.0/release-notes.md rename to developer-documentation/releases/4_0/release-notes.md diff --git a/developer-documentation/releases/4.0/schedule.md b/developer-documentation/releases/4_0/schedule.md similarity index 100% rename from developer-documentation/releases/4.0/schedule.md rename to developer-documentation/releases/4_0/schedule.md diff --git a/user-documentation/downloading-installing-upgrading/upgrade/upgrade-to-r3.0.md b/user-documentation/downloading-installing-upgrading/upgrade/upgrade-to-r3_0.md similarity index 100% rename from user-documentation/downloading-installing-upgrading/upgrade/upgrade-to-r3.0.md rename to user-documentation/downloading-installing-upgrading/upgrade/upgrade-to-r3_0.md diff --git a/user-documentation/downloading-installing-upgrading/upgrade/upgrade-to-r3.1.md b/user-documentation/downloading-installing-upgrading/upgrade/upgrade-to-r3_1.md similarity index 100% rename from user-documentation/downloading-installing-upgrading/upgrade/upgrade-to-r3.1.md rename to user-documentation/downloading-installing-upgrading/upgrade/upgrade-to-r3_1.md diff --git a/user-documentation/downloading-installing-upgrading/upgrade/upgrade-to-r3.2.md b/user-documentation/downloading-installing-upgrading/upgrade/upgrade-to-r3_2.md similarity index 100% rename from user-documentation/downloading-installing-upgrading/upgrade/upgrade-to-r3.2.md rename to user-documentation/downloading-installing-upgrading/upgrade/upgrade-to-r3_2.md diff --git a/user-documentation/downloading-installing-upgrading/upgrade/upgrade-to-r4.0.md b/user-documentation/downloading-installing-upgrading/upgrade/upgrade-to-r4_0.md similarity index 100% rename from user-documentation/downloading-installing-upgrading/upgrade/upgrade-to-r4.0.md rename to user-documentation/downloading-installing-upgrading/upgrade/upgrade-to-r4_0.md diff --git a/user-documentation/hardware/hcl.md b/user-documentation/hardware/hcl_md.md similarity index 100% rename from user-documentation/hardware/hcl.md rename to user-documentation/hardware/hcl_md.md From 12ce97a9be6b73fe8fb421dce2ccbda302735d09 Mon Sep 17 00:00:00 2001 From: dd Date: Sat, 18 Jul 2020 11:46:54 +0200 Subject: [PATCH 014/663] extracted html from security-bulletins, new include, changed layout, tx_config, new _data file --- project-security/security-bulletins.md | 14 -------------- 1 file changed, 14 deletions(-) diff --git a/project-security/security-bulletins.md b/project-security/security-bulletins.md index 33cda87f5d..fb7d3db6ea 100644 --- a/project-security/security-bulletins.md +++ b/project-security/security-bulletins.md @@ -17,17 +17,3 @@ Qubes Security Bulletins (QSBs) Qubes Security Bulletins (QSBs) are published through the [Qubes Security Pack](/security/pack/). - - - - - - -{% for qsb in site.data.qsb reversed %} - - - - - -{% endfor %} -
DateQubes Security Bulletin
{{ qsb.date }}QSB #{{ qsb.qsb }}: {{ qsb.title | truncate: 68 }}
From f371c18fc53f5dfe5bb7650fdb08b9db8d2a3b83 Mon Sep 17 00:00:00 2001 From: dd Date: Sat, 18 Jul 2020 13:52:11 +0200 Subject: [PATCH 015/663] extracted html from security-canaries, new include, changed layout, tx_config, new _data file --- project-security/canaries.md | 14 -------------- 1 file changed, 14 deletions(-) diff --git a/project-security/canaries.md b/project-security/canaries.md index 547a1187b5..bd8385e030 100644 --- a/project-security/canaries.md +++ b/project-security/canaries.md @@ -12,17 +12,3 @@ Qubes Canaries Qubes Canaries are published through the [Qubes Security Pack](/security/pack/). - - - - - - -{% for canary in site.data.canary reversed %} - - - - - -{% endfor %} -
DateQubes Canary
{{ canary.date }}Qubes Canary #{{ canary.canary }}
From 536389b85de4d9296c2960e5155f1b075846139a Mon Sep 17 00:00:00 2001 From: dd Date: Sat, 18 Jul 2020 14:26:38 +0200 Subject: [PATCH 016/663] extracted html from research, new include, changed layout --- user-documentation/reference/research.md | 12 ------------ 1 file changed, 12 deletions(-) diff --git a/user-documentation/reference/research.md b/user-documentation/reference/research.md index ac9441903d..84ac246379 100644 --- a/user-documentation/reference/research.md +++ b/user-documentation/reference/research.md @@ -14,15 +14,3 @@ title: Research Here are links to various research papers, projects, and blog posts that relate to Qubes OS. -{% for category in site.data.research.categories %} -

{{category.name}}

-
    - {% for paper in site.data.research.papers %} - {% if paper.category == category.slug %} -
  • - {{paper.title}} by {{paper.author}}{% if paper.date %}, {{paper.date}}{% endif %} -
    • - {% endif %} - {% endfor %} -
-{% endfor %} From b8cc35a8b91f0a42d16d58f7d0ea70f719c2366d Mon Sep 17 00:00:00 2001 From: dd Date: Sat, 18 Jul 2020 23:35:03 +0200 Subject: [PATCH 017/663] extracted html from experts.md, new include, changed layout, tx_config, new _data file --- introduction/experts.md | 147 ++++++---------------------------------- 1 file changed, 21 insertions(+), 126 deletions(-) diff --git a/introduction/experts.md b/introduction/experts.md index d2aec9d145..805915ec85 100644 --- a/introduction/experts.md +++ b/introduction/experts.md @@ -6,148 +6,43 @@ ref: 119 title: Experts --- +{% if page.lang == nil or page.lang == "en" %} + {% assign experts = site.data.experts %} +{% else %} + {% assign experts = site.data.translation[page.lang].experts %} + {% if experts == nil or experts.size == 0 %} + {% assign experts = site.data.experts %} + {% endif %} +{% endif %} +{% assign experts = experts | where_exp: "item", "item.experts == nil" | first %} +
-

What the experts are saying about Qubes

+

{{ experts.title }}

+ +{% for item in experts.expert %} +
- - - -
-
- -
"If you're serious about security, QubesOS is the best OS available today. It's what I use, and free. Nobody does VM isolation better." - -
Edward Snowden, whistleblower and privacy advocate
-
- -
-
-
-
- - - -
-
- -
"Happy thought of the day: An attacker who merely finds a browser bug can't listen to my microphone except when I've told Qubes to enable it." - -
Daniel J. Bernstein, mathematician, cryptologist, and computer scientist
-
- -
-
-
-
- - - -
-
- -
"When I use Qubes I feel like a god. Software thinks that it's in control, that it can do what it wants? It can't. I'm in control." - -
Micah Lee, Freedom of the Press Foundation, The Intercept
-
- -
-
-
-
- - - -
-
- -
"I am so much happier and less stressed out after switching to QubesOS. Can wholeheartedly recommend." - -
Christopher Soghoian, privacy researcher, activist, and principal technologist at the ACLU
-
- -
-
-
-
- - - -
-
- -
"With QubesOS, I feel more comfortable accessing Tor Project infrastructure from the same laptop I use to execute random GameBoy ROMs I downloaded from the internet." - -
Isis Agora Lovecruft, cypherpunk and Tor Project core developer
-
- -
-
-
-
- - - -
-
- -
"Donated a % of my consulting company's last year revenue to Qubes OS. I rely on it for all my work, and recommend it to clients too." - -
Peter Todd, Applied Cryptography Consultant
-
- -
-
-
-
- - - -
-
- -
"I really like it [Qubes OS]. If your hardware supports it, I recommend it. Everything is super well thought-out." - -
Bill Budington, security engineer and technologist, Electronic Frontier Foundation
-
- -
-
-
-
- - - -
-
- -
"Periodic shout out to [Rutkowska] and the QubesOS team for *years* of hard work to improve desktop security. Qubes is the real deal." - -
Kenn White, security researcher, Open Crypto Audit Project
-
- -
-
-
-
- - + +
- -
"Trying out Qubes OS (qubes-os.org) recently; linux distro designed around increased security by virtualizing everything and making it really convenient to hop between VMs. Surprisingly good user-friendliness!" + +
"{{ item.quote }}" -
Vitalik Buterin, creator of Ethereum
+
{{ item.name }}, {{ item.occupation }}
+ +{% endfor %}
{% include footer.html %}
From b2b4b109ac702a5802955106d5f567c519bbc7f7 Mon Sep 17 00:00:00 2001 From: Neowutran Date: Sat, 25 Jul 2020 09:50:44 +0200 Subject: [PATCH 018/663] [Kali] replace gcc8 --- external/os-guides/pentesting/kali.md | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/external/os-guides/pentesting/kali.md b/external/os-guides/pentesting/kali.md index 2bd0720b3c..5bc12580f9 100644 --- a/external/os-guides/pentesting/kali.md +++ b/external/os-guides/pentesting/kali.md @@ -122,11 +122,19 @@ $ qvm-copy kali-key.asc # echo 'deb https://http.kali.org/kali kali-rolling main non-free contrib' > /etc/apt/sources.list ``` -8. Update the template +8. Replace gcc8 + +```shell_session +# apt-get remove libgcc-8-dev && apt-get install libc6-dev +``` + +**Note:** This step is currently needed. But it will not always be the case. + +9. Update the template **Note:** During execution of the update, carefully read list of packages to be removed. If it contains `qubes-vm-dependencies` package, terminate operation and try to resolve missing dependencies first. For other `qubes-*` packages, it is up to you to decide if you need them. -9. Ensure a terminal can be opened in the new template. +10. Ensure a terminal can be opened in the new template. ```shell_session $ qvm-run -a kali-rolling gnome-terminal From 01518ea52a81686067689c500f8df004a66a767a Mon Sep 17 00:00:00 2001 From: Neowutran Date: Sat, 25 Jul 2020 10:38:54 +0200 Subject: [PATCH 019/663] [Kali] replace gcc8 - typo --- external/os-guides/pentesting/kali.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/external/os-guides/pentesting/kali.md b/external/os-guides/pentesting/kali.md index 5bc12580f9..1e7d2520d1 100644 --- a/external/os-guides/pentesting/kali.md +++ b/external/os-guides/pentesting/kali.md @@ -122,7 +122,7 @@ $ qvm-copy kali-key.asc # echo 'deb https://http.kali.org/kali kali-rolling main non-free contrib' > /etc/apt/sources.list ``` -8. Replace gcc8 +8. Replace `gcc8` ```shell_session # apt-get remove libgcc-8-dev && apt-get install libc6-dev From bb0c2b22f2eecab9ceb5fe38c4eada80c608682f Mon Sep 17 00:00:00 2001 From: Neowutran Date: Wed, 29 Jul 2020 10:19:58 +0200 Subject: [PATCH 020/663] [Kali] re-word the dependency issue workaround step --- external/os-guides/pentesting/kali.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/external/os-guides/pentesting/kali.md b/external/os-guides/pentesting/kali.md index 1e7d2520d1..81a2d58c7c 100644 --- a/external/os-guides/pentesting/kali.md +++ b/external/os-guides/pentesting/kali.md @@ -122,13 +122,15 @@ $ qvm-copy kali-key.asc # echo 'deb https://http.kali.org/kali kali-rolling main non-free contrib' > /etc/apt/sources.list ``` -8. Replace `gcc8` +8. Replace `gcc8` to work around a dependency issue ```shell_session # apt-get remove libgcc-8-dev && apt-get install libc6-dev ``` -**Note:** This step is currently needed. But it will not always be the case. +**Note:** This kind of dependency issues will pop up and disappear without notice. +It depends on the differences of dependencies between the Kali repository, the testing Qubes repository and the dependency issues related to the upgrade from stable Debian to testing Debian/Kali. +So this step [step 8] is currently needed. But it will not always be the case. 9. Update the template From 1e4660434c755d40074f3f6065c5f8ec46c395ea Mon Sep 17 00:00:00 2001 From: Neowutran Date: Sat, 19 Sep 2020 08:59:31 +0200 Subject: [PATCH 021/663] [kali] apply recommendations from pull request #989 --- external/os-guides/pentesting/kali.md | 17 +++++++++++------ 1 file changed, 11 insertions(+), 6 deletions(-) diff --git a/external/os-guides/pentesting/kali.md b/external/os-guides/pentesting/kali.md index 81a2d58c7c..8e3ea7408c 100644 --- a/external/os-guides/pentesting/kali.md +++ b/external/os-guides/pentesting/kali.md @@ -21,7 +21,7 @@ Only use this method if you want the full Kali GUI (desktop, fancy menus, etc.). It comes at the cost of much greater resources consumption. 1. Download the Kali ISO -2. Create a new HVM +2. [Create a new HVM][qubes-new-hvm] 3. Start the HVM with attached CD/DVD ```shell_session $ qvm-start --cdrom :/home/user/Downloads/.iso @@ -37,9 +37,10 @@ If you need to install custom kernel modules (wifi drivers, …) you need to use The steps can be summarized as: 1. Install Qubes stable Debian template -2. Add `testing` and `securitytesting` Qubes repositories -3. Add the Kali repository -4. Update the template +2. Upgrade from Debian `stable` to Debian `testing` for Qubes repositories +3. Add `testing` and `securitytesting` Qubes repositories +4. Replace the content of `/etc/apt/sources.list` file with the Kali repository +5. Update the template Get Kali Linux PGP key ----------------------- @@ -128,8 +129,10 @@ $ qvm-copy kali-key.asc # apt-get remove libgcc-8-dev && apt-get install libc6-dev ``` -**Note:** This kind of dependency issues will pop up and disappear without notice. -It depends on the differences of dependencies between the Kali repository, the testing Qubes repository and the dependency issues related to the upgrade from stable Debian to testing Debian/Kali. +**Note:** This kind of dependency issue will pop up and disappear without notice. +Such issues arise because of the differences of dependencies in packages from +the Kali repository, the Qubes testing repository and the Debian testing +repository. So this step [step 8] is currently needed. But it will not always be the case. 9. Update the template @@ -145,6 +148,7 @@ $ qvm-run -a kali-rolling gnome-terminal Install the Kali tools ------------------------------ At this point you should have a working template and you can install the tools you need. +You can find [a list of Kali Linux Metapackages here](https://tools.kali.org/kali-metapackages) Keep in mind that the tools you will install can easily take more than 10 GB, [so you will need to **grow** the size of the VM system storage.][qubes-resize-disk-image] Alternative Options to Kali Linux @@ -164,6 +168,7 @@ Thanks to the people in [the discussion thread](https://github.com/QubesOS/qubes [qubes-ptf]: /doc/pentesting/ptf/ [qubes-template-debian-install]: /doc/templates/debian/#install [qubes-resize-disk-image]: /doc/resize-disk-image/ +[qubes-new-hvm]: /doc/standalone-and-hvm/ [kali]: https://www.kali.org/ [kali-vbox]: https://www.offensive-security.com/kali-linux-vmware-virtualbox-image-download/ From a440a49197de9c14c9faa117e38a843fbb22778e Mon Sep 17 00:00:00 2001 From: dd Date: Mon, 21 Sep 2020 04:53:13 +0200 Subject: [PATCH 022/663] moved html from security xsa markdown file to an include --- project-security/xsa.md | 79 +---------------------------------------- 1 file changed, 1 insertion(+), 78 deletions(-) diff --git a/project-security/xsa.md b/project-security/xsa.md index d0cbce0094..902896bbed 100644 --- a/project-security/xsa.md +++ b/project-security/xsa.md @@ -30,86 +30,9 @@ Important Notes * Unused and withdrawn XSA numbers are included in the tracker for the sake of completeness, but they are excluded from the [Statistics] section for the sake of accuracy. * All dates are in UTC. - -Statistics ----------- -{% assign date_first = site.data.xsa.first.date %} -{% assign date_first_epoch = date_first | date: "%s" %} -{% assign date_last = site.data.xsa.last.date %} -{% assign date_last_epoch = date_last | date: "%s" %} -{% assign timespan_epoch = date_last_epoch | minus: date_first_epoch %} -{% assign timespan_human = timespan_epoch | divided_by: 31536000.0 | round: 1 %} -{% assign xsa_total = site.data.xsa | size | plus: 1.0 %} -{% assign xsa_unused = 0.0 %} -{% assign xsa_affected = 0.0 %} -{% for xsa in site.data.xsa %} - {% if xsa.affected == true %} - {% assign xsa_affected = xsa_affected | plus: 1.0 %} - {% endif %} - {% if xsa.unused == true %} - {% assign xsa_unused = xsa_unused | plus: 1.0 %} - {% endif %} -{% endfor %} -{% assign xsa_used = xsa_total | minus: xsa_unused %} -{% assign affected_percentage = xsa_affected | divided_by: xsa_used | times: 100.0 | round: 2 %} - -* Total time span: **{{ timespan_human }} years** ({{ date_first }} to {{ date_last }}) -* Total XSAs published: **{{ xsa_used | round }}** -* Total XSAs affecting Qubes OS: **{{ xsa_affected | round }}** -* Percentage of XSAs affecting Qubes OS: **{{ affected_percentage }}%** - -Tracker -------- - - - - - - - -{% for xsa in site.data.xsa reversed %} - - - - - - -{% endfor %} -
DateXSAIs Qubes Affected?
{{ xsa.date }} - - XSA-{{ xsa.xsa }}  - - {% if xsa.affected == false %} - {% if xsa.unused %} - No (unused or withdrawn XSA number) - {% elsif xsa.mitigation %} - No ({{ xsa.mitigation }}) - {% else %} - No - {% endif %} - {% elsif xsa.affected == true %} - Yes - {% if xsa.qsb %} - | QSB-{{ xsa.qsb }}  - {% endif %} - {% elsif xsa.affected == "tba" %} - {% if xsa.tba %} - TBA  - {% else %} - TBA - {% endif %} - {% else %} - {% endif %} -
- - [XSA]: https://xenbits.xen.org/xsa/ [QSB]: /security/bulletins/ [DoS]: https://en.wikipedia.org/wiki/Denial-of-service_attack [Xen Security Policy]: https://www.xenproject.org/security-policy.html [Statistics]: #statistics + From 9ccadf7c541944eba3af451716003d2993a8bf44 Mon Sep 17 00:00:00 2001 From: Neowutran Date: Tue, 22 Sep 2020 08:39:38 +0200 Subject: [PATCH 023/663] [kali] spellchecking --- external/os-guides/pentesting/kali.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/external/os-guides/pentesting/kali.md b/external/os-guides/pentesting/kali.md index 8e3ea7408c..9f401ea475 100644 --- a/external/os-guides/pentesting/kali.md +++ b/external/os-guides/pentesting/kali.md @@ -148,7 +148,7 @@ $ qvm-run -a kali-rolling gnome-terminal Install the Kali tools ------------------------------ At this point you should have a working template and you can install the tools you need. -You can find [a list of Kali Linux Metapackages here](https://tools.kali.org/kali-metapackages) +You can find [a list of Kali Linux `Metapackages` here](https://tools.kali.org/kali-metapackages) Keep in mind that the tools you will install can easily take more than 10 GB, [so you will need to **grow** the size of the VM system storage.][qubes-resize-disk-image] Alternative Options to Kali Linux From 4dd503f4a5de40130bae063e215c6ce591e25863 Mon Sep 17 00:00:00 2001 From: dd Date: Wed, 23 Sep 2020 01:24:15 +0200 Subject: [PATCH 024/663] hcl to squash --- user-documentation/hardware/hcl.html | 175 --------------------- user-documentation/hardware/hcl_listing.md | 10 ++ 2 files changed, 10 insertions(+), 175 deletions(-) delete mode 100644 user-documentation/hardware/hcl.html create mode 100644 user-documentation/hardware/hcl_listing.md diff --git a/user-documentation/hardware/hcl.html b/user-documentation/hardware/hcl.html deleted file mode 100644 index 27fa9476e2..0000000000 --- a/user-documentation/hardware/hcl.html +++ /dev/null @@ -1,175 +0,0 @@ ---- -lang: en -layout: full -model: all -permalink: /hcl/ -redirect_from: /compatible-hardware/ -ref: 143 -title: Hardware Compatibility List (HCL) ---- - -
-
-
-

Hardware Type

-

- Laptop Devices -

-

- Desktop, Workstation & Servers -

-

- Motherboards -

-
-

- Add Your Device -

-

Information

- -
-
-

Marks & Colours

- - - - - - - -
yes
feature is working correctly		unknown
a blank cell indicates we lack information		partial
some tweaking is needed, see remarks for more information		no
does not work or is not present
-

List Columns

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ModelManufacturer and Devicename (Socket/CPU, Chipset/Southbridge, Graphics)
BIOSReported BIOS version
HVM - Intel VT-x or AMD-v technology (required for running HVM domains, such as Windows-based AppVMs) -
- IOMMU - - Intel VT-d or AMD IOMMU technology (required for effective isolation of network VMs and PCI passthrough) -
- SLAT - - Second Level Address Translation (SLAT): Intel VT-x support for Extended Page Tables (EPT) or AMD-V support for Rapid Virtualization Indexing (RVI). -
TPM - TPM with proper BIOS support (required for Anti Evil Maid) -
QubesReported Qubes version (R=Release, rc=release candidate, B=Beta, i.e.: R1, R2B1, R2rc1)
- Kernel - - Reported dom0 kernel version (numbers in uname -r), can be selected during installation and boot in Troubleshooting menu -
RemarkFurther information field. Qubes, Kernel and this field is coloured in conjunction to reflect general machine compatibility -
CreditName linked to report in qubes-users
-
-
- -

Laptop Devices

- - - - - - - - - - - - - - - {% for device in site.hcl %} - {% if device.type == 'laptop' or device.type == 'notebook' %} - {% include hcl-device.html %} - {% endif %} - {% endfor %} -
ModelBIOSHVMIOMMUSLATTPMQubesXenKernelRemarkCredit
- -

Desktop, Workstation & Server

- - - - - - - - - - - - - - - {% for device in site.hcl %} - {% if device.type == 'desktop' or device.type == 'workstation' or device.type == 'server' %} - {% include hcl-device.html %} - {% endif %} - {% endfor %} -
ModelBIOSHVMIOMMUSLATTPMQubesXenKernelRemarkCredit
- -

Motherboards

- - - - - - - - - - - - - - - {% for device in site.hcl %} - {% if device.type == 'motherboard' %} - {% include hcl-device.html %} - {% endif %} - {% endfor %} -
ModelBIOSHVMIOMMUSLATTPMQubesXenKernelRemarkCredit
-
diff --git a/user-documentation/hardware/hcl_listing.md b/user-documentation/hardware/hcl_listing.md new file mode 100644 index 0000000000..baefbff817 --- /dev/null +++ b/user-documentation/hardware/hcl_listing.md @@ -0,0 +1,10 @@ +--- +lang: en +layout: hcl +model: all +permalink: /hcl/ +redirect_from: /compatible-hardware/ +ref: 143 +title: Hardware Compatibility List (HCL) +--- + From 6f0adb4f68112c2713c7ed4e97c47434f18860b9 Mon Sep 17 00:00:00 2001 From: dd Date: Wed, 23 Sep 2020 01:26:00 +0200 Subject: [PATCH 025/663] extracted html from getting-started.md, new include, new _data file added include to layout --- .../common-tasks/getting-started.md | 24 ------------------- 1 file changed, 24 deletions(-) diff --git a/user-documentation/common-tasks/getting-started.md b/user-documentation/common-tasks/getting-started.md index 720616d043..61d734168f 100644 --- a/user-documentation/common-tasks/getting-started.md +++ b/user-documentation/common-tasks/getting-started.md @@ -184,27 +184,3 @@ In order for the changes to take effect, restart the qube(s). More details can be found [here](/doc/full-screen-mode/). -
-
-

Compatible Hardware

-

Ready to install Qubes? Make sure your hardware is compatible, as Qubes cannot run on every type of computer. Also, check out Qubes-certified Laptops.

- - Hardware Compatibility List - -
-
-

Downloads

-

Download an ISO, learn how to verify its authenticity and integrity, and follow our guides to install Qubes. Looking for the source code? You'll find it on GitHub.

- - Downloads - -
-
-

Documentation

-

Peruse our extensive library of documentation for users and developers of Qubes. You can even help us improve it!

- - Documentation - -
-
-
From 9611d888d03d6c31713244fb7ed8211ef5f86222 Mon Sep 17 00:00:00 2001 From: dd Date: Thu, 24 Sep 2020 00:17:09 +0200 Subject: [PATCH 026/663] extracted html from video-tours.md, new include, new _data file --- introduction/video-tours.html | 113 ---------------------------------- introduction/video-tours.md | 8 +++ 2 files changed, 8 insertions(+), 113 deletions(-) delete mode 100644 introduction/video-tours.html create mode 100644 introduction/video-tours.md diff --git a/introduction/video-tours.html b/introduction/video-tours.html deleted file mode 100644 index 412d0d96ef..0000000000 --- a/introduction/video-tours.html +++ /dev/null @@ -1,113 +0,0 @@ ---- -lang: en -layout: default -permalink: /video-tours/ -ref: 120 -title: Video Tours of Qubes OS ---- - -
-
-
-

Micah Lee presents "Qubes OS: The Operating System That Can Protect You Even If You Get Hacked"

-

Micah Lee, a long-time Qubes advocate, presented Qubes OS: The Operating System That Can Protect You Even If You Get Hacked at the Circle of HOPE conference, which took place July 20-22, 2018 in New York City.

- -
-
-
-
-
-

Introduction

-

Learn the basics in this introduction to Qubes OS.


- - What is Qubes OS? - -
-
-

Screenshots

-

See what using Qubes actually looks like with these screenshots of various applications running in Qubes.

- - See Screenshots - -
-
-

Getting Started

-

Ready to get started with Qubes? Here's what you need to know after installing.

- - Getting Started - -
-
-
-
-
-

A Video Tour of Qubes 3.1 by Matthew Wilson

-
-

This video by Matthew Wilson provides an overview of Qubes 3.1. You can use the menu links to browse to specific chapters.

-
-
-

 

- -
-
-
-
-
-

Docs

-

Dive into the Qubes documentation with guides, tips, and troubleshooting help.

- - Documentation - -
-
-

Downloads

-

Download an ISO, verify your download, and install Qubes.

- - Downloads - -
-
-

Security

-

Get PGP keys, security bulletins, and canaries. Learn more about our security practices.

- - Security Center - -
-
-
-
-
-

French Video Series by Paf LeGeek (6 Parts)

-
-

This French series by Paf LeGeek provides a guide to Qubes OS across six videos. You can use the menu links to browse to specific videos in the series.

-
-
-

 

- -
-
-
diff --git a/introduction/video-tours.md b/introduction/video-tours.md new file mode 100644 index 0000000000..6f6db70684 --- /dev/null +++ b/introduction/video-tours.md @@ -0,0 +1,8 @@ +--- +lang: en +layout: default +permalink: /video-tours/ +ref: 120 +title: Video Tours of Qubes OS +--- + From 7ed388380e632a66dc4ee6c63c9e333d07e66424 Mon Sep 17 00:00:00 2001 From: dd Date: Fri, 2 Oct 2020 16:45:07 +0200 Subject: [PATCH 027/663] extracted html from style-guide.md, new include, new _data file --- .../general/style-guide.md | 90 ------------------- 1 file changed, 90 deletions(-) diff --git a/developer-documentation/general/style-guide.md b/developer-documentation/general/style-guide.md index 9635690f26..5d0244940e 100644 --- a/developer-documentation/general/style-guide.md +++ b/developer-documentation/general/style-guide.md @@ -6,93 +6,3 @@ ref: 27 title: Style-guide --- -Style Guide -=========== - -## Fonts - -Currently Qubes OS is using the following fonts for our website, branding, and other public facing (non-OS) materials. The OS itself uses what is normal for a user's desktop environment of choice. - -
-{% for font in site.data.styleguide.fonts %} -
-
-
Custom Qubes Font
-
-
- Family: {{font.family}}
-
-
-{% endfor %} -
- ---- - -## Colors - -The following **grayscale** colors are currently used on the Qubes website and documentation, and they will eventually match colors within the OS itself. - -
-{% for color in site.data.styleguide.colors %} - {% if color.type == "grayscale" %} -
-
- {{color.name}} - #{{color.hex | downcase}} -
- {% endif %} -{% endfor %} -
- -The following **colors** are currently being used on the Qubes website and documentation, and they will eventually match the colors within the OS itself! - -
-{% for color in site.data.styleguide.colors %} - {% if color.type == "colors" %} -
-
- {{color.name}} - #{{color.hex | downcase}} -
- {% endif %} -{% endfor %} -
- ---- - -## Icons - -Currently, all the icons on the Qubes-OS.org website are generated using [FontAwesome](http://fortawesome.github.io/Font-Awesome/). - -*As more custom work is done to generate icons for the operating system itself, they will be added here!* - ---- - -## Logos - -The following is a collection of various sizes and versions of the Qubes logo used both in the OS itself and on our website. -The artwork is licensed under Creative Commons Attribution-ShareAlike 4.0 International (CC BY-SA 4.0). -The code is licensed under GNU GPLv2. -GPLv2 and the source code can be [downloaded here](https://github.com/QubesOS/qubes-artwork). - -
-{% for logo in site.data.styleguide.logos %} - {% for version in logo.versions %} -
-
-
- -
-
-
-

- Image: {{logo.image}}
- Size: {{version.size}}
- Format: {{version.format}}
- Download: this image -

-
-
- {% endfor %} -{% endfor %} -
From df17b04150f436a5cecb8e51ea26eebee3903c1c Mon Sep 17 00:00:00 2001 From: dd Date: Sat, 3 Oct 2020 01:58:52 +0200 Subject: [PATCH 028/663] extracted html from intro.md, new include, new _data file, include the new intro.html file to the intro layout html file --- introduction/intro.md | 164 ------------------------------------------ 1 file changed, 164 deletions(-) diff --git a/introduction/intro.md b/introduction/intro.md index 6925762f36..fa38ad52ef 100644 --- a/introduction/intro.md +++ b/introduction/intro.md @@ -12,153 +12,6 @@ ref: 126 title: An Introduction to Qubes OS --- -What is Qubes OS? ------------------ - -
-
-

Qubes OS is a free and open-source security-oriented operating system meant for single-user desktop computing.

-

Qubes OS leverages xen-based virtualization to allow for the creation and management of isolated virtual machines called qubes. - Qubes, which are implemented as virtual machines (VMs), have specific :

-
    -
  • Purposes : with a predefined set of one or many isolated applications, for personal or professional projects, to manage the network stack, the firewall, or to fulfill other user-defined purposes.
    • -
  • Natures : full-fledged or stripped-down virtual machines which are based on popular operating systems such as Fedora, Debian or Windows.
    • -
  • Levels of trust : from complete to non-existent. All windows are displayed in a unified desktop environment with unforgeable colored window borders so different security levels are easily identifiable.
    • -
-
-
-

Qubes OS Overview Example

- -
-
- - - -

Features

- -
-
-

Strong isolation

-

Isolate software as if they were installed on separate physical machines using PV or HVM virtualization techniques

-
-
-

Template system

-

Allow qubes called AppVMs to share a root file system without sacrificing security using the innovative Template system

-
-
-

Multiple operating systems

-

Use multiple operating systems at the same time, including Fedora, Debian, or Windows

-
-
- -
-
-
-

Disposable VMs

-

Create disposable VMs which are spawned quickly and destroyed when closed

-
-
-

Whonix integration

-

Run Tor securely system-wide using Whonix with Qubes

-
-
-

Controller isolation

-

Secure device handling through isolation of network cards and USB controllers

-
-
- -
-
-
-

Split GPG

-

Utilize Split GPG to store private GPG keys in an AppVM

-
-
-

U2F proxy

-

Operate Qubes U2F proxy to use two-factor authentication

-
-
-

Open-source

-

Users are free to use, copy and modify Qubes OS and are encouraged to do so!

-
-
- - - - -Why Qubes OS ? --------------- - -

Physical isolation is a given safeguard that the digital world lacks

- -
-
-

Throughout their lives, individuals engage in various activities such as going to school, working, voting, taking care of their families or visiting with friends.

-

These activities are spatially and temporally bound : they happen in isolation of one another, in their own compartments, which often represent an essential safeguard, such as in the case of voting.

-

In one's digital life, the situation is quite different : each activity, often intertwined with its real-life counterpart, tends to happen on a single computing device.

-
-
- -
-
- -

Qubes OS compartmentalizes one's digital life

- -
-
- -
-
-

Surprisingly, personal computing devices are not designed to offer means to enforce the same kind of isolation that people enjoy in the physical world.

-

What if there were an operating system that provided a kind of digital compartmentalization almost as strong as physical isolation?

-

Qubes OS allows users to compartmentalize various parts of their digital lives into well-isolated compartments.

-
-
- -

Made to support vulnerable users

- -
-
-

Thanks to Qubes OS, vulnerable or actively targeted individuals such as journalists, political activists, whistleblowers or researchers can enjoy the same benefits of using multiple computing devices at a fraction of the cost and without the associated loss of usability.

-

It allows users to do everything on the same physical computer without having to worry about a single successful cyberattack taking down their entire digital life in one fell swoop.

-

Computing should remain an activity where mistakes can be made and where users can explore the web freely, downloading attachments and clicking on links without having to constantly evaluate a myriad of risk factors.

-

Qubes OS strives to bring back this experience. It creates a place where users can feel safe.

-
-
- -

snapshot12.png

- -
-
-
-

Video Tours

-

Want to see Qubes OS in action? Sit back and watch a guided tour!

- - Video Tours - -
-
-

Screenshots

-

See what using Qubes actually looks like with these screenshots of various applications running in Qubes.

- - Screenshots - -
-
-

Getting Started

-

Ready to get started with Qubes? Here's what you need to know after installing.

- - Getting Started - -
-
- More information ---------------- @@ -173,24 +26,7 @@ technical details have been omitted here for the sake of presentation. * Ready to give Qubes a try? Head on over to the [downloads] page or the [installation guide]. -[disposable qube]: /doc/disposablevm/ -[networking]: /doc/networking/ -[firewalls]: /doc/firewall/ -[USB]: /doc/usb/ -[file]: /doc/copying-files/ -[clipboard]: /doc/copy-paste/ -[Template]: /doc/templates/ -[Qubes-Whonix]: /doc/whonix/ -[Whonix]: https://www.whonix.org/ -[Tor]: https://www.torproject.org/ -[Anti Evil Maid]: /doc/anti-evil-maid/ -[Tails]: https://tails.boum.org/ -[Xen]: https://www.xenproject.org -[paper-compart]: https://invisiblethingslab.com/resources/2014/Software_compartmentalization_vs_physical_separation.pdf [doc]: /doc/ [user-faq]: /faq/#users [system-doc]: /doc/system-doc/ [devel-faq]: /faq/#developers -[downloads]: /downloads/ -[getting started]: /getting-started/ -[installation guide]: /doc/installation-guide/ From 9d6fb4d685b96dc00a452647a85ffe748ced439a Mon Sep 17 00:00:00 2001 From: dd Date: Sun, 4 Oct 2020 02:08:27 +0200 Subject: [PATCH 029/663] extracted html from experts.md, new include, changed layout, tx_config, new _data file --- introduction/experts.md | 40 ---------------------------------------- 1 file changed, 40 deletions(-) diff --git a/introduction/experts.md b/introduction/experts.md index 805915ec85..237f269bf1 100644 --- a/introduction/experts.md +++ b/introduction/experts.md @@ -6,43 +6,3 @@ ref: 119 title: Experts --- -{% if page.lang == nil or page.lang == "en" %} - {% assign experts = site.data.experts %} -{% else %} - {% assign experts = site.data.translation[page.lang].experts %} - {% if experts == nil or experts.size == 0 %} - {% assign experts = site.data.experts %} - {% endif %} -{% endif %} -{% assign experts = experts | where_exp: "item", "item.experts == nil" | first %} - -
-
-
-

{{ experts.title }}

-
-
-
- -{% for item in experts.expert %} - -
-
- - - -
-
- -
"{{ item.quote }}" - -
{{ item.name }}, {{ item.occupation }}
-
- -
-
- -{% endfor %} -
- {% include footer.html %} -
From ae9a0de332c95dfffc75b3f6b1bae94bb1f570cd Mon Sep 17 00:00:00 2001 From: dd Date: Sun, 18 Oct 2020 17:35:37 +0200 Subject: [PATCH 030/663] reverse doc dir renaming --- .../building/development-workflow.md | 0 .../building/qubes-builder-details.md | 0 {developer-documentation => developer}/building/qubes-builder.md | 0 .../building/qubes-iso-building.md | 0 {developer-documentation => developer}/code/code-signing.md | 0 {developer-documentation => developer}/code/coding-style.md | 0 {developer-documentation => developer}/code/license.md | 0 {developer-documentation => developer}/code/source-code.md | 0 .../debugging/automated-tests.md | 0 .../debugging/mount-lvm-image.md | 0 {developer-documentation => developer}/debugging/profiling.md | 0 .../debugging/safe-remote-ttys.md | 0 {developer-documentation => developer}/debugging/test-bench.md | 0 {developer-documentation => developer}/debugging/vm-interface.md | 0 .../debugging/windows-debugging.md | 0 {developer-documentation => developer}/general/devel-books.md | 0 {developer-documentation => developer}/general/doc-guidelines.md | 0 {developer-documentation => developer}/general/gsoc.md | 0 {developer-documentation => developer}/general/gsod.md | 0 {developer-documentation => developer}/general/join.md | 0 .../general/package-contributions.md | 0 {developer-documentation => developer}/general/style-guide.md | 0 {developer-documentation => developer}/general/usability-ux.md | 0 .../releases/1_0/release-notes.md | 0 .../releases/2_0/release-notes.md | 0 .../releases/3_0/release-notes.md | 0 {developer-documentation => developer}/releases/3_0/schedule.md | 0 .../releases/3_1/release-notes.md | 0 {developer-documentation => developer}/releases/3_1/schedule.md | 0 .../releases/3_2/release-notes.md | 0 {developer-documentation => developer}/releases/3_2/schedule.md | 0 .../releases/4_0/release-notes.md | 0 {developer-documentation => developer}/releases/4_0/schedule.md | 0 {developer-documentation => developer}/releases/notes.md | 0 {developer-documentation => developer}/releases/schedules.md | 0 {developer-documentation => developer}/releases/todo.md | 0 {developer-documentation => developer}/services/admin-api.md | 0 .../services/dom0-secure-updates.md | 0 {developer-documentation => developer}/services/dvm-impl.md | 0 {developer-documentation => developer}/services/qfilecopy.md | 0 {developer-documentation => developer}/services/qfileexchgd.md | 0 {developer-documentation => developer}/services/qmemman.md | 0 .../services/qrexec-internals.md | 0 .../services/qrexec-socket-services.md | 0 {developer-documentation => developer}/services/qrexec.md | 0 {developer-documentation => developer}/services/qrexec2.md | 0 {developer-documentation => developer}/system/architecture.md | 0 {developer-documentation => developer}/system/audio.md | 0 {developer-documentation => developer}/system/gui.md | 0 {developer-documentation => developer}/system/networking.md | 0 .../system/security-critical-code.md | 0 {developer-documentation => developer}/system/storage-pools.md | 0 {developer-documentation => developer}/system/system-doc.md | 0 .../system/template-implementation.md | 0 .../building-guides/building-archlinux-template.md | 0 .../building-guides/building-non-fedora-template.md | 0 .../building-guides/building-whonix-template.md | 0 .../configuration-guides/change-time-zone.md | 0 .../configuration-guides/disk-trim.md | 0 .../configuration-guides/external-audio.md | 0 .../configuration-guides/fetchmail.md | 0 .../configuration-guides/multiboot.md | 0 .../configuration-guides/multimedia.md | 0 {external-documentation => external}/configuration-guides/mutt.md | 0 .../configuration-guides/network-bridge-support.md | 0 .../configuration-guides/network-printer.md | 0 .../configuration-guides/postfix.md | 0 {external-documentation => external}/configuration-guides/rxvt.md | 0 .../configuration-guides/tips-and-tricks.md | 0 {external-documentation => external}/configuration-guides/vpn.md | 0 {external-documentation => external}/configuration-guides/w3m.md | 0 {external-documentation => external}/configuration-guides/zfs.md | 0 .../customization-guides/dark-theme.md | 0 .../customization-guides/fedora-minimal-template-customization.md | 0 .../customization-guides/language-localization.md | 0 .../customization-guides/removing-templatevm-packages.md | 0 .../customization-guides/windows-template-customization.md | 0 {external-documentation => external}/os-guides/centos.md | 0 {external-documentation => external}/os-guides/linux-hvm-tips.md | 0 {external-documentation => external}/os-guides/netbsd.md | 0 {external-documentation => external}/os-guides/pentesting.md | 0 .../os-guides/pentesting/blackarch.md | 0 {external-documentation => external}/os-guides/pentesting/kali.md | 0 {external-documentation => external}/os-guides/pentesting/ptf.md | 0 {external-documentation => external}/os-guides/ubuntu.md | 0 .../os-guides/windows/windows-tools.md | 0 .../os-guides/windows/windows-vm.md | 0 .../privacy-guides/anonymizing-your-mac-address.md | 0 {external-documentation => external}/privacy-guides/signal.md | 0 {external-documentation => external}/privacy-guides/tails.md | 0 {external-documentation => external}/privacy-guides/torvm.md | 0 {external-documentation => external}/privacy-guides/whonix.md | 0 .../security-guides/multifactor-authentication.md | 0 .../security-guides/security-guidelines.md | 0 .../security-guides/split-bitcoin.md | 0 .../troubleshooting/install-nvidia-driver.md | 0 .../troubleshooting/intel-igfx-troubleshooting.md | 0 .../troubleshooting/macbook-troubleshooting.md | 0 .../troubleshooting/nvidia-troubleshooting.md | 0 .../troubleshooting/out-of-memory.md | 0 .../troubleshooting/remove-vm-manually.md | 0 .../troubleshooting/sony-vaio-tinkering.md | 0 .../troubleshooting/thinkpad-troubleshooting.md | 0 .../troubleshooting/updating-debian-and-whonix.md | 0 .../troubleshooting/wireless-troubleshooting.md | 0 {user-documentation => user}/advanced-configuration/awesome.md | 0 {user-documentation => user}/advanced-configuration/bind-dirs.md | 0 .../advanced-configuration/config-files.md | 0 .../advanced-configuration/disposablevm-customization.md | 0 .../advanced-configuration/gui-configuration.md | 0 {user-documentation => user}/advanced-configuration/i3.md | 0 {user-documentation => user}/advanced-configuration/kde.md | 0 .../advanced-configuration/managing-vm-kernel.md | 0 .../advanced-configuration/mount-from-other-os.md | 0 .../advanced-configuration/newer-hardware-troubleshooting.md | 0 .../advanced-configuration/resize-disk-image.md | 0 {user-documentation => user}/advanced-configuration/rpc-policy.md | 0 {user-documentation => user}/advanced-configuration/salt.md | 0 .../advanced-configuration/secondary-storage.md | 0 .../advanced-configuration/uefi-troubleshooting.md | 0 {user-documentation => user}/advanced-configuration/usb-qubes.md | 0 .../common-tasks/backup-emergency-restore-v2.md | 0 .../common-tasks/backup-emergency-restore-v3.md | 0 .../common-tasks/backup-emergency-restore-v4.md | 0 {user-documentation => user}/common-tasks/backup-restore.md | 0 {user-documentation => user}/common-tasks/block-devices.md | 0 {user-documentation => user}/common-tasks/copy-from-dom0.md | 0 {user-documentation => user}/common-tasks/copy-paste.md | 0 {user-documentation => user}/common-tasks/copying-files.md | 0 {user-documentation => user}/common-tasks/device-handling.md | 0 {user-documentation => user}/common-tasks/disposablevm.md | 0 {user-documentation => user}/common-tasks/full-screen-mode.md | 0 {user-documentation => user}/common-tasks/getting-started.md | 0 .../common-tasks/managing-appvm-shortcuts.md | 0 {user-documentation => user}/common-tasks/optical-discs.md | 0 {user-documentation => user}/common-tasks/pci-devices.md | 0 {user-documentation => user}/common-tasks/software-update-dom0.md | 0 {user-documentation => user}/common-tasks/software-update-domu.md | 0 {user-documentation => user}/common-tasks/updating-qubes-os.md | 0 {user-documentation => user}/common-tasks/usb-devices.md | 0 {user-documentation => user}/common-tasks/volume-backup-revert.md | 0 .../downloading-installing-upgrading/custom-install.md | 0 .../downloading-installing-upgrading/download-mirrors.md | 0 .../downloading-installing-upgrading/install-security.md | 0 .../downloading-installing-upgrading/installation-guide.md | 0 .../downloading-installing-upgrading/live-usb.md | 0 .../downloading-installing-upgrading/supported-versions.md | 0 .../downloading-installing-upgrading/testing.md | 0 .../downloading-installing-upgrading/upgrade/upgrade-to-r2.md | 0 .../downloading-installing-upgrading/upgrade/upgrade-to-r2b1.md | 0 .../downloading-installing-upgrading/upgrade/upgrade-to-r2b2.md | 0 .../downloading-installing-upgrading/upgrade/upgrade-to-r2b3.md | 0 .../downloading-installing-upgrading/upgrade/upgrade-to-r3_0.md | 0 .../downloading-installing-upgrading/upgrade/upgrade-to-r3_1.md | 0 .../downloading-installing-upgrading/upgrade/upgrade-to-r3_2.md | 0 .../downloading-installing-upgrading/upgrade/upgrade-to-r4_0.md | 0 .../downloading-installing-upgrading/upgrade/upgrade.md | 0 .../downloading-installing-upgrading/version-scheme.md | 0 {user-documentation => user}/hardware/certified-hardware.md | 0 {user-documentation => user}/hardware/hardware-testing.md | 0 {user-documentation => user}/hardware/hcl_listing.md | 0 {user-documentation => user}/hardware/hcl_md.md | 0 {user-documentation => user}/hardware/system-requirements.md | 0 {user-documentation => user}/managing-os/debian/debian-upgrade.md | 0 {user-documentation => user}/managing-os/debian/debian.md | 0 {user-documentation => user}/managing-os/fedora/fedora-upgrade.md | 0 {user-documentation => user}/managing-os/fedora/fedora-xfce.md | 0 {user-documentation => user}/managing-os/fedora/fedora.md | 0 {user-documentation => user}/managing-os/minimal-templates.md | 0 {user-documentation => user}/managing-os/reinstall-template.md | 0 {user-documentation => user}/managing-os/standalone-and-hvm.md | 0 {user-documentation => user}/managing-os/templates.md | 0 {user-documentation => user}/managing-os/windows.md | 0 {user-documentation => user}/reference/glossary.md | 0 {user-documentation => user}/reference/qubes-service.md | 0 {user-documentation => user}/reference/research.md | 0 {user-documentation => user}/reference/tools.md | 0 {user-documentation => user}/security-in-qubes/anti-evil-maid.md | 0 {user-documentation => user}/security-in-qubes/data-leaks.md | 0 .../security-in-qubes/device-handling-security.md | 0 {user-documentation => user}/security-in-qubes/firewall.md | 0 {user-documentation => user}/security-in-qubes/split-gpg.md | 0 {user-documentation => user}/security-in-qubes/u2f-proxy.md | 0 {user-documentation => user}/security-in-qubes/vm-sudo.md | 0 {user-documentation => user}/security-in-qubes/yubi-key.md | 0 185 files changed, 0 insertions(+), 0 deletions(-) rename {developer-documentation => developer}/building/development-workflow.md (100%) rename {developer-documentation => developer}/building/qubes-builder-details.md (100%) rename {developer-documentation => developer}/building/qubes-builder.md (100%) rename {developer-documentation => developer}/building/qubes-iso-building.md (100%) rename {developer-documentation => developer}/code/code-signing.md (100%) rename {developer-documentation => developer}/code/coding-style.md (100%) rename {developer-documentation => developer}/code/license.md (100%) rename {developer-documentation => developer}/code/source-code.md (100%) rename {developer-documentation => developer}/debugging/automated-tests.md (100%) rename {developer-documentation => developer}/debugging/mount-lvm-image.md (100%) rename {developer-documentation => developer}/debugging/profiling.md (100%) rename {developer-documentation => developer}/debugging/safe-remote-ttys.md (100%) rename {developer-documentation => developer}/debugging/test-bench.md (100%) rename {developer-documentation => developer}/debugging/vm-interface.md (100%) rename {developer-documentation => developer}/debugging/windows-debugging.md (100%) rename {developer-documentation => developer}/general/devel-books.md (100%) rename {developer-documentation => developer}/general/doc-guidelines.md (100%) rename {developer-documentation => developer}/general/gsoc.md (100%) rename {developer-documentation => developer}/general/gsod.md (100%) rename {developer-documentation => developer}/general/join.md (100%) rename {developer-documentation => developer}/general/package-contributions.md (100%) rename {developer-documentation => developer}/general/style-guide.md (100%) rename {developer-documentation => developer}/general/usability-ux.md (100%) rename {developer-documentation => developer}/releases/1_0/release-notes.md (100%) rename {developer-documentation => developer}/releases/2_0/release-notes.md (100%) rename {developer-documentation => developer}/releases/3_0/release-notes.md (100%) rename {developer-documentation => developer}/releases/3_0/schedule.md (100%) rename {developer-documentation => developer}/releases/3_1/release-notes.md (100%) rename {developer-documentation => developer}/releases/3_1/schedule.md (100%) rename {developer-documentation => developer}/releases/3_2/release-notes.md (100%) rename {developer-documentation => developer}/releases/3_2/schedule.md (100%) rename {developer-documentation => developer}/releases/4_0/release-notes.md (100%) rename {developer-documentation => developer}/releases/4_0/schedule.md (100%) rename {developer-documentation => developer}/releases/notes.md (100%) rename {developer-documentation => developer}/releases/schedules.md (100%) rename {developer-documentation => developer}/releases/todo.md (100%) rename {developer-documentation => developer}/services/admin-api.md (100%) rename {developer-documentation => developer}/services/dom0-secure-updates.md (100%) rename {developer-documentation => developer}/services/dvm-impl.md (100%) rename {developer-documentation => developer}/services/qfilecopy.md (100%) rename {developer-documentation => developer}/services/qfileexchgd.md (100%) rename {developer-documentation => developer}/services/qmemman.md (100%) rename {developer-documentation => developer}/services/qrexec-internals.md (100%) rename {developer-documentation => developer}/services/qrexec-socket-services.md (100%) rename {developer-documentation => developer}/services/qrexec.md (100%) rename {developer-documentation => developer}/services/qrexec2.md (100%) rename {developer-documentation => developer}/system/architecture.md (100%) rename {developer-documentation => developer}/system/audio.md (100%) rename {developer-documentation => developer}/system/gui.md (100%) rename {developer-documentation => developer}/system/networking.md (100%) rename {developer-documentation => developer}/system/security-critical-code.md (100%) rename {developer-documentation => developer}/system/storage-pools.md (100%) rename {developer-documentation => developer}/system/system-doc.md (100%) rename {developer-documentation => developer}/system/template-implementation.md (100%) rename {external-documentation => external}/building-guides/building-archlinux-template.md (100%) rename {external-documentation => external}/building-guides/building-non-fedora-template.md (100%) rename {external-documentation => external}/building-guides/building-whonix-template.md (100%) rename {external-documentation => external}/configuration-guides/change-time-zone.md (100%) rename {external-documentation => external}/configuration-guides/disk-trim.md (100%) rename {external-documentation => external}/configuration-guides/external-audio.md (100%) rename {external-documentation => external}/configuration-guides/fetchmail.md (100%) rename {external-documentation => external}/configuration-guides/multiboot.md (100%) rename {external-documentation => external}/configuration-guides/multimedia.md (100%) rename {external-documentation => external}/configuration-guides/mutt.md (100%) rename {external-documentation => external}/configuration-guides/network-bridge-support.md (100%) rename {external-documentation => external}/configuration-guides/network-printer.md (100%) rename {external-documentation => external}/configuration-guides/postfix.md (100%) rename {external-documentation => external}/configuration-guides/rxvt.md (100%) rename {external-documentation => external}/configuration-guides/tips-and-tricks.md (100%) rename {external-documentation => external}/configuration-guides/vpn.md (100%) rename {external-documentation => external}/configuration-guides/w3m.md (100%) rename {external-documentation => external}/configuration-guides/zfs.md (100%) rename {external-documentation => external}/customization-guides/dark-theme.md (100%) rename {external-documentation => external}/customization-guides/fedora-minimal-template-customization.md (100%) rename {external-documentation => external}/customization-guides/language-localization.md (100%) rename {external-documentation => external}/customization-guides/removing-templatevm-packages.md (100%) rename {external-documentation => external}/customization-guides/windows-template-customization.md (100%) rename {external-documentation => external}/os-guides/centos.md (100%) rename {external-documentation => external}/os-guides/linux-hvm-tips.md (100%) rename {external-documentation => external}/os-guides/netbsd.md (100%) rename {external-documentation => external}/os-guides/pentesting.md (100%) rename {external-documentation => external}/os-guides/pentesting/blackarch.md (100%) rename {external-documentation => external}/os-guides/pentesting/kali.md (100%) rename {external-documentation => external}/os-guides/pentesting/ptf.md (100%) rename {external-documentation => external}/os-guides/ubuntu.md (100%) rename {external-documentation => external}/os-guides/windows/windows-tools.md (100%) rename {external-documentation => external}/os-guides/windows/windows-vm.md (100%) rename {external-documentation => external}/privacy-guides/anonymizing-your-mac-address.md (100%) rename {external-documentation => external}/privacy-guides/signal.md (100%) rename {external-documentation => external}/privacy-guides/tails.md (100%) rename {external-documentation => external}/privacy-guides/torvm.md (100%) rename {external-documentation => external}/privacy-guides/whonix.md (100%) rename {external-documentation => external}/security-guides/multifactor-authentication.md (100%) rename {external-documentation => external}/security-guides/security-guidelines.md (100%) rename {external-documentation => external}/security-guides/split-bitcoin.md (100%) rename {external-documentation => external}/troubleshooting/install-nvidia-driver.md (100%) rename {external-documentation => external}/troubleshooting/intel-igfx-troubleshooting.md (100%) rename {external-documentation => external}/troubleshooting/macbook-troubleshooting.md (100%) rename {external-documentation => external}/troubleshooting/nvidia-troubleshooting.md (100%) rename {external-documentation => external}/troubleshooting/out-of-memory.md (100%) rename {external-documentation => external}/troubleshooting/remove-vm-manually.md (100%) rename {external-documentation => external}/troubleshooting/sony-vaio-tinkering.md (100%) rename {external-documentation => external}/troubleshooting/thinkpad-troubleshooting.md (100%) rename {external-documentation => external}/troubleshooting/updating-debian-and-whonix.md (100%) rename {external-documentation => external}/troubleshooting/wireless-troubleshooting.md (100%) rename {user-documentation => user}/advanced-configuration/awesome.md (100%) rename {user-documentation => user}/advanced-configuration/bind-dirs.md (100%) rename {user-documentation => user}/advanced-configuration/config-files.md (100%) rename {user-documentation => user}/advanced-configuration/disposablevm-customization.md (100%) rename {user-documentation => user}/advanced-configuration/gui-configuration.md (100%) rename {user-documentation => user}/advanced-configuration/i3.md (100%) rename {user-documentation => user}/advanced-configuration/kde.md (100%) rename {user-documentation => user}/advanced-configuration/managing-vm-kernel.md (100%) rename {user-documentation => user}/advanced-configuration/mount-from-other-os.md (100%) rename {user-documentation => user}/advanced-configuration/newer-hardware-troubleshooting.md (100%) rename {user-documentation => user}/advanced-configuration/resize-disk-image.md (100%) rename {user-documentation => user}/advanced-configuration/rpc-policy.md (100%) rename {user-documentation => user}/advanced-configuration/salt.md (100%) rename {user-documentation => user}/advanced-configuration/secondary-storage.md (100%) rename {user-documentation => user}/advanced-configuration/uefi-troubleshooting.md (100%) rename {user-documentation => user}/advanced-configuration/usb-qubes.md (100%) rename {user-documentation => user}/common-tasks/backup-emergency-restore-v2.md (100%) rename {user-documentation => user}/common-tasks/backup-emergency-restore-v3.md (100%) rename {user-documentation => user}/common-tasks/backup-emergency-restore-v4.md (100%) rename {user-documentation => user}/common-tasks/backup-restore.md (100%) rename {user-documentation => user}/common-tasks/block-devices.md (100%) rename {user-documentation => user}/common-tasks/copy-from-dom0.md (100%) rename {user-documentation => user}/common-tasks/copy-paste.md (100%) rename {user-documentation => user}/common-tasks/copying-files.md (100%) rename {user-documentation => user}/common-tasks/device-handling.md (100%) rename {user-documentation => user}/common-tasks/disposablevm.md (100%) rename {user-documentation => user}/common-tasks/full-screen-mode.md (100%) rename {user-documentation => user}/common-tasks/getting-started.md (100%) rename {user-documentation => user}/common-tasks/managing-appvm-shortcuts.md (100%) rename {user-documentation => user}/common-tasks/optical-discs.md (100%) rename {user-documentation => user}/common-tasks/pci-devices.md (100%) rename {user-documentation => user}/common-tasks/software-update-dom0.md (100%) rename {user-documentation => user}/common-tasks/software-update-domu.md (100%) rename {user-documentation => user}/common-tasks/updating-qubes-os.md (100%) rename {user-documentation => user}/common-tasks/usb-devices.md (100%) rename {user-documentation => user}/common-tasks/volume-backup-revert.md (100%) rename {user-documentation => user}/downloading-installing-upgrading/custom-install.md (100%) rename {user-documentation => user}/downloading-installing-upgrading/download-mirrors.md (100%) rename {user-documentation => user}/downloading-installing-upgrading/install-security.md (100%) rename {user-documentation => user}/downloading-installing-upgrading/installation-guide.md (100%) rename {user-documentation => user}/downloading-installing-upgrading/live-usb.md (100%) rename {user-documentation => user}/downloading-installing-upgrading/supported-versions.md (100%) rename {user-documentation => user}/downloading-installing-upgrading/testing.md (100%) rename {user-documentation => user}/downloading-installing-upgrading/upgrade/upgrade-to-r2.md (100%) rename {user-documentation => user}/downloading-installing-upgrading/upgrade/upgrade-to-r2b1.md (100%) rename {user-documentation => user}/downloading-installing-upgrading/upgrade/upgrade-to-r2b2.md (100%) rename {user-documentation => user}/downloading-installing-upgrading/upgrade/upgrade-to-r2b3.md (100%) rename {user-documentation => user}/downloading-installing-upgrading/upgrade/upgrade-to-r3_0.md (100%) rename {user-documentation => user}/downloading-installing-upgrading/upgrade/upgrade-to-r3_1.md (100%) rename {user-documentation => user}/downloading-installing-upgrading/upgrade/upgrade-to-r3_2.md (100%) rename {user-documentation => user}/downloading-installing-upgrading/upgrade/upgrade-to-r4_0.md (100%) rename {user-documentation => user}/downloading-installing-upgrading/upgrade/upgrade.md (100%) rename {user-documentation => user}/downloading-installing-upgrading/version-scheme.md (100%) rename {user-documentation => user}/hardware/certified-hardware.md (100%) rename {user-documentation => user}/hardware/hardware-testing.md (100%) rename {user-documentation => user}/hardware/hcl_listing.md (100%) rename {user-documentation => user}/hardware/hcl_md.md (100%) rename {user-documentation => user}/hardware/system-requirements.md (100%) rename {user-documentation => user}/managing-os/debian/debian-upgrade.md (100%) rename {user-documentation => user}/managing-os/debian/debian.md (100%) rename {user-documentation => user}/managing-os/fedora/fedora-upgrade.md (100%) rename {user-documentation => user}/managing-os/fedora/fedora-xfce.md (100%) rename {user-documentation => user}/managing-os/fedora/fedora.md (100%) rename {user-documentation => user}/managing-os/minimal-templates.md (100%) rename {user-documentation => user}/managing-os/reinstall-template.md (100%) rename {user-documentation => user}/managing-os/standalone-and-hvm.md (100%) rename {user-documentation => user}/managing-os/templates.md (100%) rename {user-documentation => user}/managing-os/windows.md (100%) rename {user-documentation => user}/reference/glossary.md (100%) rename {user-documentation => user}/reference/qubes-service.md (100%) rename {user-documentation => user}/reference/research.md (100%) rename {user-documentation => user}/reference/tools.md (100%) rename {user-documentation => user}/security-in-qubes/anti-evil-maid.md (100%) rename {user-documentation => user}/security-in-qubes/data-leaks.md (100%) rename {user-documentation => user}/security-in-qubes/device-handling-security.md (100%) rename {user-documentation => user}/security-in-qubes/firewall.md (100%) rename {user-documentation => user}/security-in-qubes/split-gpg.md (100%) rename {user-documentation => user}/security-in-qubes/u2f-proxy.md (100%) rename {user-documentation => user}/security-in-qubes/vm-sudo.md (100%) rename {user-documentation => user}/security-in-qubes/yubi-key.md (100%) diff --git a/developer-documentation/building/development-workflow.md b/developer/building/development-workflow.md similarity index 100% rename from developer-documentation/building/development-workflow.md rename to developer/building/development-workflow.md diff --git a/developer-documentation/building/qubes-builder-details.md b/developer/building/qubes-builder-details.md similarity index 100% rename from developer-documentation/building/qubes-builder-details.md rename to developer/building/qubes-builder-details.md diff --git a/developer-documentation/building/qubes-builder.md b/developer/building/qubes-builder.md similarity index 100% rename from developer-documentation/building/qubes-builder.md rename to developer/building/qubes-builder.md diff --git a/developer-documentation/building/qubes-iso-building.md b/developer/building/qubes-iso-building.md similarity index 100% rename from developer-documentation/building/qubes-iso-building.md rename to developer/building/qubes-iso-building.md diff --git a/developer-documentation/code/code-signing.md b/developer/code/code-signing.md similarity index 100% rename from developer-documentation/code/code-signing.md rename to developer/code/code-signing.md diff --git a/developer-documentation/code/coding-style.md b/developer/code/coding-style.md similarity index 100% rename from developer-documentation/code/coding-style.md rename to developer/code/coding-style.md diff --git a/developer-documentation/code/license.md b/developer/code/license.md similarity index 100% rename from developer-documentation/code/license.md rename to developer/code/license.md diff --git a/developer-documentation/code/source-code.md b/developer/code/source-code.md similarity index 100% rename from developer-documentation/code/source-code.md rename to developer/code/source-code.md diff --git a/developer-documentation/debugging/automated-tests.md b/developer/debugging/automated-tests.md similarity index 100% rename from developer-documentation/debugging/automated-tests.md rename to developer/debugging/automated-tests.md diff --git a/developer-documentation/debugging/mount-lvm-image.md b/developer/debugging/mount-lvm-image.md similarity index 100% rename from developer-documentation/debugging/mount-lvm-image.md rename to developer/debugging/mount-lvm-image.md diff --git a/developer-documentation/debugging/profiling.md b/developer/debugging/profiling.md similarity index 100% rename from developer-documentation/debugging/profiling.md rename to developer/debugging/profiling.md diff --git a/developer-documentation/debugging/safe-remote-ttys.md b/developer/debugging/safe-remote-ttys.md similarity index 100% rename from developer-documentation/debugging/safe-remote-ttys.md rename to developer/debugging/safe-remote-ttys.md diff --git a/developer-documentation/debugging/test-bench.md b/developer/debugging/test-bench.md similarity index 100% rename from developer-documentation/debugging/test-bench.md rename to developer/debugging/test-bench.md diff --git a/developer-documentation/debugging/vm-interface.md b/developer/debugging/vm-interface.md similarity index 100% rename from developer-documentation/debugging/vm-interface.md rename to developer/debugging/vm-interface.md diff --git a/developer-documentation/debugging/windows-debugging.md b/developer/debugging/windows-debugging.md similarity index 100% rename from developer-documentation/debugging/windows-debugging.md rename to developer/debugging/windows-debugging.md diff --git a/developer-documentation/general/devel-books.md b/developer/general/devel-books.md similarity index 100% rename from developer-documentation/general/devel-books.md rename to developer/general/devel-books.md diff --git a/developer-documentation/general/doc-guidelines.md b/developer/general/doc-guidelines.md similarity index 100% rename from developer-documentation/general/doc-guidelines.md rename to developer/general/doc-guidelines.md diff --git a/developer-documentation/general/gsoc.md b/developer/general/gsoc.md similarity index 100% rename from developer-documentation/general/gsoc.md rename to developer/general/gsoc.md diff --git a/developer-documentation/general/gsod.md b/developer/general/gsod.md similarity index 100% rename from developer-documentation/general/gsod.md rename to developer/general/gsod.md diff --git a/developer-documentation/general/join.md b/developer/general/join.md similarity index 100% rename from developer-documentation/general/join.md rename to developer/general/join.md diff --git a/developer-documentation/general/package-contributions.md b/developer/general/package-contributions.md similarity index 100% rename from developer-documentation/general/package-contributions.md rename to developer/general/package-contributions.md diff --git a/developer-documentation/general/style-guide.md b/developer/general/style-guide.md similarity index 100% rename from developer-documentation/general/style-guide.md rename to developer/general/style-guide.md diff --git a/developer-documentation/general/usability-ux.md b/developer/general/usability-ux.md similarity index 100% rename from developer-documentation/general/usability-ux.md rename to developer/general/usability-ux.md diff --git a/developer-documentation/releases/1_0/release-notes.md b/developer/releases/1_0/release-notes.md similarity index 100% rename from developer-documentation/releases/1_0/release-notes.md rename to developer/releases/1_0/release-notes.md diff --git a/developer-documentation/releases/2_0/release-notes.md b/developer/releases/2_0/release-notes.md similarity index 100% rename from developer-documentation/releases/2_0/release-notes.md rename to developer/releases/2_0/release-notes.md diff --git a/developer-documentation/releases/3_0/release-notes.md b/developer/releases/3_0/release-notes.md similarity index 100% rename from developer-documentation/releases/3_0/release-notes.md rename to developer/releases/3_0/release-notes.md diff --git a/developer-documentation/releases/3_0/schedule.md b/developer/releases/3_0/schedule.md similarity index 100% rename from developer-documentation/releases/3_0/schedule.md rename to developer/releases/3_0/schedule.md diff --git a/developer-documentation/releases/3_1/release-notes.md b/developer/releases/3_1/release-notes.md similarity index 100% rename from developer-documentation/releases/3_1/release-notes.md rename to developer/releases/3_1/release-notes.md diff --git a/developer-documentation/releases/3_1/schedule.md b/developer/releases/3_1/schedule.md similarity index 100% rename from developer-documentation/releases/3_1/schedule.md rename to developer/releases/3_1/schedule.md diff --git a/developer-documentation/releases/3_2/release-notes.md b/developer/releases/3_2/release-notes.md similarity index 100% rename from developer-documentation/releases/3_2/release-notes.md rename to developer/releases/3_2/release-notes.md diff --git a/developer-documentation/releases/3_2/schedule.md b/developer/releases/3_2/schedule.md similarity index 100% rename from developer-documentation/releases/3_2/schedule.md rename to developer/releases/3_2/schedule.md diff --git a/developer-documentation/releases/4_0/release-notes.md b/developer/releases/4_0/release-notes.md similarity index 100% rename from developer-documentation/releases/4_0/release-notes.md rename to developer/releases/4_0/release-notes.md diff --git a/developer-documentation/releases/4_0/schedule.md b/developer/releases/4_0/schedule.md similarity index 100% rename from developer-documentation/releases/4_0/schedule.md rename to developer/releases/4_0/schedule.md diff --git a/developer-documentation/releases/notes.md b/developer/releases/notes.md similarity index 100% rename from developer-documentation/releases/notes.md rename to developer/releases/notes.md diff --git a/developer-documentation/releases/schedules.md b/developer/releases/schedules.md similarity index 100% rename from developer-documentation/releases/schedules.md rename to developer/releases/schedules.md diff --git a/developer-documentation/releases/todo.md b/developer/releases/todo.md similarity index 100% rename from developer-documentation/releases/todo.md rename to developer/releases/todo.md diff --git a/developer-documentation/services/admin-api.md b/developer/services/admin-api.md similarity index 100% rename from developer-documentation/services/admin-api.md rename to developer/services/admin-api.md diff --git a/developer-documentation/services/dom0-secure-updates.md b/developer/services/dom0-secure-updates.md similarity index 100% rename from developer-documentation/services/dom0-secure-updates.md rename to developer/services/dom0-secure-updates.md diff --git a/developer-documentation/services/dvm-impl.md b/developer/services/dvm-impl.md similarity index 100% rename from developer-documentation/services/dvm-impl.md rename to developer/services/dvm-impl.md diff --git a/developer-documentation/services/qfilecopy.md b/developer/services/qfilecopy.md similarity index 100% rename from developer-documentation/services/qfilecopy.md rename to developer/services/qfilecopy.md diff --git a/developer-documentation/services/qfileexchgd.md b/developer/services/qfileexchgd.md similarity index 100% rename from developer-documentation/services/qfileexchgd.md rename to developer/services/qfileexchgd.md diff --git a/developer-documentation/services/qmemman.md b/developer/services/qmemman.md similarity index 100% rename from developer-documentation/services/qmemman.md rename to developer/services/qmemman.md diff --git a/developer-documentation/services/qrexec-internals.md b/developer/services/qrexec-internals.md similarity index 100% rename from developer-documentation/services/qrexec-internals.md rename to developer/services/qrexec-internals.md diff --git a/developer-documentation/services/qrexec-socket-services.md b/developer/services/qrexec-socket-services.md similarity index 100% rename from developer-documentation/services/qrexec-socket-services.md rename to developer/services/qrexec-socket-services.md diff --git a/developer-documentation/services/qrexec.md b/developer/services/qrexec.md similarity index 100% rename from developer-documentation/services/qrexec.md rename to developer/services/qrexec.md diff --git a/developer-documentation/services/qrexec2.md b/developer/services/qrexec2.md similarity index 100% rename from developer-documentation/services/qrexec2.md rename to developer/services/qrexec2.md diff --git a/developer-documentation/system/architecture.md b/developer/system/architecture.md similarity index 100% rename from developer-documentation/system/architecture.md rename to developer/system/architecture.md diff --git a/developer-documentation/system/audio.md b/developer/system/audio.md similarity index 100% rename from developer-documentation/system/audio.md rename to developer/system/audio.md diff --git a/developer-documentation/system/gui.md b/developer/system/gui.md similarity index 100% rename from developer-documentation/system/gui.md rename to developer/system/gui.md diff --git a/developer-documentation/system/networking.md b/developer/system/networking.md similarity index 100% rename from developer-documentation/system/networking.md rename to developer/system/networking.md diff --git a/developer-documentation/system/security-critical-code.md b/developer/system/security-critical-code.md similarity index 100% rename from developer-documentation/system/security-critical-code.md rename to developer/system/security-critical-code.md diff --git a/developer-documentation/system/storage-pools.md b/developer/system/storage-pools.md similarity index 100% rename from developer-documentation/system/storage-pools.md rename to developer/system/storage-pools.md diff --git a/developer-documentation/system/system-doc.md b/developer/system/system-doc.md similarity index 100% rename from developer-documentation/system/system-doc.md rename to developer/system/system-doc.md diff --git a/developer-documentation/system/template-implementation.md b/developer/system/template-implementation.md similarity index 100% rename from developer-documentation/system/template-implementation.md rename to developer/system/template-implementation.md diff --git a/external-documentation/building-guides/building-archlinux-template.md b/external/building-guides/building-archlinux-template.md similarity index 100% rename from external-documentation/building-guides/building-archlinux-template.md rename to external/building-guides/building-archlinux-template.md diff --git a/external-documentation/building-guides/building-non-fedora-template.md b/external/building-guides/building-non-fedora-template.md similarity index 100% rename from external-documentation/building-guides/building-non-fedora-template.md rename to external/building-guides/building-non-fedora-template.md diff --git a/external-documentation/building-guides/building-whonix-template.md b/external/building-guides/building-whonix-template.md similarity index 100% rename from external-documentation/building-guides/building-whonix-template.md rename to external/building-guides/building-whonix-template.md diff --git a/external-documentation/configuration-guides/change-time-zone.md b/external/configuration-guides/change-time-zone.md similarity index 100% rename from external-documentation/configuration-guides/change-time-zone.md rename to external/configuration-guides/change-time-zone.md diff --git a/external-documentation/configuration-guides/disk-trim.md b/external/configuration-guides/disk-trim.md similarity index 100% rename from external-documentation/configuration-guides/disk-trim.md rename to external/configuration-guides/disk-trim.md diff --git a/external-documentation/configuration-guides/external-audio.md b/external/configuration-guides/external-audio.md similarity index 100% rename from external-documentation/configuration-guides/external-audio.md rename to external/configuration-guides/external-audio.md diff --git a/external-documentation/configuration-guides/fetchmail.md b/external/configuration-guides/fetchmail.md similarity index 100% rename from external-documentation/configuration-guides/fetchmail.md rename to external/configuration-guides/fetchmail.md diff --git a/external-documentation/configuration-guides/multiboot.md b/external/configuration-guides/multiboot.md similarity index 100% rename from external-documentation/configuration-guides/multiboot.md rename to external/configuration-guides/multiboot.md diff --git a/external-documentation/configuration-guides/multimedia.md b/external/configuration-guides/multimedia.md similarity index 100% rename from external-documentation/configuration-guides/multimedia.md rename to external/configuration-guides/multimedia.md diff --git a/external-documentation/configuration-guides/mutt.md b/external/configuration-guides/mutt.md similarity index 100% rename from external-documentation/configuration-guides/mutt.md rename to external/configuration-guides/mutt.md diff --git a/external-documentation/configuration-guides/network-bridge-support.md b/external/configuration-guides/network-bridge-support.md similarity index 100% rename from external-documentation/configuration-guides/network-bridge-support.md rename to external/configuration-guides/network-bridge-support.md diff --git a/external-documentation/configuration-guides/network-printer.md b/external/configuration-guides/network-printer.md similarity index 100% rename from external-documentation/configuration-guides/network-printer.md rename to external/configuration-guides/network-printer.md diff --git a/external-documentation/configuration-guides/postfix.md b/external/configuration-guides/postfix.md similarity index 100% rename from external-documentation/configuration-guides/postfix.md rename to external/configuration-guides/postfix.md diff --git a/external-documentation/configuration-guides/rxvt.md b/external/configuration-guides/rxvt.md similarity index 100% rename from external-documentation/configuration-guides/rxvt.md rename to external/configuration-guides/rxvt.md diff --git a/external-documentation/configuration-guides/tips-and-tricks.md b/external/configuration-guides/tips-and-tricks.md similarity index 100% rename from external-documentation/configuration-guides/tips-and-tricks.md rename to external/configuration-guides/tips-and-tricks.md diff --git a/external-documentation/configuration-guides/vpn.md b/external/configuration-guides/vpn.md similarity index 100% rename from external-documentation/configuration-guides/vpn.md rename to external/configuration-guides/vpn.md diff --git a/external-documentation/configuration-guides/w3m.md b/external/configuration-guides/w3m.md similarity index 100% rename from external-documentation/configuration-guides/w3m.md rename to external/configuration-guides/w3m.md diff --git a/external-documentation/configuration-guides/zfs.md b/external/configuration-guides/zfs.md similarity index 100% rename from external-documentation/configuration-guides/zfs.md rename to external/configuration-guides/zfs.md diff --git a/external-documentation/customization-guides/dark-theme.md b/external/customization-guides/dark-theme.md similarity index 100% rename from external-documentation/customization-guides/dark-theme.md rename to external/customization-guides/dark-theme.md diff --git a/external-documentation/customization-guides/fedora-minimal-template-customization.md b/external/customization-guides/fedora-minimal-template-customization.md similarity index 100% rename from external-documentation/customization-guides/fedora-minimal-template-customization.md rename to external/customization-guides/fedora-minimal-template-customization.md diff --git a/external-documentation/customization-guides/language-localization.md b/external/customization-guides/language-localization.md similarity index 100% rename from external-documentation/customization-guides/language-localization.md rename to external/customization-guides/language-localization.md diff --git a/external-documentation/customization-guides/removing-templatevm-packages.md b/external/customization-guides/removing-templatevm-packages.md similarity index 100% rename from external-documentation/customization-guides/removing-templatevm-packages.md rename to external/customization-guides/removing-templatevm-packages.md diff --git a/external-documentation/customization-guides/windows-template-customization.md b/external/customization-guides/windows-template-customization.md similarity index 100% rename from external-documentation/customization-guides/windows-template-customization.md rename to external/customization-guides/windows-template-customization.md diff --git a/external-documentation/os-guides/centos.md b/external/os-guides/centos.md similarity index 100% rename from external-documentation/os-guides/centos.md rename to external/os-guides/centos.md diff --git a/external-documentation/os-guides/linux-hvm-tips.md b/external/os-guides/linux-hvm-tips.md similarity index 100% rename from external-documentation/os-guides/linux-hvm-tips.md rename to external/os-guides/linux-hvm-tips.md diff --git a/external-documentation/os-guides/netbsd.md b/external/os-guides/netbsd.md similarity index 100% rename from external-documentation/os-guides/netbsd.md rename to external/os-guides/netbsd.md diff --git a/external-documentation/os-guides/pentesting.md b/external/os-guides/pentesting.md similarity index 100% rename from external-documentation/os-guides/pentesting.md rename to external/os-guides/pentesting.md diff --git a/external-documentation/os-guides/pentesting/blackarch.md b/external/os-guides/pentesting/blackarch.md similarity index 100% rename from external-documentation/os-guides/pentesting/blackarch.md rename to external/os-guides/pentesting/blackarch.md diff --git a/external-documentation/os-guides/pentesting/kali.md b/external/os-guides/pentesting/kali.md similarity index 100% rename from external-documentation/os-guides/pentesting/kali.md rename to external/os-guides/pentesting/kali.md diff --git a/external-documentation/os-guides/pentesting/ptf.md b/external/os-guides/pentesting/ptf.md similarity index 100% rename from external-documentation/os-guides/pentesting/ptf.md rename to external/os-guides/pentesting/ptf.md diff --git a/external-documentation/os-guides/ubuntu.md b/external/os-guides/ubuntu.md similarity index 100% rename from external-documentation/os-guides/ubuntu.md rename to external/os-guides/ubuntu.md diff --git a/external-documentation/os-guides/windows/windows-tools.md b/external/os-guides/windows/windows-tools.md similarity index 100% rename from external-documentation/os-guides/windows/windows-tools.md rename to external/os-guides/windows/windows-tools.md diff --git a/external-documentation/os-guides/windows/windows-vm.md b/external/os-guides/windows/windows-vm.md similarity index 100% rename from external-documentation/os-guides/windows/windows-vm.md rename to external/os-guides/windows/windows-vm.md diff --git a/external-documentation/privacy-guides/anonymizing-your-mac-address.md b/external/privacy-guides/anonymizing-your-mac-address.md similarity index 100% rename from external-documentation/privacy-guides/anonymizing-your-mac-address.md rename to external/privacy-guides/anonymizing-your-mac-address.md diff --git a/external-documentation/privacy-guides/signal.md b/external/privacy-guides/signal.md similarity index 100% rename from external-documentation/privacy-guides/signal.md rename to external/privacy-guides/signal.md diff --git a/external-documentation/privacy-guides/tails.md b/external/privacy-guides/tails.md similarity index 100% rename from external-documentation/privacy-guides/tails.md rename to external/privacy-guides/tails.md diff --git a/external-documentation/privacy-guides/torvm.md b/external/privacy-guides/torvm.md similarity index 100% rename from external-documentation/privacy-guides/torvm.md rename to external/privacy-guides/torvm.md diff --git a/external-documentation/privacy-guides/whonix.md b/external/privacy-guides/whonix.md similarity index 100% rename from external-documentation/privacy-guides/whonix.md rename to external/privacy-guides/whonix.md diff --git a/external-documentation/security-guides/multifactor-authentication.md b/external/security-guides/multifactor-authentication.md similarity index 100% rename from external-documentation/security-guides/multifactor-authentication.md rename to external/security-guides/multifactor-authentication.md diff --git a/external-documentation/security-guides/security-guidelines.md b/external/security-guides/security-guidelines.md similarity index 100% rename from external-documentation/security-guides/security-guidelines.md rename to external/security-guides/security-guidelines.md diff --git a/external-documentation/security-guides/split-bitcoin.md b/external/security-guides/split-bitcoin.md similarity index 100% rename from external-documentation/security-guides/split-bitcoin.md rename to external/security-guides/split-bitcoin.md diff --git a/external-documentation/troubleshooting/install-nvidia-driver.md b/external/troubleshooting/install-nvidia-driver.md similarity index 100% rename from external-documentation/troubleshooting/install-nvidia-driver.md rename to external/troubleshooting/install-nvidia-driver.md diff --git a/external-documentation/troubleshooting/intel-igfx-troubleshooting.md b/external/troubleshooting/intel-igfx-troubleshooting.md similarity index 100% rename from external-documentation/troubleshooting/intel-igfx-troubleshooting.md rename to external/troubleshooting/intel-igfx-troubleshooting.md diff --git a/external-documentation/troubleshooting/macbook-troubleshooting.md b/external/troubleshooting/macbook-troubleshooting.md similarity index 100% rename from external-documentation/troubleshooting/macbook-troubleshooting.md rename to external/troubleshooting/macbook-troubleshooting.md diff --git a/external-documentation/troubleshooting/nvidia-troubleshooting.md b/external/troubleshooting/nvidia-troubleshooting.md similarity index 100% rename from external-documentation/troubleshooting/nvidia-troubleshooting.md rename to external/troubleshooting/nvidia-troubleshooting.md diff --git a/external-documentation/troubleshooting/out-of-memory.md b/external/troubleshooting/out-of-memory.md similarity index 100% rename from external-documentation/troubleshooting/out-of-memory.md rename to external/troubleshooting/out-of-memory.md diff --git a/external-documentation/troubleshooting/remove-vm-manually.md b/external/troubleshooting/remove-vm-manually.md similarity index 100% rename from external-documentation/troubleshooting/remove-vm-manually.md rename to external/troubleshooting/remove-vm-manually.md diff --git a/external-documentation/troubleshooting/sony-vaio-tinkering.md b/external/troubleshooting/sony-vaio-tinkering.md similarity index 100% rename from external-documentation/troubleshooting/sony-vaio-tinkering.md rename to external/troubleshooting/sony-vaio-tinkering.md diff --git a/external-documentation/troubleshooting/thinkpad-troubleshooting.md b/external/troubleshooting/thinkpad-troubleshooting.md similarity index 100% rename from external-documentation/troubleshooting/thinkpad-troubleshooting.md rename to external/troubleshooting/thinkpad-troubleshooting.md diff --git a/external-documentation/troubleshooting/updating-debian-and-whonix.md b/external/troubleshooting/updating-debian-and-whonix.md similarity index 100% rename from external-documentation/troubleshooting/updating-debian-and-whonix.md rename to external/troubleshooting/updating-debian-and-whonix.md diff --git a/external-documentation/troubleshooting/wireless-troubleshooting.md b/external/troubleshooting/wireless-troubleshooting.md similarity index 100% rename from external-documentation/troubleshooting/wireless-troubleshooting.md rename to external/troubleshooting/wireless-troubleshooting.md diff --git a/user-documentation/advanced-configuration/awesome.md b/user/advanced-configuration/awesome.md similarity index 100% rename from user-documentation/advanced-configuration/awesome.md rename to user/advanced-configuration/awesome.md diff --git a/user-documentation/advanced-configuration/bind-dirs.md b/user/advanced-configuration/bind-dirs.md similarity index 100% rename from user-documentation/advanced-configuration/bind-dirs.md rename to user/advanced-configuration/bind-dirs.md diff --git a/user-documentation/advanced-configuration/config-files.md b/user/advanced-configuration/config-files.md similarity index 100% rename from user-documentation/advanced-configuration/config-files.md rename to user/advanced-configuration/config-files.md diff --git a/user-documentation/advanced-configuration/disposablevm-customization.md b/user/advanced-configuration/disposablevm-customization.md similarity index 100% rename from user-documentation/advanced-configuration/disposablevm-customization.md rename to user/advanced-configuration/disposablevm-customization.md diff --git a/user-documentation/advanced-configuration/gui-configuration.md b/user/advanced-configuration/gui-configuration.md similarity index 100% rename from user-documentation/advanced-configuration/gui-configuration.md rename to user/advanced-configuration/gui-configuration.md diff --git a/user-documentation/advanced-configuration/i3.md b/user/advanced-configuration/i3.md similarity index 100% rename from user-documentation/advanced-configuration/i3.md rename to user/advanced-configuration/i3.md diff --git a/user-documentation/advanced-configuration/kde.md b/user/advanced-configuration/kde.md similarity index 100% rename from user-documentation/advanced-configuration/kde.md rename to user/advanced-configuration/kde.md diff --git a/user-documentation/advanced-configuration/managing-vm-kernel.md b/user/advanced-configuration/managing-vm-kernel.md similarity index 100% rename from user-documentation/advanced-configuration/managing-vm-kernel.md rename to user/advanced-configuration/managing-vm-kernel.md diff --git a/user-documentation/advanced-configuration/mount-from-other-os.md b/user/advanced-configuration/mount-from-other-os.md similarity index 100% rename from user-documentation/advanced-configuration/mount-from-other-os.md rename to user/advanced-configuration/mount-from-other-os.md diff --git a/user-documentation/advanced-configuration/newer-hardware-troubleshooting.md b/user/advanced-configuration/newer-hardware-troubleshooting.md similarity index 100% rename from user-documentation/advanced-configuration/newer-hardware-troubleshooting.md rename to user/advanced-configuration/newer-hardware-troubleshooting.md diff --git a/user-documentation/advanced-configuration/resize-disk-image.md b/user/advanced-configuration/resize-disk-image.md similarity index 100% rename from user-documentation/advanced-configuration/resize-disk-image.md rename to user/advanced-configuration/resize-disk-image.md diff --git a/user-documentation/advanced-configuration/rpc-policy.md b/user/advanced-configuration/rpc-policy.md similarity index 100% rename from user-documentation/advanced-configuration/rpc-policy.md rename to user/advanced-configuration/rpc-policy.md diff --git a/user-documentation/advanced-configuration/salt.md b/user/advanced-configuration/salt.md similarity index 100% rename from user-documentation/advanced-configuration/salt.md rename to user/advanced-configuration/salt.md diff --git a/user-documentation/advanced-configuration/secondary-storage.md b/user/advanced-configuration/secondary-storage.md similarity index 100% rename from user-documentation/advanced-configuration/secondary-storage.md rename to user/advanced-configuration/secondary-storage.md diff --git a/user-documentation/advanced-configuration/uefi-troubleshooting.md b/user/advanced-configuration/uefi-troubleshooting.md similarity index 100% rename from user-documentation/advanced-configuration/uefi-troubleshooting.md rename to user/advanced-configuration/uefi-troubleshooting.md diff --git a/user-documentation/advanced-configuration/usb-qubes.md b/user/advanced-configuration/usb-qubes.md similarity index 100% rename from user-documentation/advanced-configuration/usb-qubes.md rename to user/advanced-configuration/usb-qubes.md diff --git a/user-documentation/common-tasks/backup-emergency-restore-v2.md b/user/common-tasks/backup-emergency-restore-v2.md similarity index 100% rename from user-documentation/common-tasks/backup-emergency-restore-v2.md rename to user/common-tasks/backup-emergency-restore-v2.md diff --git a/user-documentation/common-tasks/backup-emergency-restore-v3.md b/user/common-tasks/backup-emergency-restore-v3.md similarity index 100% rename from user-documentation/common-tasks/backup-emergency-restore-v3.md rename to user/common-tasks/backup-emergency-restore-v3.md diff --git a/user-documentation/common-tasks/backup-emergency-restore-v4.md b/user/common-tasks/backup-emergency-restore-v4.md similarity index 100% rename from user-documentation/common-tasks/backup-emergency-restore-v4.md rename to user/common-tasks/backup-emergency-restore-v4.md diff --git a/user-documentation/common-tasks/backup-restore.md b/user/common-tasks/backup-restore.md similarity index 100% rename from user-documentation/common-tasks/backup-restore.md rename to user/common-tasks/backup-restore.md diff --git a/user-documentation/common-tasks/block-devices.md b/user/common-tasks/block-devices.md similarity index 100% rename from user-documentation/common-tasks/block-devices.md rename to user/common-tasks/block-devices.md diff --git a/user-documentation/common-tasks/copy-from-dom0.md b/user/common-tasks/copy-from-dom0.md similarity index 100% rename from user-documentation/common-tasks/copy-from-dom0.md rename to user/common-tasks/copy-from-dom0.md diff --git a/user-documentation/common-tasks/copy-paste.md b/user/common-tasks/copy-paste.md similarity index 100% rename from user-documentation/common-tasks/copy-paste.md rename to user/common-tasks/copy-paste.md diff --git a/user-documentation/common-tasks/copying-files.md b/user/common-tasks/copying-files.md similarity index 100% rename from user-documentation/common-tasks/copying-files.md rename to user/common-tasks/copying-files.md diff --git a/user-documentation/common-tasks/device-handling.md b/user/common-tasks/device-handling.md similarity index 100% rename from user-documentation/common-tasks/device-handling.md rename to user/common-tasks/device-handling.md diff --git a/user-documentation/common-tasks/disposablevm.md b/user/common-tasks/disposablevm.md similarity index 100% rename from user-documentation/common-tasks/disposablevm.md rename to user/common-tasks/disposablevm.md diff --git a/user-documentation/common-tasks/full-screen-mode.md b/user/common-tasks/full-screen-mode.md similarity index 100% rename from user-documentation/common-tasks/full-screen-mode.md rename to user/common-tasks/full-screen-mode.md diff --git a/user-documentation/common-tasks/getting-started.md b/user/common-tasks/getting-started.md similarity index 100% rename from user-documentation/common-tasks/getting-started.md rename to user/common-tasks/getting-started.md diff --git a/user-documentation/common-tasks/managing-appvm-shortcuts.md b/user/common-tasks/managing-appvm-shortcuts.md similarity index 100% rename from user-documentation/common-tasks/managing-appvm-shortcuts.md rename to user/common-tasks/managing-appvm-shortcuts.md diff --git a/user-documentation/common-tasks/optical-discs.md b/user/common-tasks/optical-discs.md similarity index 100% rename from user-documentation/common-tasks/optical-discs.md rename to user/common-tasks/optical-discs.md diff --git a/user-documentation/common-tasks/pci-devices.md b/user/common-tasks/pci-devices.md similarity index 100% rename from user-documentation/common-tasks/pci-devices.md rename to user/common-tasks/pci-devices.md diff --git a/user-documentation/common-tasks/software-update-dom0.md b/user/common-tasks/software-update-dom0.md similarity index 100% rename from user-documentation/common-tasks/software-update-dom0.md rename to user/common-tasks/software-update-dom0.md diff --git a/user-documentation/common-tasks/software-update-domu.md b/user/common-tasks/software-update-domu.md similarity index 100% rename from user-documentation/common-tasks/software-update-domu.md rename to user/common-tasks/software-update-domu.md diff --git a/user-documentation/common-tasks/updating-qubes-os.md b/user/common-tasks/updating-qubes-os.md similarity index 100% rename from user-documentation/common-tasks/updating-qubes-os.md rename to user/common-tasks/updating-qubes-os.md diff --git a/user-documentation/common-tasks/usb-devices.md b/user/common-tasks/usb-devices.md similarity index 100% rename from user-documentation/common-tasks/usb-devices.md rename to user/common-tasks/usb-devices.md diff --git a/user-documentation/common-tasks/volume-backup-revert.md b/user/common-tasks/volume-backup-revert.md similarity index 100% rename from user-documentation/common-tasks/volume-backup-revert.md rename to user/common-tasks/volume-backup-revert.md diff --git a/user-documentation/downloading-installing-upgrading/custom-install.md b/user/downloading-installing-upgrading/custom-install.md similarity index 100% rename from user-documentation/downloading-installing-upgrading/custom-install.md rename to user/downloading-installing-upgrading/custom-install.md diff --git a/user-documentation/downloading-installing-upgrading/download-mirrors.md b/user/downloading-installing-upgrading/download-mirrors.md similarity index 100% rename from user-documentation/downloading-installing-upgrading/download-mirrors.md rename to user/downloading-installing-upgrading/download-mirrors.md diff --git a/user-documentation/downloading-installing-upgrading/install-security.md b/user/downloading-installing-upgrading/install-security.md similarity index 100% rename from user-documentation/downloading-installing-upgrading/install-security.md rename to user/downloading-installing-upgrading/install-security.md diff --git a/user-documentation/downloading-installing-upgrading/installation-guide.md b/user/downloading-installing-upgrading/installation-guide.md similarity index 100% rename from user-documentation/downloading-installing-upgrading/installation-guide.md rename to user/downloading-installing-upgrading/installation-guide.md diff --git a/user-documentation/downloading-installing-upgrading/live-usb.md b/user/downloading-installing-upgrading/live-usb.md similarity index 100% rename from user-documentation/downloading-installing-upgrading/live-usb.md rename to user/downloading-installing-upgrading/live-usb.md diff --git a/user-documentation/downloading-installing-upgrading/supported-versions.md b/user/downloading-installing-upgrading/supported-versions.md similarity index 100% rename from user-documentation/downloading-installing-upgrading/supported-versions.md rename to user/downloading-installing-upgrading/supported-versions.md diff --git a/user-documentation/downloading-installing-upgrading/testing.md b/user/downloading-installing-upgrading/testing.md similarity index 100% rename from user-documentation/downloading-installing-upgrading/testing.md rename to user/downloading-installing-upgrading/testing.md diff --git a/user-documentation/downloading-installing-upgrading/upgrade/upgrade-to-r2.md b/user/downloading-installing-upgrading/upgrade/upgrade-to-r2.md similarity index 100% rename from user-documentation/downloading-installing-upgrading/upgrade/upgrade-to-r2.md rename to user/downloading-installing-upgrading/upgrade/upgrade-to-r2.md diff --git a/user-documentation/downloading-installing-upgrading/upgrade/upgrade-to-r2b1.md b/user/downloading-installing-upgrading/upgrade/upgrade-to-r2b1.md similarity index 100% rename from user-documentation/downloading-installing-upgrading/upgrade/upgrade-to-r2b1.md rename to user/downloading-installing-upgrading/upgrade/upgrade-to-r2b1.md diff --git a/user-documentation/downloading-installing-upgrading/upgrade/upgrade-to-r2b2.md b/user/downloading-installing-upgrading/upgrade/upgrade-to-r2b2.md similarity index 100% rename from user-documentation/downloading-installing-upgrading/upgrade/upgrade-to-r2b2.md rename to user/downloading-installing-upgrading/upgrade/upgrade-to-r2b2.md diff --git a/user-documentation/downloading-installing-upgrading/upgrade/upgrade-to-r2b3.md b/user/downloading-installing-upgrading/upgrade/upgrade-to-r2b3.md similarity index 100% rename from user-documentation/downloading-installing-upgrading/upgrade/upgrade-to-r2b3.md rename to user/downloading-installing-upgrading/upgrade/upgrade-to-r2b3.md diff --git a/user-documentation/downloading-installing-upgrading/upgrade/upgrade-to-r3_0.md b/user/downloading-installing-upgrading/upgrade/upgrade-to-r3_0.md similarity index 100% rename from user-documentation/downloading-installing-upgrading/upgrade/upgrade-to-r3_0.md rename to user/downloading-installing-upgrading/upgrade/upgrade-to-r3_0.md diff --git a/user-documentation/downloading-installing-upgrading/upgrade/upgrade-to-r3_1.md b/user/downloading-installing-upgrading/upgrade/upgrade-to-r3_1.md similarity index 100% rename from user-documentation/downloading-installing-upgrading/upgrade/upgrade-to-r3_1.md rename to user/downloading-installing-upgrading/upgrade/upgrade-to-r3_1.md diff --git a/user-documentation/downloading-installing-upgrading/upgrade/upgrade-to-r3_2.md b/user/downloading-installing-upgrading/upgrade/upgrade-to-r3_2.md similarity index 100% rename from user-documentation/downloading-installing-upgrading/upgrade/upgrade-to-r3_2.md rename to user/downloading-installing-upgrading/upgrade/upgrade-to-r3_2.md diff --git a/user-documentation/downloading-installing-upgrading/upgrade/upgrade-to-r4_0.md b/user/downloading-installing-upgrading/upgrade/upgrade-to-r4_0.md similarity index 100% rename from user-documentation/downloading-installing-upgrading/upgrade/upgrade-to-r4_0.md rename to user/downloading-installing-upgrading/upgrade/upgrade-to-r4_0.md diff --git a/user-documentation/downloading-installing-upgrading/upgrade/upgrade.md b/user/downloading-installing-upgrading/upgrade/upgrade.md similarity index 100% rename from user-documentation/downloading-installing-upgrading/upgrade/upgrade.md rename to user/downloading-installing-upgrading/upgrade/upgrade.md diff --git a/user-documentation/downloading-installing-upgrading/version-scheme.md b/user/downloading-installing-upgrading/version-scheme.md similarity index 100% rename from user-documentation/downloading-installing-upgrading/version-scheme.md rename to user/downloading-installing-upgrading/version-scheme.md diff --git a/user-documentation/hardware/certified-hardware.md b/user/hardware/certified-hardware.md similarity index 100% rename from user-documentation/hardware/certified-hardware.md rename to user/hardware/certified-hardware.md diff --git a/user-documentation/hardware/hardware-testing.md b/user/hardware/hardware-testing.md similarity index 100% rename from user-documentation/hardware/hardware-testing.md rename to user/hardware/hardware-testing.md diff --git a/user-documentation/hardware/hcl_listing.md b/user/hardware/hcl_listing.md similarity index 100% rename from user-documentation/hardware/hcl_listing.md rename to user/hardware/hcl_listing.md diff --git a/user-documentation/hardware/hcl_md.md b/user/hardware/hcl_md.md similarity index 100% rename from user-documentation/hardware/hcl_md.md rename to user/hardware/hcl_md.md diff --git a/user-documentation/hardware/system-requirements.md b/user/hardware/system-requirements.md similarity index 100% rename from user-documentation/hardware/system-requirements.md rename to user/hardware/system-requirements.md diff --git a/user-documentation/managing-os/debian/debian-upgrade.md b/user/managing-os/debian/debian-upgrade.md similarity index 100% rename from user-documentation/managing-os/debian/debian-upgrade.md rename to user/managing-os/debian/debian-upgrade.md diff --git a/user-documentation/managing-os/debian/debian.md b/user/managing-os/debian/debian.md similarity index 100% rename from user-documentation/managing-os/debian/debian.md rename to user/managing-os/debian/debian.md diff --git a/user-documentation/managing-os/fedora/fedora-upgrade.md b/user/managing-os/fedora/fedora-upgrade.md similarity index 100% rename from user-documentation/managing-os/fedora/fedora-upgrade.md rename to user/managing-os/fedora/fedora-upgrade.md diff --git a/user-documentation/managing-os/fedora/fedora-xfce.md b/user/managing-os/fedora/fedora-xfce.md similarity index 100% rename from user-documentation/managing-os/fedora/fedora-xfce.md rename to user/managing-os/fedora/fedora-xfce.md diff --git a/user-documentation/managing-os/fedora/fedora.md b/user/managing-os/fedora/fedora.md similarity index 100% rename from user-documentation/managing-os/fedora/fedora.md rename to user/managing-os/fedora/fedora.md diff --git a/user-documentation/managing-os/minimal-templates.md b/user/managing-os/minimal-templates.md similarity index 100% rename from user-documentation/managing-os/minimal-templates.md rename to user/managing-os/minimal-templates.md diff --git a/user-documentation/managing-os/reinstall-template.md b/user/managing-os/reinstall-template.md similarity index 100% rename from user-documentation/managing-os/reinstall-template.md rename to user/managing-os/reinstall-template.md diff --git a/user-documentation/managing-os/standalone-and-hvm.md b/user/managing-os/standalone-and-hvm.md similarity index 100% rename from user-documentation/managing-os/standalone-and-hvm.md rename to user/managing-os/standalone-and-hvm.md diff --git a/user-documentation/managing-os/templates.md b/user/managing-os/templates.md similarity index 100% rename from user-documentation/managing-os/templates.md rename to user/managing-os/templates.md diff --git a/user-documentation/managing-os/windows.md b/user/managing-os/windows.md similarity index 100% rename from user-documentation/managing-os/windows.md rename to user/managing-os/windows.md diff --git a/user-documentation/reference/glossary.md b/user/reference/glossary.md similarity index 100% rename from user-documentation/reference/glossary.md rename to user/reference/glossary.md diff --git a/user-documentation/reference/qubes-service.md b/user/reference/qubes-service.md similarity index 100% rename from user-documentation/reference/qubes-service.md rename to user/reference/qubes-service.md diff --git a/user-documentation/reference/research.md b/user/reference/research.md similarity index 100% rename from user-documentation/reference/research.md rename to user/reference/research.md diff --git a/user-documentation/reference/tools.md b/user/reference/tools.md similarity index 100% rename from user-documentation/reference/tools.md rename to user/reference/tools.md diff --git a/user-documentation/security-in-qubes/anti-evil-maid.md b/user/security-in-qubes/anti-evil-maid.md similarity index 100% rename from user-documentation/security-in-qubes/anti-evil-maid.md rename to user/security-in-qubes/anti-evil-maid.md diff --git a/user-documentation/security-in-qubes/data-leaks.md b/user/security-in-qubes/data-leaks.md similarity index 100% rename from user-documentation/security-in-qubes/data-leaks.md rename to user/security-in-qubes/data-leaks.md diff --git a/user-documentation/security-in-qubes/device-handling-security.md b/user/security-in-qubes/device-handling-security.md similarity index 100% rename from user-documentation/security-in-qubes/device-handling-security.md rename to user/security-in-qubes/device-handling-security.md diff --git a/user-documentation/security-in-qubes/firewall.md b/user/security-in-qubes/firewall.md similarity index 100% rename from user-documentation/security-in-qubes/firewall.md rename to user/security-in-qubes/firewall.md diff --git a/user-documentation/security-in-qubes/split-gpg.md b/user/security-in-qubes/split-gpg.md similarity index 100% rename from user-documentation/security-in-qubes/split-gpg.md rename to user/security-in-qubes/split-gpg.md diff --git a/user-documentation/security-in-qubes/u2f-proxy.md b/user/security-in-qubes/u2f-proxy.md similarity index 100% rename from user-documentation/security-in-qubes/u2f-proxy.md rename to user/security-in-qubes/u2f-proxy.md diff --git a/user-documentation/security-in-qubes/vm-sudo.md b/user/security-in-qubes/vm-sudo.md similarity index 100% rename from user-documentation/security-in-qubes/vm-sudo.md rename to user/security-in-qubes/vm-sudo.md diff --git a/user-documentation/security-in-qubes/yubi-key.md b/user/security-in-qubes/yubi-key.md similarity index 100% rename from user-documentation/security-in-qubes/yubi-key.md rename to user/security-in-qubes/yubi-key.md From 28cb89d4c9217bfb21130da5ee4dcea5889a57dc Mon Sep 17 00:00:00 2001 From: dd Date: Mon, 19 Oct 2020 17:31:52 +0200 Subject: [PATCH 031/663] submodules desaster after merge fix --- _dev/_templates/.gitignore | 0 CONTRIBUTING.md => en/_doc/CONTRIBUTING.md | 0 README.md => en/_doc/README.md | 0 {_dev => en/_doc/_dev}/.gitignore | 0 {_dev => en/_doc/_dev}/Makefile | 0 {_dev/_build => en/_doc/_dev/_static}/.gitignore | 0 {_dev/_static => en/_doc/_dev/_templates}/.gitignore | 0 {_dev => en/_doc/_dev}/conf.py | 0 {_dev => en/_doc/_dev}/index.rst | 0 {developer => en/_doc/developer}/building/development-workflow.md | 0 .../_doc/developer}/building/qubes-builder-details.md | 0 {developer => en/_doc/developer}/building/qubes-builder.md | 0 {developer => en/_doc/developer}/building/qubes-iso-building.md | 0 {developer => en/_doc/developer}/code/code-signing.md | 0 {developer => en/_doc/developer}/code/coding-style.md | 0 {developer => en/_doc/developer}/code/license.md | 0 {developer => en/_doc/developer}/code/source-code.md | 0 {developer => en/_doc/developer}/debugging/automated-tests.md | 0 {developer => en/_doc/developer}/debugging/mount-lvm-image.md | 0 {developer => en/_doc/developer}/debugging/profiling.md | 0 {developer => en/_doc/developer}/debugging/safe-remote-ttys.md | 0 {developer => en/_doc/developer}/debugging/test-bench.md | 0 {developer => en/_doc/developer}/debugging/vm-interface.md | 0 {developer => en/_doc/developer}/debugging/windows-debugging.md | 0 {developer => en/_doc/developer}/general/devel-books.md | 0 {developer => en/_doc/developer}/general/doc-guidelines.md | 0 {developer => en/_doc/developer}/general/gsoc.md | 0 {developer => en/_doc/developer}/general/gsod.md | 0 {developer => en/_doc/developer}/general/join.md | 0 {developer => en/_doc/developer}/general/package-contributions.md | 0 {developer => en/_doc/developer}/general/style-guide.md | 0 {developer => en/_doc/developer}/general/usability-ux.md | 0 {developer => en/_doc/developer}/releases/1_0/release-notes.md | 0 {developer => en/_doc/developer}/releases/2_0/release-notes.md | 0 {developer => en/_doc/developer}/releases/3_0/release-notes.md | 0 {developer => en/_doc/developer}/releases/3_0/schedule.md | 0 {developer => en/_doc/developer}/releases/3_1/release-notes.md | 0 {developer => en/_doc/developer}/releases/3_1/schedule.md | 0 {developer => en/_doc/developer}/releases/3_2/release-notes.md | 0 {developer => en/_doc/developer}/releases/3_2/schedule.md | 0 {developer => en/_doc/developer}/releases/4_0/release-notes.md | 0 {developer => en/_doc/developer}/releases/4_0/schedule.md | 0 {developer => en/_doc/developer}/releases/notes.md | 0 {developer => en/_doc/developer}/releases/schedules.md | 0 {developer => en/_doc/developer}/releases/todo.md | 0 {developer => en/_doc/developer}/services/admin-api.md | 0 {developer => en/_doc/developer}/services/dom0-secure-updates.md | 0 {developer => en/_doc/developer}/services/dvm-impl.md | 0 {developer => en/_doc/developer}/services/qfilecopy.md | 0 {developer => en/_doc/developer}/services/qfileexchgd.md | 0 {developer => en/_doc/developer}/services/qmemman.md | 0 {developer => en/_doc/developer}/services/qrexec-internals.md | 0 .../_doc/developer}/services/qrexec-socket-services.md | 0 {developer => en/_doc/developer}/services/qrexec.md | 0 {developer => en/_doc/developer}/services/qrexec2.md | 0 {developer => en/_doc/developer}/system/architecture.md | 0 {developer => en/_doc/developer}/system/audio.md | 0 {developer => en/_doc/developer}/system/gui.md | 0 {developer => en/_doc/developer}/system/networking.md | 0 {developer => en/_doc/developer}/system/security-critical-code.md | 0 {developer => en/_doc/developer}/system/storage-pools.md | 0 {developer => en/_doc/developer}/system/system-doc.md | 0 .../_doc/developer}/system/template-implementation.md | 0 doc.md => en/_doc/doc.md | 0 .../_doc/external}/building-guides/building-archlinux-template.md | 0 .../external}/building-guides/building-non-fedora-template.md | 0 .../_doc/external}/building-guides/building-whonix-template.md | 0 .../_doc/external}/configuration-guides/change-time-zone.md | 0 {external => en/_doc/external}/configuration-guides/disk-trim.md | 0 .../_doc/external}/configuration-guides/external-audio.md | 0 {external => en/_doc/external}/configuration-guides/fetchmail.md | 0 {external => en/_doc/external}/configuration-guides/multiboot.md | 0 {external => en/_doc/external}/configuration-guides/multimedia.md | 0 {external => en/_doc/external}/configuration-guides/mutt.md | 0 .../_doc/external}/configuration-guides/network-bridge-support.md | 0 .../_doc/external}/configuration-guides/network-printer.md | 0 {external => en/_doc/external}/configuration-guides/postfix.md | 0 {external => en/_doc/external}/configuration-guides/rxvt.md | 0 .../_doc/external}/configuration-guides/tips-and-tricks.md | 0 {external => en/_doc/external}/configuration-guides/vpn.md | 0 {external => en/_doc/external}/configuration-guides/w3m.md | 0 {external => en/_doc/external}/configuration-guides/zfs.md | 0 {external => en/_doc/external}/customization-guides/dark-theme.md | 0 .../customization-guides/fedora-minimal-template-customization.md | 0 .../_doc/external}/customization-guides/language-localization.md | 0 .../customization-guides/removing-templatevm-packages.md | 0 .../customization-guides/windows-template-customization.md | 0 {external => en/_doc/external}/os-guides/centos.md | 0 {external => en/_doc/external}/os-guides/gentoo.md | 0 {external => en/_doc/external}/os-guides/linux-hvm-tips.md | 0 {external => en/_doc/external}/os-guides/netbsd.md | 0 {external => en/_doc/external}/os-guides/pentesting.md | 0 {external => en/_doc/external}/os-guides/pentesting/blackarch.md | 0 {external => en/_doc/external}/os-guides/pentesting/kali.md | 0 {external => en/_doc/external}/os-guides/pentesting/ptf.md | 0 {external => en/_doc/external}/os-guides/ubuntu.md | 0 {external => en/_doc/external}/os-guides/windows/windows-tools.md | 0 {external => en/_doc/external}/os-guides/windows/windows-vm.md | 0 .../_doc/external}/privacy-guides/anonymizing-your-mac-address.md | 0 {external => en/_doc/external}/privacy-guides/signal.md | 0 {external => en/_doc/external}/privacy-guides/tails.md | 0 {external => en/_doc/external}/privacy-guides/torvm.md | 0 {external => en/_doc/external}/privacy-guides/whonix.md | 0 .../_doc/external}/security-guides/multifactor-authentication.md | 0 .../_doc/external}/security-guides/security-guidelines.md | 0 {external => en/_doc/external}/security-guides/split-bitcoin.md | 0 {introduction => en/_doc/introduction}/code-of-conduct.md | 0 {introduction => en/_doc/introduction}/contributing.md | 0 {introduction => en/_doc/introduction}/experts.md | 0 {introduction => en/_doc/introduction}/faq.md | 0 {introduction => en/_doc/introduction}/intro.md | 0 {introduction => en/_doc/introduction}/reporting-bugs.md | 0 {introduction => en/_doc/introduction}/screenshots.md | 0 {introduction => en/_doc/introduction}/statistics.md | 0 {introduction => en/_doc/introduction}/support.md | 0 {introduction => en/_doc/introduction}/video-tours.md | 0 {project-security => en/_doc/project-security}/canaries.md | 0 .../_doc/project-security}/canary-checklist.md | 0 {project-security => en/_doc/project-security}/canary-template.md | 0 .../_doc/project-security}/security-bulletins-checklist.md | 0 .../_doc/project-security}/security-bulletins-template.md | 0 .../_doc/project-security}/security-bulletins.md | 0 {project-security => en/_doc/project-security}/security-goals.md | 0 {project-security => en/_doc/project-security}/security-pack.md | 0 {project-security => en/_doc/project-security}/security.md | 0 .../_doc/project-security}/verifying-signatures.md | 0 {project-security => en/_doc/project-security}/xsa.md | 0 {user => en/_doc/user}/advanced-configuration/awesome.md | 0 {user => en/_doc/user}/advanced-configuration/bind-dirs.md | 0 {user => en/_doc/user}/advanced-configuration/config-files.md | 0 .../user}/advanced-configuration/disposablevm-customization.md | 0 .../_doc/user}/advanced-configuration/gui-configuration.md | 0 {user => en/_doc/user}/advanced-configuration/i3.md | 0 {user => en/_doc/user}/advanced-configuration/kde.md | 0 .../_doc/user}/advanced-configuration/managing-vm-kernel.md | 0 .../_doc/user}/advanced-configuration/mount-from-other-os.md | 0 .../advanced-configuration/newer-hardware-troubleshooting.md | 0 .../_doc/user}/advanced-configuration/resize-disk-image.md | 0 {user => en/_doc/user}/advanced-configuration/rpc-policy.md | 0 {user => en/_doc/user}/advanced-configuration/salt.md | 0 .../_doc/user}/advanced-configuration/secondary-storage.md | 0 {user => en/_doc/user}/advanced-configuration/usb-qubes.md | 0 .../_doc/user}/common-tasks/backup-emergency-restore-v2.md | 0 .../_doc/user}/common-tasks/backup-emergency-restore-v3.md | 0 .../_doc/user}/common-tasks/backup-emergency-restore-v4.md | 0 {user => en/_doc/user}/common-tasks/backup-restore.md | 0 {user => en/_doc/user}/common-tasks/block-devices.md | 0 {user => en/_doc/user}/common-tasks/copy-from-dom0.md | 0 {user => en/_doc/user}/common-tasks/copy-paste.md | 0 {user => en/_doc/user}/common-tasks/copying-files.md | 0 {user => en/_doc/user}/common-tasks/device-handling.md | 0 {user => en/_doc/user}/common-tasks/disposablevm.md | 0 {user => en/_doc/user}/common-tasks/full-screen-mode.md | 0 {user => en/_doc/user}/common-tasks/getting-started.md | 0 {user => en/_doc/user}/common-tasks/managing-appvm-shortcuts.md | 0 {user => en/_doc/user}/common-tasks/optical-discs.md | 0 {user => en/_doc/user}/common-tasks/pci-devices.md | 0 {user => en/_doc/user}/common-tasks/software-update-dom0.md | 0 {user => en/_doc/user}/common-tasks/software-update-domu.md | 0 {user => en/_doc/user}/common-tasks/updating-qubes-os.md | 0 {user => en/_doc/user}/common-tasks/usb-devices.md | 0 {user => en/_doc/user}/common-tasks/volume-backup-revert.md | 0 .../_doc/user}/downloading-installing-upgrading/custom-install.md | 0 .../user}/downloading-installing-upgrading/download-mirrors.md | 0 .../user}/downloading-installing-upgrading/install-security.md | 0 .../user}/downloading-installing-upgrading/installation-guide.md | 0 .../_doc/user}/downloading-installing-upgrading/live-usb.md | 0 .../user}/downloading-installing-upgrading/supported-versions.md | 0 .../_doc/user}/downloading-installing-upgrading/testing.md | 0 .../downloading-installing-upgrading/upgrade/upgrade-to-r2.md | 0 .../downloading-installing-upgrading/upgrade/upgrade-to-r2b1.md | 0 .../downloading-installing-upgrading/upgrade/upgrade-to-r2b2.md | 0 .../downloading-installing-upgrading/upgrade/upgrade-to-r2b3.md | 0 .../downloading-installing-upgrading/upgrade/upgrade-to-r3_0.md | 0 .../downloading-installing-upgrading/upgrade/upgrade-to-r3_1.md | 0 .../downloading-installing-upgrading/upgrade/upgrade-to-r3_2.md | 0 .../downloading-installing-upgrading/upgrade/upgrade-to-r4_0.md | 0 .../user}/downloading-installing-upgrading/upgrade/upgrade.md | 0 .../_doc/user}/downloading-installing-upgrading/version-scheme.md | 0 {user => en/_doc/user}/hardware/certified-hardware.md | 0 {user => en/_doc/user}/hardware/hardware-testing.md | 0 {user => en/_doc/user}/hardware/hcl_listing.md | 0 {user => en/_doc/user}/hardware/hcl_md.md | 0 {user => en/_doc/user}/hardware/system-requirements.md | 0 {user => en/_doc/user}/managing-os/debian/debian-upgrade.md | 0 {user => en/_doc/user}/managing-os/debian/debian.md | 0 {user => en/_doc/user}/managing-os/fedora/fedora-upgrade.md | 0 {user => en/_doc/user}/managing-os/fedora/fedora-xfce.md | 0 {user => en/_doc/user}/managing-os/fedora/fedora.md | 0 {user => en/_doc/user}/managing-os/minimal-templates.md | 0 {user => en/_doc/user}/managing-os/reinstall-template.md | 0 {user => en/_doc/user}/managing-os/standalone-and-hvm.md | 0 {user => en/_doc/user}/managing-os/templates.md | 0 {user => en/_doc/user}/managing-os/windows.md | 0 {user => en/_doc/user}/managing-os/xfce-templates.md | 0 {user => en/_doc/user}/reference/glossary.md | 0 {user => en/_doc/user}/reference/qubes-service.md | 0 {user => en/_doc/user}/reference/research.md | 0 {user => en/_doc/user}/reference/tools.md | 0 {user => en/_doc/user}/security-in-qubes/anti-evil-maid.md | 0 {user => en/_doc/user}/security-in-qubes/data-leaks.md | 0 .../_doc/user}/security-in-qubes/device-handling-security.md | 0 {user => en/_doc/user}/security-in-qubes/firewall.md | 0 {user => en/_doc/user}/security-in-qubes/split-gpg.md | 0 {user => en/_doc/user}/security-in-qubes/u2f-proxy.md | 0 {user => en/_doc/user}/security-in-qubes/vm-sudo.md | 0 {user => en/_doc/user}/security-in-qubes/yubi-key.md | 0 {user => en/_doc/user}/troubleshooting/install-nvidia-driver.md | 0 .../_doc/user}/troubleshooting/installation-troubleshooting.md | 0 .../_doc/user}/troubleshooting/intel-igfx-troubleshooting.md | 0 {user => en/_doc/user}/troubleshooting/macbook-troubleshooting.md | 0 {user => en/_doc/user}/troubleshooting/nvidia-troubleshooting.md | 0 {user => en/_doc/user}/troubleshooting/out-of-memory.md | 0 {user => en/_doc/user}/troubleshooting/remove-vm-manually.md | 0 {user => en/_doc/user}/troubleshooting/sony-vaio-tinkering.md | 0 .../_doc/user}/troubleshooting/thinkpad-troubleshooting.md | 0 {user => en/_doc/user}/troubleshooting/uefi-troubleshooting.md | 0 .../_doc/user}/troubleshooting/updating-debian-and-whonix.md | 0 .../_doc/user}/troubleshooting/wireless-troubleshooting.md | 0 219 files changed, 0 insertions(+), 0 deletions(-) delete mode 100644 _dev/_templates/.gitignore rename CONTRIBUTING.md => en/_doc/CONTRIBUTING.md (100%) rename README.md => en/_doc/README.md (100%) rename {_dev => en/_doc/_dev}/.gitignore (100%) rename {_dev => en/_doc/_dev}/Makefile (100%) rename {_dev/_build => en/_doc/_dev/_static}/.gitignore (100%) rename {_dev/_static => en/_doc/_dev/_templates}/.gitignore (100%) rename {_dev => en/_doc/_dev}/conf.py (100%) rename {_dev => en/_doc/_dev}/index.rst (100%) rename {developer => en/_doc/developer}/building/development-workflow.md (100%) rename {developer => en/_doc/developer}/building/qubes-builder-details.md (100%) rename {developer => en/_doc/developer}/building/qubes-builder.md (100%) rename {developer => en/_doc/developer}/building/qubes-iso-building.md (100%) rename {developer => en/_doc/developer}/code/code-signing.md (100%) rename {developer => en/_doc/developer}/code/coding-style.md (100%) rename {developer => en/_doc/developer}/code/license.md (100%) rename {developer => en/_doc/developer}/code/source-code.md (100%) rename {developer => en/_doc/developer}/debugging/automated-tests.md (100%) rename {developer => en/_doc/developer}/debugging/mount-lvm-image.md (100%) rename {developer => en/_doc/developer}/debugging/profiling.md (100%) rename {developer => en/_doc/developer}/debugging/safe-remote-ttys.md (100%) rename {developer => en/_doc/developer}/debugging/test-bench.md (100%) rename {developer => en/_doc/developer}/debugging/vm-interface.md (100%) rename {developer => en/_doc/developer}/debugging/windows-debugging.md (100%) rename {developer => en/_doc/developer}/general/devel-books.md (100%) rename {developer => en/_doc/developer}/general/doc-guidelines.md (100%) rename {developer => en/_doc/developer}/general/gsoc.md (100%) rename {developer => en/_doc/developer}/general/gsod.md (100%) rename {developer => en/_doc/developer}/general/join.md (100%) rename {developer => en/_doc/developer}/general/package-contributions.md (100%) rename {developer => en/_doc/developer}/general/style-guide.md (100%) rename {developer => en/_doc/developer}/general/usability-ux.md (100%) rename {developer => en/_doc/developer}/releases/1_0/release-notes.md (100%) rename {developer => en/_doc/developer}/releases/2_0/release-notes.md (100%) rename {developer => en/_doc/developer}/releases/3_0/release-notes.md (100%) rename {developer => en/_doc/developer}/releases/3_0/schedule.md (100%) rename {developer => en/_doc/developer}/releases/3_1/release-notes.md (100%) rename {developer => en/_doc/developer}/releases/3_1/schedule.md (100%) rename {developer => en/_doc/developer}/releases/3_2/release-notes.md (100%) rename {developer => en/_doc/developer}/releases/3_2/schedule.md (100%) rename {developer => en/_doc/developer}/releases/4_0/release-notes.md (100%) rename {developer => en/_doc/developer}/releases/4_0/schedule.md (100%) rename {developer => en/_doc/developer}/releases/notes.md (100%) rename {developer => en/_doc/developer}/releases/schedules.md (100%) rename {developer => en/_doc/developer}/releases/todo.md (100%) rename {developer => en/_doc/developer}/services/admin-api.md (100%) rename {developer => en/_doc/developer}/services/dom0-secure-updates.md (100%) rename {developer => en/_doc/developer}/services/dvm-impl.md (100%) rename {developer => en/_doc/developer}/services/qfilecopy.md (100%) rename {developer => en/_doc/developer}/services/qfileexchgd.md (100%) rename {developer => en/_doc/developer}/services/qmemman.md (100%) rename {developer => en/_doc/developer}/services/qrexec-internals.md (100%) rename {developer => en/_doc/developer}/services/qrexec-socket-services.md (100%) rename {developer => en/_doc/developer}/services/qrexec.md (100%) rename {developer => en/_doc/developer}/services/qrexec2.md (100%) rename {developer => en/_doc/developer}/system/architecture.md (100%) rename {developer => en/_doc/developer}/system/audio.md (100%) rename {developer => en/_doc/developer}/system/gui.md (100%) rename {developer => en/_doc/developer}/system/networking.md (100%) rename {developer => en/_doc/developer}/system/security-critical-code.md (100%) rename {developer => en/_doc/developer}/system/storage-pools.md (100%) rename {developer => en/_doc/developer}/system/system-doc.md (100%) rename {developer => en/_doc/developer}/system/template-implementation.md (100%) rename doc.md => en/_doc/doc.md (100%) rename {external => en/_doc/external}/building-guides/building-archlinux-template.md (100%) rename {external => en/_doc/external}/building-guides/building-non-fedora-template.md (100%) rename {external => en/_doc/external}/building-guides/building-whonix-template.md (100%) rename {external => en/_doc/external}/configuration-guides/change-time-zone.md (100%) rename {external => en/_doc/external}/configuration-guides/disk-trim.md (100%) rename {external => en/_doc/external}/configuration-guides/external-audio.md (100%) rename {external => en/_doc/external}/configuration-guides/fetchmail.md (100%) rename {external => en/_doc/external}/configuration-guides/multiboot.md (100%) rename {external => en/_doc/external}/configuration-guides/multimedia.md (100%) rename {external => en/_doc/external}/configuration-guides/mutt.md (100%) rename {external => en/_doc/external}/configuration-guides/network-bridge-support.md (100%) rename {external => en/_doc/external}/configuration-guides/network-printer.md (100%) rename {external => en/_doc/external}/configuration-guides/postfix.md (100%) rename {external => en/_doc/external}/configuration-guides/rxvt.md (100%) rename {external => en/_doc/external}/configuration-guides/tips-and-tricks.md (100%) rename {external => en/_doc/external}/configuration-guides/vpn.md (100%) rename {external => en/_doc/external}/configuration-guides/w3m.md (100%) rename {external => en/_doc/external}/configuration-guides/zfs.md (100%) rename {external => en/_doc/external}/customization-guides/dark-theme.md (100%) rename {external => en/_doc/external}/customization-guides/fedora-minimal-template-customization.md (100%) rename {external => en/_doc/external}/customization-guides/language-localization.md (100%) rename {external => en/_doc/external}/customization-guides/removing-templatevm-packages.md (100%) rename {external => en/_doc/external}/customization-guides/windows-template-customization.md (100%) rename {external => en/_doc/external}/os-guides/centos.md (100%) rename {external => en/_doc/external}/os-guides/gentoo.md (100%) rename {external => en/_doc/external}/os-guides/linux-hvm-tips.md (100%) rename {external => en/_doc/external}/os-guides/netbsd.md (100%) rename {external => en/_doc/external}/os-guides/pentesting.md (100%) rename {external => en/_doc/external}/os-guides/pentesting/blackarch.md (100%) rename {external => en/_doc/external}/os-guides/pentesting/kali.md (100%) rename {external => en/_doc/external}/os-guides/pentesting/ptf.md (100%) rename {external => en/_doc/external}/os-guides/ubuntu.md (100%) rename {external => en/_doc/external}/os-guides/windows/windows-tools.md (100%) rename {external => en/_doc/external}/os-guides/windows/windows-vm.md (100%) rename {external => en/_doc/external}/privacy-guides/anonymizing-your-mac-address.md (100%) rename {external => en/_doc/external}/privacy-guides/signal.md (100%) rename {external => en/_doc/external}/privacy-guides/tails.md (100%) rename {external => en/_doc/external}/privacy-guides/torvm.md (100%) rename {external => en/_doc/external}/privacy-guides/whonix.md (100%) rename {external => en/_doc/external}/security-guides/multifactor-authentication.md (100%) rename {external => en/_doc/external}/security-guides/security-guidelines.md (100%) rename {external => en/_doc/external}/security-guides/split-bitcoin.md (100%) rename {introduction => en/_doc/introduction}/code-of-conduct.md (100%) rename {introduction => en/_doc/introduction}/contributing.md (100%) rename {introduction => en/_doc/introduction}/experts.md (100%) rename {introduction => en/_doc/introduction}/faq.md (100%) rename {introduction => en/_doc/introduction}/intro.md (100%) rename {introduction => en/_doc/introduction}/reporting-bugs.md (100%) rename {introduction => en/_doc/introduction}/screenshots.md (100%) rename {introduction => en/_doc/introduction}/statistics.md (100%) rename {introduction => en/_doc/introduction}/support.md (100%) rename {introduction => en/_doc/introduction}/video-tours.md (100%) rename {project-security => en/_doc/project-security}/canaries.md (100%) rename {project-security => en/_doc/project-security}/canary-checklist.md (100%) rename {project-security => en/_doc/project-security}/canary-template.md (100%) rename {project-security => en/_doc/project-security}/security-bulletins-checklist.md (100%) rename {project-security => en/_doc/project-security}/security-bulletins-template.md (100%) rename {project-security => en/_doc/project-security}/security-bulletins.md (100%) rename {project-security => en/_doc/project-security}/security-goals.md (100%) rename {project-security => en/_doc/project-security}/security-pack.md (100%) rename {project-security => en/_doc/project-security}/security.md (100%) rename {project-security => en/_doc/project-security}/verifying-signatures.md (100%) rename {project-security => en/_doc/project-security}/xsa.md (100%) rename {user => en/_doc/user}/advanced-configuration/awesome.md (100%) rename {user => en/_doc/user}/advanced-configuration/bind-dirs.md (100%) rename {user => en/_doc/user}/advanced-configuration/config-files.md (100%) rename {user => en/_doc/user}/advanced-configuration/disposablevm-customization.md (100%) rename {user => en/_doc/user}/advanced-configuration/gui-configuration.md (100%) rename {user => en/_doc/user}/advanced-configuration/i3.md (100%) rename {user => en/_doc/user}/advanced-configuration/kde.md (100%) rename {user => en/_doc/user}/advanced-configuration/managing-vm-kernel.md (100%) rename {user => en/_doc/user}/advanced-configuration/mount-from-other-os.md (100%) rename {user => en/_doc/user}/advanced-configuration/newer-hardware-troubleshooting.md (100%) rename {user => en/_doc/user}/advanced-configuration/resize-disk-image.md (100%) rename {user => en/_doc/user}/advanced-configuration/rpc-policy.md (100%) rename {user => en/_doc/user}/advanced-configuration/salt.md (100%) rename {user => en/_doc/user}/advanced-configuration/secondary-storage.md (100%) rename {user => en/_doc/user}/advanced-configuration/usb-qubes.md (100%) rename {user => en/_doc/user}/common-tasks/backup-emergency-restore-v2.md (100%) rename {user => en/_doc/user}/common-tasks/backup-emergency-restore-v3.md (100%) rename {user => en/_doc/user}/common-tasks/backup-emergency-restore-v4.md (100%) rename {user => en/_doc/user}/common-tasks/backup-restore.md (100%) rename {user => en/_doc/user}/common-tasks/block-devices.md (100%) rename {user => en/_doc/user}/common-tasks/copy-from-dom0.md (100%) rename {user => en/_doc/user}/common-tasks/copy-paste.md (100%) rename {user => en/_doc/user}/common-tasks/copying-files.md (100%) rename {user => en/_doc/user}/common-tasks/device-handling.md (100%) rename {user => en/_doc/user}/common-tasks/disposablevm.md (100%) rename {user => en/_doc/user}/common-tasks/full-screen-mode.md (100%) rename {user => en/_doc/user}/common-tasks/getting-started.md (100%) rename {user => en/_doc/user}/common-tasks/managing-appvm-shortcuts.md (100%) rename {user => en/_doc/user}/common-tasks/optical-discs.md (100%) rename {user => en/_doc/user}/common-tasks/pci-devices.md (100%) rename {user => en/_doc/user}/common-tasks/software-update-dom0.md (100%) rename {user => en/_doc/user}/common-tasks/software-update-domu.md (100%) rename {user => en/_doc/user}/common-tasks/updating-qubes-os.md (100%) rename {user => en/_doc/user}/common-tasks/usb-devices.md (100%) rename {user => en/_doc/user}/common-tasks/volume-backup-revert.md (100%) rename {user => en/_doc/user}/downloading-installing-upgrading/custom-install.md (100%) rename {user => en/_doc/user}/downloading-installing-upgrading/download-mirrors.md (100%) rename {user => en/_doc/user}/downloading-installing-upgrading/install-security.md (100%) rename {user => en/_doc/user}/downloading-installing-upgrading/installation-guide.md (100%) rename {user => en/_doc/user}/downloading-installing-upgrading/live-usb.md (100%) rename {user => en/_doc/user}/downloading-installing-upgrading/supported-versions.md (100%) rename {user => en/_doc/user}/downloading-installing-upgrading/testing.md (100%) rename {user => en/_doc/user}/downloading-installing-upgrading/upgrade/upgrade-to-r2.md (100%) rename {user => en/_doc/user}/downloading-installing-upgrading/upgrade/upgrade-to-r2b1.md (100%) rename {user => en/_doc/user}/downloading-installing-upgrading/upgrade/upgrade-to-r2b2.md (100%) rename {user => en/_doc/user}/downloading-installing-upgrading/upgrade/upgrade-to-r2b3.md (100%) rename {user => en/_doc/user}/downloading-installing-upgrading/upgrade/upgrade-to-r3_0.md (100%) rename {user => en/_doc/user}/downloading-installing-upgrading/upgrade/upgrade-to-r3_1.md (100%) rename {user => en/_doc/user}/downloading-installing-upgrading/upgrade/upgrade-to-r3_2.md (100%) rename {user => en/_doc/user}/downloading-installing-upgrading/upgrade/upgrade-to-r4_0.md (100%) rename {user => en/_doc/user}/downloading-installing-upgrading/upgrade/upgrade.md (100%) rename {user => en/_doc/user}/downloading-installing-upgrading/version-scheme.md (100%) rename {user => en/_doc/user}/hardware/certified-hardware.md (100%) rename {user => en/_doc/user}/hardware/hardware-testing.md (100%) rename {user => en/_doc/user}/hardware/hcl_listing.md (100%) rename {user => en/_doc/user}/hardware/hcl_md.md (100%) rename {user => en/_doc/user}/hardware/system-requirements.md (100%) rename {user => en/_doc/user}/managing-os/debian/debian-upgrade.md (100%) rename {user => en/_doc/user}/managing-os/debian/debian.md (100%) rename {user => en/_doc/user}/managing-os/fedora/fedora-upgrade.md (100%) rename {user => en/_doc/user}/managing-os/fedora/fedora-xfce.md (100%) rename {user => en/_doc/user}/managing-os/fedora/fedora.md (100%) rename {user => en/_doc/user}/managing-os/minimal-templates.md (100%) rename {user => en/_doc/user}/managing-os/reinstall-template.md (100%) rename {user => en/_doc/user}/managing-os/standalone-and-hvm.md (100%) rename {user => en/_doc/user}/managing-os/templates.md (100%) rename {user => en/_doc/user}/managing-os/windows.md (100%) rename {user => en/_doc/user}/managing-os/xfce-templates.md (100%) rename {user => en/_doc/user}/reference/glossary.md (100%) rename {user => en/_doc/user}/reference/qubes-service.md (100%) rename {user => en/_doc/user}/reference/research.md (100%) rename {user => en/_doc/user}/reference/tools.md (100%) rename {user => en/_doc/user}/security-in-qubes/anti-evil-maid.md (100%) rename {user => en/_doc/user}/security-in-qubes/data-leaks.md (100%) rename {user => en/_doc/user}/security-in-qubes/device-handling-security.md (100%) rename {user => en/_doc/user}/security-in-qubes/firewall.md (100%) rename {user => en/_doc/user}/security-in-qubes/split-gpg.md (100%) rename {user => en/_doc/user}/security-in-qubes/u2f-proxy.md (100%) rename {user => en/_doc/user}/security-in-qubes/vm-sudo.md (100%) rename {user => en/_doc/user}/security-in-qubes/yubi-key.md (100%) rename {user => en/_doc/user}/troubleshooting/install-nvidia-driver.md (100%) rename {user => en/_doc/user}/troubleshooting/installation-troubleshooting.md (100%) rename {user => en/_doc/user}/troubleshooting/intel-igfx-troubleshooting.md (100%) rename {user => en/_doc/user}/troubleshooting/macbook-troubleshooting.md (100%) rename {user => en/_doc/user}/troubleshooting/nvidia-troubleshooting.md (100%) rename {user => en/_doc/user}/troubleshooting/out-of-memory.md (100%) rename {user => en/_doc/user}/troubleshooting/remove-vm-manually.md (100%) rename {user => en/_doc/user}/troubleshooting/sony-vaio-tinkering.md (100%) rename {user => en/_doc/user}/troubleshooting/thinkpad-troubleshooting.md (100%) rename {user => en/_doc/user}/troubleshooting/uefi-troubleshooting.md (100%) rename {user => en/_doc/user}/troubleshooting/updating-debian-and-whonix.md (100%) rename {user => en/_doc/user}/troubleshooting/wireless-troubleshooting.md (100%) diff --git a/_dev/_templates/.gitignore b/_dev/_templates/.gitignore deleted file mode 100644 index e69de29bb2..0000000000 diff --git a/CONTRIBUTING.md b/en/_doc/CONTRIBUTING.md similarity index 100% rename from CONTRIBUTING.md rename to en/_doc/CONTRIBUTING.md diff --git a/README.md b/en/_doc/README.md similarity index 100% rename from README.md rename to en/_doc/README.md diff --git a/_dev/.gitignore b/en/_doc/_dev/.gitignore similarity index 100% rename from _dev/.gitignore rename to en/_doc/_dev/.gitignore diff --git a/_dev/Makefile b/en/_doc/_dev/Makefile similarity index 100% rename from _dev/Makefile rename to en/_doc/_dev/Makefile diff --git a/_dev/_build/.gitignore b/en/_doc/_dev/_static/.gitignore similarity index 100% rename from _dev/_build/.gitignore rename to en/_doc/_dev/_static/.gitignore diff --git a/_dev/_static/.gitignore b/en/_doc/_dev/_templates/.gitignore similarity index 100% rename from _dev/_static/.gitignore rename to en/_doc/_dev/_templates/.gitignore diff --git a/_dev/conf.py b/en/_doc/_dev/conf.py similarity index 100% rename from _dev/conf.py rename to en/_doc/_dev/conf.py diff --git a/_dev/index.rst b/en/_doc/_dev/index.rst similarity index 100% rename from _dev/index.rst rename to en/_doc/_dev/index.rst diff --git a/developer/building/development-workflow.md b/en/_doc/developer/building/development-workflow.md similarity index 100% rename from developer/building/development-workflow.md rename to en/_doc/developer/building/development-workflow.md diff --git a/developer/building/qubes-builder-details.md b/en/_doc/developer/building/qubes-builder-details.md similarity index 100% rename from developer/building/qubes-builder-details.md rename to en/_doc/developer/building/qubes-builder-details.md diff --git a/developer/building/qubes-builder.md b/en/_doc/developer/building/qubes-builder.md similarity index 100% rename from developer/building/qubes-builder.md rename to en/_doc/developer/building/qubes-builder.md diff --git a/developer/building/qubes-iso-building.md b/en/_doc/developer/building/qubes-iso-building.md similarity index 100% rename from developer/building/qubes-iso-building.md rename to en/_doc/developer/building/qubes-iso-building.md diff --git a/developer/code/code-signing.md b/en/_doc/developer/code/code-signing.md similarity index 100% rename from developer/code/code-signing.md rename to en/_doc/developer/code/code-signing.md diff --git a/developer/code/coding-style.md b/en/_doc/developer/code/coding-style.md similarity index 100% rename from developer/code/coding-style.md rename to en/_doc/developer/code/coding-style.md diff --git a/developer/code/license.md b/en/_doc/developer/code/license.md similarity index 100% rename from developer/code/license.md rename to en/_doc/developer/code/license.md diff --git a/developer/code/source-code.md b/en/_doc/developer/code/source-code.md similarity index 100% rename from developer/code/source-code.md rename to en/_doc/developer/code/source-code.md diff --git a/developer/debugging/automated-tests.md b/en/_doc/developer/debugging/automated-tests.md similarity index 100% rename from developer/debugging/automated-tests.md rename to en/_doc/developer/debugging/automated-tests.md diff --git a/developer/debugging/mount-lvm-image.md b/en/_doc/developer/debugging/mount-lvm-image.md similarity index 100% rename from developer/debugging/mount-lvm-image.md rename to en/_doc/developer/debugging/mount-lvm-image.md diff --git a/developer/debugging/profiling.md b/en/_doc/developer/debugging/profiling.md similarity index 100% rename from developer/debugging/profiling.md rename to en/_doc/developer/debugging/profiling.md diff --git a/developer/debugging/safe-remote-ttys.md b/en/_doc/developer/debugging/safe-remote-ttys.md similarity index 100% rename from developer/debugging/safe-remote-ttys.md rename to en/_doc/developer/debugging/safe-remote-ttys.md diff --git a/developer/debugging/test-bench.md b/en/_doc/developer/debugging/test-bench.md similarity index 100% rename from developer/debugging/test-bench.md rename to en/_doc/developer/debugging/test-bench.md diff --git a/developer/debugging/vm-interface.md b/en/_doc/developer/debugging/vm-interface.md similarity index 100% rename from developer/debugging/vm-interface.md rename to en/_doc/developer/debugging/vm-interface.md diff --git a/developer/debugging/windows-debugging.md b/en/_doc/developer/debugging/windows-debugging.md similarity index 100% rename from developer/debugging/windows-debugging.md rename to en/_doc/developer/debugging/windows-debugging.md diff --git a/developer/general/devel-books.md b/en/_doc/developer/general/devel-books.md similarity index 100% rename from developer/general/devel-books.md rename to en/_doc/developer/general/devel-books.md diff --git a/developer/general/doc-guidelines.md b/en/_doc/developer/general/doc-guidelines.md similarity index 100% rename from developer/general/doc-guidelines.md rename to en/_doc/developer/general/doc-guidelines.md diff --git a/developer/general/gsoc.md b/en/_doc/developer/general/gsoc.md similarity index 100% rename from developer/general/gsoc.md rename to en/_doc/developer/general/gsoc.md diff --git a/developer/general/gsod.md b/en/_doc/developer/general/gsod.md similarity index 100% rename from developer/general/gsod.md rename to en/_doc/developer/general/gsod.md diff --git a/developer/general/join.md b/en/_doc/developer/general/join.md similarity index 100% rename from developer/general/join.md rename to en/_doc/developer/general/join.md diff --git a/developer/general/package-contributions.md b/en/_doc/developer/general/package-contributions.md similarity index 100% rename from developer/general/package-contributions.md rename to en/_doc/developer/general/package-contributions.md diff --git a/developer/general/style-guide.md b/en/_doc/developer/general/style-guide.md similarity index 100% rename from developer/general/style-guide.md rename to en/_doc/developer/general/style-guide.md diff --git a/developer/general/usability-ux.md b/en/_doc/developer/general/usability-ux.md similarity index 100% rename from developer/general/usability-ux.md rename to en/_doc/developer/general/usability-ux.md diff --git a/developer/releases/1_0/release-notes.md b/en/_doc/developer/releases/1_0/release-notes.md similarity index 100% rename from developer/releases/1_0/release-notes.md rename to en/_doc/developer/releases/1_0/release-notes.md diff --git a/developer/releases/2_0/release-notes.md b/en/_doc/developer/releases/2_0/release-notes.md similarity index 100% rename from developer/releases/2_0/release-notes.md rename to en/_doc/developer/releases/2_0/release-notes.md diff --git a/developer/releases/3_0/release-notes.md b/en/_doc/developer/releases/3_0/release-notes.md similarity index 100% rename from developer/releases/3_0/release-notes.md rename to en/_doc/developer/releases/3_0/release-notes.md diff --git a/developer/releases/3_0/schedule.md b/en/_doc/developer/releases/3_0/schedule.md similarity index 100% rename from developer/releases/3_0/schedule.md rename to en/_doc/developer/releases/3_0/schedule.md diff --git a/developer/releases/3_1/release-notes.md b/en/_doc/developer/releases/3_1/release-notes.md similarity index 100% rename from developer/releases/3_1/release-notes.md rename to en/_doc/developer/releases/3_1/release-notes.md diff --git a/developer/releases/3_1/schedule.md b/en/_doc/developer/releases/3_1/schedule.md similarity index 100% rename from developer/releases/3_1/schedule.md rename to en/_doc/developer/releases/3_1/schedule.md diff --git a/developer/releases/3_2/release-notes.md b/en/_doc/developer/releases/3_2/release-notes.md similarity index 100% rename from developer/releases/3_2/release-notes.md rename to en/_doc/developer/releases/3_2/release-notes.md diff --git a/developer/releases/3_2/schedule.md b/en/_doc/developer/releases/3_2/schedule.md similarity index 100% rename from developer/releases/3_2/schedule.md rename to en/_doc/developer/releases/3_2/schedule.md diff --git a/developer/releases/4_0/release-notes.md b/en/_doc/developer/releases/4_0/release-notes.md similarity index 100% rename from developer/releases/4_0/release-notes.md rename to en/_doc/developer/releases/4_0/release-notes.md diff --git a/developer/releases/4_0/schedule.md b/en/_doc/developer/releases/4_0/schedule.md similarity index 100% rename from developer/releases/4_0/schedule.md rename to en/_doc/developer/releases/4_0/schedule.md diff --git a/developer/releases/notes.md b/en/_doc/developer/releases/notes.md similarity index 100% rename from developer/releases/notes.md rename to en/_doc/developer/releases/notes.md diff --git a/developer/releases/schedules.md b/en/_doc/developer/releases/schedules.md similarity index 100% rename from developer/releases/schedules.md rename to en/_doc/developer/releases/schedules.md diff --git a/developer/releases/todo.md b/en/_doc/developer/releases/todo.md similarity index 100% rename from developer/releases/todo.md rename to en/_doc/developer/releases/todo.md diff --git a/developer/services/admin-api.md b/en/_doc/developer/services/admin-api.md similarity index 100% rename from developer/services/admin-api.md rename to en/_doc/developer/services/admin-api.md diff --git a/developer/services/dom0-secure-updates.md b/en/_doc/developer/services/dom0-secure-updates.md similarity index 100% rename from developer/services/dom0-secure-updates.md rename to en/_doc/developer/services/dom0-secure-updates.md diff --git a/developer/services/dvm-impl.md b/en/_doc/developer/services/dvm-impl.md similarity index 100% rename from developer/services/dvm-impl.md rename to en/_doc/developer/services/dvm-impl.md diff --git a/developer/services/qfilecopy.md b/en/_doc/developer/services/qfilecopy.md similarity index 100% rename from developer/services/qfilecopy.md rename to en/_doc/developer/services/qfilecopy.md diff --git a/developer/services/qfileexchgd.md b/en/_doc/developer/services/qfileexchgd.md similarity index 100% rename from developer/services/qfileexchgd.md rename to en/_doc/developer/services/qfileexchgd.md diff --git a/developer/services/qmemman.md b/en/_doc/developer/services/qmemman.md similarity index 100% rename from developer/services/qmemman.md rename to en/_doc/developer/services/qmemman.md diff --git a/developer/services/qrexec-internals.md b/en/_doc/developer/services/qrexec-internals.md similarity index 100% rename from developer/services/qrexec-internals.md rename to en/_doc/developer/services/qrexec-internals.md diff --git a/developer/services/qrexec-socket-services.md b/en/_doc/developer/services/qrexec-socket-services.md similarity index 100% rename from developer/services/qrexec-socket-services.md rename to en/_doc/developer/services/qrexec-socket-services.md diff --git a/developer/services/qrexec.md b/en/_doc/developer/services/qrexec.md similarity index 100% rename from developer/services/qrexec.md rename to en/_doc/developer/services/qrexec.md diff --git a/developer/services/qrexec2.md b/en/_doc/developer/services/qrexec2.md similarity index 100% rename from developer/services/qrexec2.md rename to en/_doc/developer/services/qrexec2.md diff --git a/developer/system/architecture.md b/en/_doc/developer/system/architecture.md similarity index 100% rename from developer/system/architecture.md rename to en/_doc/developer/system/architecture.md diff --git a/developer/system/audio.md b/en/_doc/developer/system/audio.md similarity index 100% rename from developer/system/audio.md rename to en/_doc/developer/system/audio.md diff --git a/developer/system/gui.md b/en/_doc/developer/system/gui.md similarity index 100% rename from developer/system/gui.md rename to en/_doc/developer/system/gui.md diff --git a/developer/system/networking.md b/en/_doc/developer/system/networking.md similarity index 100% rename from developer/system/networking.md rename to en/_doc/developer/system/networking.md diff --git a/developer/system/security-critical-code.md b/en/_doc/developer/system/security-critical-code.md similarity index 100% rename from developer/system/security-critical-code.md rename to en/_doc/developer/system/security-critical-code.md diff --git a/developer/system/storage-pools.md b/en/_doc/developer/system/storage-pools.md similarity index 100% rename from developer/system/storage-pools.md rename to en/_doc/developer/system/storage-pools.md diff --git a/developer/system/system-doc.md b/en/_doc/developer/system/system-doc.md similarity index 100% rename from developer/system/system-doc.md rename to en/_doc/developer/system/system-doc.md diff --git a/developer/system/template-implementation.md b/en/_doc/developer/system/template-implementation.md similarity index 100% rename from developer/system/template-implementation.md rename to en/_doc/developer/system/template-implementation.md diff --git a/doc.md b/en/_doc/doc.md similarity index 100% rename from doc.md rename to en/_doc/doc.md diff --git a/external/building-guides/building-archlinux-template.md b/en/_doc/external/building-guides/building-archlinux-template.md similarity index 100% rename from external/building-guides/building-archlinux-template.md rename to en/_doc/external/building-guides/building-archlinux-template.md diff --git a/external/building-guides/building-non-fedora-template.md b/en/_doc/external/building-guides/building-non-fedora-template.md similarity index 100% rename from external/building-guides/building-non-fedora-template.md rename to en/_doc/external/building-guides/building-non-fedora-template.md diff --git a/external/building-guides/building-whonix-template.md b/en/_doc/external/building-guides/building-whonix-template.md similarity index 100% rename from external/building-guides/building-whonix-template.md rename to en/_doc/external/building-guides/building-whonix-template.md diff --git a/external/configuration-guides/change-time-zone.md b/en/_doc/external/configuration-guides/change-time-zone.md similarity index 100% rename from external/configuration-guides/change-time-zone.md rename to en/_doc/external/configuration-guides/change-time-zone.md diff --git a/external/configuration-guides/disk-trim.md b/en/_doc/external/configuration-guides/disk-trim.md similarity index 100% rename from external/configuration-guides/disk-trim.md rename to en/_doc/external/configuration-guides/disk-trim.md diff --git a/external/configuration-guides/external-audio.md b/en/_doc/external/configuration-guides/external-audio.md similarity index 100% rename from external/configuration-guides/external-audio.md rename to en/_doc/external/configuration-guides/external-audio.md diff --git a/external/configuration-guides/fetchmail.md b/en/_doc/external/configuration-guides/fetchmail.md similarity index 100% rename from external/configuration-guides/fetchmail.md rename to en/_doc/external/configuration-guides/fetchmail.md diff --git a/external/configuration-guides/multiboot.md b/en/_doc/external/configuration-guides/multiboot.md similarity index 100% rename from external/configuration-guides/multiboot.md rename to en/_doc/external/configuration-guides/multiboot.md diff --git a/external/configuration-guides/multimedia.md b/en/_doc/external/configuration-guides/multimedia.md similarity index 100% rename from external/configuration-guides/multimedia.md rename to en/_doc/external/configuration-guides/multimedia.md diff --git a/external/configuration-guides/mutt.md b/en/_doc/external/configuration-guides/mutt.md similarity index 100% rename from external/configuration-guides/mutt.md rename to en/_doc/external/configuration-guides/mutt.md diff --git a/external/configuration-guides/network-bridge-support.md b/en/_doc/external/configuration-guides/network-bridge-support.md similarity index 100% rename from external/configuration-guides/network-bridge-support.md rename to en/_doc/external/configuration-guides/network-bridge-support.md diff --git a/external/configuration-guides/network-printer.md b/en/_doc/external/configuration-guides/network-printer.md similarity index 100% rename from external/configuration-guides/network-printer.md rename to en/_doc/external/configuration-guides/network-printer.md diff --git a/external/configuration-guides/postfix.md b/en/_doc/external/configuration-guides/postfix.md similarity index 100% rename from external/configuration-guides/postfix.md rename to en/_doc/external/configuration-guides/postfix.md diff --git a/external/configuration-guides/rxvt.md b/en/_doc/external/configuration-guides/rxvt.md similarity index 100% rename from external/configuration-guides/rxvt.md rename to en/_doc/external/configuration-guides/rxvt.md diff --git a/external/configuration-guides/tips-and-tricks.md b/en/_doc/external/configuration-guides/tips-and-tricks.md similarity index 100% rename from external/configuration-guides/tips-and-tricks.md rename to en/_doc/external/configuration-guides/tips-and-tricks.md diff --git a/external/configuration-guides/vpn.md b/en/_doc/external/configuration-guides/vpn.md similarity index 100% rename from external/configuration-guides/vpn.md rename to en/_doc/external/configuration-guides/vpn.md diff --git a/external/configuration-guides/w3m.md b/en/_doc/external/configuration-guides/w3m.md similarity index 100% rename from external/configuration-guides/w3m.md rename to en/_doc/external/configuration-guides/w3m.md diff --git a/external/configuration-guides/zfs.md b/en/_doc/external/configuration-guides/zfs.md similarity index 100% rename from external/configuration-guides/zfs.md rename to en/_doc/external/configuration-guides/zfs.md diff --git a/external/customization-guides/dark-theme.md b/en/_doc/external/customization-guides/dark-theme.md similarity index 100% rename from external/customization-guides/dark-theme.md rename to en/_doc/external/customization-guides/dark-theme.md diff --git a/external/customization-guides/fedora-minimal-template-customization.md b/en/_doc/external/customization-guides/fedora-minimal-template-customization.md similarity index 100% rename from external/customization-guides/fedora-minimal-template-customization.md rename to en/_doc/external/customization-guides/fedora-minimal-template-customization.md diff --git a/external/customization-guides/language-localization.md b/en/_doc/external/customization-guides/language-localization.md similarity index 100% rename from external/customization-guides/language-localization.md rename to en/_doc/external/customization-guides/language-localization.md diff --git a/external/customization-guides/removing-templatevm-packages.md b/en/_doc/external/customization-guides/removing-templatevm-packages.md similarity index 100% rename from external/customization-guides/removing-templatevm-packages.md rename to en/_doc/external/customization-guides/removing-templatevm-packages.md diff --git a/external/customization-guides/windows-template-customization.md b/en/_doc/external/customization-guides/windows-template-customization.md similarity index 100% rename from external/customization-guides/windows-template-customization.md rename to en/_doc/external/customization-guides/windows-template-customization.md diff --git a/external/os-guides/centos.md b/en/_doc/external/os-guides/centos.md similarity index 100% rename from external/os-guides/centos.md rename to en/_doc/external/os-guides/centos.md diff --git a/external/os-guides/gentoo.md b/en/_doc/external/os-guides/gentoo.md similarity index 100% rename from external/os-guides/gentoo.md rename to en/_doc/external/os-guides/gentoo.md diff --git a/external/os-guides/linux-hvm-tips.md b/en/_doc/external/os-guides/linux-hvm-tips.md similarity index 100% rename from external/os-guides/linux-hvm-tips.md rename to en/_doc/external/os-guides/linux-hvm-tips.md diff --git a/external/os-guides/netbsd.md b/en/_doc/external/os-guides/netbsd.md similarity index 100% rename from external/os-guides/netbsd.md rename to en/_doc/external/os-guides/netbsd.md diff --git a/external/os-guides/pentesting.md b/en/_doc/external/os-guides/pentesting.md similarity index 100% rename from external/os-guides/pentesting.md rename to en/_doc/external/os-guides/pentesting.md diff --git a/external/os-guides/pentesting/blackarch.md b/en/_doc/external/os-guides/pentesting/blackarch.md similarity index 100% rename from external/os-guides/pentesting/blackarch.md rename to en/_doc/external/os-guides/pentesting/blackarch.md diff --git a/external/os-guides/pentesting/kali.md b/en/_doc/external/os-guides/pentesting/kali.md similarity index 100% rename from external/os-guides/pentesting/kali.md rename to en/_doc/external/os-guides/pentesting/kali.md diff --git a/external/os-guides/pentesting/ptf.md b/en/_doc/external/os-guides/pentesting/ptf.md similarity index 100% rename from external/os-guides/pentesting/ptf.md rename to en/_doc/external/os-guides/pentesting/ptf.md diff --git a/external/os-guides/ubuntu.md b/en/_doc/external/os-guides/ubuntu.md similarity index 100% rename from external/os-guides/ubuntu.md rename to en/_doc/external/os-guides/ubuntu.md diff --git a/external/os-guides/windows/windows-tools.md b/en/_doc/external/os-guides/windows/windows-tools.md similarity index 100% rename from external/os-guides/windows/windows-tools.md rename to en/_doc/external/os-guides/windows/windows-tools.md diff --git a/external/os-guides/windows/windows-vm.md b/en/_doc/external/os-guides/windows/windows-vm.md similarity index 100% rename from external/os-guides/windows/windows-vm.md rename to en/_doc/external/os-guides/windows/windows-vm.md diff --git a/external/privacy-guides/anonymizing-your-mac-address.md b/en/_doc/external/privacy-guides/anonymizing-your-mac-address.md similarity index 100% rename from external/privacy-guides/anonymizing-your-mac-address.md rename to en/_doc/external/privacy-guides/anonymizing-your-mac-address.md diff --git a/external/privacy-guides/signal.md b/en/_doc/external/privacy-guides/signal.md similarity index 100% rename from external/privacy-guides/signal.md rename to en/_doc/external/privacy-guides/signal.md diff --git a/external/privacy-guides/tails.md b/en/_doc/external/privacy-guides/tails.md similarity index 100% rename from external/privacy-guides/tails.md rename to en/_doc/external/privacy-guides/tails.md diff --git a/external/privacy-guides/torvm.md b/en/_doc/external/privacy-guides/torvm.md similarity index 100% rename from external/privacy-guides/torvm.md rename to en/_doc/external/privacy-guides/torvm.md diff --git a/external/privacy-guides/whonix.md b/en/_doc/external/privacy-guides/whonix.md similarity index 100% rename from external/privacy-guides/whonix.md rename to en/_doc/external/privacy-guides/whonix.md diff --git a/external/security-guides/multifactor-authentication.md b/en/_doc/external/security-guides/multifactor-authentication.md similarity index 100% rename from external/security-guides/multifactor-authentication.md rename to en/_doc/external/security-guides/multifactor-authentication.md diff --git a/external/security-guides/security-guidelines.md b/en/_doc/external/security-guides/security-guidelines.md similarity index 100% rename from external/security-guides/security-guidelines.md rename to en/_doc/external/security-guides/security-guidelines.md diff --git a/external/security-guides/split-bitcoin.md b/en/_doc/external/security-guides/split-bitcoin.md similarity index 100% rename from external/security-guides/split-bitcoin.md rename to en/_doc/external/security-guides/split-bitcoin.md diff --git a/introduction/code-of-conduct.md b/en/_doc/introduction/code-of-conduct.md similarity index 100% rename from introduction/code-of-conduct.md rename to en/_doc/introduction/code-of-conduct.md diff --git a/introduction/contributing.md b/en/_doc/introduction/contributing.md similarity index 100% rename from introduction/contributing.md rename to en/_doc/introduction/contributing.md diff --git a/introduction/experts.md b/en/_doc/introduction/experts.md similarity index 100% rename from introduction/experts.md rename to en/_doc/introduction/experts.md diff --git a/introduction/faq.md b/en/_doc/introduction/faq.md similarity index 100% rename from introduction/faq.md rename to en/_doc/introduction/faq.md diff --git a/introduction/intro.md b/en/_doc/introduction/intro.md similarity index 100% rename from introduction/intro.md rename to en/_doc/introduction/intro.md diff --git a/introduction/reporting-bugs.md b/en/_doc/introduction/reporting-bugs.md similarity index 100% rename from introduction/reporting-bugs.md rename to en/_doc/introduction/reporting-bugs.md diff --git a/introduction/screenshots.md b/en/_doc/introduction/screenshots.md similarity index 100% rename from introduction/screenshots.md rename to en/_doc/introduction/screenshots.md diff --git a/introduction/statistics.md b/en/_doc/introduction/statistics.md similarity index 100% rename from introduction/statistics.md rename to en/_doc/introduction/statistics.md diff --git a/introduction/support.md b/en/_doc/introduction/support.md similarity index 100% rename from introduction/support.md rename to en/_doc/introduction/support.md diff --git a/introduction/video-tours.md b/en/_doc/introduction/video-tours.md similarity index 100% rename from introduction/video-tours.md rename to en/_doc/introduction/video-tours.md diff --git a/project-security/canaries.md b/en/_doc/project-security/canaries.md similarity index 100% rename from project-security/canaries.md rename to en/_doc/project-security/canaries.md diff --git a/project-security/canary-checklist.md b/en/_doc/project-security/canary-checklist.md similarity index 100% rename from project-security/canary-checklist.md rename to en/_doc/project-security/canary-checklist.md diff --git a/project-security/canary-template.md b/en/_doc/project-security/canary-template.md similarity index 100% rename from project-security/canary-template.md rename to en/_doc/project-security/canary-template.md diff --git a/project-security/security-bulletins-checklist.md b/en/_doc/project-security/security-bulletins-checklist.md similarity index 100% rename from project-security/security-bulletins-checklist.md rename to en/_doc/project-security/security-bulletins-checklist.md diff --git a/project-security/security-bulletins-template.md b/en/_doc/project-security/security-bulletins-template.md similarity index 100% rename from project-security/security-bulletins-template.md rename to en/_doc/project-security/security-bulletins-template.md diff --git a/project-security/security-bulletins.md b/en/_doc/project-security/security-bulletins.md similarity index 100% rename from project-security/security-bulletins.md rename to en/_doc/project-security/security-bulletins.md diff --git a/project-security/security-goals.md b/en/_doc/project-security/security-goals.md similarity index 100% rename from project-security/security-goals.md rename to en/_doc/project-security/security-goals.md diff --git a/project-security/security-pack.md b/en/_doc/project-security/security-pack.md similarity index 100% rename from project-security/security-pack.md rename to en/_doc/project-security/security-pack.md diff --git a/project-security/security.md b/en/_doc/project-security/security.md similarity index 100% rename from project-security/security.md rename to en/_doc/project-security/security.md diff --git a/project-security/verifying-signatures.md b/en/_doc/project-security/verifying-signatures.md similarity index 100% rename from project-security/verifying-signatures.md rename to en/_doc/project-security/verifying-signatures.md diff --git a/project-security/xsa.md b/en/_doc/project-security/xsa.md similarity index 100% rename from project-security/xsa.md rename to en/_doc/project-security/xsa.md diff --git a/user/advanced-configuration/awesome.md b/en/_doc/user/advanced-configuration/awesome.md similarity index 100% rename from user/advanced-configuration/awesome.md rename to en/_doc/user/advanced-configuration/awesome.md diff --git a/user/advanced-configuration/bind-dirs.md b/en/_doc/user/advanced-configuration/bind-dirs.md similarity index 100% rename from user/advanced-configuration/bind-dirs.md rename to en/_doc/user/advanced-configuration/bind-dirs.md diff --git a/user/advanced-configuration/config-files.md b/en/_doc/user/advanced-configuration/config-files.md similarity index 100% rename from user/advanced-configuration/config-files.md rename to en/_doc/user/advanced-configuration/config-files.md diff --git a/user/advanced-configuration/disposablevm-customization.md b/en/_doc/user/advanced-configuration/disposablevm-customization.md similarity index 100% rename from user/advanced-configuration/disposablevm-customization.md rename to en/_doc/user/advanced-configuration/disposablevm-customization.md diff --git a/user/advanced-configuration/gui-configuration.md b/en/_doc/user/advanced-configuration/gui-configuration.md similarity index 100% rename from user/advanced-configuration/gui-configuration.md rename to en/_doc/user/advanced-configuration/gui-configuration.md diff --git a/user/advanced-configuration/i3.md b/en/_doc/user/advanced-configuration/i3.md similarity index 100% rename from user/advanced-configuration/i3.md rename to en/_doc/user/advanced-configuration/i3.md diff --git a/user/advanced-configuration/kde.md b/en/_doc/user/advanced-configuration/kde.md similarity index 100% rename from user/advanced-configuration/kde.md rename to en/_doc/user/advanced-configuration/kde.md diff --git a/user/advanced-configuration/managing-vm-kernel.md b/en/_doc/user/advanced-configuration/managing-vm-kernel.md similarity index 100% rename from user/advanced-configuration/managing-vm-kernel.md rename to en/_doc/user/advanced-configuration/managing-vm-kernel.md diff --git a/user/advanced-configuration/mount-from-other-os.md b/en/_doc/user/advanced-configuration/mount-from-other-os.md similarity index 100% rename from user/advanced-configuration/mount-from-other-os.md rename to en/_doc/user/advanced-configuration/mount-from-other-os.md diff --git a/user/advanced-configuration/newer-hardware-troubleshooting.md b/en/_doc/user/advanced-configuration/newer-hardware-troubleshooting.md similarity index 100% rename from user/advanced-configuration/newer-hardware-troubleshooting.md rename to en/_doc/user/advanced-configuration/newer-hardware-troubleshooting.md diff --git a/user/advanced-configuration/resize-disk-image.md b/en/_doc/user/advanced-configuration/resize-disk-image.md similarity index 100% rename from user/advanced-configuration/resize-disk-image.md rename to en/_doc/user/advanced-configuration/resize-disk-image.md diff --git a/user/advanced-configuration/rpc-policy.md b/en/_doc/user/advanced-configuration/rpc-policy.md similarity index 100% rename from user/advanced-configuration/rpc-policy.md rename to en/_doc/user/advanced-configuration/rpc-policy.md diff --git a/user/advanced-configuration/salt.md b/en/_doc/user/advanced-configuration/salt.md similarity index 100% rename from user/advanced-configuration/salt.md rename to en/_doc/user/advanced-configuration/salt.md diff --git a/user/advanced-configuration/secondary-storage.md b/en/_doc/user/advanced-configuration/secondary-storage.md similarity index 100% rename from user/advanced-configuration/secondary-storage.md rename to en/_doc/user/advanced-configuration/secondary-storage.md diff --git a/user/advanced-configuration/usb-qubes.md b/en/_doc/user/advanced-configuration/usb-qubes.md similarity index 100% rename from user/advanced-configuration/usb-qubes.md rename to en/_doc/user/advanced-configuration/usb-qubes.md diff --git a/user/common-tasks/backup-emergency-restore-v2.md b/en/_doc/user/common-tasks/backup-emergency-restore-v2.md similarity index 100% rename from user/common-tasks/backup-emergency-restore-v2.md rename to en/_doc/user/common-tasks/backup-emergency-restore-v2.md diff --git a/user/common-tasks/backup-emergency-restore-v3.md b/en/_doc/user/common-tasks/backup-emergency-restore-v3.md similarity index 100% rename from user/common-tasks/backup-emergency-restore-v3.md rename to en/_doc/user/common-tasks/backup-emergency-restore-v3.md diff --git a/user/common-tasks/backup-emergency-restore-v4.md b/en/_doc/user/common-tasks/backup-emergency-restore-v4.md similarity index 100% rename from user/common-tasks/backup-emergency-restore-v4.md rename to en/_doc/user/common-tasks/backup-emergency-restore-v4.md diff --git a/user/common-tasks/backup-restore.md b/en/_doc/user/common-tasks/backup-restore.md similarity index 100% rename from user/common-tasks/backup-restore.md rename to en/_doc/user/common-tasks/backup-restore.md diff --git a/user/common-tasks/block-devices.md b/en/_doc/user/common-tasks/block-devices.md similarity index 100% rename from user/common-tasks/block-devices.md rename to en/_doc/user/common-tasks/block-devices.md diff --git a/user/common-tasks/copy-from-dom0.md b/en/_doc/user/common-tasks/copy-from-dom0.md similarity index 100% rename from user/common-tasks/copy-from-dom0.md rename to en/_doc/user/common-tasks/copy-from-dom0.md diff --git a/user/common-tasks/copy-paste.md b/en/_doc/user/common-tasks/copy-paste.md similarity index 100% rename from user/common-tasks/copy-paste.md rename to en/_doc/user/common-tasks/copy-paste.md diff --git a/user/common-tasks/copying-files.md b/en/_doc/user/common-tasks/copying-files.md similarity index 100% rename from user/common-tasks/copying-files.md rename to en/_doc/user/common-tasks/copying-files.md diff --git a/user/common-tasks/device-handling.md b/en/_doc/user/common-tasks/device-handling.md similarity index 100% rename from user/common-tasks/device-handling.md rename to en/_doc/user/common-tasks/device-handling.md diff --git a/user/common-tasks/disposablevm.md b/en/_doc/user/common-tasks/disposablevm.md similarity index 100% rename from user/common-tasks/disposablevm.md rename to en/_doc/user/common-tasks/disposablevm.md diff --git a/user/common-tasks/full-screen-mode.md b/en/_doc/user/common-tasks/full-screen-mode.md similarity index 100% rename from user/common-tasks/full-screen-mode.md rename to en/_doc/user/common-tasks/full-screen-mode.md diff --git a/user/common-tasks/getting-started.md b/en/_doc/user/common-tasks/getting-started.md similarity index 100% rename from user/common-tasks/getting-started.md rename to en/_doc/user/common-tasks/getting-started.md diff --git a/user/common-tasks/managing-appvm-shortcuts.md b/en/_doc/user/common-tasks/managing-appvm-shortcuts.md similarity index 100% rename from user/common-tasks/managing-appvm-shortcuts.md rename to en/_doc/user/common-tasks/managing-appvm-shortcuts.md diff --git a/user/common-tasks/optical-discs.md b/en/_doc/user/common-tasks/optical-discs.md similarity index 100% rename from user/common-tasks/optical-discs.md rename to en/_doc/user/common-tasks/optical-discs.md diff --git a/user/common-tasks/pci-devices.md b/en/_doc/user/common-tasks/pci-devices.md similarity index 100% rename from user/common-tasks/pci-devices.md rename to en/_doc/user/common-tasks/pci-devices.md diff --git a/user/common-tasks/software-update-dom0.md b/en/_doc/user/common-tasks/software-update-dom0.md similarity index 100% rename from user/common-tasks/software-update-dom0.md rename to en/_doc/user/common-tasks/software-update-dom0.md diff --git a/user/common-tasks/software-update-domu.md b/en/_doc/user/common-tasks/software-update-domu.md similarity index 100% rename from user/common-tasks/software-update-domu.md rename to en/_doc/user/common-tasks/software-update-domu.md diff --git a/user/common-tasks/updating-qubes-os.md b/en/_doc/user/common-tasks/updating-qubes-os.md similarity index 100% rename from user/common-tasks/updating-qubes-os.md rename to en/_doc/user/common-tasks/updating-qubes-os.md diff --git a/user/common-tasks/usb-devices.md b/en/_doc/user/common-tasks/usb-devices.md similarity index 100% rename from user/common-tasks/usb-devices.md rename to en/_doc/user/common-tasks/usb-devices.md diff --git a/user/common-tasks/volume-backup-revert.md b/en/_doc/user/common-tasks/volume-backup-revert.md similarity index 100% rename from user/common-tasks/volume-backup-revert.md rename to en/_doc/user/common-tasks/volume-backup-revert.md diff --git a/user/downloading-installing-upgrading/custom-install.md b/en/_doc/user/downloading-installing-upgrading/custom-install.md similarity index 100% rename from user/downloading-installing-upgrading/custom-install.md rename to en/_doc/user/downloading-installing-upgrading/custom-install.md diff --git a/user/downloading-installing-upgrading/download-mirrors.md b/en/_doc/user/downloading-installing-upgrading/download-mirrors.md similarity index 100% rename from user/downloading-installing-upgrading/download-mirrors.md rename to en/_doc/user/downloading-installing-upgrading/download-mirrors.md diff --git a/user/downloading-installing-upgrading/install-security.md b/en/_doc/user/downloading-installing-upgrading/install-security.md similarity index 100% rename from user/downloading-installing-upgrading/install-security.md rename to en/_doc/user/downloading-installing-upgrading/install-security.md diff --git a/user/downloading-installing-upgrading/installation-guide.md b/en/_doc/user/downloading-installing-upgrading/installation-guide.md similarity index 100% rename from user/downloading-installing-upgrading/installation-guide.md rename to en/_doc/user/downloading-installing-upgrading/installation-guide.md diff --git a/user/downloading-installing-upgrading/live-usb.md b/en/_doc/user/downloading-installing-upgrading/live-usb.md similarity index 100% rename from user/downloading-installing-upgrading/live-usb.md rename to en/_doc/user/downloading-installing-upgrading/live-usb.md diff --git a/user/downloading-installing-upgrading/supported-versions.md b/en/_doc/user/downloading-installing-upgrading/supported-versions.md similarity index 100% rename from user/downloading-installing-upgrading/supported-versions.md rename to en/_doc/user/downloading-installing-upgrading/supported-versions.md diff --git a/user/downloading-installing-upgrading/testing.md b/en/_doc/user/downloading-installing-upgrading/testing.md similarity index 100% rename from user/downloading-installing-upgrading/testing.md rename to en/_doc/user/downloading-installing-upgrading/testing.md diff --git a/user/downloading-installing-upgrading/upgrade/upgrade-to-r2.md b/en/_doc/user/downloading-installing-upgrading/upgrade/upgrade-to-r2.md similarity index 100% rename from user/downloading-installing-upgrading/upgrade/upgrade-to-r2.md rename to en/_doc/user/downloading-installing-upgrading/upgrade/upgrade-to-r2.md diff --git a/user/downloading-installing-upgrading/upgrade/upgrade-to-r2b1.md b/en/_doc/user/downloading-installing-upgrading/upgrade/upgrade-to-r2b1.md similarity index 100% rename from user/downloading-installing-upgrading/upgrade/upgrade-to-r2b1.md rename to en/_doc/user/downloading-installing-upgrading/upgrade/upgrade-to-r2b1.md diff --git a/user/downloading-installing-upgrading/upgrade/upgrade-to-r2b2.md b/en/_doc/user/downloading-installing-upgrading/upgrade/upgrade-to-r2b2.md similarity index 100% rename from user/downloading-installing-upgrading/upgrade/upgrade-to-r2b2.md rename to en/_doc/user/downloading-installing-upgrading/upgrade/upgrade-to-r2b2.md diff --git a/user/downloading-installing-upgrading/upgrade/upgrade-to-r2b3.md b/en/_doc/user/downloading-installing-upgrading/upgrade/upgrade-to-r2b3.md similarity index 100% rename from user/downloading-installing-upgrading/upgrade/upgrade-to-r2b3.md rename to en/_doc/user/downloading-installing-upgrading/upgrade/upgrade-to-r2b3.md diff --git a/user/downloading-installing-upgrading/upgrade/upgrade-to-r3_0.md b/en/_doc/user/downloading-installing-upgrading/upgrade/upgrade-to-r3_0.md similarity index 100% rename from user/downloading-installing-upgrading/upgrade/upgrade-to-r3_0.md rename to en/_doc/user/downloading-installing-upgrading/upgrade/upgrade-to-r3_0.md diff --git a/user/downloading-installing-upgrading/upgrade/upgrade-to-r3_1.md b/en/_doc/user/downloading-installing-upgrading/upgrade/upgrade-to-r3_1.md similarity index 100% rename from user/downloading-installing-upgrading/upgrade/upgrade-to-r3_1.md rename to en/_doc/user/downloading-installing-upgrading/upgrade/upgrade-to-r3_1.md diff --git a/user/downloading-installing-upgrading/upgrade/upgrade-to-r3_2.md b/en/_doc/user/downloading-installing-upgrading/upgrade/upgrade-to-r3_2.md similarity index 100% rename from user/downloading-installing-upgrading/upgrade/upgrade-to-r3_2.md rename to en/_doc/user/downloading-installing-upgrading/upgrade/upgrade-to-r3_2.md diff --git a/user/downloading-installing-upgrading/upgrade/upgrade-to-r4_0.md b/en/_doc/user/downloading-installing-upgrading/upgrade/upgrade-to-r4_0.md similarity index 100% rename from user/downloading-installing-upgrading/upgrade/upgrade-to-r4_0.md rename to en/_doc/user/downloading-installing-upgrading/upgrade/upgrade-to-r4_0.md diff --git a/user/downloading-installing-upgrading/upgrade/upgrade.md b/en/_doc/user/downloading-installing-upgrading/upgrade/upgrade.md similarity index 100% rename from user/downloading-installing-upgrading/upgrade/upgrade.md rename to en/_doc/user/downloading-installing-upgrading/upgrade/upgrade.md diff --git a/user/downloading-installing-upgrading/version-scheme.md b/en/_doc/user/downloading-installing-upgrading/version-scheme.md similarity index 100% rename from user/downloading-installing-upgrading/version-scheme.md rename to en/_doc/user/downloading-installing-upgrading/version-scheme.md diff --git a/user/hardware/certified-hardware.md b/en/_doc/user/hardware/certified-hardware.md similarity index 100% rename from user/hardware/certified-hardware.md rename to en/_doc/user/hardware/certified-hardware.md diff --git a/user/hardware/hardware-testing.md b/en/_doc/user/hardware/hardware-testing.md similarity index 100% rename from user/hardware/hardware-testing.md rename to en/_doc/user/hardware/hardware-testing.md diff --git a/user/hardware/hcl_listing.md b/en/_doc/user/hardware/hcl_listing.md similarity index 100% rename from user/hardware/hcl_listing.md rename to en/_doc/user/hardware/hcl_listing.md diff --git a/user/hardware/hcl_md.md b/en/_doc/user/hardware/hcl_md.md similarity index 100% rename from user/hardware/hcl_md.md rename to en/_doc/user/hardware/hcl_md.md diff --git a/user/hardware/system-requirements.md b/en/_doc/user/hardware/system-requirements.md similarity index 100% rename from user/hardware/system-requirements.md rename to en/_doc/user/hardware/system-requirements.md diff --git a/user/managing-os/debian/debian-upgrade.md b/en/_doc/user/managing-os/debian/debian-upgrade.md similarity index 100% rename from user/managing-os/debian/debian-upgrade.md rename to en/_doc/user/managing-os/debian/debian-upgrade.md diff --git a/user/managing-os/debian/debian.md b/en/_doc/user/managing-os/debian/debian.md similarity index 100% rename from user/managing-os/debian/debian.md rename to en/_doc/user/managing-os/debian/debian.md diff --git a/user/managing-os/fedora/fedora-upgrade.md b/en/_doc/user/managing-os/fedora/fedora-upgrade.md similarity index 100% rename from user/managing-os/fedora/fedora-upgrade.md rename to en/_doc/user/managing-os/fedora/fedora-upgrade.md diff --git a/user/managing-os/fedora/fedora-xfce.md b/en/_doc/user/managing-os/fedora/fedora-xfce.md similarity index 100% rename from user/managing-os/fedora/fedora-xfce.md rename to en/_doc/user/managing-os/fedora/fedora-xfce.md diff --git a/user/managing-os/fedora/fedora.md b/en/_doc/user/managing-os/fedora/fedora.md similarity index 100% rename from user/managing-os/fedora/fedora.md rename to en/_doc/user/managing-os/fedora/fedora.md diff --git a/user/managing-os/minimal-templates.md b/en/_doc/user/managing-os/minimal-templates.md similarity index 100% rename from user/managing-os/minimal-templates.md rename to en/_doc/user/managing-os/minimal-templates.md diff --git a/user/managing-os/reinstall-template.md b/en/_doc/user/managing-os/reinstall-template.md similarity index 100% rename from user/managing-os/reinstall-template.md rename to en/_doc/user/managing-os/reinstall-template.md diff --git a/user/managing-os/standalone-and-hvm.md b/en/_doc/user/managing-os/standalone-and-hvm.md similarity index 100% rename from user/managing-os/standalone-and-hvm.md rename to en/_doc/user/managing-os/standalone-and-hvm.md diff --git a/user/managing-os/templates.md b/en/_doc/user/managing-os/templates.md similarity index 100% rename from user/managing-os/templates.md rename to en/_doc/user/managing-os/templates.md diff --git a/user/managing-os/windows.md b/en/_doc/user/managing-os/windows.md similarity index 100% rename from user/managing-os/windows.md rename to en/_doc/user/managing-os/windows.md diff --git a/user/managing-os/xfce-templates.md b/en/_doc/user/managing-os/xfce-templates.md similarity index 100% rename from user/managing-os/xfce-templates.md rename to en/_doc/user/managing-os/xfce-templates.md diff --git a/user/reference/glossary.md b/en/_doc/user/reference/glossary.md similarity index 100% rename from user/reference/glossary.md rename to en/_doc/user/reference/glossary.md diff --git a/user/reference/qubes-service.md b/en/_doc/user/reference/qubes-service.md similarity index 100% rename from user/reference/qubes-service.md rename to en/_doc/user/reference/qubes-service.md diff --git a/user/reference/research.md b/en/_doc/user/reference/research.md similarity index 100% rename from user/reference/research.md rename to en/_doc/user/reference/research.md diff --git a/user/reference/tools.md b/en/_doc/user/reference/tools.md similarity index 100% rename from user/reference/tools.md rename to en/_doc/user/reference/tools.md diff --git a/user/security-in-qubes/anti-evil-maid.md b/en/_doc/user/security-in-qubes/anti-evil-maid.md similarity index 100% rename from user/security-in-qubes/anti-evil-maid.md rename to en/_doc/user/security-in-qubes/anti-evil-maid.md diff --git a/user/security-in-qubes/data-leaks.md b/en/_doc/user/security-in-qubes/data-leaks.md similarity index 100% rename from user/security-in-qubes/data-leaks.md rename to en/_doc/user/security-in-qubes/data-leaks.md diff --git a/user/security-in-qubes/device-handling-security.md b/en/_doc/user/security-in-qubes/device-handling-security.md similarity index 100% rename from user/security-in-qubes/device-handling-security.md rename to en/_doc/user/security-in-qubes/device-handling-security.md diff --git a/user/security-in-qubes/firewall.md b/en/_doc/user/security-in-qubes/firewall.md similarity index 100% rename from user/security-in-qubes/firewall.md rename to en/_doc/user/security-in-qubes/firewall.md diff --git a/user/security-in-qubes/split-gpg.md b/en/_doc/user/security-in-qubes/split-gpg.md similarity index 100% rename from user/security-in-qubes/split-gpg.md rename to en/_doc/user/security-in-qubes/split-gpg.md diff --git a/user/security-in-qubes/u2f-proxy.md b/en/_doc/user/security-in-qubes/u2f-proxy.md similarity index 100% rename from user/security-in-qubes/u2f-proxy.md rename to en/_doc/user/security-in-qubes/u2f-proxy.md diff --git a/user/security-in-qubes/vm-sudo.md b/en/_doc/user/security-in-qubes/vm-sudo.md similarity index 100% rename from user/security-in-qubes/vm-sudo.md rename to en/_doc/user/security-in-qubes/vm-sudo.md diff --git a/user/security-in-qubes/yubi-key.md b/en/_doc/user/security-in-qubes/yubi-key.md similarity index 100% rename from user/security-in-qubes/yubi-key.md rename to en/_doc/user/security-in-qubes/yubi-key.md diff --git a/user/troubleshooting/install-nvidia-driver.md b/en/_doc/user/troubleshooting/install-nvidia-driver.md similarity index 100% rename from user/troubleshooting/install-nvidia-driver.md rename to en/_doc/user/troubleshooting/install-nvidia-driver.md diff --git a/user/troubleshooting/installation-troubleshooting.md b/en/_doc/user/troubleshooting/installation-troubleshooting.md similarity index 100% rename from user/troubleshooting/installation-troubleshooting.md rename to en/_doc/user/troubleshooting/installation-troubleshooting.md diff --git a/user/troubleshooting/intel-igfx-troubleshooting.md b/en/_doc/user/troubleshooting/intel-igfx-troubleshooting.md similarity index 100% rename from user/troubleshooting/intel-igfx-troubleshooting.md rename to en/_doc/user/troubleshooting/intel-igfx-troubleshooting.md diff --git a/user/troubleshooting/macbook-troubleshooting.md b/en/_doc/user/troubleshooting/macbook-troubleshooting.md similarity index 100% rename from user/troubleshooting/macbook-troubleshooting.md rename to en/_doc/user/troubleshooting/macbook-troubleshooting.md diff --git a/user/troubleshooting/nvidia-troubleshooting.md b/en/_doc/user/troubleshooting/nvidia-troubleshooting.md similarity index 100% rename from user/troubleshooting/nvidia-troubleshooting.md rename to en/_doc/user/troubleshooting/nvidia-troubleshooting.md diff --git a/user/troubleshooting/out-of-memory.md b/en/_doc/user/troubleshooting/out-of-memory.md similarity index 100% rename from user/troubleshooting/out-of-memory.md rename to en/_doc/user/troubleshooting/out-of-memory.md diff --git a/user/troubleshooting/remove-vm-manually.md b/en/_doc/user/troubleshooting/remove-vm-manually.md similarity index 100% rename from user/troubleshooting/remove-vm-manually.md rename to en/_doc/user/troubleshooting/remove-vm-manually.md diff --git a/user/troubleshooting/sony-vaio-tinkering.md b/en/_doc/user/troubleshooting/sony-vaio-tinkering.md similarity index 100% rename from user/troubleshooting/sony-vaio-tinkering.md rename to en/_doc/user/troubleshooting/sony-vaio-tinkering.md diff --git a/user/troubleshooting/thinkpad-troubleshooting.md b/en/_doc/user/troubleshooting/thinkpad-troubleshooting.md similarity index 100% rename from user/troubleshooting/thinkpad-troubleshooting.md rename to en/_doc/user/troubleshooting/thinkpad-troubleshooting.md diff --git a/user/troubleshooting/uefi-troubleshooting.md b/en/_doc/user/troubleshooting/uefi-troubleshooting.md similarity index 100% rename from user/troubleshooting/uefi-troubleshooting.md rename to en/_doc/user/troubleshooting/uefi-troubleshooting.md diff --git a/user/troubleshooting/updating-debian-and-whonix.md b/en/_doc/user/troubleshooting/updating-debian-and-whonix.md similarity index 100% rename from user/troubleshooting/updating-debian-and-whonix.md rename to en/_doc/user/troubleshooting/updating-debian-and-whonix.md diff --git a/user/troubleshooting/wireless-troubleshooting.md b/en/_doc/user/troubleshooting/wireless-troubleshooting.md similarity index 100% rename from user/troubleshooting/wireless-troubleshooting.md rename to en/_doc/user/troubleshooting/wireless-troubleshooting.md From be75075705f2a7e0922ad59b9d1be44d5fd61418 Mon Sep 17 00:00:00 2001 From: dd Date: Mon, 19 Oct 2020 22:47:44 +0200 Subject: [PATCH 032/663] ref & lang attribute for new doc files --- en/_doc/external/os-guides/gentoo.md | 6 ++++-- .../installing-contributed-packages.md | 5 +++-- en/_doc/user/managing-os/xfce-templates.md | 5 +++-- .../user/troubleshooting/installation-troubleshooting.md | 8 ++++---- en/_doc/user/troubleshooting/vm-troubleshooting.md | 6 ++++-- 5 files changed, 18 insertions(+), 12 deletions(-) diff --git a/en/_doc/external/os-guides/gentoo.md b/en/_doc/external/os-guides/gentoo.md index 219c205b3e..4deb8b25aa 100644 --- a/en/_doc/external/os-guides/gentoo.md +++ b/en/_doc/external/os-guides/gentoo.md @@ -1,7 +1,9 @@ --- +lang: en layout: doc -title: Gentoo Template permalink: /doc/templates/gentoo/ +ref: 221 +title: Gentoo Template --- # Gentoo Template @@ -32,4 +34,4 @@ After a fresh install, we recommend to [Update the TemplateVM](/doc/software-upd [uninstall]: /doc/templates/#uninstalling [Minimal TemplateVMs]: /doc/templates/minimal/ [Xfce TemplateVMs]: /doc/templates/xfce/ -[Gentoo Handbook]: https://wiki.gentoo.org/wiki/Handbook:AMD64 \ No newline at end of file +[Gentoo Handbook]: https://wiki.gentoo.org/wiki/Handbook:AMD64 diff --git a/en/_doc/user/advanced-configuration/installing-contributed-packages.md b/en/_doc/user/advanced-configuration/installing-contributed-packages.md index 31fb395edd..6a4fd6c1ce 100644 --- a/en/_doc/user/advanced-configuration/installing-contributed-packages.md +++ b/en/_doc/user/advanced-configuration/installing-contributed-packages.md @@ -1,7 +1,9 @@ --- +lang: en layout: doc -title: Installing contributed packages permalink: /doc/installing-contributed-packages/ +ref: 225 +title: Installing contributed packages --- # Installing contributed packages @@ -48,4 +50,3 @@ Please see the package's README for specific installation and setup instructions [package contributions]: /doc/package-contributions/ [QubesOS-contrib]: https://github.com/QubesOS-contrib/ - diff --git a/en/_doc/user/managing-os/xfce-templates.md b/en/_doc/user/managing-os/xfce-templates.md index 4762b64fe3..2afecdc44f 100644 --- a/en/_doc/user/managing-os/xfce-templates.md +++ b/en/_doc/user/managing-os/xfce-templates.md @@ -1,13 +1,14 @@ --- +lang: en layout: doc -title: Xfce TemplateVMs permalink: /doc/templates/xfce/ redirect_from: -- /doc/templates/xfce/ - /doc/xfce/ - /en/doc/templates/xfce/ - /doc/Templates/Xfce/ - /wiki/Templates/Xfce/ +ref: 222 +title: Xfce TemplateVMs --- # Xfce TemplateVMs diff --git a/en/_doc/user/troubleshooting/installation-troubleshooting.md b/en/_doc/user/troubleshooting/installation-troubleshooting.md index f3d51fcb9f..72cefdb7aa 100644 --- a/en/_doc/user/troubleshooting/installation-troubleshooting.md +++ b/en/_doc/user/troubleshooting/installation-troubleshooting.md @@ -1,8 +1,11 @@ --- +lang: en layout: doc -title: Installation Troubleshooting permalink: /doc/installation-troubleshooting/ +ref: 224 +title: Installation Troubleshooting --- + # Installation Troubleshooting # ## "An unknown error has occurred" error during installation ## @@ -77,6 +80,3 @@ If installing the available drivers does not help, disable the network card in t If this solves the issue, it confirms the PCI card is incompatible with Qubes. In this case, you may want to consider replacing it with a network card of a different brand. Broadcom cards are notoriously problematic with Qubes. - - - diff --git a/en/_doc/user/troubleshooting/vm-troubleshooting.md b/en/_doc/user/troubleshooting/vm-troubleshooting.md index 5fbbf2a449..10d3e545ee 100644 --- a/en/_doc/user/troubleshooting/vm-troubleshooting.md +++ b/en/_doc/user/troubleshooting/vm-troubleshooting.md @@ -1,9 +1,11 @@ --- +lang: en layout: doc -title: VM Troubleshooting permalink: /doc/vm-troubleshooting/ redirect_from: - /doc/remove-vm-manually/ +ref: 223 +title: VM Troubleshooting --- # VM troubleshooting # @@ -70,4 +72,4 @@ One solution is to add a dummy interface to allow the package to install correct If you face this error when starting a VM, look into the VM logs at `/var/log/xen/console/guest-VMNAME.log`. Common reasons that may be revealed are: too low memory, corrupted files or a VM crash on startup. -If the error occurs as a result of too little initial memory, increase the initial memory from 200MB to 400MB by navigating to VM settings » Advanced » Initial memory. +If the error occurs as a result of too little initial memory, increase the initial memory from 200MB to 400MB by navigating to VM settings » Advanced » Initial memory. From b45b31532954df60e8009580e97fc0789ca0705c Mon Sep 17 00:00:00 2001 From: dd Date: Tue, 20 Oct 2020 21:26:48 +0200 Subject: [PATCH 033/663] run mardkwon linter over developer building docs and fixed minor stuff --- .../building/development-workflow.md | 18 ++- .../building/qubes-builder-details.md | 36 +++--- en/_doc/developer/building/qubes-builder.md | 115 ++++++++++-------- .../developer/building/qubes-iso-building.md | 4 +- 4 files changed, 93 insertions(+), 80 deletions(-) diff --git a/en/_doc/developer/building/development-workflow.md b/en/_doc/developer/building/development-workflow.md index 3e801aa07f..2bfc0b9502 100644 --- a/en/_doc/developer/building/development-workflow.md +++ b/en/_doc/developer/building/development-workflow.md @@ -10,16 +10,14 @@ ref: 66 title: Development Workflow --- -Development Workflow -==================== +# Development Workflow A workflow for developing Qubes OS+ First things first, setup [QubesBuilder](/doc/qubes-builder/). This guide assumes you're using qubes-builder to build Qubes. -Repositories and committing Code --------------------------------- +# Repositories and committing Code Qubes is split into a bunch of git repos. This are all contained in the `qubes-src` directory under qubes-builder. Subdirectories there are separate @@ -164,8 +162,7 @@ verify tags and show the changes. This do not merge the changes - there are left for review as FETCH\_HEAD ref. You can merge them using `git merge FETCH_HEAD` (in each repo directory). Or `make do-merge` to merge all of them. -Copying Code to dom0 --------------------- +## Copying Code to dom0 When developing it is convenient to be able to rapidly test changes. Assuming you're developing Qubes on Qubes, you should be working in a special VM for @@ -311,7 +308,6 @@ to `testbuilder` VM. Otherwise it creates remote pointing at github account of the same name. In any case it points at repository matching current directory name. - ## Sending packages to different VM Other useful script(s) can be used to setup local package repository hosted in @@ -423,10 +419,10 @@ Remember to also import gpg public key using `rpm --import`. Steps are mostly the same as in the case of yum repo. The only details that differ: - - use [linux-deb] instead of [linux-yum] as a base - both in source and target VM - - use different `update_repo.sh` script in source VM (below) - - use `local.UpdateApt` qrexec service in target VM (code below) - - in target VM additionally place `update-local-repo.sh` script in repository dir (code below) +- use [linux-deb] instead of [linux-yum] as a base - both in source and target VM +- use different `update_repo.sh` script in source VM (below) +- use `local.UpdateApt` qrexec service in target VM (code below) +- in target VM additionally place `update-local-repo.sh` script in repository dir (code below) `update_repo.sh` script: diff --git a/en/_doc/developer/building/qubes-builder-details.md b/en/_doc/developer/building/qubes-builder-details.md index 3677eba2d1..aa8ecbbdd7 100644 --- a/en/_doc/developer/building/qubes-builder-details.md +++ b/en/_doc/developer/building/qubes-builder-details.md @@ -20,28 +20,28 @@ Components Makefile.builder file Variables for Linux build: -- `RPM_SPEC_FILES` List (space separated) of spec files for RPM package build. Path should be relative to component root directory. [QubesBuilder](/doc/qubes-builder/) will install all BuildRequires (in chroot environment) before the build. In most Qubes components all spec files are kept in *rpm\_spec* directory. This is mainly used for Fedora packages build. -- `ARCH_BUILD_DIRS` List (space separated) of directories with PKGBUILD files for Archlinux package build. Similar to RPM build, [QubesBuilder](/doc/qubes-builder/) will install all makedepends, then build the package. +- `RPM_SPEC_FILES` List (space separated) of spec files for RPM package build. Path should be relative to component root directory. [QubesBuilder](/doc/qubes-builder/) will install all BuildRequires (in chroot environment) before the build. In most Qubes components all spec files are kept in *rpm\_spec* directory. This is mainly used for Fedora packages build. +- `ARCH_BUILD_DIRS` List (space separated) of directories with PKGBUILD files for Archlinux package build. Similar to RPM build, [QubesBuilder](/doc/qubes-builder/) will install all makedepends, then build the package. Most components uses *archlinux* directory for this purpose, so its good to keep this style. Variables for Windows build: -- `WIN_COMPILER` Choose which compiler should be used for this component, thus which build scripts. Currently two options available: - - `WDK` - Windows Driver Kit (default). Command used to build: *build -cZg*. - - `mingw` - MinGW (Windows gcc port). Command used to build: *make all* -- `WIN_SOURCE_SUBDIRS` List of directories in which above command should be run. In most cases it will be only one entry: current directory (*.*). -- `WIN_PREBUILD_CMD` Command to run before build, mostly useful for WDK build (in mingw case, you can use makefile for this purpose). Can be used to set some variables, preprocess some files etc. -- `WIN_SIGN_CMD` Command used to sign resulting binaries. Note that default value is *sign.bat*. If you don't want to sign binaries, specify some placeholder here (eg. *true*). Check existing components (eg. vmm-xen-windows-pvdrivers) for example scripts. This command will be run with certain environment variables: - - `CERT_FILENAME` Path to key file (pfx format) - - `CERT_PASSWORD` Key password - - `CERT_PUBLIC_FILENAME` Certificate path in the case of self-signed cert - - `CERT_CROSS_CERT_FILENAME` Certificate path in the case of correct autheticode cert - - `SIGNTOOL` Path to signtool -- `WIN_PACKAGE_CMD` Command used to produce installation package (msi or msm). Default value is *wix.bat*, similar to above - use *true* if you don't want this command. -- `WIN_OUTPUT_HEADERS` Directory (relative to `WIN_SOURCE_SUBDIRS` element) with public headers of the package - for use in other components. -- `WIN_OUTPUT_LIBS` Directory (relative to `WIN_SOURCE_SUBDIRS` element) with libraries (both DLL and implib) of the package - for use in other components. Note that [QubesBuilder](/doc/qubes-builder/) will copy files specified as *\$(WIN\_OUTPUT\_LIBS)/\*/\** to match WDK directory layout (*\/\/\*), so you in mingw build you need to place libraries in some additional subdirectory. -- `WIN_BUILD_DEPS` List of components required to build this one. [QubesBuilder](/doc/qubes-builder/) will copy files specified with `WIN_OUTPUT_HEADERS` and `WIN_OUTPUT_LIBS` of those components to some directory and provide its path with `QUBES_INCLUDES` and `QUBES_LIBS` variables. Use those variables in your build scripts (*sources* or *Makefile* - depending on selected compiler). You can assume that the variables are always set and directories always exists, even if empty. +- `WIN_COMPILER` Choose which compiler should be used for this component, thus which build scripts. Currently two options available: + - `WDK` - Windows Driver Kit (default). Command used to build: *build -cZg*. + - `mingw` - MinGW (Windows gcc port). Command used to build: *make all* +- `WIN_SOURCE_SUBDIRS` List of directories in which above command should be run. In most cases it will be only one entry: current directory (*.*). +- `WIN_PREBUILD_CMD` Command to run before build, mostly useful for WDK build (in mingw case, you can use makefile for this purpose). Can be used to set some variables, preprocess some files etc. +- `WIN_SIGN_CMD` Command used to sign resulting binaries. Note that default value is *sign.bat*. If you don't want to sign binaries, specify some placeholder here (eg. *true*). Check existing components (eg. vmm-xen-windows-pvdrivers) for example scripts. This command will be run with certain environment variables: + - `CERT_FILENAME` Path to key file (pfx format) + - `CERT_PASSWORD` Key password + - `CERT_PUBLIC_FILENAME` Certificate path in the case of self-signed cert + - `CERT_CROSS_CERT_FILENAME` Certificate path in the case of correct autheticode cert + - `SIGNTOOL` Path to signtool +- `WIN_PACKAGE_CMD` Command used to produce installation package (msi or msm). Default value is *wix.bat*, similar to above - use *true* if you don't want this command. +- `WIN_OUTPUT_HEADERS` Directory (relative to `WIN_SOURCE_SUBDIRS` element) with public headers of the package - for use in other components. +- `WIN_OUTPUT_LIBS` Directory (relative to `WIN_SOURCE_SUBDIRS` element) with libraries (both DLL and implib) of the package - for use in other components. Note that [QubesBuilder](/doc/qubes-builder/) will copy files specified as *\$(WIN\_OUTPUT\_LIBS)/\*/\** to match WDK directory layout (*\/\/\*), so you in mingw build you need to place libraries in some additional subdirectory. +- `WIN_BUILD_DEPS` List of components required to build this one. [QubesBuilder](/doc/qubes-builder/) will copy files specified with `WIN_OUTPUT_HEADERS` and `WIN_OUTPUT_LIBS` of those components to some directory and provide its path with `QUBES_INCLUDES` and `QUBES_LIBS` variables. Use those variables in your build scripts (*sources* or *Makefile* - depending on selected compiler). You can assume that the variables are always set and directories always exists, even if empty. builder.conf settings --------------------- @@ -53,4 +53,4 @@ Most settings are documented in *builder.conf.default* file, which can be used a Notes ----- -* For a list of custom TemplateVMs available in QubesBuilder look at [Supported Versions page](https://www.qubes-os.org/doc/supported-versions/). +- For a list of custom TemplateVMs available in QubesBuilder look at [Supported Versions page](https://www.qubes-os.org/doc/supported-versions/). diff --git a/en/_doc/developer/building/qubes-builder.md b/en/_doc/developer/building/qubes-builder.md index 3a56b861a6..ad8c74493d 100644 --- a/en/_doc/developer/building/qubes-builder.md +++ b/en/_doc/developer/building/qubes-builder.md @@ -12,8 +12,7 @@ title: Qubes Builder **Note: See [ISO building instructions](/doc/qubes-iso-building/) for a streamlined overview on how to use the build system.** -Building Qubes from scratch -=========================== +# Building Qubes from scratch We have a fully automated build system for Qubes, that downloads, builds and packages all the Qubes components, and finally should spit out a ready-to-use @@ -21,27 +20,29 @@ installation ISO, all in a [secure](/news/2016/05/30/build-security/) way. In order to use it, you should use an rpm-based distro, like Fedora :), and should ensure the following packages are installed: -- sudo -- gnupg -- git -- createrepo -- rpm-build -- make -- wget -- rpmdevtools -- python3-sh -- dialog -- rpm-sign -- dpkg-dev -- debootstrap -- python3-pyyaml -- devscripts -- perl-Digest-MD5 -- perl-Digest-SHA +- sudo +- gnupg +- git +- createrepo +- rpm-build +- make +- wget +- rpmdevtools +- python3-sh +- dialog +- rpm-sign +- dpkg-dev +- debootstrap +- python3-pyyaml +- devscripts +- perl-Digest-MD5 +- perl-Digest-SHA Usually you can install those packages by just issuing: +```shell sudo dnf install gnupg git createrepo rpm-build make wget rpmdevtools python3-sh dialog rpm-sign dpkg-dev debootstrap python3-pyyaml devscripts perl-Digest-MD5 perl-Digest-SHA +``` The build system creates build environments in chroots and so no other packages are needed on the host. All files created by the build system are contained within the qubes-builder directory. @@ -51,42 +52,47 @@ The build system is configured via builder.conf file. You can use the setup.sh script to create and modify this file. Alternatively, you can copy the provided default builder.conf, and modify it as needed, e.g.: - cp example-configs/qubes-os-master.conf builder.conf - # edit the builder.conf file and set the following variables: +```shell + cp example-configs/qubes-os-master.conf builder.conf + # edit the builder.conf file and set the following variables: NO_SIGN=1 +``` -One additional useful requirement is that 'sudo root' must work without any prompt, which is default on most distros (e.g. 'sudo bash' brings you the root shell without asking for any password). +One additional useful requirement is that 'sudo root' must work without any prompt, which is default on most distros (e.g. 'sudo bash' brings you the root shell without asking for any password). This is important as the builder needs to switch to root and then back to user several times during the build process. Additionally, if building with signing enabled (NO\_SIGN is not set), you must adjust \~/.rpmmacro file so that it points to the GPG key used for package signing, e.g.: +```bash %_signature gpg %_gpg_path /home/user/.gnupg %_gpg_name AC1BF9B3 # <-- Key ID used for signing +``` It is also recommended that you use an empty passphrase for the private key used for signing. Contrary to a popular belief, this doesn't affect your key or sources security -- if somebody compromised your system, then the game is over anyway, whether you have used an additional passphrase for the key or not. So, to build Qubes you would do: - # Import the Qubes master key +```shell + # Import the Qubes master key gpg --recv-keys 0xDDFA1A3E36879494 - # Verify its fingerprint, set as 'trusted'. - # This is described here: + # Verify its fingerprint, set as 'trusted'. + # This is described here: # https://www.qubes-os.org/doc/VerifyingSignatures wget https://keys.qubes-os.org/keys/qubes-developers-keys.asc - gpg --import qubes-developers-keys.asc + gpg --import qubes-developers-keys.asc - git clone git://github.com/QubesOS/qubes-builder.git qubes-builder - cd qubes-builder + git clone git://github.com/QubesOS/qubes-builder.git qubes-builder + cd qubes-builder # Verify its integrity: git tag -v `git describe` - cp example-configs/qubes-os-master.conf builder.conf - # edit the builder.conf file and set the following variables: + cp example-configs/qubes-os-master.conf builder.conf + # edit the builder.conf file and set the following variables: # NO_SIGN="1" # Download all components: @@ -95,51 +101,58 @@ So, to build Qubes you would do: # And now to build all Qubes rpms (this will take a few hours): - make qubes + make qubes - # ... and then to build the ISO + # ... and then to build the ISO - make iso + make iso +``` And this should produce a shiny new ISO. You can also build selected component separately. Eg. to compile only gui virtualization agent/daemon: +```shell make gui-daemon +``` You can get a full list from make help. -Making customized build ------------------------ +## Making customized build ### Manual source modification You can also modify sources somehow if you wish. Here are some basic steps: -1. Download qubes-builder as described above (if you want to use marmarek's branches, you should also download qubes-builder from his repo - replace 'QubesOS' with 'marmarek' in above git clone command) -2. Edit builder.conf (still the same as above), some useful additions: - - You can also set GIT\_PREFIX="marmarek/qubes-" to use marmarek's repo instead of "mainstream" - it contains newer (but less tested) versions - -3. Download unmodified sources +1. Download qubes-builder as described above (if you want to use marmarek's branches, you should also download qubes-builder from his repo - replace 'QubesOS' with 'marmarek' in above git clone command) +2. Edit builder.conf (still the same as above), some useful additions: + - You can also set GIT\_PREFIX="marmarek/qubes-" to use marmarek's repo instead of "mainstream" - it contains newer (but less tested) versions +3. Download unmodified sources +```shell make get-sources +``` -4. **Make your modifications here** +4. **Make your modifications here** -5. Build the Qubes +5. Build the Qubes `make qubes` actually is just meta target which builds all required components in correct order. The list of components is configured in builder.conf. You can also check the current value at the end of `make - help`, or using `make build-info`. + help`, or using `make build-info`. 6. `get-sources` is already done, so continue with the next one. You can skip `sign-all` if you've disabled signing +```shell make vmm-xen core-admin linux-kernel gui-daemon template desktop-linux-kde installer-qubes-os manager linux-dom0-updates +``` -1. build iso installation image +1. build iso installation image +```shell make iso +``` ### Use pre-built Qubes packages @@ -148,19 +161,25 @@ This is especially true for `gcc`, which takes several hours to build. Before creating the `chroot`, add this to your `builder.conf`: +```bash USE_QUBES_REPO_VERSION = $(RELEASE) +``` It will add the 'current' Qubes repository to your `chroot` environment. Next, specify which components (`gcc`, for example) you want to download instead of compiling: +```bash COMPONENTS := $(filter-out gcc,$(COMPONENTS)) +``` Alternatively, edit the actual COMPONENTS list which is defined in the included version-dependent config from example-configs (see series of include directives near the beginning of `builder.conf`). This way, you can build only the packages in which you are interested. If you also want to use the 'current-testing' repository, add this to your configuration: +```bash USE_QUBES_REPO_TESTING = 1 +``` In the case of an existing `chroot`, for mock-enabled builds, this works immediately because `chroot` is constructed each time separately. For legacy builds, it will not add the necessary configuration into the build environment unless a specific builder change or configuration would force rebuilding chroot. @@ -172,22 +191,22 @@ And even if it did, there could be some leftover packages installed from those r If you are building Ubuntu templates, you cannot use this option. This is because Qubes does not provide official packages for Ubuntu templates. -Code verification keys management ---------------------------------- +## Code verification keys management [QubesBuilder](/doc/qubes-builder/) by default verifies signed tags on every downloaded code. Public keys used for that are stored in `keyrings/git`. By default Qubes developers' keys are imported automatically, but if you need some additional keys (for example your own), you can add them using: +```shell GNUPGHOME=$PWD/keyrings/git gpg --import /path/to/key.asc GNUPGHOME=$PWD/keyrings/git gpg --edit-key ID_OF_JUST_IMPORTED_KEY # here use "trust" command to set key fully or ultimately trusted - only those keys are accepted by QubesBuilder +``` All Qubes developers' keys are signed by the Qubes Master Signing Key (which is set as ultimately trusted key), so are trusted automatically. If you are the owner of Master key and want to revoke such signature, use the `revsig` gpg key edit command and update the key in qubes-developers-keys.asc - now the key will be no longer trusted (unless manually set as such). -Further information -------------------- +## Further information For advanced [QubesBuilder](/doc/qubes-builder/) use, and preparing sources, take a look at [QubesBuilderDetails](/doc/qubes-builder-details/) page, or [QubesBuilder's doc directory](https://github.com/marmarek/qubes-builder/tree/master/doc). diff --git a/en/_doc/developer/building/qubes-iso-building.md b/en/_doc/developer/building/qubes-iso-building.md index 6c1c051b88..1c5458bc97 100644 --- a/en/_doc/developer/building/qubes-iso-building.md +++ b/en/_doc/developer/building/qubes-iso-building.md @@ -44,7 +44,7 @@ Get the necessary keys to verify the sources (run these and other commands below ~~~ wget https://keys.qubes-os.org/keys/qubes-master-signing-key.asc -gpg --import qubes-master-signing-key.asc +gpg --import qubes-master-signing-key.asc gpg --edit-key 36879494 fpr # Verify fingerprint! See Note below! @@ -70,7 +70,6 @@ git tag -v `git describe` Assuming the verification went fine, we're good to go with all the rest without ever thinking more about verifying digital signatures on all the rest of the components, apart from an additional step if doing a non-scripted build. The builder will do that for us for each component, every time we build, even for all auxiliary files (e.g. Xen or Linux kernel sources). - Build using setup script ----------------- @@ -130,7 +129,6 @@ make iso Enjoy your new ISO! - Build using manual steps ----------------- From c540b36b3ae30cfb0ddbd9b0cc870aad05fefcd0 Mon Sep 17 00:00:00 2001 From: dd Date: Tue, 20 Oct 2020 21:53:34 +0200 Subject: [PATCH 034/663] mardown linter small fixes in doc/developer/code --- en/_doc/developer/code/code-signing.md | 46 +++++----- en/_doc/developer/code/coding-style.md | 118 ++++++++++++------------- en/_doc/developer/code/source-code.md | 18 ++-- 3 files changed, 88 insertions(+), 94 deletions(-) diff --git a/en/_doc/developer/code/code-signing.md b/en/_doc/developer/code/code-signing.md index 56675970cc..87c969e947 100644 --- a/en/_doc/developer/code/code-signing.md +++ b/en/_doc/developer/code/code-signing.md @@ -6,14 +6,11 @@ ref: 51 title: Code Signing --- -Code Signing -============ +# Code Signing All contributions to the Qubes OS [source code] must be cryptographically signed by the author's PGP key. - -Generating a Key ----------------- +## Generating a Key (Note: If you already have a PGP key, you may skip this step.) @@ -58,7 +55,7 @@ Real name: Bilbo Baggins E-mail address: bilbo@shire.org -Comment: +Comment: You selected this USER-ID: "Bilbo Baggins " @@ -80,8 +77,7 @@ uid Bilbo Baggins sub 4096R/69B0EA85 2013-03-13 ~~~ -Upload the Key --------------- +## Upload the Key For others to find the public key, please upload it to a server. @@ -90,8 +86,7 @@ $ gpg --send-keys --keyserver pool.sks-keyservers.net 69B0EA85 gpg: sending key 488BA441 to hkp server pool.sks-keyservers.net ``` -Using PGP with Git ------------------- +## Using PGP with Git If you're submitting a patch via GitHub (or a similar Git server), please sign your Git commits. @@ -114,7 +109,7 @@ your Git commits. commit -S ~~~ -3. (Optional) Create signed tags. +3. (Optional) Create signed tags. Signed commits are totally sufficient to contribute to Qubes OS. However, if you have commits which are not signed and you do not want to change them, you can create a signed tag for the commit and push it before the check. @@ -143,8 +138,7 @@ your Git commits. vtag = !git tag -v `git describe` ~~~ -GitHub Signature Verification (optional) ----------------------------------------- +## GitHub Signature Verification (optional) GitHub shows a green `Verified` label indicating that the GPG signature could be verified using any of the contributor’s GPG keys uploaded to GitHub. You can @@ -152,16 +146,15 @@ upload your public key on GitHub by adding your public GPG key on the [New GPG key][GitHub New GPG key] under the [SSH GPG keys page][GitHub SSH GPG keys page]. -Code Signature Checks ---------------------- +## Code Signature Checks The [signature-checker] checks if code contributions are signed. Although GitHub adds a little green `Verified` button next to the commit, the [signature-checker] uses this algorithm to check if a commit is correctly signed: -1. Is the commit signed? +1. Is the commit signed? If the commit is not signed, you can see the message > policy/qubesos/code-signing — No signature found -2. If the commit is signed, the key is downloaded from a GPG key server. +2. If the commit is signed, the key is downloaded from a GPG key server. If you can see the following error message, please check if you have uploaded the key to a key server. > policy/qubesos/code-signing — Unable to verify (no valid key found) @@ -171,23 +164,29 @@ Although GitHub adds a little green `Verified` button next to the commit, the [s In this case, you have several options to sign the commit: -1. Amend the commit and replace it with a signed commit. +1. Amend the commit and replace it with a signed commit. You can use this command to create a new signed commit: + ``` git commit --amend -S ``` + This also rewrites the commit so you need to push it forcefully: + ``` git push -f ``` -2. Create a signed tag for the unsigned commit. + +2. Create a signed tag for the unsigned commit. If the commit is back in history and you do not want to change it, you can create a signed tag for this commit and push the signature. You can use the alias from above: + ``` git checkout git spush ``` + Now, the signature checker needs to re-check the signature. Please comment on the pull request that you would like to have the signatures checked again. @@ -200,15 +199,12 @@ but is not able to verify it using the any key available. This might be that you forgot to upload the key to a key server. Please upload it. +## Using PGP with Email -Using PGP with Email --------------------- - -If you're submitting a patch by emailing the [developer mailing list], simply sign your email with your PGP key. -One good way to do this is with a program like [Enigmail]. +If you're submitting a patch by emailing the [developer mailing list], simply sign your email with your PGP key. +One good way to do this is with a program like [Enigmail]. Enigmail is a security addon for the Mozilla Thunderbird email client that allows you to easily digitally encrypt and sign your emails. - [guide]: https://alexcabal.com/creating-the-perfect-gpg-keypair/ [source code]: /doc/source-code/ [developer mailing list]: /support/#qubes-devel diff --git a/en/_doc/developer/code/coding-style.md b/en/_doc/developer/code/coding-style.md index e8ae5445ae..829e597939 100644 --- a/en/_doc/developer/code/coding-style.md +++ b/en/_doc/developer/code/coding-style.md @@ -19,10 +19,10 @@ Rationale Maintaining proper coding style is very important for any large software project, such as Qubes. Here's why: -- It eases maintenance tasks, such as adding new functionality or generalizing code later, -- It allows others (as well as the future you!) to easily understand fragments of code and what they were supposed to do, and thus makes it easier to later extend them with newer functionality or bug fixes, -- It allows others to easily review the code and catch various bugs, -- It provides for an aesthetically pleasing experience when one reads the code... +- It eases maintenance tasks, such as adding new functionality or generalizing code later, +- It allows others (as well as the future you!) to easily understand fragments of code and what they were supposed to do, and thus makes it easier to later extend them with newer functionality or bug fixes, +- It allows others to easily review the code and catch various bugs, +- It provides for an aesthetically pleasing experience when one reads the code... Often, developers, usually smart ones, undersell the value of proper coding style, thinking that it's much more important how their code works. These developers expect that if their code solves some problem using a nice and neat trick, then that's all that is really required. Such thinking shows, however, immaturity and is a signal that the developer, no matter how bright and smart, might not be a good fit for larger projects. Writing a clever exploit for a Black Hat show is one thing - writing useful software supposed to be used and maintained for years is quite a different story. If you want to show off what a smart programmer you are, then you should become a researcher and write exploits. If, on the other hand, you want to be part of a team that makes real, useful software, you should ensure your coding style is impeccable. At Qubes project, we often took shortcuts and wrote nasty code, and this has always back fired at us, sometime months, sometime years later, the net result being we had to spend time fixing code, rather than implementing new functionality. @@ -31,25 +31,25 @@ And here's a [link to the real case](https://groups.google.com/forum/#!msg/qubes General typographic conventions ------------------------------- -- **Use space-expanded tabs that equal 4 spaces.** Yes, we know, there are many arguments for using "real" tabs instead of space-expanded tabs, but we need to pick one convention to make the project consistent. One argument for using space-expanded tabs is that this way the programmer is in control of how the code will look like, despite how other users have configured their editors to visualize the tabs (of course, we assume any sane person uses a fixed-width font for viewing the source code). If it makes you feel any better, assume this is just an arbitrary choice made to enforce a unified style. +- **Use space-expanded tabs that equal 4 spaces.** Yes, we know, there are many arguments for using "real" tabs instead of space-expanded tabs, but we need to pick one convention to make the project consistent. One argument for using space-expanded tabs is that this way the programmer is in control of how the code will look like, despite how other users have configured their editors to visualize the tabs (of course, we assume any sane person uses a fixed-width font for viewing the source code). If it makes you feel any better, assume this is just an arbitrary choice made to enforce a unified style. -- **Maintain max. line length of 80 characters**. Even though today's monitors often are very wide and it's often not a problem to have 120 characters displayed in an editor, maintaining shorter line lengths improves readability. It also allows others to have two parallel windows open, side by side, each with different parts of the source code. +- **Maintain max. line length of 80 characters**. Even though today's monitors often are very wide and it's often not a problem to have 120 characters displayed in an editor, maintaining shorter line lengths improves readability. It also allows others to have two parallel windows open, side by side, each with different parts of the source code. -- **Naming conventions for any OS *other than Windows***: - - `ClassName` - - `some_variable`, `some_function`, `some_argument` +- **Naming conventions for any OS *other than Windows***: + - `ClassName` + - `some_variable`, `some_function`, `some_argument` -- **Naming convention *for Windows OS*** -- exceptionally to preserve Windows conventions please use the following: - - `ClassName`, `FunctionName` - - `pszArgumentOne`, `hPipe` -- use Hungarian notation for argument and variables +- **Naming convention *for Windows OS*** -- exceptionally to preserve Windows conventions please use the following: + - `ClassName`, `FunctionName` + - `pszArgumentOne`, `hPipe` -- use Hungarian notation for argument and variables -- **Maintain a decent amount of horizontal spacing**, e.g. add a space after `if` or before `{` in C, and similar in other languages. Whether and where to also use spaces within expressions, such as (x\*2+5) vs. (x \* 2 + 5) is left to the developer's judgment. Do not put spaces immediately after or before the brackets in expressions, so avoid constructs like this: `if ( condition )` and use ones like this: `if (condition)` instead. +- **Maintain a decent amount of horizontal spacing**, e.g. add a space after `if` or before `{` in C, and similar in other languages. Whether and where to also use spaces within expressions, such as (x\*2+5) vs. (x \* 2 + 5) is left to the developer's judgment. Do not put spaces immediately after or before the brackets in expressions, so avoid constructs like this: `if ( condition )` and use ones like this: `if (condition)` instead. -- **Use single new lines** ('\\n' aka LF) in any non-Windows source code. On Windows, exceptionally, use the CRLF line endings (--). This will allow the source code to be easily viewable in various Windows-based programs. +- **Use single new lines** ('\\n' aka LF) in any non-Windows source code. On Windows, exceptionally, use the CRLF line endings (--). This will allow the source code to be easily viewable in various Windows-based programs. -- **Use descriptive names for variables and functions**! Really, at a time when most editors have auto-completion features, there is no excuse for using short variable names. +- **Use descriptive names for variables and functions**! Really, at a time when most editors have auto-completion features, there is no excuse for using short variable names. -- **Comments should be indented together with the code**, e.g. like this: +- **Comments should be indented together with the code**, e.g. like this: ~~~ for (...) { @@ -63,33 +63,33 @@ General typographic conventions File naming conventions ----------------------- -- All file names written with small letters, use dash to separate words, rather than underscores, e.g. `qubes-dom0-update`. Never use spaces! +- All file names written with small letters, use dash to separate words, rather than underscores, e.g. `qubes-dom0-update`. Never use spaces! **File naming in Linux/Unix-like systems:** -- User commands that operate on particular VMs (also those accessible in VMs): `/usr/bin/qvm-*` -- User commands that apply to the whole system (Dom0 only): `/usr/bin/qubes-*` -- Auxiliary executables and scripts in `/usr/libexec/qubes/` (Note: previously we used `/usr/lib/qubes` but decided to change that) -- Helper, non-executable files in `/usr/share/qubes/` -- Various config files in `/etc/qubes` -- Qubes RPC services in `/etc/qubes-rpc`. Qubes RPC Policy definitions (only in Dom0) in `/etc/qubes-rpc/policy/` -- All VM-related configs, images, and other files in `/var/lib/qubes/` -- System-wide temporary files which reflect the current state of system in `/var/run/qubes` -- Logs: either log to the system-wide messages, or to `/var/log/qubes/` +- User commands that operate on particular VMs (also those accessible in VMs): `/usr/bin/qvm-*` +- User commands that apply to the whole system (Dom0 only): `/usr/bin/qubes-*` +- Auxiliary executables and scripts in `/usr/libexec/qubes/` (Note: previously we used `/usr/lib/qubes` but decided to change that) +- Helper, non-executable files in `/usr/share/qubes/` +- Various config files in `/etc/qubes` +- Qubes RPC services in `/etc/qubes-rpc`. Qubes RPC Policy definitions (only in Dom0) in `/etc/qubes-rpc/policy/` +- All VM-related configs, images, and other files in `/var/lib/qubes/` +- System-wide temporary files which reflect the current state of system in `/var/run/qubes` +- Logs: either log to the system-wide messages, or to `/var/log/qubes/` **File naming in Windows systems:** -- All base qubes-related files in `C:\Program Files\Invisible Things Lab\Qubes\` (Exceptionally spaces are allowed here to adhere to Windows naming conventions) -- Other, third-party files, not Qubes-specific, such as e.g. Xen PV drivers might be in different vendor subdirs, e.g. `C:\Program Files\Xen PV Drivers` +- All base qubes-related files in `C:\Program Files\Invisible Things Lab\Qubes\` (Exceptionally spaces are allowed here to adhere to Windows naming conventions) +- Other, third-party files, not Qubes-specific, such as e.g. Xen PV drivers might be in different vendor subdirs, e.g. `C:\Program Files\Xen PV Drivers` General programming style guidelines ------------------------------------ -- Do not try to impress with your coding kung-fu, do not use tricks to save 2 lines of code, always prefer readability over trickiness! -- Make sure your code compiles and builds without warnings. -- Always think first about interfaces (e.g. function arguments, or class methods) and data structures before you start writing the actual code. -- Use comments to explain non-trivial code fragments, or expected behavior of more complex functions, if it is not clear from their name. -- Do **not** use comments for code fragments where it is immediately clear what the code does. E.g. avoid constructs like this: +- Do not try to impress with your coding kung-fu, do not use tricks to save 2 lines of code, always prefer readability over trickiness! +- Make sure your code compiles and builds without warnings. +- Always think first about interfaces (e.g. function arguments, or class methods) and data structures before you start writing the actual code. +- Use comments to explain non-trivial code fragments, or expected behavior of more complex functions, if it is not clear from their name. +- Do **not** use comments for code fragments where it is immediately clear what the code does. E.g. avoid constructs like this: ~~~ // Return window id @@ -99,7 +99,7 @@ General programming style guidelines } ~~~ -- Do **not** use comments to disable code fragments. In production code there should really be no commented or disabled code fragments. If you really, really have a good reason to retain some fragment of unused code, use \#if or \#ifdef to disable it, e.g.: +- Do **not** use comments to disable code fragments. In production code there should really be no commented or disabled code fragments. If you really, really have a good reason to retain some fragment of unused code, use \#if or \#ifdef to disable it, e.g.: ~~~ #if 0 @@ -119,42 +119,42 @@ General programming style guidelines > But generally, there is little excuse to keep old, unused code fragments in the code. One should really use the functionality provided by the source code management system, such as git, instead. E.g. create a special branch for storing the old, unused code -- this way you will always be able to merge this code into upstream in the future. -- Do not hardcode values in the code! The only three numbers that are an exception here and for which it is acceptable to hardcode them are: `0`, `1` and `-1`, and frankly the last two are still controversial... +- Do not hardcode values in the code! The only three numbers that are an exception here and for which it is acceptable to hardcode them are: `0`, `1` and `-1`, and frankly the last two are still controversial... Source Code management (Git) guidelines --------------------------------------- -- Use git to maintain all code for Qubes project. +- Use git to maintain all code for Qubes project. -- Before you start using git, make sure you understand that git is a decentralized Source Code Management system, and that it doesn't behave like traditional, centralized source code management systems, such as SVN. Here's a good [introductory book on git](http://git-scm.com/book). Read it. +- Before you start using git, make sure you understand that git is a decentralized Source Code Management system, and that it doesn't behave like traditional, centralized source code management systems, such as SVN. Here's a good [introductory book on git](http://git-scm.com/book). Read it. -- Qubes code is divided into many git repositories. There are several reasons for that: - - This creates natural boundaries between different code blocks, enforcing proper interfaces, and easing independent development to be conducted on various code parts at the same time, without the fear of running into conflicts. - - By maintaining relatively small git repositories, it is easy for new developers to understand the code and contribute new patches, without the need to understand all the other code. - - Code repositories represent also licensing boundaries. So, e.g. because `core-agent-linux` and `core-agent-windows` are maintained in two different repositories, it is possible to have the latter under a proprietary, non-GPL license, while keeping the former fully open source. - - We have drastically changed the layout and naming of the code repositories shortly after Qubes OS R2 Beta 2 release. For details on the current code layout, please read [this article](https://blog.invisiblethings.org/2013/03/21/introducing-qubes-odyssey-framework.html). +- Qubes code is divided into many git repositories. There are several reasons for that: + - This creates natural boundaries between different code blocks, enforcing proper interfaces, and easing independent development to be conducted on various code parts at the same time, without the fear of running into conflicts. + - By maintaining relatively small git repositories, it is easy for new developers to understand the code and contribute new patches, without the need to understand all the other code. + - Code repositories represent also licensing boundaries. So, e.g. because `core-agent-linux` and `core-agent-windows` are maintained in two different repositories, it is possible to have the latter under a proprietary, non-GPL license, while keeping the former fully open source. + - We have drastically changed the layout and naming of the code repositories shortly after Qubes OS R2 Beta 2 release. For details on the current code layout, please read [this article](https://blog.invisiblethings.org/2013/03/21/introducing-qubes-odyssey-framework.html). Commit message guidelines ------------------------- Please attempt to follow these conventions when writing your Git commit messages: - * Separate the subject line from the body with a blank line. - * Limit the subject line to approximately 50 characters. - * Capitalize the subject line. - * Do not end the subject line with a period. - * Use the imperative mood in the subject line. - * Wrap the body at 72 characters. - * Use the body to explain *what* and *why* rather than *how*. +- Separate the subject line from the body with a blank line. +- Limit the subject line to approximately 50 characters. +- Capitalize the subject line. +- Do not end the subject line with a period. +- Use the imperative mood in the subject line. +- Wrap the body at 72 characters. +- Use the body to explain *what* and *why* rather than *how*. For details, examples, and the rationale behind each of these conventions, please see [this blog post](https://chris.beams.io/posts/git-commit/), which is the source of this list. Security coding guidelines -------------------------- -- As a general rule: **untrusted input** is our \#1 enemy! -- Any input that comes from untrusted, or less trusted, or just differently-trusted, entity should always be considered as malicious and should always be sanitized and verified. So, if your software runs in Dom0 and processes some input from any of the VMs, this input should be considered to be malicious. Even if your software runs in a VM, and processes input from some other VM, you should also assume that the input is malicious and verify it. -- Use `untrusted_` prefix for all variables that hold values read from untrusted party and which have not yet been verified to be decent, e.g.: +- As a general rule: **untrusted input** is our \#1 enemy! +- Any input that comes from untrusted, or less trusted, or just differently-trusted, entity should always be considered as malicious and should always be sanitized and verified. So, if your software runs in Dom0 and processes some input from any of the VMs, this input should be considered to be malicious. Even if your software runs in a VM, and processes input from some other VM, you should also assume that the input is malicious and verify it. +- Use `untrusted_` prefix for all variables that hold values read from untrusted party and which have not yet been verified to be decent, e.g.: ~~~ read_struct(untrusted_conf); @@ -167,22 +167,22 @@ Security coding guidelines height = untrusted_conf.height; ~~~ -- Use others variables, without the `untrusted_` prefix to hold the sanitized values, as shown above. +- Use others variables, without the `untrusted_` prefix to hold the sanitized values, as shown above. Python-specific guidelines -------------------------- -- Please follow the guidelines [here](http://www.python.org/dev/peps/pep-0008/), unless they were in conflict with what is written on this page. +- Please follow the guidelines [here](http://www.python.org/dev/peps/pep-0008/), unless they were in conflict with what is written on this page. C and C++ specific guidelines ----------------------------- -- Do not place code in `*.h` files. -- Use `const` whenever possible, e.g. in function arguments passed via pointers. -- Do not mix procedural and objective code together -- if you write in C++, use classes and objects. -- Think about classes hierarchy, before starting to implement specific methods. +- Do not place code in `*.h` files. +- Use `const` whenever possible, e.g. in function arguments passed via pointers. +- Do not mix procedural and objective code together -- if you write in C++, use classes and objects. +- Think about classes hierarchy, before starting to implement specific methods. Bash-specific guidelines ------------------------ -- Avoid writing scripts in bash whenever possible. Use python instead. Bash-scripts are Unix-specific and will not work under Windows VMs, or in Windows admin domain, or Windows gui domain. +- Avoid writing scripts in bash whenever possible. Use python instead. Bash-scripts are Unix-specific and will not work under Windows VMs, or in Windows admin domain, or Windows gui domain. diff --git a/en/_doc/developer/code/source-code.md b/en/_doc/developer/code/source-code.md index 5b6adef565..0b9f190a59 100644 --- a/en/_doc/developer/code/source-code.md +++ b/en/_doc/developer/code/source-code.md @@ -16,11 +16,11 @@ Qubes Source Code Repositories All the Qubes code is kept in Git repositories. We have divided the project into several components, each of which has its own separate repository, for example: - * `core-admin.git` -- The core Qubes infrastructure, responsible for VM +* `core-admin.git` -- The core Qubes infrastructure, responsible for VM management, VM templates, fs sharing, etc. - * `gui-daemon.git` -- GUI virtualization, Dom0 side. - * `gui-agent-linux.git` -- GUI virtualization, Linux VM side. - * `linux-template-builder.git` -- Scripts and other files used to create Qubes +* `gui-daemon.git` -- GUI virtualization, Dom0 side. +* `gui-agent-linux.git` -- GUI virtualization, Linux VM side. +* `linux-template-builder.git` -- Scripts and other files used to create Qubes template images. All of our repositories are available under the [QubesOS GitHub account]. @@ -37,9 +37,9 @@ e.g.: git clone https://github.com/QubesOS/qubes-core-admin.git core-admin ~~~ -To build Qubes you do not need to download all these repositories. +To build Qubes you do not need to download all these repositories. If you use [qubes builder] you can specify *what* you want to build, and download only the repositories needed to build that target. - + If you really do want to clone **all** of the repositories, you can use these commands: ~~~ @@ -55,21 +55,20 @@ find . -mindepth 1 -maxdepth 1 -type d -exec git -C {} fetch --tags --recurse-su (Alternatively, you can pull instead of just fetching.) - How to Send Patches ------------------- If you want to [contribute code] to the project, there are two ways. Whichever method you choose, you must [sign your code] before it can be accepted. -* **Preferred**: Use GitHub's [fork & pull requests]. +* **Preferred**: Use GitHub's [fork & pull requests]. Opening a pull request on GitHub greatly eases the code review and tracking process. In addition, especially for bigger changes, it's a good idea to send a message to the [qubes-devel mailing list] in order to notify people who do not receive GitHub notifications. -* Send a patch to the [qubes-devel mailing list] (`git format-patch`). +* Send a patch to the [qubes-devel mailing list] (`git format-patch`). 1. Make all the changes in your working directory, i.e. edit files, move them around (you can use 'git mv' for this), etc. @@ -85,7 +84,6 @@ method you choose, you must [sign your code] before it can be accepted. 5. Send your patch to `qubes-devel`. Start the message subject with `[PATCH]`. - [QubesOS GitHub account]: https://github.com/QubesOS/ [contribute code]: /doc/contributing/#contributing-code [sign your code]: /doc/code-signing/ From e68ee40a124275f853665b613e7ebd3303619e25 Mon Sep 17 00:00:00 2001 From: PROTechThor Date: Sat, 10 Oct 2020 09:50:00 +0100 Subject: [PATCH 035/663] Replace wireless troubleshooting with resume/suspend troubleshooting --- doc.md | 25 ++-- .../resume-suspend-troubleshooting.md | 125 ++++++++++++++++++ 2 files changed, 140 insertions(+), 10 deletions(-) create mode 100644 user/troubleshooting/resume-suspend-troubleshooting.md diff --git a/doc.md b/doc.md index f782dfe91f..dcfeecd2f9 100644 --- a/doc.md +++ b/doc.md @@ -122,16 +122,11 @@ Core documentation for Qubes users. * [Installation Troubleshooting](/doc/installation-troubleshooting) * [UEFI Troubleshooting](/doc/uefi-troubleshooting/) - * [Home directory is out of disk space error](/doc/out-of-memory/) - * [Installing on system with new AMD GPU (missing firmware problem)](https://groups.google.com/group/qubes-devel/browse_thread/thread/e27a57b0eda62f76) - * [How to install an Nvidia driver in dom0](/doc/install-nvidia-driver/) - * [Nvidia troubleshooting guide](/doc/nvidia-troubleshooting/) - * [Lenovo ThinkPad Troubleshooting](/doc/thinkpad-troubleshooting/) - * [Apple MacBook Troubleshooting](/doc/macbook-troubleshooting/) - * [Getting Sony Vaio Z laptop to work with Qubes](/doc/sony-vaio-tinkering/) - * [Fixing wireless on suspend & resume](/doc/wireless-troubleshooting/) - * [How to remove VMs manually](/doc/remove-vm-manually/) - * [Intel Integrated Graphics Troubleshooting](/doc/intel-igfx-troubleshooting/) + * [Suspend/Resume Troubleshooting](/doc/suspend-resume-troubleshooting/) + * [VM Troubleshooting](/doc/vm-troubleshooting/) + * [HVM Troubleshooting](/doc/hvm-troubleshooting/) + * [Disk Troubleshooting](/doc/disk-troubleshooting/) + * [GUI Troubleshooting](/doc/gui-troubleshooting/) ### Reference Pages @@ -274,6 +269,16 @@ For more, please see [Qubes Community Documentation](https://github.com/Qubes-Co * [Dark Theme in Dom0 and DomU](/doc/dark-theme/) * [Safely Removing TemplateVM Packages (Example: Thunderbird)](/doc/removing-templatevm-packages/) +### Troubleshooting + + * [Installing on system with new AMD GPU (missing firmware problem)](https://groups.google.com/group/qubes-devel/browse_thread/thread/e27a57b0eda62f76) + * [How to install an Nvidia driver in dom0](/doc/install-nvidia-driver/) + * [Nvidia troubleshooting guide](/doc/nvidia-troubleshooting/) + * [Lenovo ThinkPad Troubleshooting](/doc/thinkpad-troubleshooting/) + * [Apple MacBook Troubleshooting](/doc/macbook-troubleshooting/) + * [Getting Sony Vaio Z laptop to work with Qubes](/doc/sony-vaio-tinkering/) + * [Intel Integrated Graphics Troubleshooting](/doc/intel-igfx-troubleshooting/) + ### Building Guides * [Building a TemplateVM based on a new OS (ArchLinux example)](/doc/building-non-fedora-template/) diff --git a/user/troubleshooting/resume-suspend-troubleshooting.md b/user/troubleshooting/resume-suspend-troubleshooting.md new file mode 100644 index 0000000000..124465d3af --- /dev/null +++ b/user/troubleshooting/resume-suspend-troubleshooting.md @@ -0,0 +1,125 @@ +--- +layout: doc +title: Suspend/Resume Troubleshooting +permalink: /doc/suspend-resume-troubleshooting/ +redirect_from: +- /en/doc/wireless-troubleshooting/ +- /doc/wireless-troubleshooting/ +--- + +# Troubleshooting problems relating to suspend/resume # + +## Network-Manager says “Device not ready” after suspend/resume ## + +These instructions may help with suspend/resume issues for more devices than just wireless cards, that is just the (unfortunately not uncommon) example used here. + +If your wireless card works, but after suspending and resuming your computer, the Network-Manager applet just says "Device not ready", then try un-loading and re-loading the driver. + +### Determining your wireless card driver ### + +First, determine which kernel module corresponds to your wireless card. There are several ways to do this. + +The easiest is via the output of `lspci -k` in your sys-net VM: + +~~~ +[user@sys-net ~]$ lspci -k +00:00.0 Network controller: Intel Corporation Wireless 8260 (rev 3a) + Subsystem: Intel Corporation Device 0130 + Kernel driver in use: iwlwifi + Kernel modules: iwlwifi +~~~ + +Here we see that the machine in question has an Intel wireless card, being used by the `iwlwifi` kernel module. + + +### Checking logs for relevant messages ### + +View the output of `dmesg` in sys-net, and check if you see a bunch of wireless related errors. Depending on your hardware, they may look like the following (or not): + +~~~ +iwlwifi 0000:00:00.0: loaded firmware version 16.242414.0 op_mode iwlmvm +iwlwifi 0000:00:00.0: Detected Intel(R) Dual Band Wireless AC 8260, REV=0x208 +... +IPv6: ADDRCONF(NETDEV_UP): wlp0s0: link is not ready +iwlwifi 0000:00:00.0: L1 Enabled - LTR Enabled +iwlwifi 0000:00:00.0: L1 Enabled - LTR Enabled +iwlwifi 0000:00:00.0: Failed to load firmware chunk! +iwlwifi 0000:00:00.0: Could not load the [0] uCode section +iwlwifi 0000:00:00.0: Failed to start INIT ucode: -110 +iwlwifi 0000:00:00.0: Failed to run INIT ucode: -110 +... +iwlwifi 0000:00:00.0: Direct firmware load for iwlwifi-8000C-18.ucode failed with error -2 +~~~ + +### Seeing what modules you have loaded ### + +You can check which drivers are currently loaded with `lsmod`, and view details about a module with `modinfo `. + +For example, we list what modules we have loaded: + +~~~ +[user@sys-net ~]$ lsmod +Module Size Used by +iwlmvm 315392 0 +iwlwifi 155648 1 iwlmvm +mac80211 708608 1 iwlmvm +cfg80211 557056 3 iwlwifi,mac80211,iwlmvm +... +~~~ + +and check one: + +~~~ +[user@sys-net ~]$ modinfo iwlmvm | grep -E '^(description|author|depends):' +author: Copyright(c) 2003- 2015 Intel Corporation +description: The new Intel(R) wireless AGN driver for Linux +depends: iwlwifi,mac80211,cfg80211 +~~~ + +Hey, it's our wireless driver! + +Now, check if reloading the module makes wireless work again: + +~~~ +[user@sys-net ~]$ sudo rmmod iwlmvm +[user@sys-net ~]$ sudo modprobe iwlmvm +~~~ + +and try reconnecting to a network that is known to work. + +If that is successful, see below about having Qubes automatically reload the driver for you. If not, try also reloading some dependent modules, in our example we must also reload iwlwifi: + +~~~ +[user@sys-net ~]$ modinfo iwlwifi | grep -E '^(description|author|depends):' +author: Copyright(c) 2003- 2015 Intel Corporation +description: Intel(R) Wireless WiFi driver for Linux +depends: cfg80211 +~~~ + +~~~ +[user@sys-net ~]$ sudo rmmod iwlmvm +[user@sys-net ~]$ sudo rmmod iwlwifi +[user@sys-net ~]$ sudo modprobe iwlwifi # note the reverse order of loading/unloading +[user@sys-net ~]$ sudo modprobe iwlmvm +~~~ + +## Drivers do not reload automatically on suspend/resume ## + +If reloading the driver (which resets the hardware into a known-state) resolves your issue when done manually, you can have Qubes automatically un/reload them on suspend & resume by listing the relevant modules in `/rw/config/suspend-module-blacklist`. + +In the above example, it would look like this: + +~~~ +[user@sys-net config]$ cat /rw/config/suspend-module-blacklist +# You can list here modules you want to be unloaded before going to sleep. This +# file is used only if the VM has any PCI device assigned. Modules will be +# automatically loaded after resume. +iwlmvm +iwlwifi +~~~ + +## Power consumption increases after suspend/resume ## + +This problem is related to the software method used to disable sibling threads and how it interacts with suspend/resume. +To solve the problem, disable hyperthreading in the BIOS. This [external guide](https://www.pcmag.com/news/how-to-disable-hyperthreading) explains how to disable hyperthreading. +Since Qubes does disable hyperthreading by default (by not using secondary threads), you won't pay any performance cost. From 7f5332538c9f8674688e5ffa5fe6d10437d89764 Mon Sep 17 00:00:00 2001 From: Enjeck Cleopatra <32180937+PROTechThor@users.noreply.github.com> Date: Sat, 10 Oct 2020 09:55:22 +0100 Subject: [PATCH 036/663] Minor word change --- user/troubleshooting/resume-suspend-troubleshooting.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/user/troubleshooting/resume-suspend-troubleshooting.md b/user/troubleshooting/resume-suspend-troubleshooting.md index 124465d3af..4844ccaed3 100644 --- a/user/troubleshooting/resume-suspend-troubleshooting.md +++ b/user/troubleshooting/resume-suspend-troubleshooting.md @@ -9,7 +9,7 @@ redirect_from: # Troubleshooting problems relating to suspend/resume # -## Network-Manager says “Device not ready” after suspend/resume ## +## Network-Manager says “Device not ready” on suspend/resume ## These instructions may help with suspend/resume issues for more devices than just wireless cards, that is just the (unfortunately not uncommon) example used here. @@ -118,7 +118,7 @@ iwlmvm iwlwifi ~~~ -## Power consumption increases after suspend/resume ## +## Power consumption increases on suspend/resume ## This problem is related to the software method used to disable sibling threads and how it interacts with suspend/resume. To solve the problem, disable hyperthreading in the BIOS. This [external guide](https://www.pcmag.com/news/how-to-disable-hyperthreading) explains how to disable hyperthreading. From c892844b7c3ec6c1de3b6e0cfa69f55a684d5d49 Mon Sep 17 00:00:00 2001 From: PROTechThor Date: Sat, 10 Oct 2020 11:02:41 +0100 Subject: [PATCH 037/663] Add VM Troubleshooting --- .../managing-vm-kernel.md | 7 +- user/managing-os/debian/debian.md | 12 +--- user/troubleshooting/vm-troubleshooting.md | 70 +++++++++++++++++++ 3 files changed, 72 insertions(+), 17 deletions(-) create mode 100644 user/troubleshooting/vm-troubleshooting.md diff --git a/user/advanced-configuration/managing-vm-kernel.md b/user/advanced-configuration/managing-vm-kernel.md index 42dbd75d60..c8948b37d9 100644 --- a/user/advanced-configuration/managing-vm-kernel.md +++ b/user/advanced-configuration/managing-vm-kernel.md @@ -355,12 +355,7 @@ The output should look like this: #### Troubleshooting -In case of problems, you can access the VM console using `qvm-console-dispvm VMNAME` in dom0, then access the GRUB menu. -You need to call it just after starting the VM (until `GRUB_TIMEOUT` expires); for example, in a separate dom0 terminal window. - -In any case you can later access the VM's logs (especially the VM console log `/var/log/xen/console/guest-VMNAME.log`). - -You can always set the kernel back to some dom0-provided value to fix a VM kernel installation. +In case of problems, visit the [VM Troubleshooting guide](/doc/vm-troubleshooting/#vm-kernel-troubleshooting) to learn how to access the VM console, view logs and fix a VM kernel installation. [dom0-kernel-upgrade]: /doc/software-update-dom0/#kernel-upgrade diff --git a/user/managing-os/debian/debian.md b/user/managing-os/debian/debian.md index ae94a283d0..6b5a51e4a2 100644 --- a/user/managing-os/debian/debian.md +++ b/user/managing-os/debian/debian.md @@ -103,17 +103,7 @@ The lesson is that you should carefully look at what is being installed to your ### Package installation errors in Qubes 4.0 -By default, templates in 4.0 only have a loopback interface. - -Some packages will throw an error on installation in this situation. -For example, Samba expects to be configured using a network interface post installation. - -One solution is to add a dummy interface to allow the package to install correctly: - - ip link add d0 type dummy - ip addr add 192.168.0.1/24 dev d0 - ip link set d0 up - +If some packages throw installation errors, see [this guide.](/doc/vm-troubleshooting/#fixing-package-installation-errors) [TemplateVM]: /doc/templates/ [Minimal TemplateVMs]: /doc/templates/minimal/ diff --git a/user/troubleshooting/vm-troubleshooting.md b/user/troubleshooting/vm-troubleshooting.md new file mode 100644 index 0000000000..ece7b9680a --- /dev/null +++ b/user/troubleshooting/vm-troubleshooting.md @@ -0,0 +1,70 @@ +--- +layout: doc +title: Suspend/Resume Troubleshooting +permalink: /doc/vm-troubleshooting/ +redirect_from: +- /doc/remove-vm-manually/ +--- + +# VM troubleshooting # + +## VM Kernel troubleshooting ## + +In case of problems, you can access the VM console using `qvm-console-dispvm VMNAME` in dom0, then access the GRUB menu. +You need to call it just after starting the VM (until `GRUB_TIMEOUT` expires); for example, in a separate dom0 terminal window. + +In any case you can later access the VM's logs (especially the VM console log `/var/log/xen/console/guest-VMNAME.log`). + +You can always set the kernel back to some dom0-provided value to fix a VM kernel installation. + +## Qubes starts, but no VMs load ## + +This issue may occur if a dom0 update is interrupted halfway through and/or a hard power off is done without shutting down Qubes, which results in files getting corrupted. +In this case, the best fix is to reinstall Qubes and restore your files from a backup. +Even if you have not backed up data in a while, you should be able to mount the volumes to pull data from them. + +## Can not uninstall a VM / “ERROR: VM installed by package manager: template-vm-name” + +Try the [normal method] before resorting to this method to remove a VM manually. +All of the following commands should be executed in a dom0 terminal. + +When a template is marked as 'installed by package manager', but cannot be uninstalled there, trying to uninstall manually will result in the error "ERROR: VM installed by package manager: template-vm-name". Do as follows to be able to uninstall the template: + +1. Check the state of `installed_by_rpm` + + $ qvm-prefs template-vm-name + +2. If `installed_by_rpm - True]`, mark the template as not installed by package manager + + $ qvm-prefs template-vm-name installed_by_rpm false + +3. Re-check the state of `installed_by_rpm` + +- If `installed_by_rpm - False`, remove the template like you would a regular qube: + + $ qvm-remove template-vm-name + +- If `installed_by_rpm` remains `True`, reboot your computer to bring qubes.xml in sync with qubesd, and try again to remove the template. + + +[normal method]: /doc/templates/#uninstalling + + +## Fixing package installation errors ## + +By default, templates in 4.0 only have a loopback interface. + +Some packages will throw an error on installation in this situation. +For example, Samba expects to be configured using a network interface post installation. + +One solution is to add a dummy interface to allow the package to install correctly: + + ip link add d0 type dummy + ip addr add 192.168.0.1/24 dev d0 + ip link set d0 up + +## "Cannot connect to qrexec agent" error ## + +If you face this error when starting a VM, it may be due to too little initial memory. +A solution is to increase the initial memory from 200MB to 400MB by navigating to VM settings » Advanced » Initial memory. + From ea804a8f9da16f6b000e37eb5d890d80a45d9374 Mon Sep 17 00:00:00 2001 From: PROTechThor Date: Sat, 10 Oct 2020 11:50:35 +0100 Subject: [PATCH 038/663] Add HVM Troubleshooting --- external/os-guides/linux-hvm-tips.md | 36 +----------- user/troubleshooting/hvm-troubleshooting.md | 64 +++++++++++++++++++++ 2 files changed, 65 insertions(+), 35 deletions(-) create mode 100644 user/troubleshooting/hvm-troubleshooting.md diff --git a/external/os-guides/linux-hvm-tips.md b/external/os-guides/linux-hvm-tips.md index c1c99fa382..4bf5dde3b4 100644 --- a/external/os-guides/linux-hvm-tips.md +++ b/external/os-guides/linux-hvm-tips.md @@ -14,41 +14,7 @@ Tips for Linux in HVM domain How to fix bootup kernel error ------------------------------- -The HVM may pause on boot, showing a fixed cursor. -After a while a series of warnings may be shown similar to this: - - BUG: soft lockup - CPU#0 stuck for 23s! [systemd-udevd:244] - -To fix this: - -1. Kill the HVM. -1. Start the HVM -1. Press "e" at the grub screen to edit the boot parameters -1. Find the /vmlinuz line, and edit it to replace "rhgb" with "modprobe.blacklist=bochs_drm" -1. Press "Ctrl-x" to start the HVM - -If this solves the problem then you will want to make the change permanent: - -1. Edit the file `/etc/default/grub`. -1. Find the line which starts: - ~~~ - GRUB_CMDLINE_LINUX= - ~~~ -1. Remove this text from that line: - ~~~ - rhgb - ~~~ -1. Add this text to that line: - ~~~ - modprobe.blacklist=bochs_drm - ~~~ -1. Run this command: - ~~~ - grub2-mkconfig --output=/boot/grub2/grub.cfg - ~~~ - -The HVM should now start normally. - +If the HVM pauses on boot and shows a series of warnings, visit [HVM Troubleshooting](/doc/hvm-troubleshooting/#hvm-pauses-on-boot-followed-by-kernel-error) for a fix. Screen resolution ----------------- diff --git a/user/troubleshooting/hvm-troubleshooting.md b/user/troubleshooting/hvm-troubleshooting.md new file mode 100644 index 0000000000..2287ffb3e8 --- /dev/null +++ b/user/troubleshooting/hvm-troubleshooting.md @@ -0,0 +1,64 @@ +--- +layout: doc +title: HVM Troubleshooting +permalink: /doc/hvm-troubleshooting/ +redirect_from: +- /en/doc/wireless-troubleshooting/ +- /doc/wireless-troubleshooting/ +--- + +# HVM Troubleshooting # + +## HVM pauses on boot, followed by kernel error ## + +The HVM may pause on boot, showing a fixed cursor. +After a while a series of warnings may be shown similar to this: + + BUG: soft lockup - CPU#0 stuck for 23s! [systemd-udevd:244] + +To fix this: + +1. Kill the HVM. +1. Start the HVM +1. Press "e" at the grub screen to edit the boot parameters +1. Find the /vmlinuz line, and edit it to replace "rhgb" with "modprobe.blacklist=bochs_drm" +1. Press "Ctrl-x" to start the HVM + +If this solves the problem then you will want to make the change permanent: + +1. Edit the file `/etc/default/grub`. +1. Find the line which starts: + ~~~ + GRUB_CMDLINE_LINUX= + ~~~ +1. Remove this text from that line: + ~~~ + rhgb + ~~~ +1. Add this text to that line: + ~~~ + modprobe.blacklist=bochs_drm + ~~~ +1. Run this command: + ~~~ + grub2-mkconfig --output=/boot/grub2/grub.cfg + ~~~ + +The HVM should now start normally. + +## Can't start an OS in an HVM / "Probing EDD (edd=off to disable!... ok" message ## + +If you see a screen popup with SeaBios and 4 lines, last one being `Probing EDD (edd=off to disable!... ok`, then enter the following command from a `dom0` prompt: + + qvm-prefs kernel "" + +## HVM crashes when booting from ISO ## +If your HVM crashes when trying to boot an ISO, first ensure that ` qvm-prefs ` is empty, as shown above. +If this doesn't help, then disable memory balancing and set the minimum memory to 2GB. + +You can disable memory-balancing in the settings, under the “Advanced” tab. + +To give the VM a RAM of 2GB, open a terminal in `dom0` and enter: + + qvm-prefs memory 2000 + From 00dd1b6cdaba2434c44d836548875feefae3e8d0 Mon Sep 17 00:00:00 2001 From: Enjeck Cleopatra <32180937+PROTechThor@users.noreply.github.com> Date: Sat, 10 Oct 2020 12:25:36 +0100 Subject: [PATCH 039/663] Remove redirects --- user/troubleshooting/hvm-troubleshooting.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/user/troubleshooting/hvm-troubleshooting.md b/user/troubleshooting/hvm-troubleshooting.md index 2287ffb3e8..7dddd235b2 100644 --- a/user/troubleshooting/hvm-troubleshooting.md +++ b/user/troubleshooting/hvm-troubleshooting.md @@ -2,9 +2,7 @@ layout: doc title: HVM Troubleshooting permalink: /doc/hvm-troubleshooting/ -redirect_from: -- /en/doc/wireless-troubleshooting/ -- /doc/wireless-troubleshooting/ + --- # HVM Troubleshooting # From db639a563ce72cb334ebf1def7e386d348084452 Mon Sep 17 00:00:00 2001 From: Enjeck Cleopatra <32180937+PROTechThor@users.noreply.github.com> Date: Sat, 10 Oct 2020 18:10:19 +0100 Subject: [PATCH 040/663] Minor changes --- user/troubleshooting/vm-troubleshooting.md | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/user/troubleshooting/vm-troubleshooting.md b/user/troubleshooting/vm-troubleshooting.md index ece7b9680a..5fbbf2a449 100644 --- a/user/troubleshooting/vm-troubleshooting.md +++ b/user/troubleshooting/vm-troubleshooting.md @@ -1,6 +1,6 @@ --- layout: doc -title: Suspend/Resume Troubleshooting +title: VM Troubleshooting permalink: /doc/vm-troubleshooting/ redirect_from: - /doc/remove-vm-manually/ @@ -10,6 +10,8 @@ redirect_from: ## VM Kernel troubleshooting ## +This troubleshoot applies to the non-default kernel choice described in the [Managing VM docs](https://www.qubes-os.org/doc/managing-vm-kernel/#using-kernel-installed-in-the-vm). + In case of problems, you can access the VM console using `qvm-console-dispvm VMNAME` in dom0, then access the GRUB menu. You need to call it just after starting the VM (until `GRUB_TIMEOUT` expires); for example, in a separate dom0 terminal window. @@ -19,9 +21,9 @@ You can always set the kernel back to some dom0-provided value to fix a VM kerne ## Qubes starts, but no VMs load ## -This issue may occur if a dom0 update is interrupted halfway through and/or a hard power off is done without shutting down Qubes, which results in files getting corrupted. -In this case, the best fix is to reinstall Qubes and restore your files from a backup. -Even if you have not backed up data in a while, you should be able to mount the volumes to pull data from them. +First, try to start a particular VM, check any failure message and direct further steps based on that. + +This issue has been seen to occur if a dom0 update is interrupted halfway through and/or a hard power off is done without shutting down Qubes, which results in files getting corrupted. ## Can not uninstall a VM / “ERROR: VM installed by package manager: template-vm-name” @@ -65,6 +67,7 @@ One solution is to add a dummy interface to allow the package to install correct ## "Cannot connect to qrexec agent" error ## -If you face this error when starting a VM, it may be due to too little initial memory. -A solution is to increase the initial memory from 200MB to 400MB by navigating to VM settings » Advanced » Initial memory. +If you face this error when starting a VM, look into the VM logs at `/var/log/xen/console/guest-VMNAME.log`. +Common reasons that may be revealed are: too low memory, corrupted files or a VM crash on startup. +If the error occurs as a result of too little initial memory, increase the initial memory from 200MB to 400MB by navigating to VM settings » Advanced » Initial memory. From 090ccdd7b1a525c2b87a5acbbe6a40ad2266409b Mon Sep 17 00:00:00 2001 From: Enjeck Cleopatra <32180937+PROTechThor@users.noreply.github.com> Date: Sat, 10 Oct 2020 18:32:18 +0100 Subject: [PATCH 041/663] Add "kernel" word --- user/troubleshooting/hvm-troubleshooting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/user/troubleshooting/hvm-troubleshooting.md b/user/troubleshooting/hvm-troubleshooting.md index 7dddd235b2..63ef987063 100644 --- a/user/troubleshooting/hvm-troubleshooting.md +++ b/user/troubleshooting/hvm-troubleshooting.md @@ -51,7 +51,7 @@ If you see a screen popup with SeaBios and 4 lines, last one being `Probing EDD qvm-prefs kernel "" ## HVM crashes when booting from ISO ## -If your HVM crashes when trying to boot an ISO, first ensure that ` qvm-prefs ` is empty, as shown above. +If your HVM crashes when trying to boot an ISO, first ensure that ` qvm-prefs kernel` is empty, as shown above. If this doesn't help, then disable memory balancing and set the minimum memory to 2GB. You can disable memory-balancing in the settings, under the “Advanced” tab. From 7211facede0352fcf92e04eb9e08c50beabe3025 Mon Sep 17 00:00:00 2001 From: Enjeck Cleopatra <32180937+PROTechThor@users.noreply.github.com> Date: Sun, 11 Oct 2020 04:43:58 +0100 Subject: [PATCH 042/663] Add hyphen to "hyperthreading" --- user/troubleshooting/resume-suspend-troubleshooting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/user/troubleshooting/resume-suspend-troubleshooting.md b/user/troubleshooting/resume-suspend-troubleshooting.md index 4844ccaed3..fec66d8566 100644 --- a/user/troubleshooting/resume-suspend-troubleshooting.md +++ b/user/troubleshooting/resume-suspend-troubleshooting.md @@ -121,5 +121,5 @@ iwlwifi ## Power consumption increases on suspend/resume ## This problem is related to the software method used to disable sibling threads and how it interacts with suspend/resume. -To solve the problem, disable hyperthreading in the BIOS. This [external guide](https://www.pcmag.com/news/how-to-disable-hyperthreading) explains how to disable hyperthreading. +To solve the problem, disable hyper-threading in the BIOS. This [external guide](https://www.pcmag.com/news/how-to-disable-hyperthreading) explains how to disable hyper-threading. Since Qubes does disable hyperthreading by default (by not using secondary threads), you won't pay any performance cost. From 1a421c412b117c1a1b1aeacd77700d25b00f5f66 Mon Sep 17 00:00:00 2001 From: Enjeck Cleopatra <32180937+PROTechThor@users.noreply.github.com> Date: Thu, 15 Oct 2020 08:44:39 +0100 Subject: [PATCH 043/663] Add new section about PCI devices --- user/troubleshooting/resume-suspend-troubleshooting.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/user/troubleshooting/resume-suspend-troubleshooting.md b/user/troubleshooting/resume-suspend-troubleshooting.md index fec66d8566..5acacc819e 100644 --- a/user/troubleshooting/resume-suspend-troubleshooting.md +++ b/user/troubleshooting/resume-suspend-troubleshooting.md @@ -123,3 +123,12 @@ iwlwifi This problem is related to the software method used to disable sibling threads and how it interacts with suspend/resume. To solve the problem, disable hyper-threading in the BIOS. This [external guide](https://www.pcmag.com/news/how-to-disable-hyperthreading) explains how to disable hyper-threading. Since Qubes does disable hyperthreading by default (by not using secondary threads), you won't pay any performance cost. + +## Attached devices in HVM stop working on suspend/resume ## + +After the whole system gets suspended into S3 sleep and subsequently resumed, some attached devices may stop working. To make the devices work, they should be restarted within the VM. +This can be achieved under a Windows HVM by opening the Device Manager, selecting the actual device (such as a USB controller), 'Disabling' the device, and then 'Enabling' the device again. +This is illustrated on the screenshot below: + +![r2b1-win7-usb-disable.png](/attachment/wiki/HvmCreate/r2b1-win7-usb-disable.png) + From b6a07b26a073d04d91a75f7ef72f0b147fcea3d8 Mon Sep 17 00:00:00 2001 From: Enjeck Cleopatra <32180937+PROTechThor@users.noreply.github.com> Date: Sun, 18 Oct 2020 04:32:16 +0100 Subject: [PATCH 044/663] Add "Windows" word --- user/troubleshooting/resume-suspend-troubleshooting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/user/troubleshooting/resume-suspend-troubleshooting.md b/user/troubleshooting/resume-suspend-troubleshooting.md index 5acacc819e..e16871c690 100644 --- a/user/troubleshooting/resume-suspend-troubleshooting.md +++ b/user/troubleshooting/resume-suspend-troubleshooting.md @@ -124,7 +124,7 @@ This problem is related to the software method used to disable sibling threads a To solve the problem, disable hyper-threading in the BIOS. This [external guide](https://www.pcmag.com/news/how-to-disable-hyperthreading) explains how to disable hyper-threading. Since Qubes does disable hyperthreading by default (by not using secondary threads), you won't pay any performance cost. -## Attached devices in HVM stop working on suspend/resume ## +## Attached devices in Windows HVM stop working on suspend/resume ## After the whole system gets suspended into S3 sleep and subsequently resumed, some attached devices may stop working. To make the devices work, they should be restarted within the VM. This can be achieved under a Windows HVM by opening the Device Manager, selecting the actual device (such as a USB controller), 'Disabling' the device, and then 'Enabling' the device again. From b49de6a3076c931a22cf99a75cf707d9dfd322bf Mon Sep 17 00:00:00 2001 From: Enjeck Cleopatra <32180937+PROTechThor@users.noreply.github.com> Date: Mon, 19 Oct 2020 14:09:42 +0100 Subject: [PATCH 045/663] Delete wireless-troubleshooting.md All the content here is already available at Suspend-resume-troubleshooting.md. Plus, this page should redirect to /doc/suspend-resume-troubleshooting --- .../wireless-troubleshooting.md | 121 ------------------ 1 file changed, 121 deletions(-) delete mode 100644 user/troubleshooting/wireless-troubleshooting.md diff --git a/user/troubleshooting/wireless-troubleshooting.md b/user/troubleshooting/wireless-troubleshooting.md deleted file mode 100644 index 9c8ea33de5..0000000000 --- a/user/troubleshooting/wireless-troubleshooting.md +++ /dev/null @@ -1,121 +0,0 @@ ---- -layout: doc -title: Wireless Troubleshooting -permalink: /doc/wireless-troubleshooting/ -redirect_from: -- /en/doc/wireless-troubleshooting/ ---- - -Wireless Troubleshooting Guide -============================== - -These instructions may help with suspend/resume issues for more devices than just wireless cards, that is just the (unfortunately not uncommon) example used here. - -Resetting wireless cards by reloading drivers ---------------------------------------------- - -If your wireless card works, but after suspending and resuming your computer, the Network-Manager applet just says "Device not ready", then try un-loading and re-loading the driver. - -### Determining your wireless card driver ### - -First, determine which kernel module corresponds to your wireless card. There are several ways to do this. - -The easiest is via the output of `lspci -k` in your sys-net VM: - -~~~ -[user@sys-net ~]$ lspci -k -00:00.0 Network controller: Intel Corporation Wireless 8260 (rev 3a) - Subsystem: Intel Corporation Device 0130 - Kernel driver in use: iwlwifi - Kernel modules: iwlwifi -~~~ - -Here we see that the machine in question has an Intel wireless card, being used by the `iwlwifi` kernel module. - - -### Checking logs for relevant messages ### - -View the output of `dmesg` in sys-net, and check if you see a bunch of wireless related errors. Depending on your hardware, they may look like the following (or not): - -~~~ -iwlwifi 0000:00:00.0: loaded firmware version 16.242414.0 op_mode iwlmvm -iwlwifi 0000:00:00.0: Detected Intel(R) Dual Band Wireless AC 8260, REV=0x208 -... -IPv6: ADDRCONF(NETDEV_UP): wlp0s0: link is not ready -iwlwifi 0000:00:00.0: L1 Enabled - LTR Enabled -iwlwifi 0000:00:00.0: L1 Enabled - LTR Enabled -iwlwifi 0000:00:00.0: Failed to load firmware chunk! -iwlwifi 0000:00:00.0: Could not load the [0] uCode section -iwlwifi 0000:00:00.0: Failed to start INIT ucode: -110 -iwlwifi 0000:00:00.0: Failed to run INIT ucode: -110 -... -iwlwifi 0000:00:00.0: Direct firmware load for iwlwifi-8000C-18.ucode failed with error -2 -~~~ - -### Seeing what modules you have loaded ### - -You can check which drivers are currently loaded with `lsmod`, and view details about a module with `modinfo `. - -For example, we list what modules we have loaded: - -~~~ -[user@sys-net ~]$ lsmod -Module Size Used by -iwlmvm 315392 0 -iwlwifi 155648 1 iwlmvm -mac80211 708608 1 iwlmvm -cfg80211 557056 3 iwlwifi,mac80211,iwlmvm -... -~~~ - -and check one: - -~~~ -[user@sys-net ~]$ modinfo iwlmvm | grep -E '^(description|author|depends):' -author: Copyright(c) 2003- 2015 Intel Corporation -description: The new Intel(R) wireless AGN driver for Linux -depends: iwlwifi,mac80211,cfg80211 -~~~ - -Hey, it's our wireless driver! - -Now, check if reloading the module makes wireless work again: - -~~~ -[user@sys-net ~]$ sudo rmmod iwlmvm -[user@sys-net ~]$ sudo modprobe iwlmvm -~~~ - -and try reconnecting to a network that is known to work. - -If that is successful, see below about having Qubes automatically reload the driver for you. If not, try also reloading some dependent modules, in our example we must also reload iwlwifi: - -~~~ -[user@sys-net ~]$ modinfo iwlwifi | grep -E '^(description|author|depends):' -author: Copyright(c) 2003- 2015 Intel Corporation -description: Intel(R) Wireless WiFi driver for Linux -depends: cfg80211 -~~~ - -~~~ -[user@sys-net ~]$ sudo rmmod iwlmvm -[user@sys-net ~]$ sudo rmmod iwlwifi -[user@sys-net ~]$ sudo modprobe iwlwifi # note the reverse order of loading/unloading -[user@sys-net ~]$ sudo modprobe iwlmvm -~~~ - -Automatically reloading drivers on suspend/resume -------------------------------------------------- - -If reloading the driver (which resets the hardware into a known-state) resolves your issue when done manually, you can have Qubes automatically un/reload them on suspend & resume by listing the relevant modules in `/rw/config/suspend-module-blacklist`. - -In the above example, it would look like this: - -~~~ -[user@sys-net config]$ cat /rw/config/suspend-module-blacklist -# You can list here modules you want to be unloaded before going to sleep. This -# file is used only if the VM has any PCI device assigned. Modules will be -# automatically loaded after resume. -iwlmvm -iwlwifi -~~~ From dd1d327a4f16bdcbece59fff4783a05fc23be9a9 Mon Sep 17 00:00:00 2001 From: Enjeck Cleopatra <32180937+PROTechThor@users.noreply.github.com> Date: Mon, 19 Oct 2020 14:22:38 +0100 Subject: [PATCH 046/663] Add section about attached devices in Windows HVM --- user/troubleshooting/hvm-troubleshooting.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/user/troubleshooting/hvm-troubleshooting.md b/user/troubleshooting/hvm-troubleshooting.md index 63ef987063..a8c5f03936 100644 --- a/user/troubleshooting/hvm-troubleshooting.md +++ b/user/troubleshooting/hvm-troubleshooting.md @@ -60,3 +60,6 @@ To give the VM a RAM of 2GB, open a terminal in `dom0` and enter: qvm-prefs memory 2000 +## Attached devices in Windows HVM stop working on suspend/resume ## + +After the whole system gets suspended into S3 sleep and subsequently resumed, some attached devices may stop working. To know how to make the devices work, see [Suspend/resume Troubleshooting](/doc/suspend-resume-troubleshooting/). From f9a2a7c3bcedf1fad11eed79eb7b24cb10efefb9 Mon Sep 17 00:00:00 2001 From: Enjeck Cleopatra <32180937+PROTechThor@users.noreply.github.com> Date: Mon, 19 Oct 2020 14:24:18 +0100 Subject: [PATCH 047/663] Edit link to Suspend/resume Troubleshooting --- user/troubleshooting/hvm-troubleshooting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/user/troubleshooting/hvm-troubleshooting.md b/user/troubleshooting/hvm-troubleshooting.md index a8c5f03936..904d1a1648 100644 --- a/user/troubleshooting/hvm-troubleshooting.md +++ b/user/troubleshooting/hvm-troubleshooting.md @@ -62,4 +62,4 @@ To give the VM a RAM of 2GB, open a terminal in `dom0` and enter: ## Attached devices in Windows HVM stop working on suspend/resume ## -After the whole system gets suspended into S3 sleep and subsequently resumed, some attached devices may stop working. To know how to make the devices work, see [Suspend/resume Troubleshooting](/doc/suspend-resume-troubleshooting/). +After the whole system gets suspended into S3 sleep and subsequently resumed, some attached devices may stop working. To know how to make the devices work, see [Suspend/resume Troubleshooting](/doc/suspend-resume-troubleshooting/#attached-devices-in-windows-hvm-stop-working-on-suspendresume). From 7b6016dd7825e07bcfe743f80b726c4b8817e7dd Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Mon, 19 Oct 2020 11:39:51 -0700 Subject: [PATCH 048/663] Add instructions for installing contributed packages --- developer/general/package-contributions.md | 4 +++ .../installing-contributed-packages.md | 33 +++++++++++++++++++ user/common-tasks/software-update-dom0.md | 5 +++ user/common-tasks/software-update-domu.md | 4 +++ 4 files changed, 46 insertions(+) create mode 100644 user/advanced-configuration/installing-contributed-packages.md diff --git a/developer/general/package-contributions.md b/developer/general/package-contributions.md index 1fcbd41264..0c8bd9d5ec 100644 --- a/developer/general/package-contributions.md +++ b/developer/general/package-contributions.md @@ -7,6 +7,9 @@ permalink: /doc/package-contributions/ Package Contributions ===================== +_This page is for developers who wish to contribute packages. +If you want to install contributed packages, please see [installing contributed packages]._ + We're very grateful to the talented and hard-working community members who contribute software packages to Qubes OS. This page explains the inclusion criteria and procedures for such packages, as well as the roles and responsibilities of those involved. @@ -94,6 +97,7 @@ If you do not wish to be the maintainer of your package, please let us know. If you do not act on your maintainer duties for a given package for an extended period of time and after at least one reminder, we will assume that you no longer wish to be the maintainer for that package. +[installing contributed packages]: /doc/installing-contributed-packages/ [Inclusion Criteria]: #inclusion-criteria [Contribution Procedure]: #contribution-procedure [Update Procedure]: #update-procedure diff --git a/user/advanced-configuration/installing-contributed-packages.md b/user/advanced-configuration/installing-contributed-packages.md new file mode 100644 index 0000000000..24a1905a15 --- /dev/null +++ b/user/advanced-configuration/installing-contributed-packages.md @@ -0,0 +1,33 @@ +--- +layout: doc +title: Installing contributed packages +permalink: /doc/installing-contributed-packages/ +--- + +# Installing contributed packages + +_This page is for users who wish to install contributed packages. +If you want to contribute a package, please see [package contributions]._ + + +Qubes OS contributed packages are available under the [QubesOS-contrib] GitHub Project. +This is a place where our community can [contribute Qubes OS related packages, additions and various customizations][package contributions]. + +If you want to install one of these packages, first you need to enable the repository in your system (dom0 and/or templates). This can be done by installing the `qubes-repo-contrib` package. This package includes the repository definition and keys necessary to download, verify, and install [QubesOS-contrib] packages. + +In dom0, use `qubes-dom0-update`: + + sudo qubes-dom0-update qubes-repo-contrib + +In a Fedora-based template, use `dnf`: + + sudo dnf install qubes-repo-contrib + +In a Debian-based template, use `apt`: + + sudo apt update && sudo apt install qubes-repo-contrib + + +[package contributions]: /doc/package-contributions/ +[QubesOS-contrib]: https://github.com/QubesOS-contrib/ + diff --git a/user/common-tasks/software-update-dom0.md b/user/common-tasks/software-update-dom0.md index 5f4aaa743d..4512605abc 100644 --- a/user/common-tasks/software-update-dom0.md +++ b/user/common-tasks/software-update-dom0.md @@ -122,6 +122,10 @@ sudo qubes-dom0-update --enablerepo=qubes-dom0-unstable To enable or disable any of these repos permanently, change the corresponding `enabled` value to `1` in `/etc/yum.repos.d/qubes-dom0.repo`. +## Contributed package repository + +Please see [installing contributed packages]. + ## Kernel upgrade This section describes upgrading the kernel in dom0 and domUs. @@ -219,4 +223,5 @@ For example: sys-whonix. [testing]: /doc/testing/ [troubleshooting newer hardware]: /doc/newer-hardware-troubleshooting/ [Managing VM kernel]: /doc/managing-vm-kernel/ +[installing contributed packages]: /doc/installing-contributed-packages/ diff --git a/user/common-tasks/software-update-domu.md b/user/common-tasks/software-update-domu.md index f5bfa68e96..0962819bc2 100644 --- a/user/common-tasks/software-update-domu.md +++ b/user/common-tasks/software-update-domu.md @@ -43,6 +43,9 @@ Advanced users can execute the standard update command for that operating system If you wish to install updates that are still in [testing], you must enable the appropriate testing repositories. +## Contributed package repository + +Please see [installing contributed packages]. ### Fedora @@ -314,4 +317,5 @@ Note that the app will autostart only when the AppVM starts. If you would like t [RPM Fusion]: http://rpmfusion.org/ [service framework]: /doc/qubes-service/ [How to Reinstall a TemplateVM]: /doc/reinstall-template/ +[installing contributed packages]: /doc/installing-contributed-packages/ From 44f13f37210945241bd74b07bf96bb159f6e4976 Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Mon, 19 Oct 2020 11:44:15 -0700 Subject: [PATCH 049/663] Improve instructions for installing contributed packages Related issues: QubesOS/qubes-issues#953 QubesOS/qubes-issues#6124 --- .../installing-contributed-packages.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/user/advanced-configuration/installing-contributed-packages.md b/user/advanced-configuration/installing-contributed-packages.md index 24a1905a15..b1af5a718d 100644 --- a/user/advanced-configuration/installing-contributed-packages.md +++ b/user/advanced-configuration/installing-contributed-packages.md @@ -13,6 +13,8 @@ If you want to contribute a package, please see [package contributions]._ Qubes OS contributed packages are available under the [QubesOS-contrib] GitHub Project. This is a place where our community can [contribute Qubes OS related packages, additions and various customizations][package contributions]. +## Installing the repositories + If you want to install one of these packages, first you need to enable the repository in your system (dom0 and/or templates). This can be done by installing the `qubes-repo-contrib` package. This package includes the repository definition and keys necessary to download, verify, and install [QubesOS-contrib] packages. In dom0, use `qubes-dom0-update`: @@ -27,6 +29,12 @@ In a Debian-based template, use `apt`: sudo apt update && sudo apt install qubes-repo-contrib +## Installing packages + +After you've installed the repositories, you can install contributed packages. +For example, to install `qvm-screenshot-tool` in dom0: + + sudo qubes-dom0-update --clean qvm-screenshot-tool [package contributions]: /doc/package-contributions/ [QubesOS-contrib]: https://github.com/QubesOS-contrib/ From e65f69ac3dd6e9ba4e73a31aa33804e648e750ba Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Mon, 19 Oct 2020 12:05:34 -0700 Subject: [PATCH 050/663] Improve instructions for installing contributed packages Closes QubesOS/qubes-issues#6124 --- .../installing-contributed-packages.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/user/advanced-configuration/installing-contributed-packages.md b/user/advanced-configuration/installing-contributed-packages.md index b1af5a718d..31fb395edd 100644 --- a/user/advanced-configuration/installing-contributed-packages.md +++ b/user/advanced-configuration/installing-contributed-packages.md @@ -29,13 +29,23 @@ In a Debian-based template, use `apt`: sudo apt update && sudo apt install qubes-repo-contrib +The new repository definition will be in the usual location for your distro, and it will follow the naming pattern `qubes-contrib-*`, depending on your Qubes release and whether it is in dom0 or a TemplateVM. +For example, in a Fedora TemplateVM on Qubes 4.0, the new repository definition would be: + + /etc/yum.repos.d/qubes-contrib-vm-r4.0.repo + ## Installing packages After you've installed the repositories, you can install contributed packages. + +**Note:** The first time you install a contrib package in dom0, you must use the `--clean` flag. + For example, to install `qvm-screenshot-tool` in dom0: sudo qubes-dom0-update --clean qvm-screenshot-tool +Please see the package's README for specific installation and setup instructions. + [package contributions]: /doc/package-contributions/ [QubesOS-contrib]: https://github.com/QubesOS-contrib/ From e0b812785ba1e78ccda93ff99227d7a2ade4ea5c Mon Sep 17 00:00:00 2001 From: dd Date: Mon, 26 Oct 2020 04:38:34 +0100 Subject: [PATCH 051/663] introduction and video tours are back to original html formatting --- en/_doc/introduction/intro.html | 340 ++++++++++++++++++++++++++ en/_doc/introduction/intro.md | 14 -- en/_doc/introduction/video-tours.html | 113 +++++++++ en/_doc/introduction/video-tours.md | 8 - 4 files changed, 453 insertions(+), 22 deletions(-) create mode 100644 en/_doc/introduction/intro.html delete mode 100644 en/_doc/introduction/intro.md create mode 100644 en/_doc/introduction/video-tours.html delete mode 100644 en/_doc/introduction/video-tours.md diff --git a/en/_doc/introduction/intro.html b/en/_doc/introduction/intro.html new file mode 100644 index 0000000000..4c53423974 --- /dev/null +++ b/en/_doc/introduction/intro.html @@ -0,0 +1,340 @@ +--- +lang: en +layout: default +permalink: /intro/ +redirect_from: +- /tour/ +- /en/tour/ +- /tour/#what-is-qubes-os +- /about/ +- /en/about/ +ref: 126 +title: Introduction +--- + +

What is Qubes OS?

+ +
+
+

+ Qubes OS is a free and open-source, security-oriented operating system for + single-user desktop computing. Qubes OS leverages + + Xen-based virtualization to allow for the creation and management of + isolated compartments called qubes. +

+
+
+ +
+
+

+ These qubes, which are implemented as virtual + machines (VMs), have specific: +

    +
  • + Purposes: with a predefined set of one or many isolated + applications, for personal or professional projects, to manage the + network stack, + the firewall, or to fulfill other + user-defined purposes. +
    • +
  • + Natures: full-fledged or + + stripped-down virtual machines based on popular operating systems, + such as Fedora, + Debian, and + Windows. +
    • +
  • + Levels of trust: from complete to non-existent. All windows are + displayed in a unified desktop environment with + unforgeable colored window borders so + that different security levels are easily identifiable. +
    • +
+

+
+
+ + Qubes system diagram + +
+
+ + + +

Features

+ +
+
+

Strong isolation

+

+ Isolate different pieces of software as if they were installed on separate + physical machines using PV or + HVM virtualization techniques. +

+
+
+

Template system

+

+ Use AppVMs to + share a root file system without sacrificing security using the innovative + Template system. +

+
+
+

Multiple operating systems

+

+ Use multiple operating systems at the same time, including + Fedora, + Debian, and + Windows. +

+
+
+ +
+ +
+
+

DisposableVMs

+

+ Create DisposableVMs on the fly that + self-destruct when shut down. +

+
+
+

Whonix integration

+

+ Run Tor securely system-wide + using Whonix with Qubes. +

+
+
+

Device isolation

+

+ Secure device handling through + isolation of network cards and USB controllers. +

+
+
+ +
+ +
+
+

Split GPG

+

+ Utilize Split GPG to keep your private keys + safe. +

+
+
+

U2F proxy

+

+ Operate Qubes U2F proxy to use your + two-factor authentication devices without exposing your web browser to the + full USB stack. +

+
+
+

Open-source

+

+ Users are free to use, copy, and modify Qubes OS and + are encouraged to do so! +

+
+
+ + + + +

Why Qubes OS?

+ +

Physical isolation is a given safeguard that the digital world lacks

+ +
+
+

+ Throughout our lives, we engage in various activities, such as going to + school, working, voting, taking care of our families, and visiting with + friends. These activities are spatially and temporally bound: They happen + in isolation from one another, in their own compartments, which often + represent an essential safeguard, as in the case of voting. +

+

+ In our digital lives, the situation is quite different: All of our + activities typically happen on a single device. This causes us to worry + about whether it's safe to click on a link or install an app, since being + hacked imperils our entire digital existence. +

+

+ Qubes eliminates this concern by allowing us to divide a device into many + compartments, much as we divide a physical building into many rooms. + Better yet, it allows us to create new compartments whenever we need them, + and it gives us sophisticated tools for securely managing our activities + and data across these compartments. +

+
+
+ + Qube Manager + +
+
+ +

Qubes allows you to compartmentalize your digital life

+ +
+
+ + Compartmentalization example + +
+
+

+ Many of us are initially surprised to learn that our devices do not + support the kind of secure compartmentalization that our lives demand, and + we're disappointed that software vendors rely on generic defenses that + repeatedly succumb to new attacks. +

+

+ In building Qubes, our working assumption is that all software contains + bugs. Not only that, but in their stampeding rush to meet deadlines, the + world's stressed-out software developers are pumping out new code at a + staggering rate — far faster than the comparatively smaller + population of security experts could ever hope to analyze it for + vulnerabilities, much less fix everything. Rather than pretend that we can + prevent these inevitable vulnerabilities from being exploited, we've + designed Qubes under the assumption that they will be exploited. + It's only a matter of time until the next zero-day attack. +

+

+ In light of this sobering reality, Qubes takes an eminently practical + approach: confine, control, and contain the damage. It allows you to keep + valuable data separate from risky activities, preventing + cross-contamination. This means you you can do everything on the same + physical computer without having to worry about a single successful + cyberattack taking down your entire digital life in one fell swoop. In + fact, Qubes has + + distinct advantages over physical air gaps. +

+
+
+ +

Made to support vulnerable users and power users alike

+ +
+
+

+ Qubes provides practical, usable security to vulnerable and + actively-targeted individuals, such as journalists, activists, + whistleblowers, and researchers. Qubes is designed with the understanding + that people make mistakes, and it allows you to protect yourself from your + own mistakes. It's a place where you can click on links, open attachments, + plug in devices, and install software free from worry. It's a place where + you have control over your software, not the other way around. +

+

+ Qubes is also powerful. Organizations like the + Freedom of the Press + Foundation, Mullvad, and + Let's + Encrypt rely on Qubes as they build and maintain critical privacy and + security internet technologies that are in turn relied upon by countless + users around the world every day. Renowned security + experts like Edward Snowden, Daniel J. Bernstein, + Micah Lee, Christopher Soghoian, Isis Agora Lovecruft, Peter Todd, Bill + Budington, and Kenn White use and recommend Qubes. +

+

+ Qubes is one of the few operating systems that places the security of + its users above all else. It is, and always will be, free and open-source + software, because the fundamental operating system that constitutes the + core infrastructure of our digital lives must be free and + open-source in order to be trustworthy. +

+
+
+ + Qubes desktop screenshot + +
+
+ +
+ +
+
+

Video Tours

+

+ Want to see Qubes OS in action? Sit back and watch a guided tour! +

+ + Video Tours + +
+
+

Screenshots

+

+ See what using Qubes actually looks like with these screenshots of various + applications running in Qubes. +

+ + Screenshots + +
+
+

Getting Started

+

+ Ready to get started with Qubes? Here's what you need to know after + installing. +

+ + Getting Started + +
+
+ +

More information

+ +

+ This page is just a brief introduction to what Qubes is all about, and many + technical details have been omitted here for the sake of presentation. +

+

diff --git a/en/_doc/introduction/intro.md b/en/_doc/introduction/intro.md deleted file mode 100644 index bfc471c8b7..0000000000 --- a/en/_doc/introduction/intro.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -lang: en -layout: default -permalink: /intro/ -redirect_from: -- /tour/ -- /en/tour/ -- /tour/#what-is-qubes-os -- /about/ -- /en/about/ -ref: 126 -title: An Introduction to Qubes OS ---- - diff --git a/en/_doc/introduction/video-tours.html b/en/_doc/introduction/video-tours.html new file mode 100644 index 0000000000..dcbc6699bb --- /dev/null +++ b/en/_doc/introduction/video-tours.html @@ -0,0 +1,113 @@ +--- +lang: en +layout: default +permalink: /video-tours/ +ref: 226 +title: Video Tours of Qubes OS +--- + +
+
+
+

Micah Lee presents "Qubes OS: The Operating System That Can Protect You Even If You Get Hacked"

+

Micah Lee, a long-time Qubes advocate, presented Qubes OS: The Operating System That Can Protect You Even If You Get Hacked at the Circle of HOPE conference, which took place July 20-22, 2018 in New York City.

+ +
+
+
+
+
+

Introduction

+

Learn the basics in this introduction to Qubes OS.


+ + What is Qubes OS? + +
+
+

Screenshots

+

See what using Qubes actually looks like with these screenshots of various applications running in Qubes.

+ + See Screenshots + +
+
+

Getting Started

+

Ready to get started with Qubes? Here's what you need to know after installing.

+ + Getting Started + +
+
+
+
+
+

A Video Tour of Qubes 3.1 by Matthew Wilson

+
+

This video by Matthew Wilson provides an overview of Qubes 3.1. You can use the menu links to browse to specific chapters.

+
+
+

 

+ +
+
+
+
+
+

Docs

+

Dive into the Qubes documentation with guides, tips, and troubleshooting help.

+ + Documentation + +
+
+

Downloads

+

Download an ISO, verify your download, and install Qubes.

+ + Downloads + +
+
+

Security

+

Get PGP keys, security bulletins, and canaries. Learn more about our security practices.

+ + Security Center + +
+
+
+
+
+

French Video Series by Paf LeGeek (6 Parts)

+
+

This French series by Paf LeGeek provides a guide to Qubes OS across six videos. You can use the menu links to browse to specific videos in the series.

+
+
+

 

+ +
+
+
diff --git a/en/_doc/introduction/video-tours.md b/en/_doc/introduction/video-tours.md deleted file mode 100644 index 6f6db70684..0000000000 --- a/en/_doc/introduction/video-tours.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -lang: en -layout: default -permalink: /video-tours/ -ref: 120 -title: Video Tours of Qubes OS ---- - From 557f7339060db44b62aa42d3807dd503f9e47e11 Mon Sep 17 00:00:00 2001 From: dd Date: Mon, 26 Oct 2020 23:58:41 +0100 Subject: [PATCH 052/663] convert getting started to markdown, ref attribute for new files, minor changes --- en/_doc/introduction/intro.html | 2 ++ en/_doc/user/common-tasks/getting-started.md | 15 +++++++++++++-- .../user/troubleshooting/disk-troubleshooting.md | 4 +++- .../user/troubleshooting/hvm-troubleshooting.md | 5 +++-- .../user/troubleshooting/pci-troubleshooting.md | 4 +++- 5 files changed, 24 insertions(+), 6 deletions(-) diff --git a/en/_doc/introduction/intro.html b/en/_doc/introduction/intro.html index 4c53423974..728a50d2fa 100644 --- a/en/_doc/introduction/intro.html +++ b/en/_doc/introduction/intro.html @@ -13,6 +13,7 @@ ---

What is Qubes OS?

+
@@ -161,6 +162,7 @@

Open-source

Why Qubes OS?

+

Physical isolation is a given safeguard that the digital world lacks

diff --git a/en/_doc/user/common-tasks/getting-started.md b/en/_doc/user/common-tasks/getting-started.md index 4a6cf1b119..4d7e864771 100644 --- a/en/_doc/user/common-tasks/getting-started.md +++ b/en/_doc/user/common-tasks/getting-started.md @@ -142,6 +142,7 @@ You might find it helpful to read [this article][partitioning], which describes Important tasks --------------- + It's very important to [keep Qubes updated][update] to ensure you have the latest security updates. Frequently updating is one of the best ways to remain secure against new threats. @@ -160,6 +161,18 @@ Here are some other tasks you're likely to want to perform. If you encounter any problems, please visit the [Help, Support, and Mailing Lists] page. +## Compatible Hardware + +Make sure your hardware is [compatible](/hcl/), as Qubes OS cannot run on every type of computer. Also, check out [Qubes-certified Laptops](/doc/certified-laptops/). + +## Downloads + +[Download](/downloads/) an ISO, learn how to verify its authenticity and integrity, and follow our guides to install Qubes OS. Looking for the source code? You'll find it on [GitHub](https://github.com/QubesOS). + +## Documentation + +Peruse our extensive library of [documentation](/doc/) for users and developers of Qubes OS. You can even help us [improve](/doc/doc-guidelines/) it! + [getting-started-32]: /getting-started-32/ [downloading]: /downloads/ @@ -182,5 +195,3 @@ If you encounter any problems, please visit the [Help, Support, and Mailing List [DisposableVMs]: /doc/disposablevm/ [Device Handling]: /doc/device-handling/ [Help, Support, and Mailing Lists]: /support/ - - diff --git a/en/_doc/user/troubleshooting/disk-troubleshooting.md b/en/_doc/user/troubleshooting/disk-troubleshooting.md index c7891dd37f..1c1e055941 100644 --- a/en/_doc/user/troubleshooting/disk-troubleshooting.md +++ b/en/_doc/user/troubleshooting/disk-troubleshooting.md @@ -1,12 +1,14 @@ --- +lang: en layout: doc -title: Disk Troubleshooting permalink: /doc/disk-troubleshooting/ redirect_from: - /en/doc/out-of-memory/ - /doc/OutOfmemory/ - /wiki/OutOfmemory/ - /doc/out-of-memory/ +ref: 231 +title: Disk Troubleshooting --- # Disk Troubleshooting Guide # diff --git a/en/_doc/user/troubleshooting/hvm-troubleshooting.md b/en/_doc/user/troubleshooting/hvm-troubleshooting.md index 904d1a1648..31571eff7c 100644 --- a/en/_doc/user/troubleshooting/hvm-troubleshooting.md +++ b/en/_doc/user/troubleshooting/hvm-troubleshooting.md @@ -1,8 +1,9 @@ --- +lang: en layout: doc -title: HVM Troubleshooting permalink: /doc/hvm-troubleshooting/ - +ref: 232 +title: HVM Troubleshooting --- # HVM Troubleshooting # diff --git a/en/_doc/user/troubleshooting/pci-troubleshooting.md b/en/_doc/user/troubleshooting/pci-troubleshooting.md index 8dcabc7ead..916f14d356 100644 --- a/en/_doc/user/troubleshooting/pci-troubleshooting.md +++ b/en/_doc/user/troubleshooting/pci-troubleshooting.md @@ -1,7 +1,9 @@ --- +lang: en layout: doc -title: PCI Troubleshooting permalink: /doc/pci-troubleshooting/ +ref: 230 +title: PCI Troubleshooting --- # PCI troubleshooting # From 0bdf6e9313f3f34662e447a68feeb52795e8c269 Mon Sep 17 00:00:00 2001 From: PROTechThor Date: Thu, 22 Oct 2020 11:28:18 +0100 Subject: [PATCH 053/663] Add GUI Troubleshooting --- .../gui-configuration.md | 33 ++-------- user/troubleshooting/gui-troubleshooting.md | 62 +++++++++++++++++++ 2 files changed, 68 insertions(+), 27 deletions(-) create mode 100644 user/troubleshooting/gui-troubleshooting.md diff --git a/user/advanced-configuration/gui-configuration.md b/user/advanced-configuration/gui-configuration.md index 5ae0f5f2e3..14adf5875f 100644 --- a/user/advanced-configuration/gui-configuration.md +++ b/user/advanced-configuration/gui-configuration.md @@ -1,24 +1,22 @@ --- layout: doc -title: GUI Configuration and Troubleshooting -permalink: /doc/gui-configuration-and-troubleshooting/ +title: GUI Configuration +permalink: /doc/gui-configuration/ redirect_from: - /doc/gui-configuration/ --- -# GUI Configuration and Troubleshooting +# GUI Configuration ## Video RAM adjustment for high-resolution displays -**Problem:** You have a 4K external display, and when you connect it, you can't click on anything but a small area in the upper-right corner. - When a qube starts, a fixed amount of RAM is allocated to the graphics buffer called video RAM. This buffer needs to be at least as big as the whole desktop, accounting for all displays that are or will be connected to the machine. By default, it is as much as needed for the current display and an additional full HD (FHD) display (1920×1080 8 bit/channel RGBA). This logic fails when the machine has primary display in FHD resolution and, after starting some qubes, a 4K display is connected. -The buffer is too small, and internal desktop resize fails. +If the buffer is too small, and internal desktop resize fails. -**Solution:** Increase the minimum size of the video RAM buffer. +To increase the minimum size of the video RAM buffer: ```sh qvm-features dom0 gui-videoram-min $(($WIDTH * $HEIGHT * 4 / 1024)) @@ -53,24 +51,5 @@ EndSection ## GUI Troubleshooting -If you can start your VM, but can't launch any applications, then you need to fix the issues from the `VM console`, accessible from xen through: - -```sh -qvm-start # Make sure the VM is started -qvm-console-dispvm -``` - -### Tips - -#### Disable audited messages - -To disable audited messages, you need to edit your VM kernel parameters: - -```sh -previous_kernel_parameters=$(qvm-prefs --get kernelopts) # Get current kernel parameters -qvm-prefs --set kernelopts " audit=0" -``` - -Then, restart your VM. +See [GUI Troubleshooting](/doc/gui-troubleshooting) for issues relating to the Qubes graphical user interface and how to fix them. -Once your troubleshooting is done, don't forget to remove this kernel parameters, it makes troubleshooting VMs not starting easier. diff --git a/user/troubleshooting/gui-troubleshooting.md b/user/troubleshooting/gui-troubleshooting.md new file mode 100644 index 0000000000..381cc5f196 --- /dev/null +++ b/user/troubleshooting/gui-troubleshooting.md @@ -0,0 +1,62 @@ +--- +layout: doc +title: GUI Troubleshooting +permalink: /doc/gui-troubleshooting/ +--- + +# GUI Troubleshooting + +## Can't click on anything after connecting 4k external display ## + +When you connect a 4K external display, you may be unable to click on anything but a small area in the upper-right corner. + +When a qube starts, a fixed amount of RAM is allocated to the graphics buffer called video RAM. +This buffer needs to be at least as big as the whole desktop, accounting for all displays that are or will be connected to the machine. +By default, it is as much as needed for the current display and an additional full HD (FHD) display (1920×1080 8 bit/channel RGBA). +This logic fails when the machine has primary display in FHD resolution and, after starting some qubes, a 4K display is connected. +If the buffer is too small, and internal desktop resize fails. + +The solution to this problem is to increase the minimum size of the video RAM buffer, as explained in [GUI Configuration](/doc/gui-configuration/#video-ram-adjustment-for-high-resolution-displays). + + +## Screen blanks / Weird computer glitches like turning partially black or black boxes ## + +You may encountering seemingly random screen blanking while using Qubes, where the screen will black and shows the logon screen, yet, only the active window will show when you move the mouse or use the keyboard. Sometimes, you will get random black screen or black boxes. + +Similarly, while working, the XScreenSaver dialog may pop up (indicating the screen is locked) and the screen goes black. However, the screen is not locked, and you have to move a window to redraw the screen. + +If you are experiencing the any of the above sypmtoms, try disabling the window compositor: + + Q → System Tools → Window Manager Tweaks → Compositor → uncheck “Enable display compositing” + +## Post installation, screen goes black and freezes following LUKS decryption ## + +After installing Qubes, you may experience a black screen after entering your LUKS decryption password. +To fix the problem, use your preferred text editor (`nano` works) to edit `/mnt/sysimage/boot/efi/EFI/qubes/xen.cfg`, adding the `efi=no-rs` option to the end of the `options= line`. For example: + +~~~ +[4.14.18-1.pvops.qubes.x86_64] +options=loglvl=all dom0_mem=min:1024M dom0_mem=max:4096M iommu=no-igfx ucode=scan efi=no-rs +~~~ + +## Can start VM, but can't launch any applications ## + +If you can start your VM, but can't launch any applications, then you need to fix the issues from the `VM console`, accessible from xen through: + +```sh +qvm-start # Make sure the VM is started +qvm-console-dispvm +``` + +### Disable audited messages ### +During troubleshooting, you may be getting a lot of 'audit' messages which make the log very noisy. +To disable audited messages, you need to edit your VM kernel parameters: + +```sh +previous_kernel_parameters=$(qvm-prefs --get kernelopts) # Get current kernel parameters +qvm-prefs --set kernelopts " audit=0" +``` + +Then, restart your VM. + +Once your troubleshooting is done, don't forget to remove this kernel parameters, it makes troubleshooting VMs not starting easier. From 3d774c1a9c3f648b78d60442a41811b83c0e1acc Mon Sep 17 00:00:00 2001 From: Enjeck Cleopatra <32180937+PROTechThor@users.noreply.github.com> Date: Thu, 22 Oct 2020 12:06:26 +0100 Subject: [PATCH 054/663] Fix spelling errors --- user/troubleshooting/gui-troubleshooting.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/user/troubleshooting/gui-troubleshooting.md b/user/troubleshooting/gui-troubleshooting.md index 381cc5f196..de60a4d249 100644 --- a/user/troubleshooting/gui-troubleshooting.md +++ b/user/troubleshooting/gui-troubleshooting.md @@ -21,11 +21,11 @@ The solution to this problem is to increase the minimum size of the video RAM bu ## Screen blanks / Weird computer glitches like turning partially black or black boxes ## -You may encountering seemingly random screen blanking while using Qubes, where the screen will black and shows the logon screen, yet, only the active window will show when you move the mouse or use the keyboard. Sometimes, you will get random black screen or black boxes. +You may encountering seemingly random screen blanking while using Qubes, where the screen will black and shows the logon screen, yet, only the active window will show when you move the mouse or use the keyboard. Sometimes, you will get random black screens or black boxes. Similarly, while working, the XScreenSaver dialog may pop up (indicating the screen is locked) and the screen goes black. However, the screen is not locked, and you have to move a window to redraw the screen. -If you are experiencing the any of the above sypmtoms, try disabling the window compositor: +If you are experiencing the any of the above symptoms, try disabling the window compositor: Q → System Tools → Window Manager Tweaks → Compositor → uncheck “Enable display compositing” From 7303650a6621b7c30ac31961f7951c9c2810c74a Mon Sep 17 00:00:00 2001 From: Enjeck Cleopatra <32180937+PROTechThor@users.noreply.github.com> Date: Sat, 24 Oct 2020 20:38:48 +0100 Subject: [PATCH 055/663] Update gui-troubleshooting.md --- user/troubleshooting/gui-troubleshooting.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/user/troubleshooting/gui-troubleshooting.md b/user/troubleshooting/gui-troubleshooting.md index de60a4d249..ff65184736 100644 --- a/user/troubleshooting/gui-troubleshooting.md +++ b/user/troubleshooting/gui-troubleshooting.md @@ -39,6 +39,8 @@ To fix the problem, use your preferred text editor (`nano` works) to edit `/mnt/ options=loglvl=all dom0_mem=min:1024M dom0_mem=max:4096M iommu=no-igfx ucode=scan efi=no-rs ~~~ +Note the `/mnt/sysimage/boot/efi/EFI/qubes/xen.cfg` path applies when running from the installer (either directly after installation, before the reboot, or by starting the installer again in recovery mode). On the actual installed system, the file to edit is `/boot/efi/EFI/qubes/xen.cfg` -- but it may be hard to access directly when your system won't boot. + ## Can start VM, but can't launch any applications ## If you can start your VM, but can't launch any applications, then you need to fix the issues from the `VM console`, accessible from xen through: @@ -47,6 +49,15 @@ If you can start your VM, but can't launch any applications, then you need to fi qvm-start # Make sure the VM is started qvm-console-dispvm ``` +After launching a VM console using `qvm-console-dispvm`, you may look at the `qubes-gui-agent` service state with: + +~~~ +systemctl status -l qubes-gui-agent +~~~ + +If the service is in a failed state, you should see some messages on why it failed. + +Another helpful place to look into is `/home/user/.xsession-errors`, which may also contain some hints what is wrong. ### Disable audited messages ### During troubleshooting, you may be getting a lot of 'audit' messages which make the log very noisy. From 0eca83d6dd7d0e4aa50fce2ca3cd1df252c34726 Mon Sep 17 00:00:00 2001 From: Enjeck Cleopatra <32180937+PROTechThor@users.noreply.github.com> Date: Sun, 25 Oct 2020 06:08:08 +0100 Subject: [PATCH 056/663] Add "that" word --- user/troubleshooting/gui-troubleshooting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/user/troubleshooting/gui-troubleshooting.md b/user/troubleshooting/gui-troubleshooting.md index ff65184736..00191b407e 100644 --- a/user/troubleshooting/gui-troubleshooting.md +++ b/user/troubleshooting/gui-troubleshooting.md @@ -39,7 +39,7 @@ To fix the problem, use your preferred text editor (`nano` works) to edit `/mnt/ options=loglvl=all dom0_mem=min:1024M dom0_mem=max:4096M iommu=no-igfx ucode=scan efi=no-rs ~~~ -Note the `/mnt/sysimage/boot/efi/EFI/qubes/xen.cfg` path applies when running from the installer (either directly after installation, before the reboot, or by starting the installer again in recovery mode). On the actual installed system, the file to edit is `/boot/efi/EFI/qubes/xen.cfg` -- but it may be hard to access directly when your system won't boot. +Note that the `/mnt/sysimage/boot/efi/EFI/qubes/xen.cfg` path applies when running from the installer (either directly after installation, before the reboot, or by starting the installer again in recovery mode). On the actual installed system, the file to edit is `/boot/efi/EFI/qubes/xen.cfg` -- but it may be hard to access directly when your system won't boot. ## Can start VM, but can't launch any applications ## From f8b6b5fe97861e56490b7ed8198f776e4359cc70 Mon Sep 17 00:00:00 2001 From: Enjeck Cleopatra <32180937+PROTechThor@users.noreply.github.com> Date: Fri, 23 Oct 2020 08:00:05 +0100 Subject: [PATCH 057/663] Add new FAQ --- introduction/faq.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/introduction/faq.md b/introduction/faq.md index 516491a749..11c36924a0 100644 --- a/introduction/faq.md +++ b/introduction/faq.md @@ -686,6 +686,13 @@ See 'systemctl status systemd-modules-load.service' for details. ``` This is cosmetic only, and can safely be ignored. +### Why is Qubes so slow and how can I make it faster? + +During boot, Qubes starts several virtual machines. +Having so many qubes running at once inevitably strains the resources of your computer and causes slowness. +The most effective way to speed up Qubes is to get more powerful hardware -- a fast CPU, a lot of memory and fast SSDs. +Qubes is slower when reading from the disk because of the VM overhead, which is why we recommend installing it on a fast SSD. + ### Could you please make my preference the default? Wouldn't it be great if Qubes were configured just the way you like it by default with all of your favorite programs and settings? From 7eb018e442f46d9b44c8b55f6089d147980fac8c Mon Sep 17 00:00:00 2001 From: Enjeck Cleopatra <32180937+PROTechThor@users.noreply.github.com> Date: Fri, 23 Oct 2020 14:05:23 +0100 Subject: [PATCH 058/663] Create media-troubleshooting.md --- user/troubleshooting/media-troubleshooting.md | 24 +++++++++++++++++++ 1 file changed, 24 insertions(+) create mode 100644 user/troubleshooting/media-troubleshooting.md diff --git a/user/troubleshooting/media-troubleshooting.md b/user/troubleshooting/media-troubleshooting.md new file mode 100644 index 0000000000..d07a5c5b7f --- /dev/null +++ b/user/troubleshooting/media-troubleshooting.md @@ -0,0 +1,24 @@ +--- +layout: doc +title: Media Troubleshooting +permalink: /doc/media-troubleshooting/ +--- +# Video and Audio Troubleshooting # + +## Can't play media videos in a VM due to missing codecs + +If you’re having trouble playing a video file in a qube, you’re probably missing the required codecs. +The easiest way to resolve this is to install VLC Media Player and use that to play your video files. +You can do this in multiple different TemplateVM distros by following the instructions [here](/faq/#how-do-i-play-video-files). + +## Video lagging + +Playing videos may cause lags since software decoding uses a lot of CPU. + +Depending on your video player, there are some settings that may smoothen video plays: +* If using VLC media player, go to Tools--> Preferences --> Video --> Output. +By default, the Output is set to "Automatic". +Go through the list and try out other output options to see if any makes videos run smoother. +* If using mpv media player, you may be able to improve performance by entering `mpv --profile=sw-fast --vo=x11` in a terminal. +* For video lags when playing videos from a browser, disable hardware acceleration in the browser. If the problem arises when watching streams, it may be smoother to use `streamlink` to view streams in mpv instead of using the browser. + From d7e67df4aeaf6ca8b68fc28789bc62d6c39812ed Mon Sep 17 00:00:00 2001 From: Enjeck Cleopatra <32180937+PROTechThor@users.noreply.github.com> Date: Sat, 24 Oct 2020 13:25:46 +0100 Subject: [PATCH 059/663] Link to page --- doc.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/doc.md b/doc.md index dcfeecd2f9..d79c9fa3c9 100644 --- a/doc.md +++ b/doc.md @@ -127,6 +127,7 @@ Core documentation for Qubes users. * [HVM Troubleshooting](/doc/hvm-troubleshooting/) * [Disk Troubleshooting](/doc/disk-troubleshooting/) * [GUI Troubleshooting](/doc/gui-troubleshooting/) + * [Media Troubleshooting](/doc/media-troubleshooting/) ### Reference Pages @@ -268,6 +269,17 @@ For more, please see [Qubes Community Documentation](https://github.com/Qubes-Co * [Language Localization](/doc/language-localization/) * [Dark Theme in Dom0 and DomU](/doc/dark-theme/) * [Safely Removing TemplateVM Packages (Example: Thunderbird)](/doc/removing-templatevm-packages/) + + ### Troubleshooting + + * [Installing on system with new AMD GPU (missing firmware problem)](https://groups.google.com/group/qubes-devel/browse_thread/thread/e27a57b0eda62f76) + * [How to install an Nvidia driver in dom0](/doc/install-nvidia-driver/) + * [Nvidia troubleshooting guide](/doc/nvidia-troubleshooting/) + * [Lenovo ThinkPad Troubleshooting](/doc/thinkpad-troubleshooting/) + * [Apple MacBook Troubleshooting](/doc/macbook-troubleshooting/) + * [Getting Sony Vaio Z laptop to work with Qubes](/doc/sony-vaio-tinkering/) + * [Intel Integrated Graphics Troubleshooting](/doc/intel-igfx-troubleshooting/) + ### Troubleshooting From 7f8266858eb2700f74146deeeaa8603e0334852b Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Thu, 29 Oct 2020 03:42:00 -0700 Subject: [PATCH 060/663] Fix location of contrib repo section --- user/common-tasks/software-update-domu.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/user/common-tasks/software-update-domu.md b/user/common-tasks/software-update-domu.md index 0962819bc2..1ddd1ffba1 100644 --- a/user/common-tasks/software-update-domu.md +++ b/user/common-tasks/software-update-domu.md @@ -43,10 +43,6 @@ Advanced users can execute the standard update command for that operating system If you wish to install updates that are still in [testing], you must enable the appropriate testing repositories. -## Contributed package repository - -Please see [installing contributed packages]. - ### Fedora There are three Qubes VM testing repositories (where `*` denotes the Release): @@ -78,6 +74,11 @@ Debian also has three Qubes VM testing repositories (where `*` denotes the Relea To enable or disable any of these repos permanently, uncomment the corresponding `deb` line in `/etc/apt/sources.list.d/qubes-r*.list`. +## Contributed package repository + +Please see [installing contributed packages]. + + ## StandaloneVMs When you create a [StandaloneVM] from a TemplateVM, the StandaloneVM is a complete clone of the TemplateVM, including the entire filesystem. From 434c00f72dd9a48efd49f820bfa361b6e8d71a15 Mon Sep 17 00:00:00 2001 From: Tom Bassindale <17594317+tjbassindale@users.noreply.github.com> Date: Thu, 29 Oct 2020 13:02:28 +0100 Subject: [PATCH 061/663] Fix missing property (default_template) in step 9 Minor change to add missing property value. Using existing command results in error that "fedora-31" is not a valid property, updated docs to add the property name so that command works. --- user/managing-os/fedora/fedora-upgrade.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/user/managing-os/fedora/fedora-upgrade.md b/user/managing-os/fedora/fedora-upgrade.md index 11e823b719..25bfd31426 100644 --- a/user/managing-os/fedora/fedora-upgrade.md +++ b/user/managing-os/fedora/fedora-upgrade.md @@ -133,7 +133,7 @@ The same general procedure may be used to upgrade any template based on the stan 9. (Optional) Make the new template the global default. - [user@dom0 ~]$ qubes-prefs --set fedora- + [user@dom0 ~]$ qubes-prefs --set default_template fedora- 10. (Optional) Remove the old template. (Make sure to type the name of the old template, not the new one.) From d695bef4a19a199c987c422f92ef95c1b8148d10 Mon Sep 17 00:00:00 2001 From: Enjeck Cleopatra <32180937+PROTechThor@users.noreply.github.com> Date: Fri, 30 Oct 2020 07:34:01 +0100 Subject: [PATCH 062/663] Add space --- user/common-tasks/block-devices.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/user/common-tasks/block-devices.md b/user/common-tasks/block-devices.md index 460aa625c3..a3bda98f0d 100644 --- a/user/common-tasks/block-devices.md +++ b/user/common-tasks/block-devices.md @@ -123,7 +123,7 @@ To recover from this error state, in dom0 run However, if the block device originated in dom0, you will have to refer to the next section. -### What if I removed the device before detaching it from the VM?### +### What if I removed the device before detaching it from the VM? ### Currently (until issue [1082] gets implemented), if you remove the device before detaching it from the qube, Qubes OS (more precisely, `libvirtd`) will think that the device is still attached to the qube and will not allow attaching further devices under the same name. The easiest way to recover from such a situation is to reboot the qube to which the device was attached. From 27a745dd59bcc9e38a1231d378b204f551d60577 Mon Sep 17 00:00:00 2001 From: PROTechThor Date: Fri, 30 Oct 2020 15:07:40 +0100 Subject: [PATCH 063/663] Add VPN Troubleshooting --- doc.md | 12 +-------- external/configuration-guides/vpn.md | 4 +-- user/troubleshooting/vpn-troubleshooting.md | 28 +++++++++++++++++++++ 3 files changed, 30 insertions(+), 14 deletions(-) create mode 100644 user/troubleshooting/vpn-troubleshooting.md diff --git a/doc.md b/doc.md index 97581ee9bf..931ab9bab6 100644 --- a/doc.md +++ b/doc.md @@ -130,6 +130,7 @@ Core documentation for Qubes users. * [USB Troubleshooting](/doc/usb-troubleshooting/) * [GUI Troubleshooting](/doc/gui-troubleshooting/) * [Media Troubleshooting](/doc/media-troubleshooting/) + * [VPN Troubleshooting](/doc/vpn-troubleshooting/) ### Reference Pages @@ -271,17 +272,6 @@ For more, please see [Qubes Community Documentation](https://github.com/Qubes-Co * [Language Localization](/doc/language-localization/) * [Dark Theme in Dom0 and DomU](/doc/dark-theme/) * [Safely Removing TemplateVM Packages (Example: Thunderbird)](/doc/removing-templatevm-packages/) - - ### Troubleshooting - - * [Installing on system with new AMD GPU (missing firmware problem)](https://groups.google.com/group/qubes-devel/browse_thread/thread/e27a57b0eda62f76) - * [How to install an Nvidia driver in dom0](/doc/install-nvidia-driver/) - * [Nvidia troubleshooting guide](/doc/nvidia-troubleshooting/) - * [Lenovo ThinkPad Troubleshooting](/doc/thinkpad-troubleshooting/) - * [Apple MacBook Troubleshooting](/doc/macbook-troubleshooting/) - * [Getting Sony Vaio Z laptop to work with Qubes](/doc/sony-vaio-tinkering/) - * [Intel Integrated Graphics Troubleshooting](/doc/intel-igfx-troubleshooting/) - ### Troubleshooting diff --git a/external/configuration-guides/vpn.md b/external/configuration-guides/vpn.md index 1f843215e3..002a28f32d 100644 --- a/external/configuration-guides/vpn.md +++ b/external/configuration-guides/vpn.md @@ -318,6 +318,4 @@ If you want to update your TemplateVMs through the VPN, you can enable the `qube Troubleshooting --------------- -* Always test your basic VPN connection before adding scripts. -* Test DNS: Ping a familiar domain name from an appVM. It should print the IP address for the domain. -* Use `iptables -L -v` and `iptables -L -v -t nat` to check firewall rules. The latter shows the critical PR-QBS chain that enables DNS forwarding. +See the [VPN Troubleshooting](/doc/vpn-troubleshooting/) guide for tips on how to fix common VPN issues. diff --git a/user/troubleshooting/vpn-troubleshooting.md b/user/troubleshooting/vpn-troubleshooting.md new file mode 100644 index 0000000000..5ea4cc12be --- /dev/null +++ b/user/troubleshooting/vpn-troubleshooting.md @@ -0,0 +1,28 @@ +--- +layout: doc +title: VPN Troubleshooting +permalink: /doc/vpn-troubleshooting/ +--- + +# VPN Troubleshooting Guide # + +## Tips + +* Check the VPN service's log in the VPN VM by running: + ~~~ + sudo journalctl -u qubes-vpn-handler + ~~~ +* Always test your basic VPN connection before adding scripts. + +* Test DNS: Ping a familiar domain name from an appVM. It should print the IP address for the domain. + +* Use `iptables -L -v` and `iptables -L -v -t nat` to check firewall rules. The latter shows the critical PR-QBS chain that enables DNS forwarding. + +## VPN does not reconnect after suspend +After suspend/resume, your VPN may not automatically reconnect. In order to get it to work, you must kill your VPN system and restart it. + +## VPN stuck at "Ready to start link" + +After setting up your VPN system and restarting the VM, you may be repeatedly getting the popup "Ready to start link", but the VPN isn't connected. + +To figure out the root of the problem, check the VPN logs in `/var/logs/syslog`. The log may reveal issues like missing libraries, which you can then install. From 1ef9e4f1d09a91dedeb0c1b7d1ed41193b01069c Mon Sep 17 00:00:00 2001 From: Enjeck Cleopatra <32180937+PROTechThor@users.noreply.github.com> Date: Fri, 30 Oct 2020 15:27:17 +0100 Subject: [PATCH 064/663] Add firewall troubleshooting link --- doc.md | 12 +----------- 1 file changed, 1 insertion(+), 11 deletions(-) diff --git a/doc.md b/doc.md index 97581ee9bf..dfb58635d8 100644 --- a/doc.md +++ b/doc.md @@ -130,6 +130,7 @@ Core documentation for Qubes users. * [USB Troubleshooting](/doc/usb-troubleshooting/) * [GUI Troubleshooting](/doc/gui-troubleshooting/) * [Media Troubleshooting](/doc/media-troubleshooting/) + * [Firewall Troubleshooting](/doc/firewall/#firewall-troubleshooting) ### Reference Pages @@ -271,17 +272,6 @@ For more, please see [Qubes Community Documentation](https://github.com/Qubes-Co * [Language Localization](/doc/language-localization/) * [Dark Theme in Dom0 and DomU](/doc/dark-theme/) * [Safely Removing TemplateVM Packages (Example: Thunderbird)](/doc/removing-templatevm-packages/) - - ### Troubleshooting - - * [Installing on system with new AMD GPU (missing firmware problem)](https://groups.google.com/group/qubes-devel/browse_thread/thread/e27a57b0eda62f76) - * [How to install an Nvidia driver in dom0](/doc/install-nvidia-driver/) - * [Nvidia troubleshooting guide](/doc/nvidia-troubleshooting/) - * [Lenovo ThinkPad Troubleshooting](/doc/thinkpad-troubleshooting/) - * [Apple MacBook Troubleshooting](/doc/macbook-troubleshooting/) - * [Getting Sony Vaio Z laptop to work with Qubes](/doc/sony-vaio-tinkering/) - * [Intel Integrated Graphics Troubleshooting](/doc/intel-igfx-troubleshooting/) - ### Troubleshooting From a13190b7eaa95fe77326b081e4280923f84526f8 Mon Sep 17 00:00:00 2001 From: PROTechThor Date: Fri, 30 Oct 2020 16:26:50 +0100 Subject: [PATCH 065/663] Add Nvidia Troubleshooting --- doc.md | 16 +--- .../install-nvidia-driver.md | 44 +--------- .../troubleshooting/nvidia-troubleshooting.md | 86 ++++++++++++++++--- user/troubleshooting/remove-vm-manually.md | 36 -------- 4 files changed, 82 insertions(+), 100 deletions(-) rename {user/troubleshooting => external/configuration-guides}/install-nvidia-driver.md (61%) rename {user => external}/troubleshooting/nvidia-troubleshooting.md (52%) delete mode 100644 user/troubleshooting/remove-vm-manually.md diff --git a/doc.md b/doc.md index 97581ee9bf..1ed52cf043 100644 --- a/doc.md +++ b/doc.md @@ -263,6 +263,7 @@ For more, please see [Qubes Community Documentation](https://github.com/Qubes-Co * [Rxvt Guide](/doc/rxvt/) * [Adding SSD storage cache](https://groups.google.com/d/msgid/qubes-users/a08359c9-9eb0-4d1a-ad92-a8a9bc676ea6%40googlegroups.com) * [How to Make a Multimedia TemplateVM](/doc/multimedia/) + * [How to install an Nvidia driver in dom0](/doc/install-nvidia-driver/) ### Customization Guides @@ -272,22 +273,9 @@ For more, please see [Qubes Community Documentation](https://github.com/Qubes-Co * [Dark Theme in Dom0 and DomU](/doc/dark-theme/) * [Safely Removing TemplateVM Packages (Example: Thunderbird)](/doc/removing-templatevm-packages/) - ### Troubleshooting - - * [Installing on system with new AMD GPU (missing firmware problem)](https://groups.google.com/group/qubes-devel/browse_thread/thread/e27a57b0eda62f76) - * [How to install an Nvidia driver in dom0](/doc/install-nvidia-driver/) - * [Nvidia troubleshooting guide](/doc/nvidia-troubleshooting/) - * [Lenovo ThinkPad Troubleshooting](/doc/thinkpad-troubleshooting/) - * [Apple MacBook Troubleshooting](/doc/macbook-troubleshooting/) - * [Getting Sony Vaio Z laptop to work with Qubes](/doc/sony-vaio-tinkering/) - * [Intel Integrated Graphics Troubleshooting](/doc/intel-igfx-troubleshooting/) - - ### Troubleshooting - + * [Nvidia Troubleshooting](/doc/nvidia-troubleshooting/) * [Installing on system with new AMD GPU (missing firmware problem)](https://groups.google.com/group/qubes-devel/browse_thread/thread/e27a57b0eda62f76) - * [How to install an Nvidia driver in dom0](/doc/install-nvidia-driver/) - * [Nvidia troubleshooting guide](/doc/nvidia-troubleshooting/) * [Lenovo ThinkPad Troubleshooting](/doc/thinkpad-troubleshooting/) * [Apple MacBook Troubleshooting](/doc/macbook-troubleshooting/) * [Getting Sony Vaio Z laptop to work with Qubes](/doc/sony-vaio-tinkering/) diff --git a/user/troubleshooting/install-nvidia-driver.md b/external/configuration-guides/install-nvidia-driver.md similarity index 61% rename from user/troubleshooting/install-nvidia-driver.md rename to external/configuration-guides/install-nvidia-driver.md index 97b8826930..d9b65ac495 100644 --- a/user/troubleshooting/install-nvidia-driver.md +++ b/external/configuration-guides/install-nvidia-driver.md @@ -135,43 +135,7 @@ mv /root/xorg.conf.new /etc/X11/xorg.conf Reboot to verify all this works. -# Troubleshooting lack of video output during installation - -Specifically, the notes below are aimed to help when the GRUB menu shows up fine, the installation environment starts loading, and then the display(s) go into standby mode. This is, typically, related to some sort of an issue with the kernel's KMS/video card modules. - -## Initial setup. -*Note*: The steps below do *not* produce a fully-functional Qubes OS install. Rather, only a dom0 instance is functional, and there is no networking there. However, they can be used to gather data in order to troubleshoot video card issues and/or possible other basic kernel module issues. - -1. Append `nomodeset ip=dhcp inst.nokill inst.vnc` to the kernel command line. Remove `rhgb` and `quiet` to see the kernel messages scroll by, which may help in further diagnostics. - * If DHCP is not available on the installation network, the syntax becomes a bit more involved. The full list of variants is documented in the [Dracut Command-line parameters] (http://man7.org/linux/man-pages/man7/dracut.cmdline.7.html) -2. The VGA console should switch into the installer's multi-virtual-terminal display. VNC may take a number of minutes to start, please be patient. - * Using the anaconda installer interface, switch to the "shell" TTY (ALT-F2), and use `ip a` command to display the IP addresses. -3. Using the Connect to the IP (remember the :1) using a VNC viewer. -4. Follow the installation UI. - * Since this won't be a usable install, skipping LUKS encryption is an option which will simplify this troubleshooting process. - * Do *not* reboot at the end of the installation. -5. Once the installation completes, use the local VGA console switch to TTY2 via ALT-F2 - * Switch to the chroot of the newly-installed system via `chroot /mnt/sysinstall` - * Set the root password (this will also enable the root account login) - * Double-check that `/boot/grub2/grub.cfg` contains a `nomodeset` kernel parameter. - * Exit out of the chroot environment (`exit` or CTRL-D) -6. Reboot - -*Note* If the kernel parameters do *not* include `quiet` and `rhgb`, the kernel messages can easily obscure the LUKS passphrase prompt. Additionally, each character entered will cause the LUKS passphrase prompt to repeat onto next line. Both of these are cosmetic. The trade-off between kernel messages and the easy-to-spot LUKS passphrase prompt is left as an exercise to the user. - -## Gather initial `dmesg` output -If all is well, the newly-installed Qubes OS instance should allow for user root to log in. -Run `dmesg > dmesg.nomodeset.out` to gather an initial dmesg output. - -## Gather the 'video no worky' `dmesg` output -1. Reboot and interrupt the Grub2's process, modifying the kernel parameters to no longer contain `nomodeset`. - * If the LUKS passphrase was set, blindly enter it. -2. Wait for the system to finish booting (about 5 minutes, typically). -3. Blindly switch to a TTY via CTRL-ALT-F2. -4. Blindly log in as user root -5. Blindly run `dmesg > dmesg.out` -6. Blindly run `reboot` (this will also serve to confirm that logging in as root, and running commands blindly is possible rather than, say, the kernel having hung or some such). - * Should this step fail, perhaps by the time step #3 was undertaken, the OS hasn't finished coming up yet. Please retry, possibly with a different TTY (say, 3 or 4 - so CTRL-ALT-F3?) - -## Exfiltrate the dmesg outputs -Allow the system to boot normally, log in as user root, and sneakernet the files off the system for analysis, review, bug logging, et cetera. +## Troubleshooting lack of video output during installation + +The GRUB menu may show up fine, the installation environment starts loading, and then the display(s) go into standby mode. This is, typically, related to some sort of an issue with the kernel's KMS/video card modules. See the [Nvidia Troubleshooting](/doc/nvidia-troubleshooting/#lack-of-video-output-during-nvidia-driver-installation) guide for troubleshooting steps. + diff --git a/user/troubleshooting/nvidia-troubleshooting.md b/external/troubleshooting/nvidia-troubleshooting.md similarity index 52% rename from user/troubleshooting/nvidia-troubleshooting.md rename to external/troubleshooting/nvidia-troubleshooting.md index af54891a9e..70dce1925d 100644 --- a/user/troubleshooting/nvidia-troubleshooting.md +++ b/external/troubleshooting/nvidia-troubleshooting.md @@ -8,21 +8,20 @@ redirect_from: - /wiki/NvidiaTroubleshooting/ --- -NVidia Troubleshooting Guide -============================ +# Nvidia Troubleshooting Guide -If you have an NVidia graphics card it will probably not work under Xen out of the box. If your system freezes during boot and you don't see the graphical login manager after you installed Xen, then this problem most likely affects you. The following steps should provide a work around so that you should be able to use your NVidia with X under Xen, however without any fancy "desktop effects". +## System freezes during boot / Graphical login manager is not visible -Boot in failsafe ---------------------- +If you have an NVidia graphics card it will probably not work under Xen out of the box. If your system freezes during boot and you don't see the graphical login manager after you installed Xen, then this problem most likely affects you. The following steps should provide a workaround so that you should be able to use your NVidia with X under Xen, however without any fancy "desktop effects". + +### Boot in failsafe Boot your system using the "failsafe" boot menu, that should have been automatically added to your `grub.conf` when you installed the Dom0 kernel. If the X Window System doesn't start now, this is probably a non-Xen related issue and this guide will probably not help you. -Configure X with nouveau ---------------------- +### Configure X with nouveau Assuming your X Window System works fine now when you booted from the "failsafe" configuration, do the next steps... @@ -78,14 +77,15 @@ Assuming your X Window System works fine now when you booted from the "failsafe" 8. Reboot and let the system boot from the normal boot configuration. You should be able to use X under Xen now. +## Boot failure after GRUB menu / System freezes followed by reboot -Disabling Nouveau ---------------------- If Qubes fails to properly boot after the GRUB Boot menu and you are stuck on a black screen that displays messages starting with `nouveau` then it means that the nouveau driver failed to launch properly. One way to get rid of this for now is to disable nouveau. -Example error +### Disabling Nouveau + +Example error: ~~~ nouveau E[ PGRAPH][0000:01:00.0] grctx template channel unload timeout @@ -97,6 +97,32 @@ Tip: In case you only have an external monitor it is advised to attach it direct If you're seeing this error then that means another graphics card (most likely an integrated one) acted as failsafe. Disabling nouveau has the consequences of disabling nvidia support altogether. +#### EFI + + 1. Open a terminal in dom0. + + 2. To edit the `xen.cfg` file using the `nano` editor: + + ~~~ + sudo nano /boot/efi/EFI/qubes/xen.cfg + ~~~ + + 3. Locate the three `kernel=` lines. Press the left/right arrow keys to position the cursor at the end of the lines, after `rhgb quiet`. + + 4. Add the following: + + ~~~ + nouveau.modeset=0 rd.driver.blacklist=nouveau video=vesa:off + ~~~ + + This will temporarily disable nouveau until next boot. + + 5. Press either the `Ctrl+X` keys, then `y` to save changes. + + 6. Reboot + +#### GRUB + 1. Verify that that GRUB Boot Menu is displaying, you should be presented with two options and a progressbar/timer than goes rather fast. ~~~ @@ -157,3 +183,43 @@ You'll have to do the following to make this change persistent, so that it will sudo grub2-mkconfig -o /boot/grub2/grub.cfg ~~~ +## Lack of video output during Nvidia driver installation + +Specifically, the notes below are aimed to help when during Nvidia driver installation, the GRUB menu shows up fine, the installation environment starts loading, and then the display(s) go into standby mode. This is, typically, related to some sort of an issue with the kernel's KMS/video card modules. + +### Initial setup. +*Note*: The steps below do *not* produce a fully-functional Qubes OS install. Rather, only a dom0 instance is functional, and there is no networking there. However, they can be used to gather data in order to troubleshoot video card issues and/or possible other basic kernel module issues. + +1. Append `nomodeset ip=dhcp inst.nokill inst.vnc` to the kernel command line. Remove `rhgb` and `quiet` to see the kernel messages scroll by, which may help in further diagnostics. + * If DHCP is not available on the installation network, the syntax becomes a bit more involved. The full list of variants is documented in the [Dracut Command-line parameters] (http://man7.org/linux/man-pages/man7/dracut.cmdline.7.html) +2. The VGA console should switch into the installer's multi-virtual-terminal display. VNC may take a number of minutes to start, please be patient. + * Using the anaconda installer interface, switch to the "shell" TTY (ALT-F2), and use `ip a` command to display the IP addresses. +3. Using the Connect to the IP (remember the :1) using a VNC viewer. +4. Follow the installation UI. + * Since this won't be a usable install, skipping LUKS encryption is an option which will simplify this troubleshooting process. + * Do *not* reboot at the end of the installation. +5. Once the installation completes, use the local VGA console switch to TTY2 via ALT-F2 + * Switch to the chroot of the newly-installed system via `chroot /mnt/sysinstall` + * Set the root password (this will also enable the root account login) + * Double-check that `/boot/grub2/grub.cfg` contains a `nomodeset` kernel parameter. + * Exit out of the chroot environment (`exit` or CTRL-D) +6. Reboot + +*Note* If the kernel parameters do *not* include `quiet` and `rhgb`, the kernel messages can easily obscure the LUKS passphrase prompt. Additionally, each character entered will cause the LUKS passphrase prompt to repeat onto next line. Both of these are cosmetic. The trade-off between kernel messages and the easy-to-spot LUKS passphrase prompt is left as an exercise to the user. + +### Gather initial `dmesg` output +If all is well, the newly-installed Qubes OS instance should allow for user root to log in. +Run `dmesg > dmesg.nomodeset.out` to gather an initial dmesg output. + +### Gather the 'video no worky' `dmesg` output +1. Reboot and interrupt the Grub2's process, modifying the kernel parameters to no longer contain `nomodeset`. + * If the LUKS passphrase was set, blindly enter it. +2. Wait for the system to finish booting (about 5 minutes, typically). +3. Blindly switch to a TTY via CTRL-ALT-F2. +4. Blindly log in as user root +5. Blindly run `dmesg > dmesg.out` +6. Blindly run `reboot` (this will also serve to confirm that logging in as root, and running commands blindly is possible rather than, say, the kernel having hung or some such). + * Should this step fail, perhaps by the time step #3 was undertaken, the OS hasn't finished coming up yet. Please retry, possibly with a different TTY (say, 3 or 4 - so CTRL-ALT-F3?) + +### Exfiltrate the dmesg outputs +Allow the system to boot normally, log in as user root, and sneakernet the files off the system for analysis, review, bug logging, et cetera. diff --git a/user/troubleshooting/remove-vm-manually.md b/user/troubleshooting/remove-vm-manually.md deleted file mode 100644 index fbc1c145b8..0000000000 --- a/user/troubleshooting/remove-vm-manually.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -layout: doc -title: How to Remove VMs Manually -permalink: /doc/remove-vm-manually/ ---- - -How to Remove VMs Manually -========================== - -How to Remove a TemplateVM Manually ------------------------------------ - -Try the [normal method] before resorting to this. -All of the following commands should be executed in a dom0 terminal. - -When a template is marked as 'installed by package manager', but cannot be uninstalled there, trying to uninstall manually will result in the error "ERROR: VM installed by package manager: template-vm-name". Do as follows to be able to uninstall the template: - -1. Check the state of `installed_by_rpm` - - $ qvm-prefs template-vm-name - -2. If `installed_by_rpm - True]`, mark the template as not installed by package manager - - $ qvm-prefs template-vm-name installed_by_rpm false - -3. Re-check the state of `installed_by_rpm` - -- If `installed_by_rpm - False`, remove the template like you would a regular qube: - - $ qvm-remove template-vm-name - -- If `installed_by_rpm` remains `True`, reboot your computer to bring qubes.xml in sync with qubesd, and try again to remove the template. - - -[normal method]: /doc/templates/#uninstalling - From bc84b14cddfe6728041ab35748cd5dea0d5c5641 Mon Sep 17 00:00:00 2001 From: dd Date: Sat, 31 Oct 2020 22:34:54 +0100 Subject: [PATCH 066/663] added lang & ref attributes --- en/_doc/user/advanced-configuration/gui-configuration.md | 8 +++----- en/_doc/user/troubleshooting/gui-troubleshooting.md | 4 +++- en/_doc/user/troubleshooting/media-troubleshooting.md | 6 ++++-- en/_doc/user/troubleshooting/usb-troubleshooting.md | 7 ++++--- 4 files changed, 14 insertions(+), 11 deletions(-) diff --git a/en/_doc/user/advanced-configuration/gui-configuration.md b/en/_doc/user/advanced-configuration/gui-configuration.md index d2de5a504d..ff966ca35a 100644 --- a/en/_doc/user/advanced-configuration/gui-configuration.md +++ b/en/_doc/user/advanced-configuration/gui-configuration.md @@ -1,11 +1,10 @@ --- lang: en layout: doc -title: GUI Configuration permalink: /doc/gui-configuration/ -redirect_from: -- /doc/gui-configuration/ +redirect_from: [] ref: 184 +title: GUI Configuration --- # GUI Configuration @@ -53,5 +52,4 @@ EndSection ## GUI Troubleshooting -See [GUI Troubleshooting](/doc/gui-troubleshooting) for issues relating to the Qubes graphical user interface and how to fix them. - +See [GUI Troubleshooting](/doc/gui-troubleshooting) for issues relating to the Qubes graphical user interface and how to fix them. diff --git a/en/_doc/user/troubleshooting/gui-troubleshooting.md b/en/_doc/user/troubleshooting/gui-troubleshooting.md index 00191b407e..cf9113d2e2 100644 --- a/en/_doc/user/troubleshooting/gui-troubleshooting.md +++ b/en/_doc/user/troubleshooting/gui-troubleshooting.md @@ -1,7 +1,9 @@ --- +lang: en layout: doc -title: GUI Troubleshooting permalink: /doc/gui-troubleshooting/ +ref: 233 +title: GUI Troubleshooting --- # GUI Troubleshooting diff --git a/en/_doc/user/troubleshooting/media-troubleshooting.md b/en/_doc/user/troubleshooting/media-troubleshooting.md index d07a5c5b7f..b7ada45279 100644 --- a/en/_doc/user/troubleshooting/media-troubleshooting.md +++ b/en/_doc/user/troubleshooting/media-troubleshooting.md @@ -1,8 +1,11 @@ --- +lang: en layout: doc -title: Media Troubleshooting permalink: /doc/media-troubleshooting/ +ref: 235 +title: Media Troubleshooting --- + # Video and Audio Troubleshooting # ## Can't play media videos in a VM due to missing codecs @@ -21,4 +24,3 @@ By default, the Output is set to "Automatic". Go through the list and try out other output options to see if any makes videos run smoother. * If using mpv media player, you may be able to improve performance by entering `mpv --profile=sw-fast --vo=x11` in a terminal. * For video lags when playing videos from a browser, disable hardware acceleration in the browser. If the problem arises when watching streams, it may be smoother to use `streamlink` to view streams in mpv instead of using the browser. - diff --git a/en/_doc/user/troubleshooting/usb-troubleshooting.md b/en/_doc/user/troubleshooting/usb-troubleshooting.md index 2cf294ebd4..509eee8f49 100644 --- a/en/_doc/user/troubleshooting/usb-troubleshooting.md +++ b/en/_doc/user/troubleshooting/usb-troubleshooting.md @@ -1,7 +1,9 @@ --- +lang: en layout: doc -title: USB Troubleshooting permalink: /doc/usb-troubleshooting/ +ref: 234 +title: USB Troubleshooting --- # USB troubleshooting # @@ -79,5 +81,4 @@ To solve the problem, disable the USB qube by not having it autostart, or unassi Note that this procedure will attach your USB controllers to dom0, so do this only with USB devices you trust. -If your computer has a PS/2 port, you may instead use a PS/2 keyboard to enter the LUKS password. - +If your computer has a PS/2 port, you may instead use a PS/2 keyboard to enter the LUKS password. From 6716eb0b4adbbaf97109d3a256e1fa4057b8edec Mon Sep 17 00:00:00 2001 From: dd Date: Sun, 1 Nov 2020 00:11:36 +0100 Subject: [PATCH 067/663] linted docs in developer/debugging --- .../developer/debugging/automated-tests.md | 29 ++-- .../developer/debugging/mount-lvm-image.md | 11 +- en/_doc/developer/debugging/profiling.md | 18 +- en/_doc/developer/debugging/test-bench.md | 21 ++- en/_doc/developer/debugging/vm-interface.md | 157 +++++++++--------- .../developer/debugging/windows-debugging.md | 42 +++-- 6 files changed, 148 insertions(+), 130 deletions(-) diff --git a/en/_doc/developer/debugging/automated-tests.md b/en/_doc/developer/debugging/automated-tests.md index a44f6c5a81..5bc0bf3ebc 100644 --- a/en/_doc/developer/debugging/automated-tests.md +++ b/en/_doc/developer/debugging/automated-tests.md @@ -9,11 +9,9 @@ ref: 45 title: Automated Tests --- -Automated Tests -=============== +# Automated Tests -Unit and Integration Tests --------------------------- +## Unit and Integration Tests Starting with Qubes R3 we use [python unittest][unittest] to perform automatic tests of Qubes OS. Despite the name, we use it for both [unit tests](https://en.wikipedia.org/wiki/Unit_tests) and [integration tests](https://en.wikipedia.org/wiki/Integration_tests). @@ -48,6 +46,7 @@ Our test runner runs mostly the same as the standard one, but it has some nice a You can use `python3 -m qubes.tests.run -h` to get usage information: +``` [user@dom0 ~]$ python3 -m qubes.tests.run -h usage: run.py [-h] [--verbose] [--quiet] [--list] [--failfast] [--no-failfast] [--do-not-clean] [--do-clean] [--loglevel LEVEL] @@ -85,9 +84,11 @@ You can use `python3 -m qubes.tests.run -h` to get usage information: When running only specific tests, write their names like in log, in format: MODULE+"/"+CLASS+"/"+FUNCTION. MODULE should omit initial "qubes.tests.". Example: basic/TC_00_Basic/test_000_create +``` For instance, to run only the tests for the fedora-21 template, you can use the `-l` option, then filter the list: +``` [user@dom0 ~]$ python3 -m qubes.tests.run -l | grep fedora-21 network/VmNetworking_fedora-21/test_000_simple_networking network/VmNetworking_fedora-21/test_010_simple_proxyvm @@ -110,6 +111,7 @@ For instance, to run only the tests for the fedora-21 template, you can use the vm_qrexec_gui/TC_20_DispVM_fedora-21/test_020_gui_app vm_qrexec_gui/TC_20_DispVM_fedora-21/test_030_edit_file [user@dom0 ~]$ sudo -E python3 -m qubes.tests.run -v `python3 -m qubes.tests.run -l | grep fedora-21` +``` Example test run: @@ -117,11 +119,12 @@ Example test run: Tests are also compatible with nose2 test runner, so you can use this instead: +```bash sudo systemctl stop qubesd; sudo -E nose2 -v --plugin nose2.plugins.loader.loadtests qubes.tests; sudo systemctl start qubesd +``` This may be especially useful together with various nose2 plugins to store tests results (for example `nose2.plugins.junitxml`), to ease presenting results. This is what we use on [OpenQA]. - ### Unit testing inside a VM Many unit tests will also work inside a VM. However all of the tests requiring a dedicated VM to be run (mostly the integration tests) will be skipped. @@ -134,6 +137,7 @@ its dependency [qubes-core-qrexec](https://github.com/QubesOS/qubes-core-qrexec) The below example however will assume that you set up a build environment as described in the [Qubes Builder documentation](/doc/qubes-builder/). Assuming you cloned the `qubes-builder` repository to your home directory inside a fedora VM, you can use the following commands to run the unit tests: + ```{.bash} cd ~ sudo dnf install python3-pip lvm2 python35 python3-virtualenv @@ -160,16 +164,17 @@ the current stable branch. Test runs can be altered using environment variables: - - `DEFAULT_LVM_POOL` - LVM thin pool to use for tests, in `VolumeGroup/ThinPool` format - - `QUBES_TEST_PCIDEV` - PCI device to be used in PCI passthrough tests (for example sound card) - - `QUBES_TEST_TEMPLATES` - space separated list of templates to run tests on; if not set, all installed templates are tested - - `QUBES_TEST_LOAD_ALL` - load all tests (including tests for all templates) when relevant test modules are imported; this needs to be set for test runners not supporting [load_tests protocol](https://docs.python.org/3/library/unittest.html#load-tests-protocol) +- `DEFAULT_LVM_POOL` - LVM thin pool to use for tests, in `VolumeGroup/ThinPool` format +- `QUBES_TEST_PCIDEV` - PCI device to be used in PCI passthrough tests (for example sound card) +- `QUBES_TEST_TEMPLATES` - space separated list of templates to run tests on; if not set, all installed templates are tested +- `QUBES_TEST_LOAD_ALL` - load all tests (including tests for all templates) when relevant test modules are imported; this needs to be set for test runners not supporting [load_tests protocol](https://docs.python.org/3/library/unittest.html#load-tests-protocol) ### Adding a new test to core-admin -After adding a new unit test to [core-admin/qubes/tests](https://github.com/QubesOS/qubes-core-admin/tree/master/qubes/tests) you'll have to include it in [core-admin/qubes/tests/\_\_init\_\_.py](https://github.com/QubesOS/qubes-core-admin/tree/master/qubes/tests/__init__.py) +After adding a new unit test to [core-admin/qubes/tests](https://github.com/QubesOS/qubes-core-admin/tree/master/qubes/tests) you'll have to include it in [core-admin/qubes/tests/\_\_init\_\_.py](https://github.com/QubesOS/qubes-core-admin/tree/master/qubes/tests/__init__.py) #### Editing `__init__.py` + You'll also need to add your test at the bottom of the `__init__.py` file, in the method `def load_tests`, in the for loop with `modname`. Again, given the hypothetical `example.py` test: @@ -239,9 +244,7 @@ class SomeTestCase(unittest.TestCase): gc.collect() ~~~ - -Installation Tests with openQA ------------------------------- +## Installation Tests with openQA **URL:** **Tests:** diff --git a/en/_doc/developer/debugging/mount-lvm-image.md b/en/_doc/developer/debugging/mount-lvm-image.md index 65615feb0b..91a469f4d0 100644 --- a/en/_doc/developer/debugging/mount-lvm-image.md +++ b/en/_doc/developer/debugging/mount-lvm-image.md @@ -28,6 +28,7 @@ From dom0 terminal: 3: Attach the device to your newly created disp VM From the GUI, or from the command line: + ```bash [user@dom0]$ qvm-block attach NEWLY_CREATED_DISPVM dom0:$dev ``` @@ -39,15 +40,19 @@ From the GUI, or from the command line: ``` 5: Umount and kill the VM -``` + +```bash [user@dispXXXX]$ umount /mnt/ ``` 6: Remove the image from qubesdb -``` + +```bash [user@dom0]$ qubesdb-rm /qubes-block-devices/$dev/ ``` # References -https://github.com/QubesOS/qubes-issues/issues/4687#issuecomment-451626625 +Please consult this issue's [comment]. + +[comment]: https://github.com/QubesOS/qubes-issues/issues/4687#issuecomment-451626625 diff --git a/en/_doc/developer/debugging/profiling.md b/en/_doc/developer/debugging/profiling.md index 69d5149194..e211dd304e 100644 --- a/en/_doc/developer/debugging/profiling.md +++ b/en/_doc/developer/debugging/profiling.md @@ -10,15 +10,13 @@ ref: 48 title: Profiling --- -Profiling -========= +# Profiling This is a python profiling primer. For the purpose of this document, `qubes-dev` is name of the domain used for postprocessing profiling stats. -Requirements ------------- +## Requirements ~~~ yum install gprof2dot graphviz @@ -32,10 +30,9 @@ mkdir -p ~/profiling qvm-run -p qubes-dev 'cat ~/profiling/Upload.sh' > ~/profiling/Upload.sh ~~~ -- WARNING: this will obviously be running third-party code which is not signed by ITL nor Fedora. You have been warned. +- WARNING: this will obviously be running third-party code which is not signed by ITL nor Fedora. You have been warned. -Workflow --------- +## Workflow ### Identify function responsible for some slow action @@ -45,17 +42,21 @@ You have to select the area in which you suspect less than optimal performance. Replace +```python def foo(self, bar): # function content +``` with +```python def foo(self, *args, **kwargs): profile.runctx('self.real_foo(*args, **kwargs)', globals(), locals(), time.strftime('/home/user/profiling/foo-%Y%m%d-%H%M%S.pstats')) def real_foo(self, bar): # function content +``` ### Run application @@ -90,8 +91,7 @@ This creates `index.html` with all SVG graphics linked to TXT files, ready for u make REMOTE=example.com:public_html/qubes/profiling/ upload ~~~ -Example -------- +## Example This example is from `qubes-manager` (`qubesmanager/main.py`). diff --git a/en/_doc/developer/debugging/test-bench.md b/en/_doc/developer/debugging/test-bench.md index bd631900d6..29d7447231 100644 --- a/en/_doc/developer/debugging/test-bench.md +++ b/en/_doc/developer/debugging/test-bench.md @@ -10,20 +10,19 @@ ref: 44 title: Test Bench --- -Test bench for Dom0 -=================== +# Test bench for Dom0 This guide shows how to set up simple test bench that automatically test your code you're about to push. It is written especially for `core3` branch of `core-admin.git` repo, but some ideas are universal. We will set up a spare machine (bare metal, not a virtual) that will be hosting our experimental Dom0. We will communicate with it via Ethernet and SSH. This tutorial assumes you are familiar with [QubesBuilder](/doc/qubes-builder/) and you have it set up and running flawlessly. -Setting up the machine ----------------------- +## Setting up the machine First, do a clean install from ISO you built or grabbed elsewhere. You have to fix network, because it is intentionally broken. This script should reenable your network card without depending on anything else. +```bash #!/bin/sh # adjust this for your NIC (run lspci) @@ -55,6 +54,7 @@ You have to fix network, because it is intentionally broken. This script should pcibind ${BDF} e1000e dhclient +``` TODO: describe how to run this at every startup @@ -68,8 +68,7 @@ yum install openssh-server Ensure that sudo works without password from your user account (it should by default). -Development VM --------------- +## Development VM ### SSH @@ -97,12 +96,15 @@ This step is optional, but very helpful. Put these scripts somewhere in your `${ `qtb-runtests`: +```bash #!/bin/sh ssh testbench python -m qubes.tests.run +``` `qtb-install`: +```bash #!/bin/sh TMPDIR=/tmp/qtb-rpms @@ -121,9 +123,11 @@ This step is optional, but very helpful. Put these scripts somewhere in your `${ ssh testbench sudo rpm -i --replacepkgs --replacefiles "${TMPDIR}/$(basename ${1})" shift done +``` `qtb-iterate`: +```bash #!/bin/sh set -e @@ -138,6 +142,7 @@ This step is optional, but very helpful. Put these scripts somewhere in your `${ make core-admin qtb-install qubes-src/core-admin/rpm/x86_64/qubes-core-dom0-*.rpm qtb-runtests +``` ### Hooking git @@ -145,14 +150,18 @@ I (woju) have those two git hooks. They ensure tests are passing (or are marked `core-admin/.git/hooks/pre-commit`: (you may retain also the default hook, here omitted for readability) +```bash #!/bin/sh set -e python -c "import sys, qubes.tests.run; sys.exit(not qubes.tests.run.main())" +``` `core-admin/.git/hooks/pre-push`: +```bash #!/bin/sh exec qtb-iterate +``` diff --git a/en/_doc/developer/debugging/vm-interface.md b/en/_doc/developer/debugging/vm-interface.md index 89f379669e..f24669104a 100644 --- a/en/_doc/developer/debugging/vm-interface.md +++ b/en/_doc/developer/debugging/vm-interface.md @@ -11,45 +11,43 @@ ref: 47 title: VM Configuration Interface --- -VM Configuration Interface -========================== +# VM Configuration Interface Qubes VM have some settings set by dom0 based on VM settings. There are multiple configuration channels, which includes: -- QubesDB -- XenStore (in Qubes 2, data the same as in QubesDB, keys without leading `/`) -- Qubes RPC (called at VM startup, or when configuration changed) -- GUI protocol - -QubesDB --------------------- - -### Keys exposed by dom0 to VM ### - -- `/qubes-vm-type` - VM type, the same as `type` field in `qvm-prefs`. One of `AppVM`, `ProxyVM`, `NetVM`, `TemplateVM`, `HVM`, `TemplateHVM` -- `/qubes-vm-updatable` - flag whether VM is updatable (whether changes in root.img will survive VM restart). One of `True`, `False` -- `/qubes-vm-persistence` - what data do persist between VM restarts: - - `full` - all disks - - `rw-only` - only `/rw` disk - - `none` - none -- `/qubes-timezone - name of timezone based on dom0 timezone. For example `Europe/Warsaw` -- `/qubes-keyboard` (deprecated in R4.1) - keyboard layout based on dom0 layout. Its syntax is suitable for `xkbcomp` command (after expanding escape sequences like `\n` or `\t`). This is meant only as some default value, VM can ignore this option and choose its own keyboard layout (this is what keyboard setting from Qubes Manager does). This entry is created as part of gui-daemon initialization (so not available when gui-daemon disabled, or not started yet). -- `/keyboard-layout` - keyboard layout based on GuiVM layout. Its syntax can be `layout+variant+options`, `layout+variant`, `layout++options` or simply `layout`. For example, `fr+oss`, `pl++compose:caps` or `fr`. This is meant only as some default value, VM can ignore this option and choose its own keyboard layout (this is what keyboard setting from Qubes Manager does). -- `/qubes-debug-mode` - flag whether VM has debug mode enabled (qvm-prefs setting). One of `1`, `0` -- `/qubes-service/SERVICE_NAME` - subtree for VM services controlled from dom0 (using the `qvm-service` command or Qubes Manager). One of `1`, `0`. Note that not every service will be listed here, if entry is missing, it means "use VM default". A list of currently supported services is in the `qvm-service` man page. -- `/qubes-netmask` - network mask (only when VM has netvm set); currently hardcoded "255.255.255.0" -- `/qubes-ip - IP address for this VM (only when VM has netvm set) -- `/qubes-gateway` - default gateway IP (only when VM has netvm set); VM should add host route to this address directly via eth0 (or whatever default interface name is) -- `/qubes-primary-dns` - primary DNS address (only when VM has netvm set) -- `/qubes-secondary-dns` - secondary DNS address (only when VM has netvm set) -- `/qubes-netvm-gateway` - same as `qubes-gateway` in connected VMs (only when VM serves as network backend - ProxyVM and NetVM) -- `/qubes-netvm-netmask` - same as `qubes-netmask` in connected VMs (only when VM serves as network backend - ProxyVM and NetVM) -- `/qubes-netvm-network` - network address (only when VM serves as network backend - ProxyVM and NetVM); can be also calculated from qubes-netvm-gateway and qubes-netvm-netmask -- `/qubes-netvm-primary-dns` - same as `qubes-primary-dns` in connected VMs (only when VM serves as network backend - ProxyVM and NetVM); traffic sent to this IP on port 53 should be redirected to primary DNS server -- `/qubes-netvm-secondary-dns` - same as `qubes-secondary-dns` in connected VMs (only when VM serves as network backend - ProxyVM and NetVM); traffic sent to this IP on port 53 should be redirected to secondary DNS server -- `/guivm-windows-prefix` - title prefix for any window not originating from another qube. This means windows of applications running in GuiVM itself - -#### Firewall rules in 3.x #### +- QubesDB +- XenStore (in Qubes 2, data the same as in QubesDB, keys without leading `/`) +- Qubes RPC (called at VM startup, or when configuration changed) +- GUI protocol + +## QubesDB + +### Keys exposed by dom0 to VM + +- `/qubes-vm-type` - VM type, the same as `type` field in `qvm-prefs`. One of `AppVM`, `ProxyVM`, `NetVM`, `TemplateVM`, `HVM`, `TemplateHVM` +- `/qubes-vm-updatable` - flag whether VM is updatable (whether changes in root.img will survive VM restart). One of `True`, `False` +- `/qubes-vm-persistence` - what data do persist between VM restarts: + - `full` - all disks + - `rw-only` - only `/rw` disk + - `none` - none +- `/qubes-timezone - name of timezone based on dom0 timezone. For example `Europe/Warsaw` +- `/qubes-keyboard` (deprecated in R4.1) - keyboard layout based on dom0 layout. Its syntax is suitable for `xkbcomp` command (after expanding escape sequences like `\n` or `\t`). This is meant only as some default value, VM can ignore this option and choose its own keyboard layout (this is what keyboard setting from Qubes Manager does). This entry is created as part of gui-daemon initialization (so not available when gui-daemon disabled, or not started yet). +- `/keyboard-layout` - keyboard layout based on GuiVM layout. Its syntax can be `layout+variant+options`, `layout+variant`, `layout++options` or simply `layout`. For example, `fr+oss`, `pl++compose:caps` or `fr`. This is meant only as some default value, VM can ignore this option and choose its own keyboard layout (this is what keyboard setting from Qubes Manager does). +- `/qubes-debug-mode` - flag whether VM has debug mode enabled (qvm-prefs setting). One of `1`, `0` +- `/qubes-service/SERVICE_NAME` - subtree for VM services controlled from dom0 (using the `qvm-service` command or Qubes Manager). One of `1`, `0`. Note that not every service will be listed here, if entry is missing, it means "use VM default". A list of currently supported services is in the `qvm-service` man page. +- `/qubes-netmask` - network mask (only when VM has netvm set); currently hardcoded "255.255.255.0" +- `/qubes-ip - IP address for this VM (only when VM has netvm set) +- `/qubes-gateway` - default gateway IP (only when VM has netvm set); VM should add host route to this address directly via eth0 (or whatever default interface name is) +- `/qubes-primary-dns` - primary DNS address (only when VM has netvm set) +- `/qubes-secondary-dns` - secondary DNS address (only when VM has netvm set) +- `/qubes-netvm-gateway` - same as `qubes-gateway` in connected VMs (only when VM serves as network backend - ProxyVM and NetVM) +- `/qubes-netvm-netmask` - same as `qubes-netmask` in connected VMs (only when VM serves as network backend - ProxyVM and NetVM) +- `/qubes-netvm-network` - network address (only when VM serves as network backend - ProxyVM and NetVM); can be also calculated from qubes-netvm-gateway and qubes-netvm-netmask +- `/qubes-netvm-primary-dns` - same as `qubes-primary-dns` in connected VMs (only when VM serves as network backend - ProxyVM and NetVM); traffic sent to this IP on port 53 should be redirected to primary DNS server +- `/qubes-netvm-secondary-dns` - same as `qubes-secondary-dns` in connected VMs (only when VM serves as network backend - ProxyVM and NetVM); traffic sent to this IP on port 53 should be redirected to secondary DNS server +- `/guivm-windows-prefix` - title prefix for any window not originating from another qube. This means windows of applications running in GuiVM itself + +#### Firewall rules in 3.x QubesDB is also used to configure firewall in ProxyVMs. Rules are stored in separate key for each target VM. Entries: @@ -65,7 +63,7 @@ VM after applying rules may signal some error, writing a message to `/qubes-iptables-error` key. This does not exclude any other way of communicating problems - like a popup. -#### Firewall rules in 4.x #### +#### Firewall rules in 4.x QubesDB is also used to configure firewall in ProxyVMs. Each rule is stored as a separate entry, grouped on target VM: @@ -87,19 +85,19 @@ Each rule is a single QubesDB entry, consisting of pairs `key=value` separated by space. QubesDB enforces limit on a single entry length - 3072 bytes. Possible options for a single rule: - - `action`, values: `accept`, `drop`; this is present in every rule - - `dst4`, value: destination IPv4 address with a mask; for example: `192.168.0.0/24` - - `dst6`, value: destination IPv6 address with a mask; for example: `2000::/3` - - `dsthost`, value: DNS hostname of destination host - - `proto`, values: `tcp`, `udp`, `icmp` - - `specialtarget`, value: One of predefined target, currently defined values: - - `dns` - such option should match DNS traffic to default DNS server (but +- `action`, values: `accept`, `drop`; this is present in every rule +- `dst4`, value: destination IPv4 address with a mask; for example: `192.168.0.0/24` +- `dst6`, value: destination IPv6 address with a mask; for example: `2000::/3` +- `dsthost`, value: DNS hostname of destination host +- `proto`, values: `tcp`, `udp`, `icmp` +- `specialtarget`, value: One of predefined target, currently defined values: + - `dns` - such option should match DNS traffic to default DNS server (but not any DNS server), on both TCP and UDP - - `dstports`, value: destination ports range separated with `-`, valid only +- `dstports`, value: destination ports range separated with `-`, valid only together with `proto=tcp` or `proto=udp`; for example `1-1024`, `80-80` - - `icmptype`, value: numeric (decimal) icmp message type, for example `8` for +- `icmptype`, value: numeric (decimal) icmp message type, for example `8` for echo request, valid only together with `proto=icmp` - - `dpi`, value: Deep Packet Inspection protocol (like: HTTP, SSL, SMB, SSH, SMTP) or the default 'NO' as no DPI, only packet filtering +- `dpi`, value: Deep Packet Inspection protocol (like: HTTP, SSL, SMB, SSH, SMTP) or the default 'NO' as no DPI, only packet filtering Options must appear in the rule in the order listed above. Duplicated options are forbidden. @@ -119,48 +117,46 @@ Example valid rules: - `action=drop proto=tcp specialtarget=dns` - drop DNS queries sent using TCP - `action=drop` -### Keys set by VM for passing info to dom0 ### +### Keys set by VM for passing info to dom0 -- `memory/meminfo` (**xenstore**) - used memory (updated by qubes-meminfo-writer), input information for qmemman; - - Qubes 3.x format: 6 lines (EOL encoded as `\n`), each in format "FIELD: VALUE kB"; fields: `MemTotal`, `MemFree`, `Buffers`, `Cached`, `SwapTotal`, `SwapFree`; meaning the same as in `/proc/meminfo` in Linux. - - Qubes 4.0+ format: used memory size in the VM, in kbytes -- `/qubes-block-devices` - list of block devices exposed by this VM, each device (subdirectory) should be named in a way that VM can attach the device based on it. Each should contain these entries: - - `desc` - device description (ASCII text) - - `size` - device size in bytes - - `mode` - default connection mode; `r` for read-only, `w` for read-write -- `/qubes-usb-devices` - list of USB devices exposed by this VM, each device (subdirectory) should contain: - - `desc` - device description (ASCII text) - - `usb-ver` - USB version (1, 2 or 3) +- `memory/meminfo` (**xenstore**) - used memory (updated by qubes-meminfo-writer), input information for qmemman; + - Qubes 3.x format: 6 lines (EOL encoded as `\n`), each in format "FIELD: VALUE kB"; fields: `MemTotal`, `MemFree`, `Buffers`, `Cached`, `SwapTotal`, `SwapFree`; meaning the same as in `/proc/meminfo` in Linux. + - Qubes 4.0+ format: used memory size in the VM, in kbytes +- `/qubes-block-devices` - list of block devices exposed by this VM, each device (subdirectory) should be named in a way that VM can attach the device based on it. Each should contain these entries: + - `desc` - device description (ASCII text) + - `size` - device size in bytes + - `mode` - default connection mode; `r` for read-only, `w` for read-write +- `/qubes-usb-devices` - list of USB devices exposed by this VM, each device (subdirectory) should contain: + - `desc` - device description (ASCII text) + - `usb-ver` - USB version (1, 2 or 3) -Qubes RPC ---------- +## Qubes RPC Services called by dom0 to provide some VM configuration: -- `qubes.SetMonitorLayout` - provide list of monitors, one per line. Each line contains four numbers: `width height X Y width_mm height_mm` (physical dimensions - `width_mm` and `height_mm` - are optional) -- `qubes.WaitForSession` - called to wait for full VM startup -- `qubes.GetAppmenus` - receive appmenus from given VM (template); TODO: describe format here -- `qubes.GetImageRGBA` - receive image/application icon. Protocol: +- `qubes.SetMonitorLayout` - provide list of monitors, one per line. Each line contains four numbers: `width height X Y width_mm height_mm` (physical dimensions - `width_mm` and `height_mm` - are optional) +- `qubes.WaitForSession` - called to wait for full VM startup +- `qubes.GetAppmenus` - receive appmenus from given VM (template); TODO: describe format here +- `qubes.GetImageRGBA` - receive image/application icon. Protocol: - 1. Caller sends name of requested icon. This can be one of: - * `xdgicon:NAME` - search for NAME in standard icons theme - * `-` - get icon data from stdin (the caller), can be prefixed with format name, for example `png:-` - * file name - 2. The service responds with image dimensions: width and height as + 1. Caller sends name of requested icon. This can be one of: + * `xdgicon:NAME` - search for NAME in standard icons theme + * `-` - get icon data from stdin (the caller), can be prefixed with format name, for example `png:-` + * file name + 2. The service responds with image dimensions: width and height as decimal numbers, separated with space and with EOL marker at the and; then image data in RGBA format (32 bits per pixel) -- `qubes.SetDateTime` - set VM time, called periodically by dom0 (can be +- `qubes.SetDateTime` - set VM time, called periodically by dom0 (can be triggered manually from dom0 by calling `qvm-sync-clock`). The service receives one line at stdin - time in format of `date -u -Iseconds`, for example `2015-07-31T16:10:43+0000`. -- `qubes.SetGuiMode` - called in HVM to switch between fullscreen and seamless +- `qubes.SetGuiMode` - called in HVM to switch between fullscreen and seamless GUI mode. The service receives a single word on stdin - either `FULLSCREEN` or `SEAMLESS` -- `qubes.ResizeDisk` - called to inform that underlying disk was resized. +- `qubes.ResizeDisk` - called to inform that underlying disk was resized. Name of disk image is passed on standard input (`root`, `private`, `volatile`, or other). This is used starting with Qubes 4.0. - Other Qrexec services installed by default: - `qubes.Backup` - store Qubes backup. The service receives location chosen by @@ -195,15 +191,15 @@ Other Qrexec services installed by default: can send icon for the same window multiple times to replace previous one (for example for animated icons) - `qubes.VMShell` - call any command in the VM; the command(s) is passed one per line - - `qubes.VMShell+WaitForSession` waits for full VM startup first + - `qubes.VMShell+WaitForSession` waits for full VM startup first - `qubes.VMExec` - call any command in the VM, without using shell, the command needs to be passed as argument and encoded as follows: - - the executable name and arguments are separated by `+` - - everything except alphanumeric characters, `.` and `_` needs to be + - the executable name and arguments are separated by `+` + - everything except alphanumeric characters, `.` and `_` needs to be escaped - - bytes are escaped as `-HH` (where `HH` is hex code, capital letters only) - - `-` itself can be escaped as `--` - - example: to run `ls -a /home/user`, use + - bytes are escaped as `-HH` (where `HH` is hex code, capital letters only) + - `-` itself can be escaped as `--` + - example: to run `ls -a /home/user`, use `qubes.VMExec+ls+--a+-2Fhome-2Fuser` - `qubes.VMExecGUI` - a variant of `qubes.VMExec` that waits for full VM startup first @@ -226,7 +222,6 @@ abstraction. This will change in the future. Those tools are: Additionally, automatic tests extensively run various commands directly in VMs. We do not plan to change that. -GUI protocol ------------- +## GUI protocol GUI initialization includes passing the whole screen dimensions from dom0 to VM. This will most likely be overwritten by qubes.SetMonitorLayout Qubes RPC call. diff --git a/en/_doc/developer/debugging/windows-debugging.md b/en/_doc/developer/debugging/windows-debugging.md index 93846db32c..f8c07613f8 100644 --- a/en/_doc/developer/debugging/windows-debugging.md +++ b/en/_doc/developer/debugging/windows-debugging.md @@ -10,8 +10,7 @@ ref: 50 title: Windows Debugging --- -Debugging Windows HVMs -====================== +# Debugging Windows HVMs Debugging Windows code can be tricky in a virtualized environment. The guide below assumes Xen hypervisor and Windows 7 VMs. @@ -19,22 +18,25 @@ User-mode debugging is usually straightforward if it can be done on one machine. Things get complicated if you need to perform kernel debugging or troubleshoot problems that only manifest on system boot, user logoff or similar. For that you need two Windows VMs: the *host* and the *target*. The *host* will contain [WinDbg](https://msdn.microsoft.com/en-us/library/windows/hardware/ff551063(v=vs.85).aspx) installation, your source code and private symbols. The *target* will run the code being debugged. Both will be linked by virtual serial ports. -- First, you need to prepare separate copies of both *target* and *host* VM configuration files with some changes. Copy the files from **/var/lib/qubes/appvms/vmname/vmname.conf** to some convenient location, let's call them **host.conf** and **target.conf**. -- In both copied files add the following line at the end: `serial = 'pty'`. This will make Xen connect VM's serial ports to dom0's ptys. -- From now on you need to start both VMs like this: `qvm-start --custom-config=/your/edited/host.conf host` -- To connect both VM serial ports together you will either need [socat](http://www.dest-unreach.org/socat/) or a custom utility described later. -- To determine which dom0 pty corresponds to VM's serial port you need to read xenstore, example script below: +- First, you need to prepare separate copies of both *target* and *host* VM configuration files with some changes. Copy the files from **/var/lib/qubes/appvms/vmname/vmname.conf** to some convenient location, let's call them **host.conf** and **target.conf**. +- In both copied files add the following line at the end: `serial = 'pty'`. This will make Xen connect VM's serial ports to dom0's ptys. +- From now on you need to start both VMs like this: `qvm-start --custom-config=/your/edited/host.conf host` +- To connect both VM serial ports together you will either need [socat](http://www.dest-unreach.org/socat/) or a custom utility described later. +- To determine which dom0 pty corresponds to VM's serial port you need to read xenstore, example script below: +```bash #!/bin/sh id1=$(xl domid "$1-dm") tty1=$(xenstore-read /local/domain/${id1}/device/console/3/tty) echo $tty1 +``` - Pass it a running VM name and it will output the corresponding pty name. +Pass it a running VM name and it will output the corresponding pty name. -- To connect both ptys you can use [socat](http://www.dest-unreach.org/socat/) like that: +- To connect both ptys you can use [socat](http://www.dest-unreach.org/socat/) like that: +```bash #!/bin/sh id1=$(xl domid "$1-dm") @@ -42,14 +44,15 @@ Things get complicated if you need to perform kernel debugging or troubleshoot p tty1=$(xenstore-read /local/domain/${id1}/device/console/3/tty) tty2=$(xenstore-read /local/domain/${id2}/device/console/3/tty) socat $tty1,raw $tty2,raw +``` - ...but there is a catch. Xen seems to process the traffic that goes through serial ports and changes all **0x0a** bytes into **0x0d, 0x0a** pairs (newline conversion). I didn't find a way to turn that off (setting ptys to raw mode didn't change anything) and it's not mentioned anywhere on the Internet, so maybe it's something on my system. If the above script works for you then you don't need anything more in dom0. +...but there is a catch. Xen seems to process the traffic that goes through serial ports and changes all **0x0a** bytes into **0x0d, 0x0a** pairs (newline conversion). I didn't find a way to turn that off (setting ptys to raw mode didn't change anything) and it's not mentioned anywhere on the Internet, so maybe it's something on my system. If the above script works for you then you don't need anything more in dom0. -- On the *target* system, run `bcdedit /set debug on` on the console to turn on kernel debugging. It defaults to the first serial port. -- On the *host* system, install [WinDbg](http://msdn.microsoft.com/en-us/library/windows/hardware/ff551063(v=vs.85).aspx) and start the kernel debug (Ctrl-K), choose **com1** as the debug port. -- Reboot the *target* VM. -- Run the above shell script in dom0. -- If everything is fine you should see the proper kernel debugging output in WinDbg. However, if you see something like that: +- On the *target* system, run `bcdedit /set debug on` on the console to turn on kernel debugging. It defaults to the first serial port. +- On the *host* system, install [WinDbg](http://msdn.microsoft.com/en-us/library/windows/hardware/ff551063(v=vs.85).aspx) and start the kernel debug (Ctrl-K), choose **com1** as the debug port. +- Reboot the *target* VM. +- Run the above shell script in dom0. +- If everything is fine you should see the proper kernel debugging output in WinDbg. However, if you see something like that: ~~~ Opened \\.\com1 @@ -75,6 +78,7 @@ Things get complicated if you need to perform kernel debugging or troubleshoot p ...then you're most likely a victim of the CRLF issue mentioned above. To get around it I wrote a small utility that basically does what socat would do and additionally corrects those replaced bytes in the stream. It's not pretty but it works: +```c #include #include #include @@ -184,6 +188,7 @@ Things get complicated if you need to perform kernel debugging or troubleshoot p close(fd2); return 0; } +``` > This utility is a unidirectional relay so you need to run two instances to get duplex communication, like: > @@ -195,7 +200,6 @@ Things get complicated if you need to perform kernel debugging or troubleshoot p > tty2=$(xenstore-read /local/domain/${id2}/device/console/3/tty) > ./ptycrlf ${tty1} ${tty2} - & > ./ptycrlf ${tty2} ${tty1} + & - > With this everything should be good: > > ~~~ @@ -216,7 +220,7 @@ Things get complicated if you need to perform kernel debugging or troubleshoot p There are two main issues to be adopted to get all things to work in the R4.0. -## Add a virtual serial port ## +## Add a virtual serial port Qemu in the stub domain with virtual serial port added in a recommended way (``````) fails to start (Could not open '/dev/hvc1': No such device). It seems like a lack of multiple xen consoles support/configuration. The only way that I have found is to attach serial port explicitly to the available console. @@ -230,15 +234,17 @@ $ gunzip stubdom-linux-rootfs.gz $ cpio -i -d -H newc --no-absolute-filenames < stubdom-linux-rootfs $ rm stubdom-linux-rootfs ``` + 2. Edit Init script to remove last loop and to add "-serial /dev/hvc0" to the qemu command line. 3. Apply changes: + ```shell_session $ find . -print0 | cpio --null -ov --format=newc | gzip -9 > ../stubdom-linux-rootfs $ sudo mv ../stubdom-linux-rootfs /usr/lib/xen/boot ``` -## Connect two consoles ## +## Connect two consoles Run the following script: From b618997fef431ec95e89e6253d962ce3928269fe Mon Sep 17 00:00:00 2001 From: dd Date: Sun, 1 Nov 2020 00:37:59 +0100 Subject: [PATCH 068/663] linted docs in developer/general --- en/_doc/developer/general/devel-books.md | 14 +- en/_doc/developer/general/doc-guidelines.md | 97 +++---- en/_doc/developer/general/gsoc.md | 251 +++++++++--------- en/_doc/developer/general/gsod.md | 29 +- .../general/package-contributions.md | 79 +++--- en/_doc/developer/general/usability-ux.md | 4 +- 6 files changed, 236 insertions(+), 238 deletions(-) diff --git a/en/_doc/developer/general/devel-books.md b/en/_doc/developer/general/devel-books.md index 6d57eff907..2fc9e56618 100644 --- a/en/_doc/developer/general/devel-books.md +++ b/en/_doc/developer/general/devel-books.md @@ -13,19 +13,19 @@ title: Developer Books Below is a list of various books that might be useful in learning some basics needed for Qubes development. - A must-read about Xen internals: - * _[The Definitive Guide to the Xen Hypervisor](https://www.amazon.com/Definitive-Guide-Xen-Hypervisor/dp/013234971X)_, by David Chisnall + - _[The Definitive Guide to the Xen Hypervisor](https://www.amazon.com/Definitive-Guide-Xen-Hypervisor/dp/013234971X)_, by David Chisnall - Some good books about the Linux kernel: - * _[Linux Kernel Development](https://www.amazon.com/Linux-Kernel-Development-Robert-Love/dp/0672329468)_, by Robert Love - * _[Linux Device Drivers](https://www.amazon.com/Linux-Device-Drivers-Jonathan-Corbet/dp/0596005903)_, by Jonathan Corbet + - _[Linux Kernel Development](https://www.amazon.com/Linux-Kernel-Development-Robert-Love/dp/0672329468)_, by Robert Love + - _[Linux Device Drivers](https://www.amazon.com/Linux-Device-Drivers-Jonathan-Corbet/dp/0596005903)_, by Jonathan Corbet - Solid intro into Trusted Computing: - * _[Dynamics of a Trusted Platform](https://www.amazon.com/Dynamics-Trusted-Platform-Buildin-Grawrock/dp/1934053082)_, by David Grawrock (original Intel architect for TXT) + - _[Dynamics of a Trusted Platform](https://www.amazon.com/Dynamics-Trusted-Platform-Buildin-Grawrock/dp/1934053082)_, by David Grawrock (original Intel architect for TXT) - Good book about GIT: - * _[Pro Git](https://git-scm.com/book/en/v2)_, by Scott Chacon and Ben Straub (complete book available free online) + - _[Pro Git](https://git-scm.com/book/en/v2)_, by Scott Chacon and Ben Straub (complete book available free online) - Useful books about Python: - * _[Programming in Python 3](http://www.qtrac.eu/py3book.html)_, by Mark Summerfield - * _[Rapid GUI Programming with Python and Qt](http://www.qtrac.eu/pyqtbook.html)_, by Mark Summerfield + - _[Programming in Python 3](http://www.qtrac.eu/py3book.html)_, by Mark Summerfield + - _[Rapid GUI Programming with Python and Qt](http://www.qtrac.eu/pyqtbook.html)_, by Mark Summerfield (Although note that [Qt is being replaced by GTK](/doc/usability-ux/#gnome-kde-and-xfce) in Qubes code.) diff --git a/en/_doc/developer/general/doc-guidelines.md b/en/_doc/developer/general/doc-guidelines.md index 37b7ae546d..eb13d6b777 100644 --- a/en/_doc/developer/general/doc-guidelines.md +++ b/en/_doc/developer/general/doc-guidelines.md @@ -10,8 +10,7 @@ ref: 30 title: Documentation Guidelines --- -Documentation Guidelines -======================== +# Documentation Guidelines All Qubes OS documentation pages are stored as plain text files in the dedicated [qubes-doc] repository. By cloning and regularly pulling from this repo, users can maintain their own up-to-date offline copy of all Qubes documentation rather than relying solely on the web. @@ -19,9 +18,7 @@ By cloning and regularly pulling from this repo, users can maintain their own up The documentation is a community effort. Volunteers work hard trying to keep everything accurate and comprehensive. If you notice a problem or some way it can be improved, please [edit the documentation][contribute]! - -Security --------- +## Security All pull requests against [qubes-doc] must pass review prior to be merged, except in the case of [external documentation] (see [#4693]). This process is designed to ensure that contributed text is accurate and non-malicious. @@ -35,28 +32,24 @@ The documentation maintainer then verifies that the pull request is mechanically If so, the documentation maintainer then merges the pull request, adds a PGP-signed tag to the latest commit (usually the merge commit), then pushes to the remote. In cases in which another reviewer is not required, the documentation maintainer may review the pull request (in which case no signed comment is necessary, since it would be redundant with the signed tag). - -Questions, problems, and improvements -------------------------------------- +## Questions, problems, and improvements If you have a question about something you read in the documentation, please send it to the appropriate [mailing list][support]. If you see that something in the documentation should be fixed or improved, please [contribute] the change yourself. To report an issue with the documentation, please follow our standard [issue reporting guidelines][issue]. (If you report an issue with the documentation, you will likely be asked to address it, unless there is a clear indication in your report that you are not willing or able to do so.) - -How to Contribute ------------------ +## How to Contribute Editing the documentation is easy, so if you see that a change should be made, please contribute it! A few notes before we get started: - * Since Qubes is a security-oriented project, every documentation change will be reviewed before it's accepted. +* Since Qubes is a security-oriented project, every documentation change will be reviewed before it's accepted. This allows us to maintain quality control and protect our users. - * We don't want you to spend time and effort on a contribution that we can't accept. +* We don't want you to spend time and effort on a contribution that we can't accept. If your contribution would take a lot of time, please [file an issue][issue] for it first so that we can make sure we're on the same page before significant works begins. - * Alternatively, you may already have written content that doesn't conform to these guidelines, but you'd be willing to modify it so that it does. +* Alternatively, you may already have written content that doesn't conform to these guidelines, but you'd be willing to modify it so that it does. In this case, you can still submit it by following the instructions below. Just make a note in your pull request that you're aware of the changes that need to be made and that you're just asking for the content to be reviewed before you spend time making those changes. @@ -117,9 +110,7 @@ If, for some reason, we can't accept your pull request, we'll post a comment exp ![done](/attachment/wiki/doc-edit/10-done.png) - -How to add images ------------------ +## How to add images To add an image to a page, use the following syntax in the main document: @@ -129,9 +120,7 @@ To add an image to a page, use the following syntax in the main document: Then, submit your image(s) in a separate pull request to the [qubes-attachment] repository using the same path and filename. - -Version-specific Documentation ------------------------------- +## Version-specific Documentation We maintain only one set of documentation for Qubes OS. We do not maintain a different set of documentation for each version of Qubes. @@ -141,7 +130,7 @@ Our second priority is to document the next, upcoming release (if any) that is c In cases where a documentation page covers functionality that differs considerably between Qubes OS versions, the page should be subdivided into clearly-labeled sections that cover the different functionality in different versions: -### Incorrect Example ### +### Incorrect Example ``` # Page Title # @@ -166,7 +155,7 @@ command introduced in 4.0: Once you foo, make sure to close the baz before fooing the next bar. ``` -### Correct Example ### +### Correct Example ``` # Page Title # @@ -185,7 +174,6 @@ To foo: Once you foo, make sure to close the baz before fooing the next bar. - ## Qubes 4.0 ## ### How to Foo ### @@ -205,7 +193,7 @@ Once you foo, make sure to close the baz before fooing the next bar. Subdividing the page into clearly-labeled sections for each version has several benefits: - * It preserves good content for older (but still supported) versions. +* It preserves good content for older (but still supported) versions. Many documentation contributors are also people who prefer to use the latest version. Many of them are tempted to *replace* existing content that applies to an older, supported version with content that applies only to the latest version. This is somewhat understandable. @@ -215,15 +203,15 @@ Subdividing the page into clearly-labeled sections for each version has several With the older, supported version, there has been more time to fix bugs and make improvements in both the software and the documentation. Consequently, much of the documentation content for this version may have gone through several rounds of editing, review, and revision. It would be a tragedy for this content to vanish while the very set of users who most prize stability and reliability are depending on it. - * It's easy for readers to quickly find the information they're looking for, since they can go directly to the section that applies to their version. - * It's hard for readers to miss information they need, since it's all in one place. +* It's easy for readers to quickly find the information they're looking for, since they can go directly to the section that applies to their version. +* It's hard for readers to miss information they need, since it's all in one place. In the incorrect example, information that the reader needs could be in any paragraph in the entire document, and there's no way to tell without reading the entire page. In the correct example, the reader can simply skim the headings in order to know which parts of the page need to be read and which can be safely ignored. The fact that some content is repeated in the two version-specific sections is not a problem, since no reader has to read the same thing twice. Moreover, as one version gets updated, it's likely that the documentation for that version will also be updated. Therefore, content that is initially duplicated between version-specific sections will not necessarily stay that way, and this is a good thing: We want the documentation for a version that *doesn't* change to stay the same, and we want the documentation for a version that *does* change to change along with the software. - * It's easy for documentation contributors and maintainers to know which file to edit and update, since there's only one page for all Qubes OS versions. +* It's easy for documentation contributors and maintainers to know which file to edit and update, since there's only one page for all Qubes OS versions. Initially creating the new headings and duplicating content that applies to both is only a one-time cost for each page, and many pages don't even require this treatment, since they apply to all currently-supported Qubes OS versions. By contrast, an alternative approach, such as segregating the documentation into two different branches, would mean that contributions that apply to both Qubes versions would only end up in one branch, unless someone remembered to manually submit the same thing to the other branch and actually made the effort to do so. @@ -235,38 +223,35 @@ Good general content that was submitted only to one branch would effectively dis For further discussion about version-specific documentation in Qubes, see [here][version-thread]. +## Style Guidelines -Style Guidelines ----------------- - - * Familiarize yourself with the terms defined in the [glossary]. Use these +* Familiarize yourself with the terms defined in the [glossary]. Use these terms consistently and accurately throughout your writing. - -Markdown Conventions --------------------- +## Markdown Conventions All the documentation is written in Markdown for maximum accessibility. When making contributions, please try to observe the following style conventions: - * Use spaces instead of tabs. - * In order to enable offline browsing, use relative paths (e.g., `/doc/doc-guidelines/` instead of `https://www.qubes-os.org/doc/doc-guidelines/`, except when the source text will be reproduced outside of the Qubes website repo. +* Use spaces instead of tabs. +* In order to enable offline browsing, use relative paths (e.g., `/doc/doc-guidelines/` instead of `https://www.qubes-os.org/doc/doc-guidelines/`, except when the source text will be reproduced outside of the Qubes website repo. Examples of exceptions: - * [QSBs] (intended to be read as plain text) - * [News] posts (plain text is reproduced on the [mailing lists][support]) - * URLs that appear inside code blocks (e.g., in comments and document templates) - * Files like `README.md` and `CONTRIBUTING.md` - * Insert a newline at, and only at, the end of each sentence, except when the text will be reproduced outside of the Qubes website repo (see previous item for examples). - * Rationale: This practice results in one sentence per line, which is most appropriate for source that consists primarily of natural language text. + * [QSBs] (intended to be read as plain text) + * [News] posts (plain text is reproduced on the [mailing lists][support]) + * URLs that appear inside code blocks (e.g., in comments and document templates) + * Files like `README.md` and `CONTRIBUTING.md` +* Insert a newline at, and only at, the end of each sentence, except when the text will be reproduced outside of the Qubes website repo (see previous item for examples). + * Rationale: This practice results in one sentence per line, which is most appropriate for source that consists primarily of natural language text. It results in the most useful diffs and facilitates translation into other languages while mostly preserving source readability. - * If appropriate, make numerals in numbered lists match between Markdown source and HTML output. - * Rationale: In the event that a user is required to read the Markdown source directly, this will make it easier to follow, e.g., numbered steps in a set of instructions. - * Use hanging indentations +* If appropriate, make numerals in numbered lists match between Markdown source and HTML output. + * Rationale: In the event that a user is required to read the Markdown source directly, this will make it easier to follow, e.g., numbered steps in a set of instructions. +* Use hanging indentations where appropriate. - * Use Atx-style headings: `# h1`, `##h 2`, `### h3`, etc. - * When writing code blocks, use [syntax highlighting](https://github.github.com/gfm/#info-string) where [possible](https://github.com/jneen/rouge/wiki/List-of-supported-languages-and-lexers) and use `[...]` for anything omitted. - * When providing command line examples: - * Tell the reader where to open a terminal (dom0 or a specific domU), and show the command along with its output (if any) in a code block, e.g.: +* Use Atx-style headings: `# h1`, `##h 2`, `### h3`, etc. +* When writing code blocks, use [syntax highlighting](https://github.github.com/gfm/#info-string) where [possible](https://github.com/jneen/rouge/wiki/List-of-supported-languages-and-lexers) and use `[...]` for anything omitted. +* When providing command line examples: + * Tell the reader where to open a terminal (dom0 or a specific domU), and show the command along with its output (if any) in a code block, e.g.: + ~~~markdown Open a terminal in dom0 and run: ```shell_session @@ -275,10 +260,12 @@ When making contributions, please try to observe the following style conventions Hello ``` ~~~ - * Precede each command with the appropriate command prompt: + + * Precede each command with the appropriate command prompt: At a minimum, the prompt should contain a trailing `#` (for the user `root`) or `$` (for other users) on Linux systems and `>` on Windows systems, respectively. - * Don't try to add comments inside the code block. + * Don't try to add comments inside the code block. For example, *don't* do this: + ~~~markdown Open a terminal in dom0 and run: ```shell_session @@ -289,22 +276,20 @@ When making contributions, please try to observe the following style conventions Hello ``` ~~~ + The `#` symbol preceding each comment is ambiguous with a root command prompt. Instead, put your comments *outside* of the code block in normal prose. - * Use `[reference-style][ref]` links. +* Use `[reference-style][ref]` links. `[ref]: https://daringfireball.net/projects/markdown/syntax#link` ([This][md] is a great source for learning about Markdown.) - -Git Conventions ---------------- +## Git Conventions Please try to write good commit messages, according to the [instructions in our coding style guidelines][git-commit]. - [qubes-doc]: https://github.com/QubesOS/qubes-doc [glossary]: /doc/glossary/ [issue]: /doc/reporting-bugs/ diff --git a/en/_doc/developer/general/gsoc.md b/en/_doc/developer/general/gsoc.md index 0af12965bf..4266cebc04 100644 --- a/en/_doc/developer/general/gsoc.md +++ b/en/_doc/developer/general/gsoc.md @@ -7,8 +7,8 @@ ref: 33 title: Google Summer of Code --- -2020 Google Summer of Code -================ +# 2020 Google Summer of Code + ## Information for Students Thank you for your interest in participating in the [Google Summer of Code program][gsoc-qubes] with the [Qubes OS team][team]. You can read more about the Google Summer of Code program at the [official website][gsoc] and the [official FAQ][gsoc-faq]. @@ -110,42 +110,42 @@ would override all the user changes there). More details: **Expected results**: - - Design new mechanism for distributing templates (possibly including some +- Design new mechanism for distributing templates (possibly including some package format - either reuse something already existing, or design new one). The mechanism needs to handle: - - integrity protection (digital signatures), not parsing any data in dom0 + - integrity protection (digital signatures), not parsing any data in dom0 prior to signature verification - - efficient handling of large sparse files - - ability to deploy the template into various storage mechanisms (sparse + - efficient handling of large sparse files + - ability to deploy the template into various storage mechanisms (sparse files, LVM thin volumes etc). - - template metadata, templates repository - enable the user to browse + - template metadata, templates repository - enable the user to browse available templates (probably should be done in dedicated VM, or DisposableVM) - - manual template removal by users (without it, see problems such + - manual template removal by users (without it, see problems such as [#5509](https://github.com/QubesOS/qubes-issues/issues/5509) - - Implement the above mechanism: - - tool to download named template - should perform download operation in +- Implement the above mechanism: + - tool to download named template - should perform download operation in some VM (as dom0 have no network access), then transfer the data to dom0, verify its integrity and then create Template VM and feed it's root filesystem image with downloaded data. - - tool to browse templates repository - both CLI and GUI (preferably integrated + - tool to browse templates repository - both CLI and GUI (preferably integrated with existing Template Manager tool) - - integrate both tools - user should be able to choose some template to be + - integrate both tools - user should be able to choose some template to be installed from repository browsing tool - see [#1705](https://github.com/QubesOS/qubes-issues/issues/1705) for some idea (this one lacks integrity verification, but a similar service could be developed with that added) - - If new "package" format is developed, add support for it into +- If new "package" format is developed, add support for it into [linux-template-builder](https://github.com/QubesOS/qubes-linux-template-builder). - - Document the mechanism. - - Write unit tests and integration tests. +- Document the mechanism. +- Write unit tests and integration tests. **Knowledge prerequisite**: - - Large files (disk images) handling (sparse files, archive formats) - - Bash and Python scripting - - Data integrity handling - digital signatures (gpg2, gpgv2) - - PyGTK - - RPM package format, (yum) repository basics +- Large files (disk images) handling (sparse files, archive formats) +- Bash and Python scripting +- Data integrity handling - digital signatures (gpg2, gpgv2) +- PyGTK +- RPM package format, (yum) repository basics **Mentor**: [Marek Marczykowski-Górecki](/team/) @@ -157,12 +157,12 @@ would override all the user changes there). More details: **Expected results**: - - Evaluate possible approaches (including flexibility, compatibility and performance), suggested ideas: - - use [USBIP for Windows](https://github.com/cezuni/usbip-win) and make it work with qrexec - similar as done for Linux - - use qrexec+USBIP in Linux-based stubdomain and plug it into USB emulation in qemu - - Choose one approach, write (very simple) design documentation - - Write relevant new code (applies mostly for usbip-win case) - - Plug the mechanism into Qubes core toolstack ([Devices API](https://dev.qubes-os.org/projects/core-admin/en/latest/qubes-devices.html)) +- Evaluate possible approaches (including flexibility, compatibility and performance), suggested ideas: + - use [USBIP for Windows](https://github.com/cezuni/usbip-win) and make it work with qrexec - similar as done for Linux + - use qrexec+USBIP in Linux-based stubdomain and plug it into USB emulation in qemu +- Choose one approach, write (very simple) design documentation +- Write relevant new code (applies mostly for usbip-win case) +- Plug the mechanism into Qubes core toolstack ([Devices API](https://dev.qubes-os.org/projects/core-admin/en/latest/qubes-devices.html)) **Knowledge prerequisite**: @@ -201,17 +201,17 @@ would override all the user changes there). More details: **Expected results**: - - Design how Vagrant Qubes provider should look like, including: - - [box format](https://www.vagrantup.com/docs/plugins/providers.html#box-format) - - method for running commands inside (ssh vs qvm-run) - - Write a Vagrant provider able to create/start/stop/etc a VM - - Document how to configure and use the provider, including required qrexec policy changes and possibly firewall rules - - Write integration tests +- Design how Vagrant Qubes provider should look like, including: + - [box format](https://www.vagrantup.com/docs/plugins/providers.html#box-format) + - method for running commands inside (ssh vs qvm-run) +- Write a Vagrant provider able to create/start/stop/etc a VM +- Document how to configure and use the provider, including required qrexec policy changes and possibly firewall rules +- Write integration tests **Knowledge prerequisite**: - - Ruby - - Vagrant concepts +- Ruby +- Vagrant concepts **Mentor**: [Wojtek Porczyk](/team/), [Marek Marczykowski-Górecki](/team/) @@ -227,7 +227,6 @@ would override all the user changes there). More details: - Implementation of the above mechanism. - Documentation how to configure it securely. - **Knowledge prerequisite**: - shell and/or python scripting @@ -254,10 +253,11 @@ Choose either of GUI agent, GUI daemon. Both are of similar complexity and each - implement tests for new GUI handling, similar to existing tests for X11 based GUI Relevant links: - - [Low level GUI documentation](/doc/gui/) - - [qubes-gui-agent-linux](https://github.com/qubesos/qubes-gui-agent-linux) - - [qubes-gui-daemon](https://github.com/qubesos/qubes-gui-daemon) - - [Use Wayland instead of X11 to increase performance](https://github.com/qubesos/qubes-issues/issues/3366) + +- [Low level GUI documentation](/doc/gui/) +- [qubes-gui-agent-linux](https://github.com/qubesos/qubes-gui-agent-linux) +- [qubes-gui-daemon](https://github.com/qubesos/qubes-gui-daemon) +- [Use Wayland instead of X11 to increase performance](https://github.com/qubesos/qubes-issues/issues/3366) **Knowledge prerequisite**: @@ -284,21 +284,21 @@ details: [#1552](https://github.com/QubesOS/qubes-issues/issues/1552), **Expected results**: - - Adjust set of VMs and templates included in live edition. - - Update and fix build scripts for recent Qubes OS version. - - Update startup script to mount appropriate directories as either - copy-on-write (device-mapper snapshot), or tmpfs. - - Optimize memory usage: should be possible to run sys-net, sys-firewall, and - at least two more VMs on 4GB machine. This include minimizing writes to - copy-on-write layer and tmpfs (disable logging etc). - - Research option to install the system from live image. If feasible add - this option. +- Adjust set of VMs and templates included in live edition. +- Update and fix build scripts for recent Qubes OS version. +- Update startup script to mount appropriate directories as either + copy-on-write (device-mapper snapshot), or tmpfs. +- Optimize memory usage: should be possible to run sys-net, sys-firewall, and + at least two more VMs on 4GB machine. This include minimizing writes to + copy-on-write layer and tmpfs (disable logging etc). +- Research option to install the system from live image. If feasible add + this option. **Knowledge prerequisite**: - - System startup sequence: bootloaders (isolinux, syslinux, grub, UEFI), initramfs, systemd. - - Python and Bash scripting - - Filesystems and block devices: loop devices, device-mapper, tmpfs, overlayfs, sparse files. +- System startup sequence: bootloaders (isolinux, syslinux, grub, UEFI), initramfs, systemd. +- Python and Bash scripting +- Filesystems and block devices: loop devices, device-mapper, tmpfs, overlayfs, sparse files. **Mentor**: [Frédéric Pierret](/team/) @@ -322,7 +322,6 @@ REMOVED as of January 2020: work is being done on this **Mentor**: [Thomas Leonard](mailto:talex5@gmail.com), [Marek Marczykowski-Górecki](/team/) --> - ### LogVM(s) **Project**: LogVM(s) @@ -335,22 +334,22 @@ immune to altering past entries. See **Expected results**: - - Design a _simple_ protocol for transferring logs. The less metadata (parsed - in log-collecting VM) the better. - - Implement log collecting service. Besides logs itself, should save - information about logs origin (VM name) and timestamp. The service should - _not_ trust sending VM in any of those. - - Implement log forwarder compatible with systemd-journald and rsyslog. A - mechanism (service/plugin) fetching logs in real time from those and sending - to log-collecting VM over qrexec service. - - Document the protocol. - - Write unit tests and integration tests. +- Design a _simple_ protocol for transferring logs. The less metadata (parsed + in log-collecting VM) the better. +- Implement log collecting service. Besides logs itself, should save + information about logs origin (VM name) and timestamp. The service should + _not_ trust sending VM in any of those. +- Implement log forwarder compatible with systemd-journald and rsyslog. A + mechanism (service/plugin) fetching logs in real time from those and sending + to log-collecting VM over qrexec service. +- Document the protocol. +- Write unit tests and integration tests. **Knowledge prerequisite**: - - syslog - - systemd - - Python/Bash scripting +- syslog +- systemd +- Python/Bash scripting **Mentor**: [Frédéric Pierret](/team/) @@ -393,14 +392,15 @@ details in [#2618](https://github.com/QubesOS/qubes-issues/issues/2618). --> ### Whonix IPv6 and nftables support + **Project**: Whonix IPv6 and nftables support **Brief explanation**: [T509](https://phabricator.whonix.org/T509) **Expected results**: -- Work at upstream Tor: An older version of https://trac.torproject.org/projects/tor/wiki/doc/TransparentProxy page was the origin of Whonix. Update that page for nftables / IPv6 support without mentioning Whonix. Then discuss that on the tor-talk mailing list for wider input. - https://trac.torproject.org/projects/tor/ticket/21397 -- implement corridor feature request add IPv6 support / port to nftables - https://github.com/rustybird/corridor/issues/39 +- Work at upstream Tor: An older version of [TransparentProxy](https://trac.torproject.org/projects/tor/wiki/doc/TransparentProxy) page was the origin of Whonix. Update that page for nftables / IPv6 support without mentioning Whonix. Then discuss that on the tor-talk mailing list for wider input. [here](https://trac.torproject.org/projects/tor/ticket/21397) +- implement corridor feature request add IPv6 support / port to nftables - [issue](https://github.com/rustybird/corridor/issues/39) - port [whonix-firewall](https://github.com/Whonix/whonix-firewall) to nftables - make connections to IPv6 Tor relays work - make connections to IPv6 destinations work @@ -414,6 +414,7 @@ details in [#2618](https://github.com/QubesOS/qubes-issues/issues/2618). **Mentor**: [Patrick Schleizer](/team/) ### Audio support for Qubes Windows Tools + **Project**: Audio support for Qubes Windows Tools **Brief explanation**: Add audio support for Windows HVMs via Qubes Windows Tools. [#2624](https://github.com/QubesOS/qubes-issues/issues/2624) @@ -425,6 +426,7 @@ details in [#2618](https://github.com/QubesOS/qubes-issues/issues/2618). **Mentor**: [Rafał Wojdyła](/team/) ### Improve Windows GUI agent performance and stability + **Project**: Improve Windows GUI agent performance and stability **Brief explanation**: Previous profiling has shown that the Windows GUI agent uses significant portion of VM's CPU time for mouse input simulation. This can be improved, as well as agent's stability in some cases (desktop/user switching, logon/logoff, domain-joined VMs, multiple monitors). Seamless GUI experience can be significantly improved, but that may require changes in the Qubes video driver. [#1044](https://github.com/QubesOS/qubes-issues/issues/1044) [#1045](https://github.com/QubesOS/qubes-issues/issues/1045) [#1500](https://github.com/QubesOS/qubes-issues/issues/1500) [#2138](https://github.com/QubesOS/qubes-issues/issues/2138) [#2487](https://github.com/QubesOS/qubes-issues/issues/2487) [#2589](https://github.com/QubesOS/qubes-issues/issues/2589) @@ -436,6 +438,7 @@ details in [#2618](https://github.com/QubesOS/qubes-issues/issues/2618). **Mentor**: [Rafał Wojdyła](/team/) ### GUI agent for Windows 8/10 + **Project**: GUI agent for Windows 8/10 **Brief explanation**: Add support for Windows 8+ to the Qubes GUI agent and video driver. Starting from Windows 8, Microsoft requires all video drivers to conform to the WDDM display driver model which is incompatible with the current Qubes video driver. Unfortunately the WDDM model is much more complex than the old XPDM one and officially *requires* a physical GPU device (which may be emulated). Some progress has been made to create a full WDDM driver that *doesn't* require a GPU device, but the driver isn't working correctly yet. Alternatively, WDDM model supports display-only drivers which are much simpler but don't have access to system video memory and rendering surfaces (a key feature that would simplify seamless GUI mode). [#1861](https://github.com/QubesOS/qubes-issues/issues/1861) @@ -454,19 +457,19 @@ details in [#2618](https://github.com/QubesOS/qubes-issues/issues/2618). **Expected results**: - - A template for `autounattended.xml` file for Windows installer - the template should have placeholders for settings that need to be provided by the user. - - A tool for generating actual `autounattended.xml` file based on the template and user settings. - - A tool for launching Windows installation, given installation image and `autounattended.xml` file (can be the same as in the above point). - - (Optional) Unattended installation should also include Qubes Windows Tools. - - (Optional) A tool should be able to use Windows license embedded in ACPI tables - [related discussion](https://groups.google.com/d/msgid/qubes-devel/0b7fabae-f843-e7ce-40cf-193326cecdb0%40zrubi.hu) - - User documentation - - Automated tests (unit tests, integration tests) +- A template for `autounattended.xml` file for Windows installer - the template should have placeholders for settings that need to be provided by the user. +- A tool for generating actual `autounattended.xml` file based on the template and user settings. +- A tool for launching Windows installation, given installation image and `autounattended.xml` file (can be the same as in the above point). +- (Optional) Unattended installation should also include Qubes Windows Tools. +- (Optional) A tool should be able to use Windows license embedded in ACPI tables - [related discussion](https://groups.google.com/d/msgid/qubes-devel/0b7fabae-f843-e7ce-40cf-193326cecdb0%40zrubi.hu) +- User documentation +- Automated tests (unit tests, integration tests) **Knowledge prerequisite**: - - Python scripting - - Linux administration, including handling loop devices, partition tables, filesystems etc - - For optional features, C language and x86 architecture (ACPI tables) +- Python scripting +- Linux administration, including handling loop devices, partition tables, filesystems etc +- For optional features, C language and x86 architecture (ACPI tables) **Mentor**: [Rafał Wojdyła](/team/), [Marek Marczykowski-Górecki](/team/) @@ -476,33 +479,33 @@ details in [#2618](https://github.com/QubesOS/qubes-issues/issues/2618). **Brief explanation**: Integrating GNOME into Qubes dom0. This include: - - patching window manager to add colorful borders - - removing stuff not needed in dom0 (file manager(s), indexing services etc) - - adjusting menu for easy navigation (same applications in different VMs and such problems, dom0-related entries in one place) - - More info: [#1806](https://github.com/QubesOS/qubes-issues/issues/1806) +- patching window manager to add colorful borders +- removing stuff not needed in dom0 (file manager(s), indexing services etc) +- adjusting menu for easy navigation (same applications in different VMs and such problems, dom0-related entries in one place) +- More info: [#1806](https://github.com/QubesOS/qubes-issues/issues/1806) **Expected results**: - - Review existing support for other desktop environments (KDE, Xfce4, i3, awesome). - - Patch window manager to draw colorful borders (we use only server-side - decorations), there is already very similar patch in - [Cappsule project](https://github.com/cappsule/cappsule-gui). - - Configure GNOME to not make use of dom0 user home in visible way (no search - in files there, no file manager, etc). - - Configure GNOME to not look into external devices plugged in (no auto - mounting, device notifications etc). - - Package above modifications as rpms, preferably as extra configuration files - and/or plugins than overwriting existing files. Exceptions to this rule may - apply if no other option. - - Adjust comps.xml (in installer-qubes-os repo) to define package group with - all required packages. - - Document installation procedure. +- Review existing support for other desktop environments (KDE, Xfce4, i3, awesome). +- Patch window manager to draw colorful borders (we use only server-side + decorations), there is already very similar patch in + [Cappsule project](https://github.com/cappsule/cappsule-gui). +- Configure GNOME to not make use of dom0 user home in visible way (no search + in files there, no file manager, etc). +- Configure GNOME to not look into external devices plugged in (no auto + mounting, device notifications etc). +- Package above modifications as rpms, preferably as extra configuration files + and/or plugins than overwriting existing files. Exceptions to this rule may + apply if no other option. +- Adjust comps.xml (in installer-qubes-os repo) to define package group with + all required packages. +- Document installation procedure. **Knowledge prerequisite**: - - GNOME architecture - - C language (patching metacity) - - Probably also javascript - for modifying GNOME shell extensions +- GNOME architecture +- C language (patching metacity) +- Probably also javascript - for modifying GNOME shell extensions **Mentor**: [Frédéric Pierret](/team/), [Marek Marczykowski-Górecki](/team/) @@ -519,6 +522,7 @@ details in [#2618](https://github.com/QubesOS/qubes-issues/issues/2618). **Mentors**: Andrew Clausen and Jean-Philippe Ouellet ### Progress towards reproducible builds + **Project**: Progress towards reproducible builds **Brief explanation**: A long-term goal is to be able to build the entire OS and installation media in a completely bit-wise deterministic manner, but there are many baby steps to be taken along that path. See: @@ -545,21 +549,21 @@ Qubes currently only supports the x86_64 CPU architecture. Xen currently has add Some related discussion: - - [#4318](https://github.com/QubesOS/qubes-issues/issues/4318) on porting to ppc64. - - [#3894](https://github.com/QubesOS/qubes-issues/issues/3894) on porting to L4 microkernel. +- [#4318](https://github.com/QubesOS/qubes-issues/issues/4318) on porting to ppc64. +- [#3894](https://github.com/QubesOS/qubes-issues/issues/3894) on porting to L4 microkernel. **Expected results**: - - Add cross-compilation support to qubes-builder and related components. - - Make aarch64 specific adjustments to Qubes toolstacks/manager (including passthrough of devices from device tree to guest domains). - - Aarch64 specific integration and unit tests. - - Production of generic u-boot or uefi capable image/iso for target hardware. +- Add cross-compilation support to qubes-builder and related components. +- Make aarch64 specific adjustments to Qubes toolstacks/manager (including passthrough of devices from device tree to guest domains). +- Aarch64 specific integration and unit tests. +- Production of generic u-boot or uefi capable image/iso for target hardware. **Knowledge prerequisite**: - - Libvirt and Qubes toolstacks (C and python languages). - - Xen debugging. - - General ARM architecture knowledge. +- Libvirt and Qubes toolstacks (C and python languages). +- Xen debugging. +- General ARM architecture knowledge. **Mentor**: [Marek Marczykowski-Górecki](/team/) @@ -582,16 +586,16 @@ More information and further links can be found in the related issue: **Expected results**: - - Add cross-compilation support to qubes-builder and related components. - - Make ppc64 specific adjustments to Qubes toolstacks/manager (including passthrough of devices from device tree to guest domains). - - ppc64 specific integration and unit tests. - - Production of generic u-boot or uefi capable image/iso for target hardware. +- Add cross-compilation support to qubes-builder and related components. +- Make ppc64 specific adjustments to Qubes toolstacks/manager (including passthrough of devices from device tree to guest domains). +- ppc64 specific integration and unit tests. +- Production of generic u-boot or uefi capable image/iso for target hardware. **Knowledge prerequisite**: - - Libvirt and Qubes toolstacks (C and python languages). - - KVM or XEN internals - - General ppc64 architecture knowledge. +- Libvirt and Qubes toolstacks (C and python languages). +- KVM or XEN internals +- General ppc64 architecture knowledge. **Mentor**: [Marek Marczykowski-Górecki](/team/) @@ -605,11 +609,12 @@ Since it's software emulation it's rather slow. Details, reference: [#2233](https://github.com/QubesOS/qubes-issues/issues/2233) **Expected results**: - - a simple way of setting up Android qubes with hardware emulation + +- a simple way of setting up Android qubes with hardware emulation (distributed as a template or as a salt, handling various modern Android versions) - - figuring out and implementing an easy and secure way to connect an Android +- figuring out and implementing an easy and secure way to connect an Android qube to a development qube with Android studio - - documentation and tests +- documentation and tests **Knowledge prerequisite**: @@ -629,13 +634,15 @@ Since the Admin API is continuously growing and changing, continuous security as A [Fuzzer](https://en.wikipedia.org/wiki/Fuzzing) would help to automate part of these assessments. **Expected results**: - - fully automated & extensible Fuzzer for parts of the Admin API - - user & developer documentation + +- fully automated & extensible Fuzzer for parts of the Admin API +- user & developer documentation **Prerequisites**: - - basic Python understanding - - some knowledge about fuzzing & existing fuzzing frameworks (e.g. [oss-fuzz](https://github.com/google/oss-fuzz/tree/master/projects/qubes-os)) - - a hacker's curiosity + +- basic Python understanding +- some knowledge about fuzzing & existing fuzzing frameworks (e.g. [oss-fuzz](https://github.com/google/oss-fuzz/tree/master/projects/qubes-os)) +- a hacker's curiosity **Mentor**: Inquire on [qubes-devel][ml-devel]. diff --git a/en/_doc/developer/general/gsod.md b/en/_doc/developer/general/gsod.md index 176940fed4..206739a609 100644 --- a/en/_doc/developer/general/gsod.md +++ b/en/_doc/developer/general/gsod.md @@ -33,6 +33,7 @@ Here's a suggested template for adding project ideas: **Mentor**: Name and email address. ``` + ### Offline documentation **Project**: Offline documentation @@ -41,13 +42,13 @@ Here's a suggested template for adding project ideas: **Expected results**: - - Review [past discussions on the issue](https://github.com/QubesOS/qubes-issues/issues/1019) - - Recommend workflow and platform for displaying offline documentation - - Test workflow and platform to ensure usability and functionality +- Review [past discussions on the issue](https://github.com/QubesOS/qubes-issues/issues/1019) +- Recommend workflow and platform for displaying offline documentation +- Test workflow and platform to ensure usability and functionality **Knowledge prerequisite**: - - [Markdown][markdown] +- [Markdown][markdown] **Mentor**: [Marek Marczykowski-Górecki][team] @@ -59,12 +60,12 @@ Here's a suggested template for adding project ideas: **Expected results**: - - Review [past discussions on the issue](https://github.com/QubesOS/qubes-issues/issues/1774) - - Provide visual mock-ups and proposed text +- Review [past discussions on the issue](https://github.com/QubesOS/qubes-issues/issues/1774) +- Provide visual mock-ups and proposed text **Knowledge prerequisite**: - - some experience with Anaconda would be helpful +- some experience with Anaconda would be helpful **Mentor**: [Marek Marczykowski-Górecki][team] @@ -116,14 +117,16 @@ This could be helped by writing consolidated guide with with a clear list of sym **Brief explanation**: The Qubes OS is missing an installation guide for virtual machines. Users are installing an outdated and unsupported version of Qubes OS (3.2) instead of the supported version. There is unofficial [existing installation guide] for Qubes OS on a virtual box but it is misleading and lacks documentation. Usually, users face some errors and bugs while installing Qubes OS on a virtual machine.[virtual box issue] **Expected results**: - -Provide a new option of installation guide for users working on virtual machines. - -Review existing problems and provide solutions to them. - -Giving a warning for using outdated versions. + +- Provide a new option of installation guide for users working on virtual machines. +- Review existing problems and provide solutions to them. +- Giving a warning for using outdated versions. **Knowledge prerequisite**: - - Experience in virtual boxes and machines. - - Basic Knowledge about Fedora linux architecture. - - [Markdown][markdown] + +- Experience in virtual boxes and machines. +- Basic Knowledge about Fedora linux architecture. +- [Markdown][markdown] **Mentor**: [Marek Marczykowski-Górecki][team] diff --git a/en/_doc/developer/general/package-contributions.md b/en/_doc/developer/general/package-contributions.md index e078396b62..7262b3e4af 100644 --- a/en/_doc/developer/general/package-contributions.md +++ b/en/_doc/developer/general/package-contributions.md @@ -17,38 +17,41 @@ This page explains the inclusion criteria and procedures for such packages, as w Inclusion Criteria ------------------ + In order to be accepted, packages must: - * In no way weaken the security of Qubes OS. - * Be published under an open-source license (read about the [Qubes OS License]). - * Follow our [coding guidelines]. - * Be thoroughly tested. - * Have a clearly-defined use case for Qubes users. - * Not be unduly burdensome to review. +* In no way weaken the security of Qubes OS. +* Be published under an open-source license (read about the [Qubes OS License]). +* Follow our [coding guidelines]. +* Be thoroughly tested. +* Have a clearly-defined use case for Qubes users. +* Not be unduly burdensome to review. (Please note that we always reserve the right to add criteria to this list.) Contribution Procedure ---------------------- + Before you start putting serious work into a package, we recommend that you discuss your idea with the Qubes developers and the broader community on the [qubes-devel mailing list]. Once you have a package that's ready to become part of Qubes OS, please follow this procedure: - 1. Ensure that your package satisfies the [Inclusion Criteria]. - 2. If your code isn't already on GitHub, create a GitHub repo that contains your code. You can have a look to an example package called [qubes-skeleton]. - 3. If you haven't already, [sign your code][sig]. - 4. Create an issue in [qubes-issues] with the title `[Contribution] your-package-name`. - Include a link to your repo, a brief description of your package, and a brief explanation of why you think it should be included in Qubes. - Please note that the Qubes core developers are very busy. - If they are under heavy load when you submit your contribution, it may be a very long time before they have time to review your package. - If this happens, please do not be discouraged. - If you think they may have forgotten about your pending contribution, you may "bump" your request by commenting on your issue, but please do this *very* sparingly (i.e., no more than once a month). - We appreciate your understanding! - 5. You may be asked followup questions. - If we decide to accept your contribution, you will be invited to join the [QubesOS-contrib] organization on GitHub as public recognition of your contribution (but without push access; see [Review Procedure]), and [QubesOS-contrib] will fork your repo. - If we decide not to accept your contribution, we will state the reason and close the issue. +1. Ensure that your package satisfies the [Inclusion Criteria]. +2. If your code isn't already on GitHub, create a GitHub repo that contains your code. You can have a look to an example package called [qubes-skeleton]. +3. If you haven't already, [sign your code][sig]. +4. Create an issue in [qubes-issues] with the title `[Contribution] your-package-name`. + Include a link to your repo, a brief description of your package, and a brief explanation of why you think it should be included in Qubes. + Please note that the Qubes core developers are very busy. + If they are under heavy load when you submit your contribution, it may be a very long time before they have time to review your package. + If this happens, please do not be discouraged. + If you think they may have forgotten about your pending contribution, you may "bump" your request by commenting on your issue, but please do this *very* sparingly (i.e., no more than once a month). + We appreciate your understanding! +5. You may be asked followup questions. + If we decide to accept your contribution, you will be invited to join the [QubesOS-contrib] organization on GitHub as public recognition of your contribution (but without push access; see [Review Procedure]), and [QubesOS-contrib] will fork your repo. + If we decide not to accept your contribution, we will state the reason and close the issue. Update Procedure ---------------- + *Anyone* can provide an update (patch) to a contributed package, not just the person who contributed that package! The update procedure is the same for everyone, including the original package contributor. @@ -59,6 +62,7 @@ Please be prepared to read and respond to these comments. Review Procedure ---------------- + This review procedure covers both original package contributions (see [Contribution Procedure]) and all subsequent updates to those packages, including updates from the original package contributor (see [Update Procedure]). All changes will be reviewed by a Qubes Core Reviewer (QCR) and the [Package Maintainer] (PM). In all cases, the QCR will be a core Qubes developer. @@ -67,38 +71,39 @@ For example, if someone contributes a package, then disappears, and no suitable The review procedure is as follows: - 1. Someone, S, wishes to make a change to a package, P. - 2. S submits a fast-forwardable pull request against the fork of P's repo owned by [QubesOS-contrib]. - 3. The PM reviews the pull request. - If the the pull request passes the PM's review, the PM adds a [signed][sig] *comment* on the pull request stating that it has passed review. - (In cases in which S = PM, the PM can simply add a [signed][sig] *tag* to the HEAD commit prior to submitting the pull request.) - If the pull request does not pass the PM's review, the PM leaves a comment on the pull request explaining why not. - 4. The QCR reviews the pull request. - If the pull request passes the QCR's review, the QCR pushes a [signed][sig] tag to the HEAD commit stating that it has passed review and fast-forward merges the pull request. - If the pull request does not pass the QCR's review, the QCR leaves a comment on the pull request explaining why not, and the QCR may decide to close the pull request. +1. Someone, S, wishes to make a change to a package, P. +2. S submits a fast-forwardable pull request against the fork of P's repo owned by [QubesOS-contrib]. +3. The PM reviews the pull request. + If the the pull request passes the PM's review, the PM adds a [signed][sig] *comment* on the pull request stating that it has passed review. + (In cases in which S = PM, the PM can simply add a [signed][sig] *tag* to the HEAD commit prior to submitting the pull request.) + If the pull request does not pass the PM's review, the PM leaves a comment on the pull request explaining why not. +4. The QCR reviews the pull request. + If the pull request passes the QCR's review, the QCR pushes a [signed][sig] tag to the HEAD commit stating that it has passed review and fast-forward merges the pull request. + If the pull request does not pass the QCR's review, the QCR leaves a comment on the pull request explaining why not, and the QCR may decide to close the pull request. In all the cases, the first condition to be validated by the QCR's review is to ensure that the contribution **will not** hijack any core packages of [QubesOS] and of course, none of the [QubesOS-contrib] packages too. More precisely, particular attention to the whole build pipeline will be made with a specific review of: - - Package dependencies, - - Build scripts (including downloaded ones), - - All downloaded components should be verified against static hash, - - RPM/DEB installation scripts (e.g. looking at constraints who would hijack other packages), - - Makefiles, - - Package build [reproducible] + +* Package dependencies, +* Build scripts (including downloaded ones), +* All downloaded components should be verified against static hash, +* RPM/DEB installation scripts (e.g. looking at constraints who would hijack other packages), +* Makefiles, +* Package build [reproducible] and any steps which would result in partial/total compromise of legitimate components. For this part, you can have a look to an example package called [qubes-skeleton]. Package Maintainers ------------------- + If you contribute a package, we assume that you will be the maintainer of that package, unless you tell us otherwise. As the maintainer of the package, it is your privilege and responsibility to: - * [Review][Review Procedure] each pull request made against the package. - * Decide when the package has reached a new version, and notify the Qubes core developers when this occurs. +* [Review][Review Procedure] each pull request made against the package. +* Decide when the package has reached a new version, and notify the Qubes core developers when this occurs. If you do not wish to be the maintainer of your package, please let us know. If you do not act on your maintainer duties for a given package for an extended period of time and after at least one reminder, we will assume that you no longer wish to be the maintainer for that package. - [installing contributed packages]: /doc/installing-contributed-packages/ [Inclusion Criteria]: #inclusion-criteria [Contribution Procedure]: #contribution-procedure diff --git a/en/_doc/developer/general/usability-ux.md b/en/_doc/developer/general/usability-ux.md index 9cf64b4ba0..6e0e8c85c6 100644 --- a/en/_doc/developer/general/usability-ux.md +++ b/en/_doc/developer/general/usability-ux.md @@ -6,8 +6,7 @@ ref: 31 title: Usability & UX --- -Usability & UX -============== +# Usability & UX Software that is too complicated to use, is often unused. Because we want as many people as possible to benefit from its unique security properties, the usability and user experience of Qubes OS is an utmost priority! @@ -41,7 +40,6 @@ Perhaps the most common cause of mistakes is complexity. If there is a configura In making software easy to use, it is crucial to be mindful of [cognitive load](https://en.wikipedia.org/wiki/Cognitive_load) which dictates that *"humans are generally able to hold only seven +/- two units of information in short-term memory."* Making sure your interfaces don't pass this short-term memory limit is perhaps the most important factor in helping a user feel comfortable instead of overwhelmed. - --- ## Easy to Understand From af92194d508709c1bab9d4cf8c918ab868cd3dd4 Mon Sep 17 00:00:00 2001 From: dd Date: Sun, 1 Nov 2020 01:13:44 +0100 Subject: [PATCH 069/663] linted docs in developer/services --- en/_doc/developer/services/admin-api.md | 28 +++---- .../developer/services/dom0-secure-updates.md | 6 +- en/_doc/developer/services/dvm-impl.md | 38 +++++----- en/_doc/developer/services/qfilecopy.md | 8 +- en/_doc/developer/services/qfileexchgd.md | 34 ++++----- en/_doc/developer/services/qmemman.md | 48 ++++++------ .../developer/services/qrexec-internals.md | 32 ++++---- .../services/qrexec-socket-services.md | 5 ++ en/_doc/developer/services/qrexec2.md | 76 +++++++++++-------- 9 files changed, 148 insertions(+), 127 deletions(-) diff --git a/en/_doc/developer/services/admin-api.md b/en/_doc/developer/services/admin-api.md index 374c8683a0..c3d7bcad74 100644 --- a/en/_doc/developer/services/admin-api.md +++ b/en/_doc/developer/services/admin-api.md @@ -150,23 +150,22 @@ to set the policy using current mechanism. Volume properties: - - `pool` - - `vid` - - `size` - - `usage` - - `rw` - - `source` - - `save_on_stop` - - `snap_on_start` - - `revisions_to_keep` - - `is_outdated` +- `pool` +- `vid` +- `size` +- `usage` +- `rw` +- `source` +- `save_on_stop` +- `snap_on_start` +- `revisions_to_keep` +- `is_outdated` Method `admin.vm.Stats` returns `vm-stats` events every `stats_interval` seconds, for every running VM. Parameters of `vm-stats` events: - - `memory_kb` - memory usage in kB - - `cpu_time` - absolute CPU time (in milliseconds) spent by the VM since its startup, normalized for one CPU - - `cpu_usage` - CPU usage in percents - +- `memory_kb` - memory usage in kB +- `cpu_time` - absolute CPU time (in milliseconds) spent by the VM since its startup, normalized for one CPU +- `cpu_usage` - CPU usage in percents ## Returned messages @@ -331,6 +330,7 @@ The changes are validated before saving, so that the policy cannot end up in an invalid state (e.g. syntax error, missing include file). In addition, there is a mechanism to prevent concurrent modifications of the policy files: + - A `*.Get` call returns a file along with a *token* (currently implemented as a hash of the file). - When calling `Replace` or `Remove`, you need to include the current token as diff --git a/en/_doc/developer/services/dom0-secure-updates.md b/en/_doc/developer/services/dom0-secure-updates.md index 1902fa5f5f..1636c02601 100644 --- a/en/_doc/developer/services/dom0-secure-updates.md +++ b/en/_doc/developer/services/dom0-secure-updates.md @@ -20,9 +20,9 @@ Normally there should be few reasons for updating software in Dom0. This is beca However, we anticipate some other situations when updating Dom0 software might be required: -- Updating drivers/libs for new hardware support -- Correcting non-security related bugs (e.g. new buttons for qubes manager) -- Adding new features (e.g. GUI backup tool) +- Updating drivers/libs for new hardware support +- Correcting non-security related bugs (e.g. new buttons for qubes manager) +- Adding new features (e.g. GUI backup tool) Problems with traditional network-based update mechanisms --------------------------------------------------------- diff --git a/en/_doc/developer/services/dvm-impl.md b/en/_doc/developer/services/dvm-impl.md index dbda0cef08..56733c6835 100644 --- a/en/_doc/developer/services/dvm-impl.md +++ b/en/_doc/developer/services/dvm-impl.md @@ -22,19 +22,19 @@ DisposableVM is not started like other VMs, by executing equivalent of `xl creat Preparing a savefile is done by `/usr/lib/qubes/qubes_prepare_saved_domain.sh` script. It takes two mandatory arguments, appvm name (APPVM) and the savefile name, and optional path to "prerun" script. The script executes the following steps: -1. APPVM is started by `qvm-start` -2. xenstore key `/local/domain/appvm_domain_id/qubes_save_request` is created -3. if prerun script was specified, copy it to `qubes_save_script` xenstore key -4. wait for the `qubes_used_mem` key to appear -5. (in APPVM) APPVM boots normally, up to the point in `/etc/init.d/qubes_core` script when the presence of `qubes_save_request` key is tested. If it exists, then - 1. (in APPVM) if exists, prerun script is retrieved from the respective xenstore key and executed. This preloads filesystem cache with useful applications, so that they will start faster. - 2. (in APPVM) the amount of used memory is stored to `qubes_used_mem` xenstore key - 3. (in APPVM) busy-waiting for `qubes_restore_complete` xenstore key to appear - -6. when `qubes_used_mem` key appears, the domain memory is reduced to this amount, to make the savefile smaller. -7. APPVM private image is detached -8. the domain is saved via `xl save` -9. the COW file volatile.img (cow for root fs and swap) is packed to `saved_cows.tar` archive +1. APPVM is started by `qvm-start` +2. xenstore key `/local/domain/appvm_domain_id/qubes_save_request` is created +3. if prerun script was specified, copy it to `qubes_save_script` xenstore key +4. wait for the `qubes_used_mem` key to appear +5. (in APPVM) APPVM boots normally, up to the point in `/etc/init.d/qubes_core` script when the presence of `qubes_save_request` key is tested. If it exists, then + 1. (in APPVM) if exists, prerun script is retrieved from the respective xenstore key and executed. This preloads filesystem cache with useful applications, so that they will start faster. + 2. (in APPVM) the amount of used memory is stored to `qubes_used_mem` xenstore key + 3. (in APPVM) busy-waiting for `qubes_restore_complete` xenstore key to appear + +6. when `qubes_used_mem` key appears, the domain memory is reduced to this amount, to make the savefile smaller. +7. APPVM private image is detached +8. the domain is saved via `xl save` +9. the COW file volatile.img (cow for root fs and swap) is packed to `saved_cows.tar` archive The `qubes_prepare_saved_domain.sh` script is lowlevel. It is usually called by `qvm-create-default-dvm` script, that takes care of creating a special AppVM (named template\_name-dvm) to be passed to `qubes_prepare_saved_domain.sh`, as well as copying the savefile to /dev/shm (the latter action is not done if the `/var/lib/qubes/dvmdata/dont_use_shm` file exists). @@ -43,12 +43,12 @@ Restoring a DisposableVM from the savefile Normally, disposable VM is created when qubes rpc request with target *\$dispvm* is received. Then, as a part of rpc connection setup, the `qfile-daemon-dvm` program is executed; it executes `/usr/lib/qubes/qubes_restore` program. It is crucial that this program executes quickly, to make DisposableVM creation overhead bearable for the user. Its main steps are: -1. modify the savefile so that the VM name, VM UUID, MAC address and IP address are unique -2. restore the COW files from the `saved_cows.tar` -3. create the `/var/run/qubes/fast_block_attach` file, whose presence tells the `/etc/xen/scripts/block` script to bypass some redundant checks and execute as fast as possible. -4. execute `xl restore` in order to restore a domain. -5. create the same xenstore keys as normally created when AppVM boots (e.g. `qubes_ip`) -6. create the `qubes_restore_complete` xenstore key. This allows the boot process in DisposableVM to continue. +1. modify the savefile so that the VM name, VM UUID, MAC address and IP address are unique +2. restore the COW files from the `saved_cows.tar` +3. create the `/var/run/qubes/fast_block_attach` file, whose presence tells the `/etc/xen/scripts/block` script to bypass some redundant checks and execute as fast as possible. +4. execute `xl restore` in order to restore a domain. +5. create the same xenstore keys as normally created when AppVM boots (e.g. `qubes_ip`) +6. create the `qubes_restore_complete` xenstore key. This allows the boot process in DisposableVM to continue. The actual passing of files between AppVM and a DisposableVM is implemented via qubes rpc. diff --git a/en/_doc/developer/services/qfilecopy.md b/en/_doc/developer/services/qfilecopy.md index 4f4260e0cd..4a4cca9dfe 100644 --- a/en/_doc/developer/services/qfilecopy.md +++ b/en/_doc/developer/services/qfilecopy.md @@ -15,15 +15,15 @@ InterVM file copy design There are two cases when we need a mechanism to copy files between VMs: -- "regular" file copy - when user instructs file manager to copy a given files/directories to a different VM -- DispVM copy - user selects "open in DispVM" on a file; this file must be copied to a DisposableVM, edited by user, and possibly a modified file copied back from DispVM to VM. +- "regular" file copy - when user instructs file manager to copy a given files/directories to a different VM +- DispVM copy - user selects "open in DispVM" on a file; this file must be copied to a DisposableVM, edited by user, and possibly a modified file copied back from DispVM to VM. Prior to Qubes Beta1, for both cases, a block device (backed by a file in dom0 with a vfat filesystem on it) was attached to VM, file(s) copied there, and then the device was detached and attached to target VM. In the DispVM case, if a edited file has been modified, another block device is passed to requester VM in order to update the source file. This has the following disadvantages: -- performance - dom0 has to prepare and attach/detach block devices, which is slow because of hotplug scripts involvement. -- security - VM kernel parses partition table and filesystem metadata from the block device; they are controlled by (potentially untrusted) sender VM. +- performance - dom0 has to prepare and attach/detach block devices, which is slow because of hotplug scripts involvement. +- security - VM kernel parses partition table and filesystem metadata from the block device; they are controlled by (potentially untrusted) sender VM. In Qubes Beta1, we have reimplemented interVM file copy using qrexec, which addresses the above mentioned disadvantages. In Qubes Beta2, even more generic solution (qubes rpc) is used. See the developer docs on qrexec and qubes rpc. In a nutshell, the file sender and the file receiver just read/write from stdin/stdout, and the qubes rpc layer passes data properly - so, no block devices are used. diff --git a/en/_doc/developer/services/qfileexchgd.md b/en/_doc/developer/services/qfileexchgd.md index 934ae0836c..0786c6b7eb 100644 --- a/en/_doc/developer/services/qfileexchgd.md +++ b/en/_doc/developer/services/qfileexchgd.md @@ -23,36 +23,36 @@ Overview *qfilexchgd* is a dom0 daemon responsible for managing exchange of block devices ("virtual pendrives") between VMs. It is used for -- copying files between AppVMs -- copying a single file between an AppVM and a DisposableVM +- copying files between AppVMs +- copying a single file between an AppVM and a DisposableVM *qfilexchgd* is started after first *qubes\_guid* has been started, so that it has access to X display in dom0 to present dialog messages. *qfilexchgd* is event driven. The sources of events are: -- trigger of xenstore watch for the changes in `/local/domain` xenstore hierarchy - to detect start/stop of VMs, and maintain vmname-\>vm\_xid dictionary -- trigger of xenstore watch for a change in `/local/domain/domid/device/qpen` key - VMs write to this key to request service from *qfilexchgd* +- trigger of xenstore watch for the changes in `/local/domain` xenstore hierarchy - to detect start/stop of VMs, and maintain vmname-\>vm\_xid dictionary +- trigger of xenstore watch for a change in `/local/domain/domid/device/qpen` key - VMs write to this key to request service from *qfilexchgd* Copying files between AppVMs ---------------------------- -1. AppVM1 user runs *qvm-copy-to-vm* script (accessible from Dolphin file manager by right click on a "file(s)-\>Actions-\>Send to VM" menu). It calls */usr/lib/qubes/qubes\_penctl new*, and it writes "new" request to its `device/qpen` xenstore key. *qfilexchgd* creates a new 1G file, makes vfat fs on it, and does block-attach so that this file is attached as `/dev/xvdg` in AppVM1. -2. AppVM1 mounts `/dev/xvdg` on `/mnt/outgoing` and copies requested files there, then unmounts it. -3. AppVM1 writes "send DestVM" request to its `device/qpen` xenstore key (calling */usr/lib/qubes/qubes\_penctl send DestVM*). After getting confirmation by displaying a dialog box in dom0 display, *qfilexchgd* detaches `/dev/xvdg` from AppVM1, attaches it as `/dev/xvdh` to DestVM. -4. In DestVM, udev script for `/dev/xvdh` named *qubes\_add\_pendrive\_script* (see `/etc/udev/rules.d/qubes.rules`) mounts `/dev/xvdh` on `/mnt/incoming`, and then waits for `/mnt/incoming` to become unmounted. A file manager running in DestVM shows a new volume, and user in DestVM may copy files from it. When user in DestVM is done, then user unmounts `/mnt/incoming`. *qubes\_add\_pendrive*\_script then tells *qfilexchgd* to detach `/dev/xvdh` and terminates. +1. AppVM1 user runs *qvm-copy-to-vm* script (accessible from Dolphin file manager by right click on a "file(s)-\>Actions-\>Send to VM" menu). It calls */usr/lib/qubes/qubes\_penctl new*, and it writes "new" request to its `device/qpen` xenstore key. *qfilexchgd* creates a new 1G file, makes vfat fs on it, and does block-attach so that this file is attached as `/dev/xvdg` in AppVM1. +2. AppVM1 mounts `/dev/xvdg` on `/mnt/outgoing` and copies requested files there, then unmounts it. +3. AppVM1 writes "send DestVM" request to its `device/qpen` xenstore key (calling */usr/lib/qubes/qubes\_penctl send DestVM*). After getting confirmation by displaying a dialog box in dom0 display, *qfilexchgd* detaches `/dev/xvdg` from AppVM1, attaches it as `/dev/xvdh` to DestVM. +4. In DestVM, udev script for `/dev/xvdh` named *qubes\_add\_pendrive\_script* (see `/etc/udev/rules.d/qubes.rules`) mounts `/dev/xvdh` on `/mnt/incoming`, and then waits for `/mnt/incoming` to become unmounted. A file manager running in DestVM shows a new volume, and user in DestVM may copy files from it. When user in DestVM is done, then user unmounts `/mnt/incoming`. *qubes\_add\_pendrive*\_script then tells *qfilexchgd* to detach `/dev/xvdh` and terminates. Copying a single file between AppVM and a DisposableVM ------------------------------------------------------ In order to minimize attack surface presented by necessity to process virtual pendrive metadata sent by (potentially compromised and malicious) DisposableVM, AppVM\<-\>DisposableVM file exchange protocol does not use any filesystem. -1. User in AppVM1 runs *qvm-open-in-dvm* (accessible from Dolphin file manager by right click on a "file-\>Actions-\>Open in DisposableVM" menu). *qvm-open-in-dvm* - 1. gets a new `/dev/xvdg` (just as described in previous paragraph) - 2. computes a new unique transaction seq SEQ by incrementing `/home/user/.dvm/seq` contents, - 3. writes the requested file name (say, /home/user/document.txt) to `/home/user/.dvm/SEQ` - 4. creates a dvm\_header (see core.git/appvm/dvm.h) on `/dev/xvdg`, followed by file contents - 5. writes the "send disposable SEQ" command to its `device/qpen` xenstore key. +1. User in AppVM1 runs *qvm-open-in-dvm* (accessible from Dolphin file manager by right click on a "file-\>Actions-\>Open in DisposableVM" menu). *qvm-open-in-dvm* + 1. gets a new `/dev/xvdg` (just as described in previous paragraph) + 2. computes a new unique transaction seq SEQ by incrementing `/home/user/.dvm/seq` contents, + 3. writes the requested file name (say, /home/user/document.txt) to `/home/user/.dvm/SEQ` + 4. creates a dvm\_header (see core.git/appvm/dvm.h) on `/dev/xvdg`, followed by file contents + 5. writes the "send disposable SEQ" command to its `device/qpen` xenstore key. -2. *qfilexchgd* sees that "send" argument=="disposable", and creates a new DisposableVM by calling */usr/lib/qubes/qubes\_restore*. It adds the new DisposableVM to qubesDB via qvm\_collection.add\_new\_disposablevm. Then it attaches the virtual pendrive (previously attached as `/dev/xvdg` at AppVM1) as `/dev/xvdh` in DisposableVM. -3. In DisposableVM, *qubes\_add\_pendrive\_script* sees non-zero `qubes_transaction_seq` key in xenstore, and instead processing the virtual pendrive as in the case of normal copy, treats it as DVM transaction (a request, because we run in DisposableVM). It retrieves the body of the file passed in `/dev/xvdh`, copies to /tmp, and runs *mime-open* utility to open appropriate executable to edit it. When *mime-open* returns, if the file was modified, it is sent back to AppVM1 (by writing "send AppVM1 SEQ" to `device/qpen` xenstore key). Then DisposableVM destroys itself. -4. In AppVM1, a new `/dev/xvdh` appears (because DisposableVM has sent it). *qubes\_add\_pendrive\_script* sees non-zero `qubes_transaction_seq` key, and treats it as DVM transaction (a response, because we run in AppVM, not DisposableVM). It retrieves the filename from `/home/user/.dvm/SEQ`, and copies data from `/dev/xvdh` to it. +2. *qfilexchgd* sees that "send" argument=="disposable", and creates a new DisposableVM by calling */usr/lib/qubes/qubes\_restore*. It adds the new DisposableVM to qubesDB via qvm\_collection.add\_new\_disposablevm. Then it attaches the virtual pendrive (previously attached as `/dev/xvdg` at AppVM1) as `/dev/xvdh` in DisposableVM. +3. In DisposableVM, *qubes\_add\_pendrive\_script* sees non-zero `qubes_transaction_seq` key in xenstore, and instead processing the virtual pendrive as in the case of normal copy, treats it as DVM transaction (a request, because we run in DisposableVM). It retrieves the body of the file passed in `/dev/xvdh`, copies to /tmp, and runs *mime-open* utility to open appropriate executable to edit it. When *mime-open* returns, if the file was modified, it is sent back to AppVM1 (by writing "send AppVM1 SEQ" to `device/qpen` xenstore key). Then DisposableVM destroys itself. +4. In AppVM1, a new `/dev/xvdh` appears (because DisposableVM has sent it). *qubes\_add\_pendrive\_script* sees non-zero `qubes_transaction_seq` key, and treats it as DVM transaction (a response, because we run in AppVM, not DisposableVM). It retrieves the filename from `/home/user/.dvm/SEQ`, and copies data from `/dev/xvdh` to it. diff --git a/en/_doc/developer/services/qmemman.md b/en/_doc/developer/services/qmemman.md index 8aed1e460b..3abf362d25 100644 --- a/en/_doc/developer/services/qmemman.md +++ b/en/_doc/developer/services/qmemman.md @@ -20,8 +20,8 @@ Traditionally, Xen VMs are assigned a fixed amount of memory. It is not the opti The [tmem](https://oss.oracle.com/projects/tmem/) project provides a "pseudo-RAM" that is assigned on per-need basis. However this solution has some disadvantages: -- It does not provide real RAM, just an interface to copy memory to/from fast, RAM-based storage. It is perfect for swap, good for file cache, but not ideal for many tasks. -- It is deeply integrated with the Linux kernel. When Qubes will support Windows guests natively, we would have to port *tmem* to Windows, which may be challenging. +- It does not provide real RAM, just an interface to copy memory to/from fast, RAM-based storage. It is perfect for swap, good for file cache, but not ideal for many tasks. +- It is deeply integrated with the Linux kernel. When Qubes will support Windows guests natively, we would have to port *tmem* to Windows, which may be challenging. Therefore, in Qubes another solution is used. There is the *qmemman* dom0 daemon. All VMs report their memory usage (via xenstore) to *qmemman*, and it makes decisions on whether to balance memory across domains. The actual mechanism to add/remove memory from a domain (*xc.domain\_set\_target\_mem*) is already supported by both PV Linux guests and Windows guests (the latter via PV drivers). @@ -29,24 +29,24 @@ Similarly, when there is need for Xen free memory (for instance, in order to cre To sum up, *qmemman* pros and cons. Pros: -- provides automatic balancing of memory across participating PV and HVM domains, based on their memory demand -- works well in practice, with less than 1% CPU consumption in the idle case -- simple, concise implementation +- provides automatic balancing of memory across participating PV and HVM domains, based on their memory demand +- works well in practice, with less than 1% CPU consumption in the idle case +- simple, concise implementation Cons: -- the algorithm to calculate the memory requirement for a domain is necessarily simple, and may not closely reflect reality -- *qmemman* is notified by a VM about memory usage change not more often than 10 times per second (to limit CPU overhead in VM). Thus, there can be up to 0.1s delay until qmemman starts to react to the new memory requirements -- it takes more time to obtain free Xen memory, as all participating domains need to instructed to yield memory +- the algorithm to calculate the memory requirement for a domain is necessarily simple, and may not closely reflect reality +- *qmemman* is notified by a VM about memory usage change not more often than 10 times per second (to limit CPU overhead in VM). Thus, there can be up to 0.1s delay until qmemman starts to react to the new memory requirements +- it takes more time to obtain free Xen memory, as all participating domains need to instructed to yield memory Interface --------- *qmemman* listens for the following events: -- writes to `/local/domain/domid/memory/meminfo` xenstore keys by *meminfo-writer* process in VM. The content of this key is taken from the VM's `/proc/meminfo` pseudofile ; *meminfo-writer* just strips some unused lines from it. Note that *meminfo-writer* writes its xenstore key only if the VM memory usage has changed significantly enough since the last update (by default 30MB), to prevent flooding with almost identical data -- commands issued over Unix socket `/var/run/qubes/qmemman.sock`. Currently, the only command recognized is to free the specified amount of memory. The QMemmanClient class implements the protocol. -- if the `/var/run/qubes/do-not-membalance` file exists, *qmemman* suspends memory balancing. It is primarily used when allocating memory for a to-be-created domain, to prevent using up the free Xen memory by the balancing algorithm before the domain creation is completed. +- writes to `/local/domain/domid/memory/meminfo` xenstore keys by *meminfo-writer* process in VM. The content of this key is taken from the VM's `/proc/meminfo` pseudofile ; *meminfo-writer* just strips some unused lines from it. Note that *meminfo-writer* writes its xenstore key only if the VM memory usage has changed significantly enough since the last update (by default 30MB), to prevent flooding with almost identical data +- commands issued over Unix socket `/var/run/qubes/qmemman.sock`. Currently, the only command recognized is to free the specified amount of memory. The QMemmanClient class implements the protocol. +- if the `/var/run/qubes/do-not-membalance` file exists, *qmemman* suspends memory balancing. It is primarily used when allocating memory for a to-be-created domain, to prevent using up the free Xen memory by the balancing algorithm before the domain creation is completed. Algorithms basics ----------------- @@ -55,27 +55,27 @@ The core VM property is `prefmem`. It denotes the amount of memory that should b Whenever *meminfo-writer* running in domain A provides new data on memory usage to *qmemman*, the `prefmem` value for A is updated and the following balance algorithm (*qmemman\_algo.balance*) is triggered. Its output is the list of (domain\_id, new\_memory\_target\_to\_be\_set) pairs: -1. TOTAL\_PREFMEM = sum of `prefmem` of all participating domains -2. TOTAL\_MEMORY = sum of all memory assigned to participating domains plus Xen free memory -3. if TOTAL\_MEMORY \> TOTAL\_PREFMEM, then redistribute TOTAL\_MEMORY across all domains proportionally to their `prefmem` -4. if TOTAL\_MEMORY \< TOTAL\_PREFMEM, then - 1. for all domains whose `prefmem` is less than actual memory, shrink them to their `prefmem` - 2. redistribute memory reclaimed in the previous step between the rest of domains, proportionally to their `prefmem` +1. TOTAL\_PREFMEM = sum of `prefmem` of all participating domains +2. TOTAL\_MEMORY = sum of all memory assigned to participating domains plus Xen free memory +3. if TOTAL\_MEMORY \> TOTAL\_PREFMEM, then redistribute TOTAL\_MEMORY across all domains proportionally to their `prefmem` +4. if TOTAL\_MEMORY \< TOTAL\_PREFMEM, then + 1. for all domains whose `prefmem` is less than actual memory, shrink them to their `prefmem` + 2. redistribute memory reclaimed in the previous step between the rest of domains, proportionally to their `prefmem` In order to avoid too frequent memory redistribution, it is actually executed only if one of the below conditions hold: -- the sum of memory size changes for all domains is more than MIN\_TOTAL\_MEMORY\_TRANSFER (150MB) -- one of the domains is below its `prefmem`, and more than MIN\_MEM\_CHANGE\_WHEN\_UNDER\_PREF (15MB) would be added to it +- the sum of memory size changes for all domains is more than MIN\_TOTAL\_MEMORY\_TRANSFER (150MB) +- one of the domains is below its `prefmem`, and more than MIN\_MEM\_CHANGE\_WHEN\_UNDER\_PREF (15MB) would be added to it Additionally, the balance algorithm is tuned so that XEN\_FREE\_MEM\_LEFT (50MB) is always left as Xen free memory, to make coherent memory allocations in driver domains work. Whenever *qmemman* is asked to return X megabytes of memory to Xen free pool, the following algorithm (*qmemman\_algo.balloon*) is executed: -1. find all domains ("donors") whose actual memory is greater than its `prefmem` -2. calculate how much memory can be reclaimed by shrinking donors to their `prefmem`. If it is less than X, return error. -3. shrink donors, proportionally to their `prefmem`, so that X MB should become free -4. wait BALOON\_DELAY (0.1s) -5. if some domain have not given back any memory, remove it from the donors list, and go to step 2, unless we already did MAX\_TRIES (20) iterations (then return error). +1. find all domains ("donors") whose actual memory is greater than its `prefmem` +2. calculate how much memory can be reclaimed by shrinking donors to their `prefmem`. If it is less than X, return error. +3. shrink donors, proportionally to their `prefmem`, so that X MB should become free +4. wait BALOON\_DELAY (0.1s) +5. if some domain have not given back any memory, remove it from the donors list, and go to step 2, unless we already did MAX\_TRIES (20) iterations (then return error). Notes ----- diff --git a/en/_doc/developer/services/qrexec-internals.md b/en/_doc/developer/services/qrexec-internals.md index 6771482d78..5abf10aed7 100644 --- a/en/_doc/developer/services/qrexec-internals.md +++ b/en/_doc/developer/services/qrexec-internals.md @@ -34,6 +34,7 @@ These tools are not designed to be used by users directly. One instance is required for every active domain. `qrexec-daemon` is responsible for both: + - handling execution and service requests from **dom0** (source: `qrexec-client`); and - handling service requests from the associated domain (source: `qrexec-client-vm`, then `qrexec-agent`). @@ -41,9 +42,9 @@ Command line usage: `qrexec-daemon domain-id domain-name [default user]` -* `domain-id`: Numeric Qubes ID assigned to the associated domain. -* `domain-name`: Associated domain name. -* `default user`: Optional. If passed, `qrexec-daemon` uses this user as default for all execution requests that don't specify one. +- `domain-id`: Numeric Qubes ID assigned to the associated domain. +- `domain-name`: Associated domain name. +- `default user`: Optional. If passed, `qrexec-daemon` uses this user as default for all execution requests that don't specify one. ### qrexec-client @@ -53,11 +54,11 @@ Used to pass execution and service requests to `qrexec-daemon`. Command line usage: -* `-d target-domain-name`: Specifies the target for the execution/service request. -* `-l local-program`: Optional. If present, `local-program` is executed and its stdout/stdin are used when sending/receiving data to/from the remote peer. -* `-e`: Optional. If present, stdout/stdin are not connected to the remote peer. Only process creation status code is received. -* `-c `: used for connecting a VM-VM service request by `qrexec-policy`. Details described below in the service example. -* `cmdline`: Command line to pass to `qrexec-daemon` as the execution/service request. Service request format is described below in the service example. +- `-d target-domain-name`: Specifies the target for the execution/service request. +- `-l local-program`: Optional. If present, `local-program` is executed and its stdout/stdin are used when sending/receiving data to/from the remote peer. +- `-e`: Optional. If present, stdout/stdin are not connected to the remote peer. Only process creation status code is received. +- `-c `: used for connecting a VM-VM service request by `qrexec-policy`. Details described below in the service example. +- `cmdline`: Command line to pass to `qrexec-daemon` as the execution/service request. Service request format is described below in the service example. ## VM tools implementation @@ -67,8 +68,9 @@ Command line usage: One instance runs in each active domain. Responsible for: - * Handling service requests from `qrexec-client-vm` and passing them to connected `qrexec-daemon` in dom0. - * Executing associated `qrexec-daemon` execution/service requests. + +- Handling service requests from `qrexec-client-vm` and passing them to connected `qrexec-daemon` in dom0. +- Executing associated `qrexec-daemon` execution/service requests. The `qrexec-agent` command takes no parameters. @@ -83,26 +85,30 @@ Command line usage: `qrexec-client-vm target-domain-name service-name local-program [local program arguments]` -* `target-domain-name`: Target domain for the service request. Source is the current domain. -* `service-name`: Requested service name. -* `local-program`: `local-program` is executed locally and its stdin/stdout are connected to the remote service endpoint. +- `target-domain-name`: Target domain for the service request. Source is the current domain. +- `service-name`: Requested service name. +- `local-program`: `local-program` is executed locally and its stdin/stdout are connected to the remote service endpoint. ## Qrexec protocol details The qrexec protocol is message-based. All messages share a common header followed by an optional data packet. +```c /* uniform for all peers, data type depends on message type */ struct msg_header { uint32_t type; /* message type */ uint32_t len; /* data length */ }; +``` When two peers establish connection, the server sends `MSG_HELLO` followed by `peer_info` struct: +```c struct peer_info { uint32_t version; /* qrexec protocol version */ }; +``` The client then should reply with its own `MSG_HELLO` and `peer_info`. The lower of two versions define protocol used for this connection. diff --git a/en/_doc/developer/services/qrexec-socket-services.md b/en/_doc/developer/services/qrexec-socket-services.md index f6a8275042..2c223fddcb 100644 --- a/en/_doc/developer/services/qrexec-socket-services.md +++ b/en/_doc/developer/services/qrexec-socket-services.md @@ -22,11 +22,15 @@ If the file is a Unix socket, qrexec will try to connect to it. Before passing user input, the socket service will receive a null-terminated service descriptor, i.e. the part after `QUBESRPC`. When running in a VM, this is: +``` \0 +``` When running in dom0, it is: +``` \0 +``` (The target type can be `name`, in which case target is a domain name, or `keyword`, in which the target is a keyword like `@dispvm`). @@ -60,6 +64,7 @@ See the below example. `qrexec-policy-agent` is the program that handles "ask" prompts for Qubes RPC calls. It is a good example of an application that: + * Uses Python and asyncio. * Runs as a daemon, to save some overhead on starting process. * Runs as a normal user. diff --git a/en/_doc/developer/services/qrexec2.md b/en/_doc/developer/services/qrexec2.md index 20dff90c81..378936bb5f 100644 --- a/en/_doc/developer/services/qrexec2.md +++ b/en/_doc/developer/services/qrexec2.md @@ -19,7 +19,6 @@ Qubes **qrexec** is a framework for implementing inter-VM (incl. Dom0-VM) services. It offers a mechanism to start programs in VMs, redirect their stdin/stdout, and a policy framework to control this all. - ## Qrexec basics ## During each domain creation a process named `qrexec-daemon` is started in @@ -33,7 +32,9 @@ the stdin/stdout/stderr from this remote process will be passed to the E.g., to start a primitive shell in a VM type the following in Dom0 console: +```shell_session [user@dom0 ~]$ /usr/lib/qubes/qrexec-client -d user:bash +``` The string before first semicolon specifies what user to run the command as. @@ -57,7 +58,6 @@ There is a similar command line utility available inside Linux AppVMs (note the `-vm` suffix): `qrexec-client-vm` that will be described in subsequent sections. - ## Qubes RPC services ## Apart from simple Dom0-\>VM command executions, as discussed above, it is @@ -92,7 +92,6 @@ themselves. Qrexec framework is careful about connecting the stdin/stdout of the server process with the corresponding stdin/stdout of the requesting process in the requesting VM (see example Hello World service described below). - ## Qubes RPC administration ## Besides each VM needing to provide explicit programs to serve each supported @@ -102,6 +101,7 @@ In dom0, there is a bunch of files in `/etc/qubes-rpc/policy/` directory, whose names describe the available RPC actions; their content is the RPC access policy database. Some example of the default services in Qubes are: +``` qubes.Filecopy qubes.OpenInVM qubes.ReceiveUpdates @@ -111,10 +111,13 @@ access policy database. Some example of the default services in Qubes are: qubes.Gpg qubes.NotifyUpdates qubes.PdfConvert +``` These files contain lines with the following format: +``` srcvm destvm (allow|deny|ask)[,user=user_to_run_as][,target=VM_to_redirect_to] +``` You can specify `srcvm` and `destvm` by name, or by one of `$anyvm`, `$dispvm`, `dom0` reserved keywords (note string `dom0` does not match the @@ -134,12 +137,13 @@ if still there is no policy file after prompting, the action is denied. On the target VM, the `/etc/qubes-rpc/XYZ` must exist, containing the file name of the program that will be invoked. - ### Requesting VM-VM (and VM-Dom0) services execution ### In a src VM, one should invoke the qrexec client via the following command: +``` /usr/lib/qubes/qrexec-client-vm [local program arguments] +``` Note that only stdin/stdout is passed between RPC server and client -- notably, no cmdline argument are passed. @@ -171,7 +175,9 @@ to the policy file, which will unconditionally allow further calls for given In order to remove such authorization, issue this command from a Dom0 terminal (example below for `qubes.Filecopy` service): +```shell_session sudo nano /etc/qubes-rpc/policy/qubes.Filecopy +``` and then remove any line(s) ending in "allow" (before the first `##` comment) which are the "Yes to All" results. @@ -180,35 +186,44 @@ A user might also want to set their own policies in this section. This may mostly serve to prevent the user from mistakenly copying files or text from a trusted to untrusted domain, or vice-versa. - ### Qubes RPC "Hello World" service ### We will show the necessary files to create a simple RPC call that adds two integers on the target VM and returns back the result to the invoking VM. - * Client code on source VM (`/usr/bin/our_test_add_client`) +* Client code on source VM (`/usr/bin/our_test_add_client`) +```bash #!/bin/sh echo $1 $2 # pass data to rpc server exec cat >&$SAVED_FD_1 # print result to the original stdout, not to the other rpc endpoint +``` - * Server code on target VM (`/usr/bin/our_test_add_server`) +* Server code on target VM (`/usr/bin/our_test_add_server`) +```bash #!/bin/sh read arg1 arg2 # read from stdin, which is received from the rpc client echo $(($arg1+$arg2)) # print to stdout - so, pass to the rpc client +``` - * Policy file in dom0 (`/etc/qubes-rpc/policy/test.Add`) +* Policy file in dom0 (`/etc/qubes-rpc/policy/test.Add`) +```shell_session $anyvm $anyvm ask +``` - * Server path definition on target VM (`/etc/qubes-rpc/test.Add`) +* Server path definition on target VM (`/etc/qubes-rpc/test.Add`) +``` /usr/bin/our_test_add_server +``` - * To test this service, run the following in the source VM: +* To test this service, run the following in the source VM: +``` /usr/lib/qubes/qrexec-client-vm test.Add /usr/bin/our_test_add_client 1 2 +``` and we should get "3" as answer, provided dom0 policy allows the call to pass through, which would happen after we click "Yes" in the popup that should @@ -229,7 +244,6 @@ users/app developers are always free to run more high-level RPC protocols on top of qrexec. Care should be taken, however, to consider potential attack surfaces that are exposed to untrusted or less trusted VMs in that case. - # Qubes RPC internals # (*This is about the implementation of qrexec v2. For the implementation of @@ -237,52 +251,48 @@ qrexec v3, see [here](/doc/qrexec-internals/). Note that the user API in v3 is backward compatible: qrexec apps written for Qubes R2 should run without modification on Qubes R3.*) - ## Dom0 tools implementation ## Players: - * `/usr/lib/qubes/qrexec-daemon`: started by mgmt stack (qubes.py) when a +* `/usr/lib/qubes/qrexec-daemon`: started by mgmt stack (qubes.py) when a VM is started. - * `/usr/lib/qubes/qrexec-policy`: internal program used to evaluate the +* `/usr/lib/qubes/qrexec-policy`: internal program used to evaluate the policy file and making the 2nd half of the connection. - * `/usr/lib/qubes/qrexec-client`: raw command line tool that talks to the +* `/usr/lib/qubes/qrexec-client`: raw command line tool that talks to the daemon via unix socket (`/var/run/qubes/qrexec.XID`) **Note:** None of the above tools are designed to be used by users. - ## Linux VMs implementation ## Players: - * `/usr/lib/qubes/qrexec-agent`: started by VM bootup scripts, a daemon. - * `/usr/lib/qubes/qubes-rpc-multiplexer`: executes the actual service program, +* `/usr/lib/qubes/qrexec-agent`: started by VM bootup scripts, a daemon. +* `/usr/lib/qubes/qubes-rpc-multiplexer`: executes the actual service program, as specified in VM's `/etc/qubes-rpc/qubes.XYZ`. - * `/usr/lib/qubes/qrexec-client-vm`: raw command line tool that talks to +* `/usr/lib/qubes/qrexec-client-vm`: raw command line tool that talks to the agent. **Note:** None of the above tools are designed to be used by users. `qrexec-client-vm` is designed to be wrapped up by Qubes apps. - ## Windows VMs implementation ## `%QUBES_DIR%` is the installation path (`c:\Program Files\Invisible Things Lab\Qubes OS Windows Tools` by default). - * `%QUBES_DIR%\bin\qrexec-agent.exe`: runs as a system service. Responsible +* `%QUBES_DIR%\bin\qrexec-agent.exe`: runs as a system service. Responsible both for raw command execution and interpreting RPC service requests. - * `%QUBES_DIR%\qubes-rpc`: directory with `qubes.XYZ` files that contain +* `%QUBES_DIR%\qubes-rpc`: directory with `qubes.XYZ` files that contain commands for executing RPC services. Binaries for the services are contained in `%QUBES_DIR%\qubes-rpc-services`. - * `%QUBES_DIR%\bin\qrexec-client-vm`: raw command line tool that talks to +* `%QUBES_DIR%\bin\qrexec-client-vm`: raw command line tool that talks to the agent. **Note:** None of the above tools are designed to be used by users. `qrexec-client-vm` is designed to be wrapped up by Qubes apps. - ## All the pieces together at work ## **Note:** This section is not needed to use qrexec for writing Qubes @@ -300,30 +310,30 @@ vchan connections. When a user in a source VM executes `qrexec-client-vm` utility, the following steps are taken: - * `qrexec-client-vm` connects to `qrexec-agent`'s +* `qrexec-client-vm` connects to `qrexec-agent`'s `/var/run/qubes/qrexec-agent-fdpass` unix socket 3 times. Reads 4 bytes from each of them, which is the fd number of the accepted socket in agent. These 3 integers, in text, concatenated, form "connection identifier" (CID) - * `qrexec-client-vm` writes to `/var/run/qubes/qrexec-agent` fifo a blob, +* `qrexec-client-vm` writes to `/var/run/qubes/qrexec-agent` fifo a blob, consisting of target vmname, rpc action, and CID - * `qrexec-client-vm` executes the rpc client, passing the above mentioned +* `qrexec-client-vm` executes the rpc client, passing the above mentioned unix sockets as process stdin/stdout, and optionally stderr (if the `PASS_LOCAL_STDERR` env variable is set) - * `qrexec-agent` passes the blob to `qrexec-daemon`, via +* `qrexec-agent` passes the blob to `qrexec-daemon`, via `MSG_AGENT_TO_SERVER_TRIGGER_CONNECT_EXISTING` message over vchan - * `qrexec-daemon` executes `qrexec-policy`, passing source vmname, target +* `qrexec-daemon` executes `qrexec-policy`, passing source vmname, target vmname, rpc action, and CID as cmdline arguments - * `qrexec-policy` evaluates the policy file. If successful, creates a pair of +* `qrexec-policy` evaluates the policy file. If successful, creates a pair of `qrexec-client` processes, whose stdin/stdout are cross-connected. - * The first `qrexec-client` connects to the src VM, using the `-c ClientID` + * The first `qrexec-client` connects to the src VM, using the `-c ClientID` parameter, which results in not creating a new process, but connecting to the existing process file descriptors (these are the fds of unix socket created in step 1). - * The second `qrexec-client` connects to the target VM, and executes + * The second `qrexec-client` connects to the target VM, and executes `qubes-rpc-multiplexer` command there with the rpc action as the cmdline argument. Finally, `qubes-rpc-multiplexer` executes the correct rpc server on the target. - * In the above step, if the target VM is `$dispvm`, the DispVM is created +* In the above step, if the target VM is `$dispvm`, the DispVM is created via the `qfile-daemon-dvm` program. The latter waits for the `qrexec-client` process to exit, and then destroys the DispVM. From 7179ba8b4ba5f0ec257fec56a132e10a85a11c91 Mon Sep 17 00:00:00 2001 From: dd Date: Sun, 1 Nov 2020 02:55:28 +0100 Subject: [PATCH 070/663] linted docs in developer/releases --- .../developer/releases/1_0/release-notes.md | 25 +++++++--------- .../developer/releases/2_0/release-notes.md | 30 ++++++++----------- .../developer/releases/3_0/release-notes.md | 18 ++++------- .../developer/releases/3_1/release-notes.md | 18 ++++------- en/_doc/developer/releases/3_1/schedule.md | 2 +- .../developer/releases/3_2/release-notes.md | 18 ++++------- en/_doc/developer/releases/3_2/schedule.md | 6 ++-- .../developer/releases/4_0/release-notes.md | 1 - en/_doc/developer/releases/4_0/schedule.md | 10 +++---- en/_doc/developer/releases/notes.md | 12 ++++---- en/_doc/developer/releases/schedules.md | 8 ++--- en/_doc/developer/releases/todo.md | 3 ++ 12 files changed, 62 insertions(+), 89 deletions(-) diff --git a/en/_doc/developer/releases/1_0/release-notes.md b/en/_doc/developer/releases/1_0/release-notes.md index 780b738f03..54fa1bcfbe 100644 --- a/en/_doc/developer/releases/1_0/release-notes.md +++ b/en/_doc/developer/releases/1_0/release-notes.md @@ -8,41 +8,36 @@ ref: 18 title: Qubes R1.0 Release Notes --- -Qubes R1.0 Release Notes -======================== +# Qubes R1.0 Release Notes Detailed release notes in [this blog post](http://blog.invisiblethings.org/2012/09/03/introducing-qubes-10.html). -Known issues ------------- +## Known issues -- Installer might not support some USB keyboards (\#230). This seems to include all the Mac Book keyboards (most PC laptops have PS2 keyboards and are not affected). +- Installer might not support some USB keyboards (\#230). This seems to include all the Mac Book keyboards (most PC laptops have PS2 keyboards and are not affected). -- If you don't enable Composition (System Setting -\> Desktop -\> Enable desktop effects), which you really should do, then the KDE task bar might get ugly (e.g. half of it might be black). This is some KDE bug that we don't plan to fix. +- If you don't enable Composition (System Setting -\> Desktop -\> Enable desktop effects), which you really should do, then the KDE task bar might get ugly (e.g. half of it might be black). This is some KDE bug that we don't plan to fix. -- Some keyboard layout set by KDE System Settings can cause [keyboard not working at all](https://groups.google.com/group/qubes-devel/browse_thread/thread/77d076b65dda7226). If you hit this issue, you can switch to console (by console login option) and manually edit `/etc/X11/xorg.conf.d/00-system-setup-keyboard.conf` (and `/etc/sysconfig/keyboard`) and place correct keyboard layout settings (details in linked thread). You can check if specific keyboard layout settings are proper using `setxkbmap` tool. +- Some keyboard layout set by KDE System Settings can cause [keyboard not working at all](https://groups.google.com/group/qubes-devel/browse_thread/thread/77d076b65dda7226). If you hit this issue, you can switch to console (by console login option) and manually edit `/etc/X11/xorg.conf.d/00-system-setup-keyboard.conf` (and `/etc/sysconfig/keyboard`) and place correct keyboard layout settings (details in linked thread). You can check if specific keyboard layout settings are proper using `setxkbmap` tool. -- On systems with more than 8GB of RAM there is problem with DisposableVM. To fix it, limit maximum memory allocation for DispVM to 3GB +- On systems with more than 8GB of RAM there is problem with DisposableVM. To fix it, limit maximum memory allocation for DispVM to 3GB ~~~ qvm-prefs -s fedora-17-x64-dvm maxmem 3072 qvm-create-default-dvm --default-template --default-script ~~~ -- On some systems the KDE Window Manager might freeze upon resuming from S3 sleep when compositing is enabled (and the only method to log in to the system if this happens is to switch to a text console, enter your user's password, kill the kwin process, go back to the Xorg console, log in, and start a new instance of kwin using Konsole application :) If you experience such problems, make sure to disable compositing before putting the system into sleep by pressing Alt-Ctrl-F12 (and then enabling it back once you log in after resume) -- this way you should never see this problem again. +- On some systems the KDE Window Manager might freeze upon resuming from S3 sleep when compositing is enabled (and the only method to log in to the system if this happens is to switch to a text console, enter your user's password, kill the kwin process, go back to the Xorg console, log in, and start a new instance of kwin using Konsole application :) If you experience such problems, make sure to disable compositing before putting the system into sleep by pressing Alt-Ctrl-F12 (and then enabling it back once you log in after resume) -- this way you should never see this problem again. -Downloads ---------- +## Downloads See [Qubes Downloads](/doc/QubesDownloads/). -Installation instructions -------------------------- +## Installation instructions See [Installation Guide](/doc/installation-guide/). -Upgrading ---------- +## Upgrading ### From Qubes 1.0-rc1 diff --git a/en/_doc/developer/releases/2_0/release-notes.md b/en/_doc/developer/releases/2_0/release-notes.md index 8a9027e372..86c09ac813 100644 --- a/en/_doc/developer/releases/2_0/release-notes.md +++ b/en/_doc/developer/releases/2_0/release-notes.md @@ -8,13 +8,11 @@ ref: 25 title: Qubes R2.0 Release Notes --- -Qubes R2.0 Release Notes -======================== +# Qubes R2.0 Release Notes Detailed release notes in [this blog post](http://blog.invisiblethings.org/2014/09/26/announcing-qubes-os-release-2.html) -New features since 1.0 ----------------------- +## New features since 1.0 * Support for generic fully virtualized VMs (without qemu in the TCB!) * Support for Windows-based AppVMs integration (clipboard, file exchange, qrexec, pv drivers) @@ -30,35 +28,31 @@ New features since 1.0 * Support for dynamic screen resolution change * Dom0 distribution upgraded to Fedora 20 -Known issues ------------- +## Known issues -- On some graphics cards the Xfce4 Window Manager (one of the two supported Dom0 Windows Managers in Qubes R2, the other being KDE) might behave "strangely", e.g. decorations might not be drawn sometimes. Also the accompanying lightdm login manager might incorrectly display the wallpaper. If you're facing those problems, it's advisable to use the KDE Window Manager and kdm instead of Xfce4 and lightdm (this is default if one chooses the KDE only installation option in the installer). +* On some graphics cards the Xfce4 Window Manager (one of the two supported Dom0 Windows Managers in Qubes R2, the other being KDE) might behave "strangely", e.g. decorations might not be drawn sometimes. Also the accompanying lightdm login manager might incorrectly display the wallpaper. If you're facing those problems, it's advisable to use the KDE Window Manager and kdm instead of Xfce4 and lightdm (this is default if one chooses the KDE only installation option in the installer). -- Some icons in the Qubes Manager application might not be drawn correctly when using the Xfce4 environment in Dom0. If this bothers you, please use the KDE environment instead. +* Some icons in the Qubes Manager application might not be drawn correctly when using the Xfce4 environment in Dom0. If this bothers you, please use the KDE environment instead. -- If your GPU is not correctly supported by the Dom0 kernel (e.g. the 3D desktop effects do not run smoothly) then you might experience "heaviness" with Windows 7-based AppVMs. In that case, please solve the problem with your GPU support in Dom0 in the first place (by using a different kernel), or install Qubes OS on a different system. +* If your GPU is not correctly supported by the Dom0 kernel (e.g. the 3D desktop effects do not run smoothly) then you might experience "heaviness" with Windows 7-based AppVMs. In that case, please solve the problem with your GPU support in Dom0 in the first place (by using a different kernel), or install Qubes OS on a different system. -- Under some circumstances, Qubes backup can create broken backup, without any visible message (\#902). It is advisable to verify a backup to spot the problem. If you encounter this problem, backup VM directory manually. +* Under some circumstances, Qubes backup can create broken backup, without any visible message (\#902). It is advisable to verify a backup to spot the problem. If you encounter this problem, backup VM directory manually. -- System shutdown sometimes is very slow (\#903). To mitigate the problem, shutdown all the VMs first. +* System shutdown sometimes is very slow (\#903). To mitigate the problem, shutdown all the VMs first. -- For other known issues take a look at [our trac tickets](https://wiki.qubes-os.org/query?status=accepted&status=assigned&status=new&status=reopened&type=defect&milestone=Release+2.1+(post+R2)&col=id&col=summary&col=status&col=type&col=priority&col=milestone&col=component&order=priority) +* For other known issues take a look at [our trac tickets](https://wiki.qubes-os.org/query?status=accepted&status=assigned&status=new&status=reopened&type=defect&milestone=Release+2.1+(post+R2)&col=id&col=summary&col=status&col=type&col=priority&col=milestone&col=component&order=priority) It is advised to install updates just after system installation to apply bug fixes for (some of) the above problems. -Downloads ---------- +## Downloads See [Qubes Downloads](/doc/QubesDownloads/). -Installation instructions -------------------------- +## Installation instructions See [Installation Guide](/doc/installation-guide/). -Upgrading ---------- +## Upgrading ### From Qubes R2 rc1 diff --git a/en/_doc/developer/releases/3_0/release-notes.md b/en/_doc/developer/releases/3_0/release-notes.md index 95d677a120..44fa79c480 100644 --- a/en/_doc/developer/releases/3_0/release-notes.md +++ b/en/_doc/developer/releases/3_0/release-notes.md @@ -8,13 +8,11 @@ ref: 19 title: Qubes R3.0 Release Notes --- -Qubes R3.0 Release Notes -======================== +### Qubes R3.0 Release Notes This Qubes OS release is dedicated to the memory of Caspar Bowden. -New features since 2.0 ----------------------- +## New features since 2.0 * HAL (Hypervisor Abstraction Layer) - based on libvirt, opens a whole new possibilities of using different hypervisors. Currently Qubes OS uses Xen. @@ -29,8 +27,7 @@ New features since 2.0 templates using DispVM. * Automated tests - makes much easier to find bugs, before its even shipped to users -Known issues ------------- +## Known issues * Windows Tools: `qvm-block` does not work @@ -44,18 +41,15 @@ Known issues It is advised to install updates just after system installation to apply bug fixes for (some of) the above problems. -Downloads ---------- +## Downloads See [Qubes Downloads](/doc/QubesDownloads/). -Installation instructions -------------------------- +## Installation instructions See [Installation Guide](/doc/installation-guide/). -Upgrading ---------- +## Upgrading ### From R3.0 release candidate diff --git a/en/_doc/developer/releases/3_1/release-notes.md b/en/_doc/developer/releases/3_1/release-notes.md index 85dc042792..3a192e3859 100644 --- a/en/_doc/developer/releases/3_1/release-notes.md +++ b/en/_doc/developer/releases/3_1/release-notes.md @@ -6,11 +6,9 @@ ref: 16 title: Qubes R3.1 release notes --- -Qubes R3.1 release notes -======================== +# Qubes R3.1 release notes -New features since 3.0 ----------------------- +## New features since 3.0 * Management Stack based of Salt Stack in dom0 - [documentation][salt-doc] * Out of the box Whonix setup @@ -25,8 +23,7 @@ New features since 3.0 You can get detailed description in [completed github issues][github-release-notes] -Known issues ------------- +## Known issues * Installation image does not fit on DVD, requires either DVD DL, or USB stick (5GB or more) @@ -40,18 +37,15 @@ Known issues It is advised to install updates just after system installation to apply bug fixes for (some of) the above problems. -Downloads ---------- +## Downloads See [Qubes Downloads](/downloads/). -Installation instructions -------------------------- +## Installation instructions See [Installation Guide](/doc/installation-guide/). -Upgrading ---------- +## Upgrading ### From R3.0 diff --git a/en/_doc/developer/releases/3_1/schedule.md b/en/_doc/developer/releases/3_1/schedule.md index 46dfe8b44c..99ba5436f1 100644 --- a/en/_doc/developer/releases/3_1/schedule.md +++ b/en/_doc/developer/releases/3_1/schedule.md @@ -20,4 +20,4 @@ This schedule is based on [Version Scheme](/doc/version-scheme/#release-schedule | 12 Jan 2016 | 3.1-rc2 release | | 26 Jan 2016 | decide whether 3.1-rc2 is the final 3.1 | | 9 Feb 2016 | current-testing freeze before 3.1-rc3 | -| 16 Feb 2016
23 Feb 2016 | 3.1-rc3 release | +| ~~16 Feb 2016~~
23 Feb 2016 | 3.1-rc3 release | diff --git a/en/_doc/developer/releases/3_2/release-notes.md b/en/_doc/developer/releases/3_2/release-notes.md index b411a6c666..dac6218ddb 100644 --- a/en/_doc/developer/releases/3_2/release-notes.md +++ b/en/_doc/developer/releases/3_2/release-notes.md @@ -6,11 +6,9 @@ ref: 21 title: Qubes R3.2 release notes --- -Qubes R3.2 release notes -======================== +# Qubes R3.2 release notes -New features since 3.1 ----------------------- +## New features since 3.1 * Management Stack extended to support in-VM configuration - [documentation][salt-doc] * PV USB - [documentation][usb] @@ -23,8 +21,7 @@ New features since 3.1 You can get detailed description in [completed github issues][github-release-notes] -Known issues ------------- +## Known issues * [Fedora 23 reached EOL in December 2016](https://fedoraproject.org/wiki/End_of_life). There is a [manual procedure to upgrade your VMs](/news/2018/01/06/fedora-26-upgrade/). @@ -36,19 +33,16 @@ Known issues It is advised to install updates just after system installation to apply bug fixes for (some of) the above problems. -Downloads ---------- +## Downloads See [Qubes Downloads](/downloads/). -Installation instructions -------------------------- +## Installation instructions See [Installation Guide](/doc/installation-guide/). After installation, [manually upgrade to Fedora 26](/news/2018/01/06/fedora-26-upgrade/). -Upgrading ---------- +## Upgrading ### From R3.1 diff --git a/en/_doc/developer/releases/3_2/schedule.md b/en/_doc/developer/releases/3_2/schedule.md index 5fc3fdd5fc..3ac05f3d91 100644 --- a/en/_doc/developer/releases/3_2/schedule.md +++ b/en/_doc/developer/releases/3_2/schedule.md @@ -17,9 +17,9 @@ This schedule is based on [Version Scheme](/doc/version-scheme/#release-schedule | -----------:| --------------------------------------- | | 18 Jun 2016 | 3.2-rc1 release | | 2 Jul 2016 | decide whether 3.2-rc1 is the final 3.2 | -| 16 Jul 2016
20 Jul 2016 | current-testing freeze before 3.2-rc2 | -| 23 Jul 2016
27 Jul 2016 | 3.2-rc2 release | -| 5 Aug 2016
9 Aug 2016 | decide whether 3.2-rc2 is the final 3.2 | +| ~~16 Jul 2016~~
20 Jul 2016 | current-testing freeze before 3.2-rc2 | +| ~~23 Jul 2016~~
27 Jul 2016 | 3.2-rc2 release | +| ~~5 Aug 2016~~
9 Aug 2016 | decide whether 3.2-rc2 is the final 3.2 | | 24 Aug 2016 | current-testing freeze before 3.2-rc3 | | 31 Aug 2016 | 3.2-rc3 release | | 29 Sep 2016 | 3.2 release | diff --git a/en/_doc/developer/releases/4_0/release-notes.md b/en/_doc/developer/releases/4_0/release-notes.md index 0e4e1d5842..a24e7c88fe 100644 --- a/en/_doc/developer/releases/4_0/release-notes.md +++ b/en/_doc/developer/releases/4_0/release-notes.md @@ -105,7 +105,6 @@ supported option to upgrade to Qubes R4.0 is to install it from scratch and use [qubes backup and restore tools][backup] for migrating of all of the user VMs. We also provide [detailed instruction][upgrade-to-r4.0] for this procedure. - [backup]: /doc/backup-restore/ [github-release-notes]: https://github.com/QubesOS/qubes-issues/issues?q=is%3Aissue+sort%3Aupdated-desc+milestone%3A%22Release+4.0%22+label%3Arelease-notes+is%3Aclosed [custom-ip]: https://github.com/QubesOS/qubes-issues/issues/1477 diff --git a/en/_doc/developer/releases/4_0/schedule.md b/en/_doc/developer/releases/4_0/schedule.md index 29e0a5866e..dbfc003b25 100644 --- a/en/_doc/developer/releases/4_0/schedule.md +++ b/en/_doc/developer/releases/4_0/schedule.md @@ -16,15 +16,15 @@ This schedule is based on [Version Scheme](/doc/version-scheme/#release-schedule | Date | Stage | | -----------:| --------------------------------------- | | 31 Jul 2017 | 4.0-rc1 release | -| 28 Aug 2017
11 Sep 2017
9 Oct 2017
18 Oct 2017 | current-testing freeze before 4.0-rc2 | -| 4 Sep 2017
18 Sep 2017
16 Oct 2017
23 Oct 2017 | 4.0-rc2 release | -| 6 Nov 2017 | decide whether 4.0-rc2 is the final 4.0 | +| ~~28 Aug 2017~~
~~11 Sep 2017~~
~~9 Oct 2017~~
18 Oct 2017 | current-testing freeze before 4.0-rc2 | +| ~~4 Sep 2017~~
~~18 Sep 2017~~
~~16 Oct 2017~~
23 Oct 2017 | 4.0-rc2 release | +| 6 Nov 2017 | decide whether 4.0-rc2 is the final 4 | 20 Nov 2017 | current-testing freeze before 4.0-rc3 | | 27 Nov 2017 | 4.0-rc3 release | | 11 Dec 2017 | decide whether 4.0-rc3 is the final 4.0 | | 1 Jan 2018 | current-testing freeze before 4.0-rc4 | -| 8 Jan 2018
31 Jan 2018 | 4.0-rc4 release | -| 22 Jan 2018
14 Feb 2018 | decide whether 4.0-rc4 is the final 4.0 | +| ~~8 Jan 2018~~
31 Jan 2018 | 4.0-rc4 release | +| ~~22 Jan 2018~~
14 Feb 2018 | decide whether 4.0-rc4 is the final 4.0 | | 27 Feb 2018 | current-testing freeze before 4.0-rc5 | | 6 Mar 2018 | 4.0-rc5 release | | 20 Mar 2018 | decide whether 4.0-rc5 is the final 4.0 | diff --git a/en/_doc/developer/releases/notes.md b/en/_doc/developer/releases/notes.md index 0a6f9f02d8..29c700d942 100644 --- a/en/_doc/developer/releases/notes.md +++ b/en/_doc/developer/releases/notes.md @@ -9,9 +9,9 @@ title: Release Notes Release Notes ============= - * [Qubes R1.0 release notes](/doc/releases/1.0/release-notes/) - * [Qubes R2.0 release notes](/doc/releases/2.0/release-notes/) - * [Qubes R3.0 release notes](/doc/releases/3.0/release-notes/) - * [Qubes R3.1 release notes](/doc/releases/3.1/release-notes/) - * [Qubes R3.2 release notes](/doc/releases/3.2/release-notes/) - * [Qubes R4.0 release notes](/doc/releases/4.0/release-notes/) +* [Qubes R1.0 release notes](/doc/releases/1.0/release-notes/) +* [Qubes R2.0 release notes](/doc/releases/2.0/release-notes/) +* [Qubes R3.0 release notes](/doc/releases/3.0/release-notes/) +* [Qubes R3.1 release notes](/doc/releases/3.1/release-notes/) +* [Qubes R3.2 release notes](/doc/releases/3.2/release-notes/) +* [Qubes R4.0 release notes](/doc/releases/4.0/release-notes/) diff --git a/en/_doc/developer/releases/schedules.md b/en/_doc/developer/releases/schedules.md index 2e5257ec2f..4b0aaaac02 100644 --- a/en/_doc/developer/releases/schedules.md +++ b/en/_doc/developer/releases/schedules.md @@ -9,7 +9,7 @@ title: Release Schedules Release Schedules ================= - * [Qubes R3.0 release schedule](/doc/releases/3.0/schedule/) - * [Qubes R3.1 release schedule](/doc/releases/3.1/schedule/) - * [Qubes R3.2 release schedule](/doc/releases/3.2/schedule/) - * [Qubes R4.0 release schedule](/doc/releases/4.0/schedule/) +* [Qubes R3.0 release schedule](/doc/releases/3.0/schedule/) +* [Qubes R3.1 release schedule](/doc/releases/3.1/schedule/) +* [Qubes R3.2 release schedule](/doc/releases/3.2/schedule/) +* [Qubes R4.0 release schedule](/doc/releases/4.0/schedule/) diff --git a/en/_doc/developer/releases/todo.md b/en/_doc/developer/releases/todo.md index 28b5fc53df..9ac108a743 100644 --- a/en/_doc/developer/releases/todo.md +++ b/en/_doc/developer/releases/todo.md @@ -15,6 +15,7 @@ Release Checklist On -rc1 ------- + * write schedule * create package repositories (linux-yum, linux-deb) * update repository definition (core-agent-linux, installer-qubes-os/qubes-release) @@ -26,6 +27,7 @@ On -rc1 On subsequent -rc ----------------- + * push packages to `current` * update release notes * build ISO and push to mirrors @@ -33,6 +35,7 @@ On subsequent -rc On final release ---------------- + * push packages to `current` * finish release notes * update InstallationInstructions From ad86bc46102782e6c0669598ea480dd7f6168fde Mon Sep 17 00:00:00 2001 From: dd Date: Sun, 1 Nov 2020 03:10:38 +0100 Subject: [PATCH 071/663] linted docs in developer/system --- en/_doc/developer/system/architecture.md | 60 ++++++++-------- en/_doc/developer/system/audio.md | 24 +++---- en/_doc/developer/system/gui.md | 56 +++++++-------- en/_doc/developer/system/networking.md | 18 ++--- .../system/security-critical-code.md | 33 ++++----- en/_doc/developer/system/storage-pools.md | 1 - .../system/template-implementation.md | 71 +++++++++---------- 7 files changed, 124 insertions(+), 139 deletions(-) diff --git a/en/_doc/developer/system/architecture.md b/en/_doc/developer/system/architecture.md index 9034e0f0ff..104ce96a8b 100644 --- a/en/_doc/developer/system/architecture.md +++ b/en/_doc/developer/system/architecture.md @@ -20,25 +20,23 @@ Qubes implements a Security by Isolation approach. To do this, Qubes utilizes vi Qubes lets the user define many security domains, which are implemented as lightweight Virtual Machines (VMs), or “AppVMs.” For example, the user can have “personal,” “work,” “shopping,” “bank,” and “random” AppVMs and can use the applications within those VMs just as if they were executing on the local machine. At the same time, however, these applications are well isolated from each other. Qubes also supports secure copy-and-paste and file sharing between the AppVMs, of course. - Key Architecture features ------------------------- -- Based on a secure bare-metal hypervisor (Xen) -- Networking code sand-boxed in an unprivileged VM (using IOMMU/VT-d) -- USB stacks and drivers sand-boxed in an unprivileged VM (currently experimental feature) -- No networking code in the privileged domain (dom0) -- All user applications run in “AppVMs,” lightweight VMs based on Linux -- Centralized updates of all AppVMs based on the same template -- Qubes GUI virtualization presents applications as if they were running locally -- Qubes GUI provides isolation between apps sharing the same desktop -- Secure system boot based (optional) +- Based on a secure bare-metal hypervisor (Xen) +- Networking code sand-boxed in an unprivileged VM (using IOMMU/VT-d) +- USB stacks and drivers sand-boxed in an unprivileged VM (currently experimental feature) +- No networking code in the privileged domain (dom0) +- All user applications run in “AppVMs,” lightweight VMs based on Linux +- Centralized updates of all AppVMs based on the same template +- Qubes GUI virtualization presents applications as if they were running locally +- Qubes GUI provides isolation between apps sharing the same desktop +- Secure system boot based (optional) (For those interested in the history of the project, [Architecture Spec v0.3 [PDF]](/attachment/wiki/QubesArchitecture/arch-spec-0.3.pdf) is the original 2009 document that started this all. Please note that this document is for historical interest only. For the latest information, please see the rest of the [System Documentation](/doc/#system).) - Qubes Core Stack ---------------- @@ -47,26 +45,26 @@ the glue that connects all the other components together, and which allows users and admins to interact with and configure the system. The other components of the Qubes system include: - - VM-located core agents (implementing e.g. qrexec endpoints used by various - Qubes services) - - VM-customizations (making the VMs lightweight and working well with seamless - GUI virtualization) - - Qubes GUI virtualization (the protocol, VM-located agents, and daemons - located in the GUI domain which, for now, happens to be the same as dom0), - - GUI domain customizations (Desktop Environment customizations, decoration - coloring plugin, etc) - - The AdminVM distribution (various customizations, special services, such as - for receiving and verifying updates, in the future: custom distro) - - The Xen hypervisor (with a bunch of customization patches, occasional - hardening) or - in the future - some other virtualising or containerizing - software or technology - - Multiple "Qubes Apps" (various services built on top of Qubes qrexec - infrastructure, such as: trusted PDF and Image converters, Split GPG, safe - USB proxies for HID devices, USB proxy for offering USB devices (exposed via - qvm-usb), Yubikey support, USB Armory support, etc) - - Various ready-to-use templates (e.g. Debian-, Whonix-based), which are used - to create actual VMs, i.e. provide the root filesystem to the VMs - - Salt Stack integration +- VM-located core agents (implementing e.g. qrexec endpoints used by various + Qubes services) +- VM-customizations (making the VMs lightweight and working well with seamless + GUI virtualization) +- Qubes GUI virtualization (the protocol, VM-located agents, and daemons + located in the GUI domain which, for now, happens to be the same as dom0), +- GUI domain customizations (Desktop Environment customizations, decoration + coloring plugin, etc) +- The AdminVM distribution (various customizations, special services, such as + for receiving and verifying updates, in the future: custom distro) +- The Xen hypervisor (with a bunch of customization patches, occasional + hardening) or - in the future - some other virtualising or containerizing + software or technology +- Multiple "Qubes Apps" (various services built on top of Qubes qrexec + infrastructure, such as: trusted PDF and Image converters, Split GPG, safe + USB proxies for HID devices, USB proxy for offering USB devices (exposed via + qvm-usb), Yubikey support, USB Armory support, etc) +- Various ready-to-use templates (e.g. Debian-, Whonix-based), which are used + to create actual VMs, i.e. provide the root filesystem to the VMs +- Salt Stack integration And all these components are "glued together" by the Qubes Core Stack. diff --git a/en/_doc/developer/system/audio.md b/en/_doc/developer/system/audio.md index 63de31983b..e1f2dbe6ac 100644 --- a/en/_doc/developer/system/audio.md +++ b/en/_doc/developer/system/audio.md @@ -12,8 +12,8 @@ Audio Virtualization VMs on Qubes OS have access to virtualized audio through the PulseAudio module. It consists of two parts: - - `pacat-simple-vchan` running in a dom0/Audio VM (standalone application, one per VM, connected to the PulseAudio daemon) - - `module-vchan-sink` running in a VM (loaded into the PulseAudio process) +- `pacat-simple-vchan` running in a dom0/Audio VM (standalone application, one per VM, connected to the PulseAudio daemon) +- `module-vchan-sink` running in a VM (loaded into the PulseAudio process) Protocol -------- @@ -35,10 +35,10 @@ Each such notification is a 4-byte number in little-endian format. List of defined codes: - - `0x00010001` -- VM wants to receive audio input (some process is listening); prior to this message, `pacat-simple-vchan` will not send any audio samples to the VM. - - `0x00010000` -- VM does not want to receive audio input (no process is listening anymore); after this message, `pacat-simple-vchan` will not send any audio samples to the VM. - - `0x00020000` -- VM does not want to send audio output; informational for dom0, to avoid buffer under runs (may affect PulseAudio calculated delays). - - `0x00020001` -- VM does want to send audio output. +- `0x00010001` -- VM wants to receive audio input (some process is listening); prior to this message, `pacat-simple-vchan` will not send any audio samples to the VM. +- `0x00010000` -- VM does not want to receive audio input (no process is listening anymore); after this message, `pacat-simple-vchan` will not send any audio samples to the VM. +- `0x00020000` -- VM does not want to send audio output; informational for dom0, to avoid buffer under runs (may affect PulseAudio calculated delays). +- `0x00020001` -- VM does want to send audio output. pacat-simple-vchan ------------------ @@ -54,16 +54,16 @@ It needs to be both requested by the VM part and explicitly enabled in `pacat-si The mechanism to do this differs between Qubes versions. In Qubes before R4.1, `pacat-simple-vchan` is controlled over system D-Bus: - - destination: `org.qubesos.Audio.VMNAME` (where `VMNAME` is the VM's name) - - object path: `/org/qubesos/audio` - - interface: `org.qubesos.Audio` - - property: `RecAllowed` (which can be set using the `org.freedesktop.DBus.Properties` interface) +- destination: `org.qubesos.Audio.VMNAME` (where `VMNAME` is the VM's name) +- object path: `/org/qubesos/audio` +- interface: `org.qubesos.Audio` +- property: `RecAllowed` (which can be set using the `org.freedesktop.DBus.Properties` interface) In Qubes R4.1 and later, `pacat-simple-vchan` is controlled over a UNIX socket at `/var/run/qubes/audio-control.VMNAME` (where `VMNAME` is the VM's name). Supported commands: - - `audio-input 1\n` - enable audio input - - `audio-input 0\n` - disable audio input +- `audio-input 1\n` - enable audio input +- `audio-input 0\n` - disable audio input These commands can be sent using the `qubes.AudioInputEnable+VMNAME` and `qubes.AudioInputDisable+VMNAME` qrexec services, respectively. The current status is written into QubesDB at `/audio-input/VMNAME` (where `VMNAME` is the VM's name) with either `1` or `0` values. diff --git a/en/_doc/developer/system/gui.md b/en/_doc/developer/system/gui.md index d4eba90def..c0be550e70 100644 --- a/en/_doc/developer/system/gui.md +++ b/en/_doc/developer/system/gui.md @@ -19,23 +19,23 @@ qubes_gui and qubes_guid processes All AppVM X applications connect to local (running in AppVM) Xorg servers that use the following "hardware" drivers: -- *dummyqsb_drv* - video driver, that paints onto a framebuffer located in RAM, not connected to real hardware -- *qubes_drv* - it provides a virtual keyboard and mouse (in fact, more, see below) +- *dummyqsb_drv* - video driver, that paints onto a framebuffer located in RAM, not connected to real hardware +- *qubes_drv* - it provides a virtual keyboard and mouse (in fact, more, see below) For each AppVM, there is a pair of *qubes_gui* (running in AppVM) and *qubes_guid* (running in dom0) processes connected over vchan. The main responsibilities of *qubes_gui* are: -- call XCompositeRedirectSubwindows on the root window, so that each window has its own composition buffer -- instruct the local Xorg server to notify it about window creation, configuration and damage events; pass information on these events to dom0 -- receive information about keyboard and mouse events from dom0, tell *qubes_drv* to fake appropriate events -- receive information about window size/position change, apply them to the local window +- call XCompositeRedirectSubwindows on the root window, so that each window has its own composition buffer +- instruct the local Xorg server to notify it about window creation, configuration and damage events; pass information on these events to dom0 +- receive information about keyboard and mouse events from dom0, tell *qubes_drv* to fake appropriate events +- receive information about window size/position change, apply them to the local window The main responsibilities of *qubes_guid* are: -- create a window in dom0 whenever an information on window creation in AppVM is received from *qubes_gui* -- whenever the local window receives XEvent, pass information on it to AppVM (particularly, mouse and keyboard data) -- whenever AppVM signals damage event, tell local Xorg server to repaint a given window fragment -- receive information about window size/position change, apply them to the local window +- create a window in dom0 whenever an information on window creation in AppVM is received from *qubes_gui* +- whenever the local window receives XEvent, pass information on it to AppVM (particularly, mouse and keyboard data) +- whenever AppVM signals damage event, tell local Xorg server to repaint a given window fragment +- receive information about window size/position change, apply them to the local window Note that keyboard and mouse events are passed to AppVM only if a window belonging to this AppVM has focus. AppVM has no way to get information on keystrokes fed to other AppVMs (e.g. XTEST extension will report the status of local AppVM keyboard only) or synthesize and pass events to other AppVMs. @@ -47,26 +47,26 @@ Typical remote desktop applications, like *vnc*, pass information on all changed As that channel has limited throughput, this impacts video performance. In the case of Qubes, *qubes_gui* does not transfer all changed pixels via vchan. Instead, for each window, upon its creation or size change, *qubes_gui* -- asks *qubes_drv* driver for the list of physical memory frames that hold the composition buffer of a window -- passes this information via `MFNDUMP` message to *qubes_guid* in dom0 +- asks *qubes_drv* driver for the list of physical memory frames that hold the composition buffer of a window +- passes this information via `MFNDUMP` message to *qubes_guid* in dom0 Now, *qubes_guid* has to tell the dom0 Xorg server about the location of the buffer. There is no supported way (e.g. Xorg extension) to do this zero-copy style. The following method is used in Qubes: -- in dom0, the Xorg server is started with *LD_PRELOAD*-ed library named *shmoverride.so*. This library hooks all function calls related to shared memory. -- *qubes_guid* creates a shared memory segment, and then tells Xorg to attach it via *MIT-SHM* extension -- when Xorg tries to attach the segment (via glibc *shmat*) *shmoverride.so* intercepts this call and instead maps AppVM memory via *xc_map_foreign_pages* -- since then, we can use MIT-SHM functions, e.g. *XShmPutImage* to draw onto a dom0 window. *XShmPutImage* will paint with DRAM speed; actually, many drivers use DMA for this. +- in dom0, the Xorg server is started with *LD_PRELOAD*-ed library named *shmoverride.so*. This library hooks all function calls related to shared memory. +- *qubes_guid* creates a shared memory segment, and then tells Xorg to attach it via *MIT-SHM* extension +- when Xorg tries to attach the segment (via glibc *shmat*) *shmoverride.so* intercepts this call and instead maps AppVM memory via *xc_map_foreign_pages* +- since then, we can use MIT-SHM functions, e.g. *XShmPutImage* to draw onto a dom0 window. *XShmPutImage* will paint with DRAM speed; actually, many drivers use DMA for this. The important detail is that *xc_map_foreign_pages* verifies that a given mfn range actually belongs to a given domain id (and the latter is provided by trusted *qubes_guid*). Therefore, rogue AppVM cannot gain anything by passing crafted mnfs in the `MFNDUMP` message. To sum up, this solution has the following benefits: -- window updates at DRAM speed -- no changes to Xorg code -- minimal size of the supporting code +- window updates at DRAM speed +- no changes to Xorg code +- minimal size of the supporting code ![gui.png](/attachment/wiki/GUIdocs/gui.png) @@ -83,9 +83,9 @@ Clipboard sharing implementation Certainly, it would be insecure to allow AppVM to read/write the clipboards of other AppVMs unconditionally. Therefore, the following mechanism is used: -- there is a "qubes clipboard" in dom0 - its contents are stored in a regular file in dom0. -- if the user wants to copy local AppVM clipboard to qubes clipboard, she must focus on any window belonging to this AppVM, and press **Ctrl-Shift-C**. This combination is trapped by *qubes-guid*, and `CLIPBOARD_REQ` message is sent to AppVM. *qubes-gui* responds with *CLIPBOARD_DATA* message followed by clipboard contents. -- the user focuses on other AppVM window, presses **Ctrl-Shift-V**. This combination is trapped by *qubes-guid*, and `CLIPBOARD_DATA` message followed by qubes clipboard contents is sent to AppVM; *qubes_gui* copies data to the local clipboard, and then user can paste its contents to local applications normally. +- there is a "qubes clipboard" in dom0 - its contents are stored in a regular file in dom0. +- if the user wants to copy local AppVM clipboard to qubes clipboard, she must focus on any window belonging to this AppVM, and press **Ctrl-Shift-C**. This combination is trapped by *qubes-guid*, and `CLIPBOARD_REQ` message is sent to AppVM. *qubes-gui* responds with *CLIPBOARD_DATA* message followed by clipboard contents. +- the user focuses on other AppVM window, presses **Ctrl-Shift-V**. This combination is trapped by *qubes-guid*, and `CLIPBOARD_DATA` message followed by qubes clipboard contents is sent to AppVM; *qubes_gui* copies data to the local clipboard, and then user can paste its contents to local applications normally. This way, the user can quickly copy clipboards between AppVMs. This action is fully controlled by the user, it cannot be triggered/forced by any AppVM. @@ -95,8 +95,8 @@ This action is fully controlled by the user, it cannot be triggered/forced by an Both applications are structured similarly. They use *select* function to wait for any of these two event sources: -- messages from the local X server -- messages from the vchan connecting to the remote party +- messages from the local X server +- messages from the vchan connecting to the remote party The XEvents are handled by the *handle_xevent_eventname* function, and messages are handled by *handle_messagename* function. One should be very careful when altering the actual *select* loop, because both XEvents and vchan messages are buffered, and *select* will not wake for each message. @@ -117,7 +117,7 @@ Window manager hints and flags are described in the [Extended Window Manager Hin Each message starts with the following header: -~~~ +```c struct msghdr { uint32_t type; uint32_t window; @@ -128,7 +128,7 @@ struct msghdr { * whatever it wants! */ uint32_t untrusted_len; }; -~~~ +``` This header is followed by message-specific data: @@ -281,12 +281,12 @@ Proper handling of the below messages is NOT security-critical. Each message starts with the following header -~~~ +```c struct msghdr { uint32_t type; uint32_t window; }; -~~~ +``` The header is followed by message-specific data: diff --git a/en/_doc/developer/system/networking.md b/en/_doc/developer/system/networking.md index 936744602b..0669a526fd 100644 --- a/en/_doc/developer/system/networking.md +++ b/en/_doc/developer/system/networking.md @@ -11,18 +11,15 @@ ref: 59 title: Networking --- -VM network in Qubes -=================== +# VM network in Qubes -Overall description -------------------- +## Overall description In Qubes, the standard Xen networking is used, based on backend driver in the driver domain and frontend drivers in VMs. In order to eliminate layer 2 attacks originating from a compromised VM, routed networking is used instead of the default bridging of `vif` devices and NAT is applied at each network hop. The default *vif-route* script had some deficiencies (requires `eth0` device to be up, and sets some redundant iptables rules), therefore the custom *vif-route-qubes* script is used. The IP address of `eth0` interface in AppVM, as well as two IP addresses to be used as nameservers (`DNS1` and `DNS2`), are passed via QubesDB to AppVM during its boot (thus, there is no need for DHCP daemon in the network driver domain). `DNS1` and `DNS2` are private addresses; whenever an interface is brought up in the network driver domain, the */usr/lib/qubes/qubes\_setup\_dnat\_to\_ns* script sets up the DNAT iptables rules translating `DNS1` and `DNS2` to the newly learned real dns servers. This way AppVM networking configuration does not need to be changed when configuration in the network driver domain changes (e.g. user switches to a different WLAN). Moreover, in the network driver domain, there is no DNS server either, and consequently there are no ports open to the VMs. -Routing tables examples ------------------------ +## Routing tables examples VM routing table is simple: @@ -42,18 +39,21 @@ Network driver domain routing table is a bit longer: |192.168.0.0|0.0.0.0|255.255.255.0|U|1|0|0|eth0| |0.0.0.0|192.168.0.1|0.0.0.0|UG|0|0|0|eth0| -IPv6 ----- +## IPv6 Starting with Qubes 4.0, there is opt-in support for IPv6 forwarding. Similar to the IPv4, traffic is routed and NAT is applied at each network gateway. This way we avoid reconfiguring every connected qube whenever uplink connection is changed, and even telling the qube what that uplink is - which may be complex when VPN or other tunneling services are employed. The feature can be enabled on any network-providing qube, and will be propagated down the network tree, so every qube connected to it will also have IPv6 enabled. To enable the `ipv6` feature use `qvm-features` tool and set the value to `1`. For example to enable it on `sys-net`, execute in dom0: +``` qvm-features sys-net ipv6 1 +``` It is also possible to explicitly disable IPv6 support for some qubes, even if it is connected to IPv6-providing one. This can be done by setting `ipv6` feature to empty value: +``` qvm-features ipv4-only-qube ipv6 '' +``` This configuration is presented below - green qubes have IPv6 access, red one does not. @@ -66,7 +66,7 @@ Such configuration can be expressed by enabling `ipv6` feature only on some subs Besides enabling IPv6 forwarding, standard Qubes firewall can be used to limit what network resources are available to each qube. Currently only `qvm-firewall` command support adding IPv6 rules, GUI firewall editor will have this ability later. -### Limitations ### +### Limitations Currently only IPv4 DNS servers are configured, regardless of `ipv6` feature state. It is done this way to avoid reconfiguring all connected qubes whenever IPv6 DNS becomes available or not. Configuring qubes to always use IPv6 DNS and only fallback to IPv4 may result in relatively long timeouts and poor usability. But note that DNS using IPv4 does not prevent to return IPv6 addresses. In practice this is only a problem for IPv6-only networks. diff --git a/en/_doc/developer/system/security-critical-code.md b/en/_doc/developer/system/security-critical-code.md index 9adf926be9..a266a5dcc5 100644 --- a/en/_doc/developer/system/security-critical-code.md +++ b/en/_doc/developer/system/security-critical-code.md @@ -23,20 +23,18 @@ The size of the current TCB is on the order order of hundreds of thousands of li For more information, see [Qubes Security Goals]. - Security-critical Qubes-specific Components ------------------------------------------- The following code components are security-critical in Qubes OS: - - Dom0-side of the libvchan library - - Dom0-side of the GUI virtualization code (`qubes-guid`) - - Dom0-side of the sound virtualization code (`pacat-simple-vchan`) - - Dom0-side in qrexec-related code (`qrexec_daemon`) - - VM memory manager (`qmemman`) that runs in Dom0 - - Select Qubes RPC servers that run in Dom0: `qubes.ReceiveUpdates` and `qubes.SyncAppMenus` - - The `qubes.Filecopy` RPC server that runs in a VM (critical because it could allow one VM to compromise another if the user allows a file copy operation to be performed between them) - +- Dom0-side of the libvchan library +- Dom0-side of the GUI virtualization code (`qubes-guid`) +- Dom0-side of the sound virtualization code (`pacat-simple-vchan`) +- Dom0-side in qrexec-related code (`qrexec_daemon`) +- VM memory manager (`qmemman`) that runs in Dom0 +- Select Qubes RPC servers that run in Dom0: `qubes.ReceiveUpdates` and `qubes.SyncAppMenus` +- The `qubes.Filecopy` RPC server that runs in a VM (critical because it could allow one VM to compromise another if the user allows a file copy operation to be performed between them) Security-critical Third-party Components ---------------------------------------- @@ -44,26 +42,24 @@ Security-critical Third-party Components We did not create these components, but Qubes OS relies on them. At the current stage of the project, we cannot afford to spend the time to thoroughly review and audit them, so we more or less "blindly" trust that they are secure. - - The Xen hypervisor - - Xen's xenstore backend running in Dom0 - - Xen's block backend running in Dom0's kernel - - The RPM program used in Dom0 for verifying signatures on dom0 updates - - Somewhat trusted: log viewing software in dom0 that parses VM-influenced logs - +- The Xen hypervisor +- Xen's xenstore backend running in Dom0 +- Xen's block backend running in Dom0's kernel +- The RPM program used in Dom0 for verifying signatures on dom0 updates +- Somewhat trusted: log viewing software in dom0 that parses VM-influenced logs Attacks on Networking Components -------------------------------- Here are two examples of networking components that an adversary might seek to attack (or in which to exploit a vulnerability as part of an attack): - - Xen network PV frontends - - VMs' core networking stacks (core TCP/IP code) +- Xen network PV frontends +- VMs' core networking stacks (core TCP/IP code) Hypothetically, an adversary could compromise a NetVM, `sys-net-1`, and try to use it to attack the VMs connected to that NetVM. However, Qubes allows for the existence of more than one NetVM, so the adversary would not be able to use `sys-net-1` in order to attack VMs connected to a *different* NetVM, `sys-net-2` without also compromising `sys-net-2`. In addition, the adversary would not be able to use `sys-net-1` (or, for that matter, `sys-net-2`) to attack VMs that have networking disabled (i.e., VMs that are not connected to any NetVM). - Buggy Code vs. Backdoored Code ------------------------------ @@ -76,7 +72,6 @@ This means that we must trust at least some of the vendors that supply the code In practice, we trust the software provided by the [Fedora Project]. This software is signed by Fedora distribution keys, so it is also critical that the tools used in domains for software updates (`dnf` and `rpm`) are trustworthy. - [Qubes Security Goals]: /security/goals/ [Fedora Project]: https://getfedora.org/ [Understanding and Preventing Data Leaks]: /doc/data-leaks/ diff --git a/en/_doc/developer/system/storage-pools.md b/en/_doc/developer/system/storage-pools.md index 70c30d3d3b..1bfcea3c9f 100644 --- a/en/_doc/developer/system/storage-pools.md +++ b/en/_doc/developer/system/storage-pools.md @@ -34,7 +34,6 @@ When installed, the system has, as you can see from the contents of default pool is special in R3.2. It will add `dir_path=/var/lib/qubes` configuration value from `defaults[pool_config]`, if not overwritten. - Currently the only supported driver out of the box is `xen`. The benefit of pools (besides that you can write your own storage driver e.g. for Btrfs) in R3.2 is that you can store your domains in multiple places. diff --git a/en/_doc/developer/system/template-implementation.md b/en/_doc/developer/system/template-implementation.md index b1bd137444..42904368b4 100644 --- a/en/_doc/developer/system/template-implementation.md +++ b/en/_doc/developer/system/template-implementation.md @@ -10,59 +10,54 @@ ref: 58 title: Template Implementation --- -Overview of VM block devices -============================ +# Overview of VM block devices Every VM has 4 block devices connected: -- **xvda** – base root device (/) – details described below -- **xvdb** – private.img – place where VM always can write. -- **xvdc** – volatile.img, discarded at each VM restart – here is placed swap and temporal "/" modifications (see below) -- **xvdd** – modules.img – kernel modules and firmware +- **xvda** – base root device (/) – details described below +- **xvdb** – private.img – place where VM always can write. +- **xvdc** – volatile.img, discarded at each VM restart – here is placed swap and temporal "/" modifications (see below) +- **xvdd** – modules.img – kernel modules and firmware -private.img (xvdb) ------------------- +## private.img (xvdb) This is mounted as /rw and here is placed all VM private data. This includes: -- */home* – which is bind mounted to /rw/home -- */usr/local* – which is symlink to /rw/usrlocal -- some config files (/rw/config) called by qubes core scripts (ex /rw/config/rc.local) +- */home* – which is bind mounted to /rw/home +- */usr/local* – which is symlink to /rw/usrlocal +- some config files (/rw/config) called by qubes core scripts (ex /rw/config/rc.local) **Note:** Whenever a TemplateBasedVM is created, the contents of the `/home` directory of its parent TemplateVM are copied to the child TemplateBasedVM's `/home`. From that point onward, the child TemplateBasedVM's `/home` is independent from its parent TemplateVM's `/home`, which means that any subsequent changes to the parent TemplateVM's `/home` will no longer affect the child TemplateBasedVM's `/home`. Once a TemplateBasedVM has been created, any changes in its `/home`, `/usr/local`, or `/rw/config` directories will be persistent across reboots, which means that any files stored there will still be available after restarting the TemplateBasedVM. No changes in any other directories in TemplateBasedVMs persist in this manner. If you would like to make changes in other directories which *do* persist in this manner, you must make those changes in the parent TemplateVM. -modules.img (xvdd) ------------------- +## modules.img (xvdd) As the kernel is chosen in dom0, there must be some way to provide matching kernel modules to VM. Qubes kernel directory consists of 3 files: -- *vmlinuz* – actual kernel -- *initramfs* – initial ramdisk containing script to setup snapshot devices (see below) and mount /lib/modules -- *modules.img* – filesystem image of /lib/modules with matching kernel modules and firmware (/lib/firmware/updates is symlinked to /lib/modules/firmware) +- *vmlinuz* – actual kernel +- *initramfs* – initial ramdisk containing script to setup snapshot devices (see below) and mount /lib/modules +- *modules.img* – filesystem image of /lib/modules with matching kernel modules and firmware (/lib/firmware/updates is symlinked to /lib/modules/firmware) Normally kernel "package" is common for many VMs (can be set using qvm-prefs). One of them can be set as default (qvm-set-default-kernel) to simplify kernel updates (by default all VMs use the default kernel). All installed kernels are placed in /var/lib/qubes/vm-kernels as separate subdirs. In this case, modules.img is attached to the VM as R/O device. There is a special case when the VM can have a custom kernel – when it is updateable (StandaloneVM or TemplateVM) and the kernel is set to "none" (by qvm-prefs). In this case the VM uses the kernel from the "kernels" VM subdir and modules.img is attached as R/W device. FIXME: "none" should be renamed to "custom". -Qubes TemplateVM implementation -=============================== +# Qubes TemplateVM implementation TemplateVM has a shared root.img across all AppVMs that are based on it. This mechanism has some advantages over a simple common device connected to multiple VMs: -- root.img can be modified while there are AppVMs running – without corrupting the filesystem -- multiple AppVMs that are using different versions of root.img (from various points in time) can be running concurrently +- root.img can be modified while there are AppVMs running – without corrupting the filesystem +- multiple AppVMs that are using different versions of root.img (from various points in time) can be running concurrently There are two layers of the device-mapper snapshot device; the first one enables modifying root.img without stopping the AppVMs and the second one, which is contained in the AppVM, enables temporal modifications to its filesystem. These modifications will be discarded after a restart of the AppVM. ![TemplateSharing2.png](/attachment/wiki/TemplateImplementation/TemplateSharing2.png) -Snapshot device in Dom0 ------------------------ +## Snapshot device in Dom0 This device consists of: -- root.img – real template filesystem -- root-cow.img – differences between the device as seen by AppVM and the current root.img +- root.img – real template filesystem +- root-cow.img – differences between the device as seen by AppVM and the current root.img The above is achieved through creating device-mapper snapshots for each version of root.img. When an AppVM is started, a xen hotplug script (/etc/xen/scripts/block-snapshot) reads the inode numbers of root.img and root-cow.img; these numbers are used as the snapshot device's name. When a device with the same name exists the new AppVM will use it – therefore, AppVMs based on the same version of root.img will use the same device. Of course, the device-mapper cannot use the files directly – it must be connected through /dev/loop\*. The same mechanism detects if there is a loop device associated with a file determined by the device and inode numbers – or if creating a new loop device is necessary. @@ -84,31 +79,29 @@ This is done using snapshot-merge device-mapper target (available from 2.6.34 ke Steps performed by **qvm-revert-template-changes**: -1. Ensure that no other VMs uses this template. -2. Prepare snapshot device with ***root-cow.img.old*** instead of *root-cow.img* (*/etc/xen/scripts/block-snapshot prepare*). -3. Replace *snapshot* device-mapper target with *snapshot-merge*, other parameters (chunk size etc) remains untouched. Now kernel starts merging changes stored in *root-cow.img.old* into *root.img*. d-m device can be used normally (if needed). -4. Waits for merge completed: *dmsetup status* shows used snapshot blocks – it should be equal to metadata size when completed. -5. Replace *snapshot-merge* d-m target back to *snapshot*. -6. Cleanup snapshot device (if nobody uses it at the moment). -7. Move *root-cow.img.old* to *root-cow.img* (overriding existing file). +1. Ensure that no other VMs uses this template. +2. Prepare snapshot device with ***root-cow.img.old*** instead of *root-cow.img* (*/etc/xen/scripts/block-snapshot prepare*). +3. Replace *snapshot* device-mapper target with *snapshot-merge*, other parameters (chunk size etc) remains untouched. Now kernel starts merging changes stored in *root-cow.img.old* into *root.img*. d-m device can be used normally (if needed). +4. Waits for merge completed: *dmsetup status* shows used snapshot blocks – it should be equal to metadata size when completed. +5. Replace *snapshot-merge* d-m target back to *snapshot*. +6. Cleanup snapshot device (if nobody uses it at the moment). +7. Move *root-cow.img.old* to *root-cow.img* (overriding existing file). -Snapshot device in AppVM ------------------------- +## Snapshot device in AppVM Root device is exposed to AppVM in read-only mode. AppVM can write only in: -- private.img – persistent storage (mounted in /rw) used for /home, /usr/local – in future versions, its use may be extended -- volatile.img – temporary storage, which is discarded after an AppVM restart +- private.img – persistent storage (mounted in /rw) used for /home, /usr/local – in future versions, its use may be extended +- volatile.img – temporary storage, which is discarded after an AppVM restart volatile.img is divided into two partitions: -1. changes to root device -2. swap partition +1. changes to root device +2. swap partition Inside of an AppVM, the root device is wrapped by the snapshot in the first partition of volatile.img. Therefore, the AppVM can write anything to its filesystem – however, such changes will be discarded after a restart. -StandaloneVM ------------- +## StandaloneVM Standalone VM enables user to modify root filesystem persistently. It can be created using *--standalone* switch to *qvm-create*. From f2627eadb6fe6ee10f01fdde8bb0e4cf8e151b07 Mon Sep 17 00:00:00 2001 From: dd Date: Sun, 1 Nov 2020 03:14:15 +0100 Subject: [PATCH 072/663] minor lint one doc in developer/building --- en/_doc/developer/building/development-workflow.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/en/_doc/developer/building/development-workflow.md b/en/_doc/developer/building/development-workflow.md index 2bfc0b9502..ab70f1b3d6 100644 --- a/en/_doc/developer/building/development-workflow.md +++ b/en/_doc/developer/building/development-workflow.md @@ -149,14 +149,14 @@ RPMS will appear in qubes-src/linux-kernel/pkgs/fc20/x86\_64: ### Useful [QubesBuilder](/doc/qubes-builder/) commands -1. `make check` - will check if all the code was committed into repository and +1. `make check` - will check if all the code was committed into repository and if all repository are tagged with signed tag. -2. `make show-vtags` - show version of each component (based on git tags) - +2. `make show-vtags` - show version of each component (based on git tags) - mostly useful just before building ISO. **Note:** this will not show version for components containing changes since last version tag -3. `make push` - push change from **all** repositories to git server. You must +3. `make push` - push change from **all** repositories to git server. You must set proper remotes (see above) for all repositories first. -4. `make prepare-merge` - fetch changes from remote repositories (can be +4. `make prepare-merge` - fetch changes from remote repositories (can be specified on commandline via GIT\_SUBDIR or GIT\_REMOTE vars), (optionally) verify tags and show the changes. This do not merge the changes - there are left for review as FETCH\_HEAD ref. You can merge them using `git merge From 56ec6c2a0458e34afded621b54624093222059fe Mon Sep 17 00:00:00 2001 From: Enjeck Cleopatra <32180937+PROTechThor@users.noreply.github.com> Date: Sun, 1 Nov 2020 08:35:33 +0100 Subject: [PATCH 073/663] Update nvidia-troubleshooting.md --- external/troubleshooting/nvidia-troubleshooting.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/external/troubleshooting/nvidia-troubleshooting.md b/external/troubleshooting/nvidia-troubleshooting.md index 70dce1925d..ddd922f551 100644 --- a/external/troubleshooting/nvidia-troubleshooting.md +++ b/external/troubleshooting/nvidia-troubleshooting.md @@ -115,9 +115,9 @@ If you're seeing this error then that means another graphics card (most likely a nouveau.modeset=0 rd.driver.blacklist=nouveau video=vesa:off ~~~ - This will temporarily disable nouveau until next boot. + This will disable nouveau until the option is manually edited back to its original state. - 5. Press either the `Ctrl+X` keys, then `y` to save changes. + 5. Press the `Ctrl+X` keys, then `y` to save changes. 6. Reboot From cf04fba2228bff6c25ce0931eb7e2f50cabca03a Mon Sep 17 00:00:00 2001 From: Enjeck Cleopatra <32180937+PROTechThor@users.noreply.github.com> Date: Sun, 1 Nov 2020 14:50:05 +0100 Subject: [PATCH 074/663] Update vpn-troubleshooting.md --- user/troubleshooting/vpn-troubleshooting.md | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/user/troubleshooting/vpn-troubleshooting.md b/user/troubleshooting/vpn-troubleshooting.md index 5ea4cc12be..67882f7b17 100644 --- a/user/troubleshooting/vpn-troubleshooting.md +++ b/user/troubleshooting/vpn-troubleshooting.md @@ -8,7 +8,7 @@ permalink: /doc/vpn-troubleshooting/ ## Tips -* Check the VPN service's log in the VPN VM by running: +* If using qubes-vpn, check the VPN service's log in the VPN VM by running: ~~~ sudo journalctl -u qubes-vpn-handler ~~~ @@ -19,10 +19,13 @@ permalink: /doc/vpn-troubleshooting/ * Use `iptables -L -v` and `iptables -L -v -t nat` to check firewall rules. The latter shows the critical PR-QBS chain that enables DNS forwarding. ## VPN does not reconnect after suspend -After suspend/resume, your VPN may not automatically reconnect. In order to get it to work, you must kill your VPN system and restart it. + +This applies when using OpenVPN. + +After suspend/resume, OpenVPN may not automatically reconnect. In order to get it to work, you must kill the OpenVPN process and restart it. ## VPN stuck at "Ready to start link" -After setting up your VPN system and restarting the VM, you may be repeatedly getting the popup "Ready to start link", but the VPN isn't connected. +After setting up OpenVPN and restarting the VM, you may be repeatedly getting the popup "Ready to start link", but the VPN isn't connected. -To figure out the root of the problem, check the VPN logs in `/var/logs/syslog`. The log may reveal issues like missing libraries, which you can then install. +To figure out the root of the problem, check the VPN logs in `/var/logs/syslog`. The log may reveal issues like missing OpenVPN libraries, which you can then install. From fc0a6faf4a1f16ff52e63e346609a93396103fab Mon Sep 17 00:00:00 2001 From: dd Date: Mon, 2 Nov 2020 00:27:47 +0100 Subject: [PATCH 075/663] linted the docs of external building guides --- .../building-archlinux-template.md | 134 ++++++++++++------ .../building-non-fedora-template.md | 60 ++++---- .../building-whonix-template.md | 7 +- 3 files changed, 123 insertions(+), 78 deletions(-) diff --git a/en/_doc/external/building-guides/building-archlinux-template.md b/en/_doc/external/building-guides/building-archlinux-template.md index 8f9fe814e4..e0e685acc8 100644 --- a/en/_doc/external/building-guides/building-archlinux-template.md +++ b/en/_doc/external/building-guides/building-archlinux-template.md @@ -17,52 +17,63 @@ Archlinux template building instructions 1: Create and configure a qube for template building ------------------------------------------------------------ -* The qube should be based on a Fedora template. I named the qube - `build-archlinux2`, based on the minimal Fedora template. + +* The qube should be based on a Fedora template. I named the qube + `build-archlinux2`, based on the minimal Fedora template. ![arch-template-01](/attachment/wiki/ArchlinuxTemplate/arch-template-01.png) -* Ensure there is at least 15GB of free space in the private storage. +* Ensure there is at least 15GB of free space in the private storage. ![arch-template-02](/attachment/wiki/ArchlinuxTemplate/arch-template-02.png) - 2: Create GitHub Account (optional) ------------------------------------------- -* It can be helpful. Creating only a basic account is all that is needed. This will allow you to help, going forward, with the Qubes project. You could be help edit errors in documentation. It can also be of use building other templates. -* Create user account here https://github.com + +* It can be helpful. Creating only a basic account is all that is needed. This will allow you to help, going forward, with the Qubes project. You could be help edit errors in documentation. It can also be of use building other templates. +* Create user account [here](https://github.com) ![arch-template-03](/attachment/wiki/ArchlinuxTemplate/arch-template-03.png) 3: Install necessary packages to `build-archlinux2` qube for "Qubes Automated Build System" ----------------------------------------------------------------------------------------------- + ```shell_session # dnf install git make ``` 4: Downloading and verifying the integrity of the "Qubes Automated Build System" --------------------------------------------------------------------------------- + * Import the Qubes master key + ```shell_session $ gpg --import /usr/share/qubes/qubes-master-key.asc ``` + * Verify its fingerprint, set as 'trusted'. [This is described here](/doc/VerifyingSignatures). * Download the Qubes developers' keys. + ```shell_session $ wget https://keys.qubes-os.org/keys/qubes-developers-keys.asc $ gpg --import qubes-developers-keys.asc ``` * Download the latest stable qubes-builder repository: + ```shell_session $ git clone https://github.com/QubesOS/qubes-builder.git /home/user/qubes-builder/ ``` + * Verify the integrity of the downloaded repository. The last line should read `gpg: Good signature from`... + ```shell_session $ cd /home/user/qubes-builder/ $ git tag -v $(git describe) ``` + * Install the remaining dependencies + ```shell_session $ make install-deps ``` @@ -71,92 +82,99 @@ $ make install-deps ------------------------------------------------------------- ( The manual way would be to copy an example config like '**/home/user/qubes-builder/example-configs/qubes-os-r4.0.conf**' to '**/home/user/qubes-builder/builder.conf**' and edit the file ) -* Run the 'setup' script located in '**/home/user/qubes-builder/**' Make sure you are in directory '**qubes-builder**' + +* Run the 'setup' script located in '**/home/user/qubes-builder/**' Make sure you are in directory '**qubes-builder**' + ```shell_session $ cd /home/user/qubes-builder/ $ ./setup ``` + ![arch-template-04](/attachment/wiki/ArchlinuxTemplate/arch-template-04.png) * Install the missing dependencies ![arch-template-05](/attachment/wiki/ArchlinuxTemplate/arch-template-05.png) -* First screen will ask you to import 'Qubes-Master-Signing-key.asc'. The 'setup' script not only downloads but confirms the key to that of the key on Qubes-OS website. - * Select '**YES**' - * Select '**OK**' Press '**Enter**' +* First screen will ask you to import 'Qubes-Master-Signing-key.asc'. The 'setup' script not only downloads but confirms the key to that of the key on Qubes-OS website. + * Select '**YES**' + * Select '**OK**' Press '**Enter**' ![arch-template-06](/attachment/wiki/ArchlinuxTemplate/arch-template-06.png) -* Next screen will ask you to import Marek Marczykowski-Goracki (Qubes OS signing key). Again 'setup' will confirm this key to the fingerprint. - * Select '**YES**' - * Select '**OK**' Press '**Enter**' +* Next screen will ask you to import Marek Marczykowski-Goracki (Qubes OS signing key). Again 'setup' will confirm this key to the fingerprint. + * Select '**YES**' + * Select '**OK**' Press '**Enter**' ![arch-template-07](/attachment/wiki/ArchlinuxTemplate/arch-template-07.png) -* This screen will give you the choice of which Qubes Release to build the template for. - * Select '**Qubes Release 4.0**' - * Select '**OK**' Press '**Enter**' +* This screen will give you the choice of which Qubes Release to build the template for. + * Select '**Qubes Release 4.0**' + * Select '**OK**' Press '**Enter**' ![arch-template-08](/attachment/wiki/ArchlinuxTemplate/arch-template-08.png) -* Screen "**Choose Repos To Use To Build Packages**" - * Select 'QubesOS/qubes- Stable - Default Repo' - * Select '**OK**' Press '**Enter**' +* Screen "**Choose Repos To Use To Build Packages**" + * Select 'QubesOS/qubes- Stable - Default Repo' + * Select '**OK**' Press '**Enter**' - ![arch-template-09](/attachment/wiki/ArchlinuxTemplate/arch-template-09.png) * Screen "**Git Clone Faster**" - * Select '**OK**' Press '**Enter**' + * Select '**OK**' Press '**Enter**' ![arch-template-10](/attachment/wiki/ArchlinuxTemplate/arch-template-10.png) * Screen '**Choose Pre-Build Packages Repositories**' - * Select nothing, Press '**Enter**' + * Select nothing, Press '**Enter**' ![arch-template-11](/attachment/wiki/ArchlinuxTemplate/arch-template-11.png) -* Screen "**Build Template Only?**" - * Select '**Yes**' Press '**Enter**' +* Screen "**Build Template Only?**" + * Select '**Yes**' Press '**Enter**' ![arch-template-12](/attachment/wiki/ArchlinuxTemplate/arch-template-12.png) * Screen '**Template Distribution Selection**' will give choices of distributions to build - * Deselect everything - * Select '**archlinux**' + * Deselect everything + * Select '**archlinux**' ![arch-template-13](/attachment/wiki/ArchlinuxTemplate/arch-template-13.png) -* Screen '**Builder Plugin Selection**' will give choices of builder plugins to use for the build. - * Deselect everything - * Select '**builder-archlinux**' - * Select '**OK**' Press **Enter** +* Screen '**Builder Plugin Selection**' will give choices of builder plugins to use for the build. + * Deselect everything + * Select '**builder-archlinux**' + * Select '**OK**' Press **Enter** ![arch-template-14](/attachment/wiki/ArchlinuxTemplate/arch-template-14.png) -* Screen '**Get sources**' wants to download additional packages needed for the choosen plugin/s. - * Select '**Yes**' Press '**Enter**' +* Screen '**Get sources**' wants to download additional packages needed for the choosen plugin/s. + * Select '**Yes**' Press '**Enter**' ![arch-template-15](/attachment/wiki/ArchlinuxTemplate/arch-template-15.png) -* Then wait for download to finish and press '**OK**' +* Then wait for download to finish and press '**OK**' 6: Get all the require sources for the build ----------------------------------------------- + ```shell_session $ make get-sources ``` 7: Make all the require Qubes Components ------------------------------------------------ -* **Note:** You can run a single command to build all the Qubes components or you can run them each individually. - Both ways below: -* Single command to build all Qubes components together: (this command can take a long time to process depending of your pc proccessing power) + +* **Note:** You can run a single command to build all the Qubes components or you can run them each individually. + Both ways below: +* Single command to build all Qubes components together: (this command can take a long time to process depending of your pc proccessing power) + ```shell_session $ make qubes-vm ``` -* These are the indivual component 'make' commands: + +* These are the indivual component 'make' commands: + ```shell_session $ make vmm-xen-vm $ make core-vchan-xen-vm @@ -178,13 +196,16 @@ $ make app-linux-split-gpg-vm 8: Make the actual Archlinux template ---------------------------------------- + ```shell_session $ make template ``` 9: Transfer Template into Dom0 ---------------------------------- -* You need to ensure these two files are in the '**noarch**' directory + +* You need to ensure these two files are in the '**noarch**' directory + ```shell_session $ cd /home/user/qubes-builder/qubes-src/linux-template-builder/rpm/ $ ls @@ -196,18 +217,21 @@ qubes-template-archlinux-X.X.X-XXXXXXXXXXXX.noarch.rpm ![arch-template-16](/attachment/wiki/ArchlinuxTemplate/arch-template-16.png) -* **Transfer the install-templates.sh script file into Dom0** +* **Transfer the install-templates.sh script file into Dom0** *Note: as there is not a typical file transfer method for Dom0, for security reasons, this less than simple transfer function has to be used* - * Switch to Dom0 and open a terminal window. + * Switch to Dom0 and open a terminal window. + ```shell_session $ qvm-run --pass-io build-archlinux2 'cat /home/user/qubes-builder/qubes-src/linux-template-builder/rpm/install-templates.sh' > install-templates.sh $ chmod +x install-templates.sh $ ./install-templates.sh ``` + * If everything went correct there should be a Archlinux template listed in your Qubes Manager Debugging the build process =============================== + Archlinux use bleeding edge version of everything, so it is usually the first template to break when new software version came out. So an important point is to understand how to debug the template, how to fix @@ -217,11 +241,13 @@ it, and then do a pull request :). The most important part about this script is where to add custom code that is not in the QubesOS repositories After the command: + ```shell_session $ make get-sources ``` And before the command: + ```shell_session $ make qubes-vm ``` @@ -238,10 +264,13 @@ Example ----------------------- Launch the build + ```shell_session $ ./build_arch.sh ``` + It crash + ~~~~ Makefile:202: target 'builder-archlinux.get-sources' given more than once in the same rule Makefile:204: target 'builder-archlinux.get-sources-extra' given more than once in the same rule @@ -251,7 +280,9 @@ Makefile:585: target 'builder-archlinux.grep' given more than once in the same r -> Building template archlinux (logfile: build-logs/template-archlinux.log)... make: *** [Makefile:319: template-local-archlinux+minimal] Error 1 ~~~~ + Let's check '**build-logs/template-archlinux.log**' + ~~~~ --> Finishing installation of qubes packages... resolving dependencies... @@ -264,17 +295,20 @@ warning: cannot resolve "xorg-server<1.20.7", a dependency of "qubes-vm-gui" :: unable to satisfy dependency 'xorg-server<1.20.7' required by qubes-vm-gui make[1]: *** [Makefile:64: rootimg-build] Error 1 ~~~~ + The xorg-server package was probably updated to a version greater than 1.20.7. Let's search what is the current version of xorg-server... Currently, it is **1.20.7-1**. Nor a fix nor a minor version change is likely to break things. So let's find the dependency for "**xorg-server<1.20.7**" and change it to "**xorg-server<1.21**". + ```shell_session $ rg -iuu "xorg-server<1.20.7" ./qubes-builder/qubes-src/ 2> /dev/null ./qubes-builder/qubes-src/gui-agent-linux/archlinux/PKGBUILD -55: 'xorg-server>=1.20.4' 'xorg-server<1.20.7' +55: 'xorg-server>=1.20.4' 'xorg-server<1.20.7' ``` + So we need to modify the file **/archlinux/PKGBUILD** of the repository "qubes-gui-agent-linux". Let's clone "qubes-gui-agent-linux", be sure to checkout the correct @@ -288,11 +322,13 @@ Example, add this to the script $ rm -Rf "~/qubes-builder/qubes-src/gui-agent-linux/" $ cp -R ~/qubes-gui-agent-linux "~/qubes-builder/qubes-src/gui-agent-linux" ``` + and retry to build the template. If it build successfully and that the template work as expected, do a pull request on github to share your fix. Debugging the qube runtime ================================================================ + If you are able to launch a terminal and execute command, just use your usual archlinux-fu to fix the issue. If you are not able to launch a terminal, then, shutdown the qube, create a new @@ -303,11 +339,13 @@ reddit](https://old.reddit.com/r/Qubes/comments/eg50ne/built_arch_linux_template Question ------------------------------ + Hello. I just built archlinux template and moved to dom0 and installed the template. Then I tried to open a terminal in archlinux TemplateVM, but it shows nothing. Can you please check this logs and please tell me what is wrong. Thanks I searched the word 'Failed" and found few. + ~~~~ [0m] Failed to start..... Initialize and mount /rw and /home.... see 'systemctl status qubes-mount-dirs.service' for details [0m] Failed unmounting.... /usr/lib/modules.... @@ -320,24 +358,31 @@ failed to mount moving /run to /sysroot/dev: Invalid argument when I tried to run terminal, in log says audit: type=1131 audit(some number): pid=1 uid=0 auid=some number ses=some number msg='unit=systemd=tmpfiles-clean cmm="systemd" exe="/usr/lib/systemd" hostname=? addr=? terminal? res=success' ~~~~ + how can I debug this qube? Answer --------- + I tried to rebuild archlinux and got the same issue. The issue come from a systemd unit named "qubes-mount-dirs". We want to know more about that. We can't execute command into the qube, so let's shut it down. Then, we mount the archlinux root disk into a DisposableVM ( [mount_lvm_image.sh](https://github.com/Qubes-Community/Contents/blob/master/code/OS-administration/mount_lvm_image.sh) & [mount-lvm-image](https://www.qubes-os.org/doc/mount-lvm-image/) ) + ```shell_session $ ./mount_lvm_image.sh /dev/qubes_dom0/vm-archlinux-minimal-root fedora-dvm ``` + then in the newly created DisposableVM we mount the disk and chroot to it + ```shell_session # mount /dev/xvdi3 /mnt # chroot /mnt ``` + Then check the journal: + ~~~~ [root@disp9786 /]# journalctl -u qubes-mount-dirs -- Logs begin at Fri 2019-12-27 09:26:15 CET, end at Fri 2019-12-27 09:27:58 CET. -- @@ -377,11 +422,15 @@ Dec 27 09:26:54 archlinux systemd[1]: qubes-mount-dirs.service: Main process exi Dec 27 09:26:54 archlinux systemd[1]: qubes-mount-dirs.service: Failed with result 'exit-code'. Dec 27 09:26:54 archlinux systemd[1]: Failed to start Initialize and mount /rw and /home. ~~~~ + The most important line we saw is: + ~~~~ /usr/lib/qubes/init/setup-rwdev.sh: line 16: cmp: command not found ~~~~ + Let's check `setup-rwdev.sh`: + ~~~~ [root@disp9786 /]# cat /usr/lib/qubes/init/setup-rwdev.sh #!/bin/sh @@ -412,6 +461,7 @@ That is definitely something that we want to be working. So the binary `cmp` is ```shell_session # pacman -Fy cmp ``` + It is in `core/diffutils`, that, for some unknown reason, is not installed. Let's modify the archlinux template builder to add this package. Modify the files `qubes-builder/qubes-src/builder-archlinux/script/packages` to add the `diffutils`, and rebuild the template. Why this package was not installed in the first place? I am unsure. It could be that it was a dependency of the package `xf86dgaproto` that was removed few days ago, but I don't have the PKGBUILD of this package since it was deleted, so can't confirm. It can be something else too. @@ -453,11 +503,13 @@ Server = https://neowutran.ovh/qubes/vm-archlinux/pkgs About the package `qubes-vm-keyring` ===================================== + The goal of this package was to add a `pacman` source for the Qubes OS packages, and to set the maintainer gpg key as trusted. Currently, no one want to provide binary packages. **So this package is currently useless.** If in the future, enough people think it is better to restart providing binary packages instead of the current "Do It Yourself" way, the gpg key and fingerprint of the new maintainer should be added in the files below: + * https://github.com/QubesOS/qubes-core-agent-linux/blob/master/archlinux/PKGBUILD-keyring-keys * https://github.com/QubesOS/qubes-core-agent-linux/blob/master/archlinux/archlinux/PKGBUILD-keyring-trusted diff --git a/en/_doc/external/building-guides/building-non-fedora-template.md b/en/_doc/external/building-guides/building-non-fedora-template.md index 99e752e9df..a17f70ade9 100644 --- a/en/_doc/external/building-guides/building-non-fedora-template.md +++ b/en/_doc/external/building-guides/building-non-fedora-template.md @@ -10,8 +10,7 @@ ref: 117 title: Building Non-Fedora Template --- -Building a TemplateVM for a new OS -============================================================== +# Building a TemplateVM for a new OS If you don't like using one of the existing templates because of specific administration, package management or other building needs, you can build a TemplateVM for your distribution of choice. @@ -19,14 +18,12 @@ This article shows how to go about building a template for a different OS. You should make sure you understand the details of the BuilderPlugins API - they are explained [here][API]. -Qubes builder scripts -===================== +## Qubes builder scripts One way to start is by creating Qubes builder scripts for your new OS. Note that this will probably make your testing process harder than trying to build the package directly in an HVM on which you have already installed the new OS. -chroot initialization ---------------------- +## chroot initialization You need to customize some scripts that will be used to build all the Qubes tools. Create a new directory to hold the files for the new os. @@ -58,8 +55,7 @@ Then try to create (make) the template to check that at least these first two sc make linux-template-builder ~~~ -Qubes builder Makefiles ------------------------ +## Qubes builder Makefiles Now you need to create Makefiles specific to your OS. You will find the required scripts to adapt in the `builder-*` folders: @@ -75,47 +71,44 @@ The goal of this file is to prepare a development environment of your target OS You will reuse the `00_prepare.sh` and `01_install_core.sh` scripts. Additionally, the following things have to be done in this Makefile: -- the `$1` variable will contain the installation directory (`$INSTALLDIR` should contain the same value as `$1` when you run `00_prepare.sh` or `01_install_core.sh`) -- after your base system is installed, you should install development tools and libraries (gcc, make, ...) -- create a user called 'user' inside your chroot, and give them enough rights to run the command sudo without any password -- register all the repositories that will be necessary and synchronize the package database -- register a custom repository that will be used to store Qubes packages +- the `$1` variable will contain the installation directory (`$INSTALLDIR` should contain the same value as `$1` when you run `00_prepare.sh` or `01_install_core.sh`) +- after your base system is installed, you should install development tools and libraries (gcc, make, ...) +- create a user called 'user' inside your chroot, and give them enough rights to run the command sudo without any password +- register all the repositories that will be necessary and synchronize the package database +- register a custom repository that will be used to store Qubes packages ### Makefile.yourOSname This file will be used to define the action required when installing a custom package. The most important one are: -- `dist-prepare-chroot`: that's where you will call `prepare-chroot-yourOSname` if the chroot has not been initialized. -- `dist-package`: that's where you will chroot the development environment and run the command used to build a package. -- `dist-build-dep`: that's where you will create the custom repository for your target OS based on already compiled packages. +- `dist-prepare-chroot`: that's where you will call `prepare-chroot-yourOSname` if the chroot has not been initialized. +- `dist-package`: that's where you will chroot the development environment and run the command used to build a package. +- `dist-build-dep`: that's where you will create the custom repository for your target OS based on already compiled packages. These additional targets need to exist once you have created your first packages: -- `dist-copy-out`: that's where you will retrieve the package you just built and put it with all the other packages you prepared. -- `update-repo`: that's where you will retrieve the package that has been built and add it to the custom repository. +- `dist-copy-out`: that's where you will retrieve the package you just built and put it with all the other packages you prepared. +- `update-repo`: that's where you will retrieve the package that has been built and add it to the custom repository. ### Testing the development chroot You will be able to test these scripts when making the first Qubes packages. Don't forget that the first things that run when running `make somecomponent-vm` will be these two scripts, and that you will need to debug it at this point. -Qubes packages --------------- +## Qubes packages -* [vmm-xen](https://github.com/QubesOS/qubes-vmm-xen) -* [core-vchan-xen](https://github.com/QubesOS/qubes-core-vchan-xen) -* [linux-utils](https://github.com/QubesOS/qubes-linux-utils) -* [core-agent-linux](https://github.com/QubesOS/qubes-core-agent-linux) -* [gui-common](https://github.com/QubesOS/qubes-gui-common) -* [gui-agent-linux](https://github.com/QubesOS/qubes-gui-agent-linux) +- [vmm-xen](https://github.com/QubesOS/qubes-vmm-xen) +- [core-vchan-xen](https://github.com/QubesOS/qubes-core-vchan-xen) +- [linux-utils](https://github.com/QubesOS/qubes-linux-utils) +- [core-agent-linux](https://github.com/QubesOS/qubes-core-agent-linux) +- [gui-common](https://github.com/QubesOS/qubes-gui-common) +- [gui-agent-linux](https://github.com/QubesOS/qubes-gui-agent-linux) -Additional Installation scripts -------------------------------- +## Additional Installation scripts Again you need to create new scripts based on the existing scripts in these folders: - ~~~ builder-archlinux/scripts builder-debian/template-debian @@ -135,15 +128,14 @@ Also you need to edit the fstab file of your template to mount Qubes virtual har This script is used to finalize and to remove unnecessary things from your template, such as cached packages, unused development packages ... -Starting with an HVM -==================== +# Starting with an HVM If no Qubes packages are available for your selected OS you could start by installing your OS in an HVM. Your goals will be: -- to identify how to install the OS using command lines -- to create required Qubes packages -- to identify potential issues, making sure all Qubes agents and scripts work correctly. +- to identify how to install the OS using command lines +- to create required Qubes packages +- to identify potential issues, making sure all Qubes agents and scripts work correctly. As soon as you manage to get `qrexec` and `qubes-gui-agent` working, you will be ready to start preparing a template VM. diff --git a/en/_doc/external/building-guides/building-whonix-template.md b/en/_doc/external/building-guides/building-whonix-template.md index 4ee9f4ff7e..52304af61e 100644 --- a/en/_doc/external/building-guides/building-whonix-template.md +++ b/en/_doc/external/building-guides/building-whonix-template.md @@ -43,6 +43,7 @@ Once it completes downloading, re-run `setup` to add the Whonix templates: # whonix-gateway-14, whonix-workstation-14 # If prompted, choose Yes to add adrelanos's third party key ~~~ + Continue the build process with: ~~~ @@ -76,11 +77,11 @@ You can add/edit the `WHONIX_TBB_VERSION` variable in `~/qubes-builder/builder.c Finally, use: -~~~ +``` make qubes-vm make template -~~~ - +``` + Once the build is complete, the install packages for your newly built templates will be located in `~/qubes-builder/qubes-src/linux-template-builder/rpm/noarch`. Copy them from there to dom0 and install: From dc0cc955ac630f00ca05d8a8274987a030459e5e Mon Sep 17 00:00:00 2001 From: dd Date: Mon, 2 Nov 2020 00:29:25 +0100 Subject: [PATCH 076/663] linted the docs of external conf guides --- .../configuration-guides/change-time-zone.md | 4 ++ .../configuration-guides/disk-trim.md | 26 +++++------ .../configuration-guides/external-audio.md | 9 ++-- .../configuration-guides/multiboot.md | 6 --- .../configuration-guides/multimedia.md | 21 ++++++--- en/_doc/external/configuration-guides/mutt.md | 10 ++++- .../network-bridge-support.md | 20 ++++----- .../configuration-guides/network-printer.md | 10 ++--- .../external/configuration-guides/postfix.md | 12 ++---- .../configuration-guides/tips-and-tricks.md | 5 +++ en/_doc/external/configuration-guides/vpn.md | 38 ++++++++-------- en/_doc/external/configuration-guides/w3m.md | 16 ++++--- en/_doc/external/configuration-guides/zfs.md | 43 +++++++------------ 13 files changed, 113 insertions(+), 107 deletions(-) diff --git a/en/_doc/external/configuration-guides/change-time-zone.md b/en/_doc/external/configuration-guides/change-time-zone.md index 7bdd5f8635..3e453e3813 100644 --- a/en/_doc/external/configuration-guides/change-time-zone.md +++ b/en/_doc/external/configuration-guides/change-time-zone.md @@ -19,7 +19,9 @@ zone in terminal you can issue the `timedatectl` command with the option For example, to set the system's time zone to Berlin, Germany type in a dom0 terminal: +```shwll_session $ sudo timedatectl set-timezone 'Europe/Berlin' +``` You can list the available time zones with the option `list-timezones` and show the current settings of the system clock and time zone with option `status`. @@ -27,6 +29,7 @@ the current settings of the system clock and time zone with option `status`. Example output status of `timedatectl` on a system with time zone set to Europe/Berlin: +```shell_session [user@dom0 ~]$ timedatectl status Local time: Sun 2018-10-14 06:20:00 CEST Universal time: Sun 2018-10-14 04:20:00 UTC @@ -35,3 +38,4 @@ Europe/Berlin: Network time on: no NTP synchronized: no RTC in local TZ: no +``` diff --git a/en/_doc/external/configuration-guides/disk-trim.md b/en/_doc/external/configuration-guides/disk-trim.md index 66b7afdc14..32c3b71f9c 100644 --- a/en/_doc/external/configuration-guides/disk-trim.md +++ b/en/_doc/external/configuration-guides/disk-trim.md @@ -23,22 +23,23 @@ When instructed by the operating system, discards are issued by the file-system In Qubes, this gets more complex due to virtualization, LUKS, and LVM (and thin pools on R4.0 and up). If you run `fstrim --all` inside a TemplateVM, in a worst case the `discard` can follow a path like: - OS -> File-system Driver -> Virtual Storage Driver -> Backend Storage Driver -> LVM Storage Driver -> LUKS Driver -> Physical Storage Driver -> Physical Storage Device - +``` +OS -> File-system Driver -> Virtual Storage Driver -> Backend Storage Driver -> LVM Storage Driver -> LUKS Driver -> Physical Storage Driver -> Physical Storage Device +``` + If discards are not supported at any one of those layers, it will not make it to the underlying physical device. There are some security implications to permitting TRIM (read for example [this article](https://asalor.blogspot.com/2011/08/trim-dm-crypt-problems.html)), but in most cases not exploitable. Conversely, TRIM can improve security against local forensics when using SSDs, because with TRIM enabled deleting data (usually) results in the actual data being erased quickly, rather than remaining in unallocated space indefinitely. However deletion is not guaranteed, and can fail to happen without warning for a variety of reasons. - Configuration ---------- In all versions of Qubes, you may want to set up a periodic job in `dom0` to trim the disk. This can be done with either systemd (weekly only) or cron (daily or weekly). - * **Systemd** +* **Systemd** From a terminal as a regular user: @@ -47,7 +48,7 @@ This can be done with either systemd (weekly only) or cron (daily or weekly). systemctl start fstrim.timer ``` - * **Cron** +* **Cron** This can be done from a terminal as root, by creating a `trim` file in `/etc/cron.daily` (or `/etc/cron.weekly`). Add the following contents: @@ -56,6 +57,7 @@ This can be done with either systemd (weekly only) or cron (daily or weekly). #!/bin/bash /sbin/fstrim --all ``` + And mark it as executable with `chmod 755 /etc/cron.daily/trim`. **Note** Although discards can be issued on every delete inside `dom0` by adding the `discard` mount option to `/etc/fstab`, this option can hurt performance so the above procedure is recommended instead. @@ -66,7 +68,6 @@ Setting this option will permit LVM to issue discards to the SSD when logical vo In R4.x, LVM Logical volumes are frequently deleted (every time a disposable VM is shut down, for example) so you may want to set `issue_discards = 1` if using an SSD, but see the article linked in the first section of this page. However, this is relatively rare in R3.x. - LUKS ---------- @@ -87,17 +88,16 @@ To enable TRIM support in dom0 with LUKS you need to: ~~~ 3. Add `rd.luks.options=discard` to kernel cmdline (follow either GRUB2 or EFI, not both): - * GRUB2: `/etc/default/grub`, `GRUB_CMDLINE_LINUX` line and - Rebuild grub config (`grub2-mkconfig -o /boot/grub2/grub.cfg`), then - Rebuild initrd (`dracut -f`) - * EFI: `/boot/efi/EFI/qubes/xen.cfg`, `kernel=` line(s), then - Rebuild initrd (`dracut -f /boot/efi/EFI/qubes/initramfs-$(uname -r).img $(uname -r)`) + * GRUB2: `/etc/default/grub`, `GRUB_CMDLINE_LINUX` line and + Rebuild grub config (`grub2-mkconfig -o /boot/grub2/grub.cfg`), then + Rebuild initrd (`dracut -f`) + * EFI: `/boot/efi/EFI/qubes/xen.cfg`, `kernel=` line(s), then + Rebuild initrd (`dracut -f /boot/efi/EFI/qubes/initramfs-$(uname -r).img $(uname -r)`) 4. Reboot the system. 5. To verify if discards are enabled you may use `dmsetup table` (confirm the line for your device mentions "discards") or just run `fstrim -av` (you should see a `/` followed by the number of bytes trimmed). - Swap Space ---------- @@ -109,6 +109,8 @@ If you only want the security against local forensics benefit of TRIM, you can u To verify that TRIM is enabled, check `dmesg` for what flags were enabled when the swap space was activated. You should see something like the following: +``` Adding 32391164k swap on /dev/mapper/qubes_dom0-swap. Priority:-2 extents:1 across:32391164k SSDscFS +``` The `s` indicates that the entire swap device will be trimmed at boot, and `c` indicates that individual pages are trimmed after they are no longer being used. diff --git a/en/_doc/external/configuration-guides/external-audio.md b/en/_doc/external/configuration-guides/external-audio.md index 029c9d6f40..a6a7e85246 100644 --- a/en/_doc/external/configuration-guides/external-audio.md +++ b/en/_doc/external/configuration-guides/external-audio.md @@ -10,11 +10,9 @@ ref: 100 title: External Audio --- -Using External Audio Devices -============================ +# Using External Audio Devices -Why you want to use external audio devices ------------------------------------------- +## Why you want to use external audio devices Qubes audio virtualization protocol does not implement latency reporting for security reasons, keeping the protocol as simple as possible. Also, in a compromise between low latency and low CPU usage, latency may be around 200 ms. @@ -22,8 +20,7 @@ So applications demanding higher audio quality (even Skype) need a better enviro But Qubes flexibility fully allows that using external audio devices. These are mostly USB audio cards, but firewire devices also might be used. -Implementing external audio devices ------------------------------------ +## Implementing external audio devices First you need to identify an user VM dedicated to audio and [assign a device](/doc/AssigningDevices) to it. In the most common case the assigned device is the USB controller to which your USB audio card will be connected. diff --git a/en/_doc/external/configuration-guides/multiboot.md b/en/_doc/external/configuration-guides/multiboot.md index ce411572c7..20e97c2e3e 100644 --- a/en/_doc/external/configuration-guides/multiboot.md +++ b/en/_doc/external/configuration-guides/multiboot.md @@ -54,8 +54,6 @@ The general approach is: * Manually add boot stanzas to /etc/grub.d/40_custom * Update grub - - Windows ---------------------- @@ -113,7 +111,6 @@ menuentry "Windows" { (Change `X` to reflect the relevant system partition.) - Linux ---------------------- @@ -144,7 +141,6 @@ sudo grub2-mkconfig -o /boot/grub2/grub.cfg There is no need to reinstall grub itself. - Existing /boot partition, grub installed in MBR ---------------------- @@ -171,8 +167,6 @@ Then update the grub config: sudo grub2-mkconfig -o /boot/grub2/grub.cfg ~~~ - - Troubleshooting ---------------------- diff --git a/en/_doc/external/configuration-guides/multimedia.md b/en/_doc/external/configuration-guides/multimedia.md index 6167dedf33..b7f1455023 100644 --- a/en/_doc/external/configuration-guides/multimedia.md +++ b/en/_doc/external/configuration-guides/multimedia.md @@ -59,19 +59,21 @@ Import GPG-Key for spotify As the template VM can't connect to internet you need to get the public key file from another AppVM and copy it to the template VM. The easiest way is to use the Qubes Clipboard to copy the keys from the AppVM where you get the key to the Template VM. In an AppVM which has Internet access: + - Open - Copy content of page to the Clipboard (Ctrl+A and Ctrl+C) - open a Terminal in this AppVM and copy the content of the clipboard to a file `xclip -o > spotify.pubkey` Copy the public signing key over to the multimedia template VM + - copy the file via `qvm-copy-to-vm t-multimedia spotify.pubkey` - or create a new file on the Template VM and copy the content of the clipboard (the public key) Copy content of page to the Qubes Clipboard (Ctrl+C and then Shift+Ctrl+C) Switch to the gnome terminal in the Multimedia Template VM `nano spotify.pubkey` Paste the content from the Qubes Clipboard into nano (Shift+Ctrl+V and then Paste) - Save the file (Ctrl+O Ctrl+X) + Save the file (`Ctrl+O Ctrl+X`) Check the signature of the signing key (in the multimedia Template VM). Hint: depending on your installed version of GnuPG the command to show a public might slightly be different. @@ -82,11 +84,13 @@ If this command doesn't show a fingerprint choose one of the other commands ment This should look like: +```shell_session [user@t-multimedia ~]$ `gpg --with-fingerprint spotify.pubkey` pub 4096R/130D1D45 2019-07-15 Spotify Public Repository Signing Key Key fingerprint = 2EBF 997C 15BD A244 B6EB F5D8 4773 BD5E 130D 1D45 +``` You can (and should) lookup the fingerprint on at least one (or more) keyservers as the above information might be outdated. @@ -112,7 +116,6 @@ Create a spotify desktop-entry `cp /usr/share/spotify/icons/spotify-linux-16.png /usr/share/icons/hicolor/16x16/apps/spotify.png` - Installation of VLC ------------------- @@ -120,18 +123,20 @@ To play DVDs you can install VLC with the needed Codecs Download the public key which signs the VLC package repositories In an AppVM which has Internet access: + - Open - Repeat all steps to save the public signing key on the AppVM (see above / Spotify example) `xclip -o > videolan.pubkey` Copy the public signing key over to the multimedia template VM + - copy the file via `qvm-copy-to-vm t-multimedia videolan.pubkey` - or create a new file on the Template VM and copy the content of the clipboard (the public key) Copy content of page to the Qubes Clipboard (Ctrl+C and then Shift+Ctrl+C) Switch to the gnome terminal in the Multimedia Template VM `nano videolan.pubkey` Paste the content from the Qubes Clipboard into nano (Shift+Ctrl+V and then Paste) - Save the file (Ctrl+O Ctrl+X) + Save the file (`Ctrl+O Ctrl+X`) Check the signature of the signing key @@ -139,6 +144,7 @@ Check the signature of the signing key This should look like: +```shell_session [user@t-multimedia ~]$ `gpg --with-fingerprint videolan.pubkey` pub 2048R/B84288D9 2013-08-27 VideoLAN APT Signing Key @@ -146,6 +152,7 @@ This should look like: Key fingerprint = 8F08 45FE 77B1 6294 429A 7934 6BCA 5E4D B842 88D9 sub 2048R/288D4A2C 2013-08-27 +``` You can (and should) lookup the fingerprint on at least one (or more) keyservers as the above information might be outdated. @@ -168,7 +175,6 @@ Install libdvdcss and VLC `apt-get install -y libdvdcss2 vlc` - Installation Google Chrome -------------------------- @@ -177,18 +183,20 @@ Hint: Using Chromium will not work for some reasons. Download the public key which signs the Google package repositories In an AppVM which has Internet access: + - Open - Repeat all steps to save the public signing key on the AppVM (see above / Spotify example) `xclip -o > google.pubkey` Copy the public signing key over to the multimedia template VM + - copy the file via `qvm-copy-to-vm t-multimedia google.pubkey` - or create a new file on the Template VM and copy the content of the clipboard (the public key) Copy content of page to the Qubes Clipboard (Ctrl+C and then Shift+Ctrl+C) Switch to the gnome terminal in the Multimedia Template VM `nano google.pubkey` Paste the content from the Qubes Clipboard into nano (Shift+Ctrl+V and then Paste) - Save the file (Ctrl+O Ctrl+X) + Save the file (`Ctrl+O Ctrl+X`) Check the signature of the signing key (still in the AppVM where you downloaded the key) @@ -196,6 +204,7 @@ Check the signature of the signing key (still in the AppVM where you downloaded This should look like: +```shell_session [user@t-multimedia ~]$ `gpg --with-fingerprint google.pubkey` pub 4096R/D38B4796 2016-04-12 Google Inc. (Linux Packages Signing Authority) @@ -207,6 +216,7 @@ This should look like: sub 4096R/640DB551 2016-04-12 [expires: 2019-04-12] sub 4096R/997C215E 2017-01-24 [expires: 2020-01-24] +``` You can (and should) lookup the fingerprint on at least one (or more) keyservers as the above information might be outdated. @@ -232,7 +242,6 @@ Install Chrome `apt-get install google-chrome-stable` - Create a Multimedia AppVM ------------------------- diff --git a/en/_doc/external/configuration-guides/mutt.md b/en/_doc/external/configuration-guides/mutt.md index 3805410483..d903c638b8 100644 --- a/en/_doc/external/configuration-guides/mutt.md +++ b/en/_doc/external/configuration-guides/mutt.md @@ -159,6 +159,7 @@ Some additional useful settings In `muttrc`: +``` ###qubes integration stuff #open links in a dispvm using urlview @@ -170,9 +171,11 @@ In `muttrc`: set mailcap_path=~/.mailcap bind attach view-mailcap +``` Debian-specific options: +``` #use debian mutt-patched package for mailbox sidebar hack set sidebar_width = 30 set sidebar_visible = no @@ -188,18 +191,20 @@ Debian-specific options: bind index CO sidebar-open bind pager CP sidebar-prev bind pager CN sidebar-next - +``` In `.urlview`: +``` ### TODO: this doesn't work with encrypted emails -- ### urlview can't find the links ### COMMAND qvm-open-in-dvm %s - +``` In `.mailcap`: +``` ### TODO: override most/all default mailcap settings to prevent ### opening in muttvm ### is there a way to do this polymorphically? i.e. not @@ -226,3 +231,4 @@ In `.mailcap`: # HTML text/html; w3m -T text/html '%s' | cat --squeeze-blank; nametemplate=%s.html; copiousoutput text/html; qvm-open-in-dvm %s +``` diff --git a/en/_doc/external/configuration-guides/network-bridge-support.md b/en/_doc/external/configuration-guides/network-bridge-support.md index d703aa96a7..2ccdac15fd 100644 --- a/en/_doc/external/configuration-guides/network-bridge-support.md +++ b/en/_doc/external/configuration-guides/network-bridge-support.md @@ -15,10 +15,10 @@ Network Bridge Support (EXPERIMENTAL and UNSUPPORTED) The Qubes development team does not support bridging the network interfaces found in NetVM and don't plan to support it at all. Several reasons for that: -- Using a bridged VM is almost only necessary for developers testing or working on OSI layer 2 or layer 3 tools (MAC or routing protocols). If not for testing, such tools are almost only used directly on routers ...). -- Most of these tools can be anyway used directly inside the NetVM, which has direct access to the network card. -- It is also possible to use a secondary network card plugged into a specific development VM. -- Such a setup could break security features of Qubes such as AppVM firewalling. +- Using a bridged VM is almost only necessary for developers testing or working on OSI layer 2 or layer 3 tools (MAC or routing protocols). If not for testing, such tools are almost only used directly on routers ...). +- Most of these tools can be anyway used directly inside the NetVM, which has direct access to the network card. +- It is also possible to use a secondary network card plugged into a specific development VM. +- Such a setup could break security features of Qubes such as AppVM firewalling. Now if you really want to work with OSI layer2 / layer 3 tools, that you don't have a secondary network card, or that you want to completely expose services of a given AppVM (at your own risk), a bridged setup may help you. @@ -53,7 +53,7 @@ You need to modify manually the NetVM iptable script inside the NetVM. The reaso Modify manually the Template you use for your NetVM (not the NetVM itself). This is by default fedora-x86\_64. Edit the file /etc/sysconfig/iptables. You need to modify two parts of the file. -- Starting from the line -A POSTROUTING -j MASQUERADE that you need to comment : +- Starting from the line -A POSTROUTING -j MASQUERADE that you need to comment : ~~~ # Bridge support @@ -66,7 +66,7 @@ Modify manually the Template you use for your NetVM (not the NetVM itself). This # End Bridge support ~~~ -- Starting from the line -A FORWARD -i vif+ -j ACCEPT: +- Starting from the line -A FORWARD -i vif+ -j ACCEPT: ~~~ -A FORWARD -i vif+ -o vif+ -j DROP @@ -92,14 +92,14 @@ A bridge can be created inside the standard network manager (the network icon in This requires: -- creating a bridge that will be your main IP (ex: setup the bridge with DHCP) -- attach eth0 to your bridge +- creating a bridge that will be your main IP (ex: setup the bridge with DHCP) +- attach eth0 to your bridge Note: A wireless interface cannot be bridged. The bridge edition GUI is somewhat buggy as it does not remember all the parameters you set up. You can fix it by editing manually the files in /etc/NetworkManager/system-connections/. Here is one example for these files: -- Bridge-DHCP +- Bridge-DHCP ~~~ [connection] @@ -122,7 +122,7 @@ The bridge edition GUI is somewhat buggy as it does not remember all the paramet Note: Do not forget to put stp=false if you bridge only eth0 because sending BPDUs could make your admins angry :) -- bridge0-eth0 +- bridge0-eth0 ~~~ [802-3-ethernet] diff --git a/en/_doc/external/configuration-guides/network-printer.md b/en/_doc/external/configuration-guides/network-printer.md index 180a44a439..fe636f2d0d 100644 --- a/en/_doc/external/configuration-guides/network-printer.md +++ b/en/_doc/external/configuration-guides/network-printer.md @@ -45,12 +45,12 @@ Consider not using printing from your more trusted AppVMs for this reason. Steps to configure a network printer in a template VM ---------------------------------------------------------- -1. Start the "Printer Settings" App in a template VM (either via Qubes "Start Menu", or by launching the `system-config-printer` in the template). -2. Add/Configure the printer in the same way as one would do on any normal Linux. +1. Start the "Printer Settings" App in a template VM (either via Qubes "Start Menu", or by launching the `system-config-printer` in the template). +2. Add/Configure the printer in the same way as one would do on any normal Linux. You may need to allow network access from the template VM to your printer to complete configuration, as normally the template VM is not allowed any network access except to the Qubes proxy for software installation. One can use Qubes Manager to modify firewall rules for particular VMs. -3. Optional: Test the printer by printing a test page. If it works, shut down the template VM. -4. Open an AppVM (make sure it's based on the template where you just installed the printer, normally all AppVMs are based on the default template), and test if printing works. +3. Optional: Test the printer by printing a test page. If it works, shut down the template VM. +4. Open an AppVM (make sure it's based on the template where you just installed the printer, normally all AppVMs are based on the default template), and test if printing works. If it doesn't then probably the AppVM doesn't have networking access to the printer -- in that case adjust the firewall settings for that AppVM in Qubes Manager. Also, make sure that the AppVM gets restarted after the template was shutdown. -5. Alternatively if you do not want to modify the firewall rules of the template VM (that have security scope) you can simply shut down the template VM without trying to print the test page (which will not work), start or restart an AppVM based on the template and test printing there. +5. Alternatively if you do not want to modify the firewall rules of the template VM (that have security scope) you can simply shut down the template VM without trying to print the test page (which will not work), start or restart an AppVM based on the template and test printing there. diff --git a/en/_doc/external/configuration-guides/postfix.md b/en/_doc/external/configuration-guides/postfix.md index 327ff4ae56..e0c5b42431 100644 --- a/en/_doc/external/configuration-guides/postfix.md +++ b/en/_doc/external/configuration-guides/postfix.md @@ -10,13 +10,11 @@ ref: 107 title: Postfix --- -Postfix -======= +# Postfix Postfix is full featured MTA (Message Transfer Agent). Here we will configure it in smarthost mode as part of common [Mutt](/doc/mutt/)+Postfix+[Fetchmail](/doc/fetchmail/) stack. -Installation ------------- +## Installation `dnf install postfix procmail make cyrus-sasl cyrus-sasl-plain` @@ -24,8 +22,7 @@ Cyrus-sasl is installed to authenticate to remote servers. Procmail is not stric You should also check `alternatives` command, to see if it is the default `mta`. It probably is not. You may need to `dnf remove ssmtp` or something -Configuration -------------- +## Configuration In TemplateVM open `/etc/aliases` and add line: @@ -142,8 +139,7 @@ list/qubes-users/ list/qubes-devel/ ~~~ -Run ---- +## Run Open `/rw/config/rc.local` and add those two lines (before fetchmail lines, if you have them): diff --git a/en/_doc/external/configuration-guides/tips-and-tricks.md b/en/_doc/external/configuration-guides/tips-and-tricks.md index 2e6d5e3655..dbfd7c8706 100644 --- a/en/_doc/external/configuration-guides/tips-and-tricks.md +++ b/en/_doc/external/configuration-guides/tips-and-tricks.md @@ -8,10 +8,12 @@ title: Tips and Tricks Tips and Tricks =============== + This section provides user suggested tips that aim to increase Qubes OS usability, security or that allow users to discover new ways to use your computer that are unique to Qubes OS. Opening links in your preferred AppVM ------------------------------------- + To increase both security and usability you can set an AppVM so that it automatically opens any link in an different AppVM of your choice. You can do this for example in the email AppVM, in this way you avoid to make mistakes like opening links in it. To learn more you can check [security guidelines](/doc/security-guidelines/) and [security goals](/security/goals/). The command `qvm-open-in-vm` lets you open a document or a URL in another VM. It takes two parameters: vmname and filename. @@ -26,6 +28,7 @@ If you want this to happen automatically you can create a .desktop file that adv Open a text editor and copy and paste this into it: +``` [Desktop Entry] Encoding=UTF-8 Name=BrowserVM @@ -35,6 +38,7 @@ Open a text editor and copy and paste this into it: Type=Application Categories=Network;WebBrowser; MimeType=x-scheme-handler/unknown;x-scheme-handler/about;text/html;text/xml;application/xhtml+xml;application/xml;application/vnd.mozilla.xul+xml;application/rss+xml;application/rdf+xml;image/gif;image/jpeg;image/png;x-scheme-handler/http;x-scheme-handler/https; +``` Replace `APPVMNAME` with the AppVM name you want to open links in. Now save, in the AppVM that you want to modify, this file to `~/.local/share/applications/browser_vm.desktop` @@ -46,6 +50,7 @@ Credit: [Micah Lee](https://micahflee.com/2016/06/qubes-tip-opening-links-in-you Preventing data leaks --------------------- + First make sure to read [Understanding and Preventing Data Leaks](/doc/data-leaks/) section to understand the limits of this tip. Suppose that you have within a not so trusted environment - for example, a Windows VM - an application that tracks and reports its usage, or you simply want to protect your data. diff --git a/en/_doc/external/configuration-guides/vpn.md b/en/_doc/external/configuration-guides/vpn.md index 6ddacb5e34..573b3dcc5f 100644 --- a/en/_doc/external/configuration-guides/vpn.md +++ b/en/_doc/external/configuration-guides/vpn.md @@ -11,8 +11,7 @@ ref: 102 title: VPN --- -How To make a VPN Gateway in Qubes -================================== +# How To make a VPN Gateway in Qubes - * Physical separation doesn't rely on a hypervisor. (It's very unlikely that an attacker will break out of Qubes' hypervisor, but if one were to manage to do so, one could potentially gain control over the entire system.) - * Physical separation can be a natural complement to physical security. - (For example, you might find it natural to lock your secure laptop in a safe when you take your unsecure laptop out with you.) +- Physical separation doesn't rely on a hypervisor. (It's very unlikely that an attacker will break out of Qubes' hypervisor, but if one were to manage to do so, one could potentially gain control over the entire system.) +- Physical separation can be a natural complement to physical security. + (For example, you might find it natural to lock your secure laptop in a safe when you take your unsecure laptop out with you.)
Cons
- * Physical separation can be cumbersome and expensive, since we may have to obtain and set up a separate physical machine for each security level we need. - * There's generally no secure way to transfer data between physically separate computers running conventional OSes. - (Qubes has a secure inter-VM file transfer system to handle this.) - * Physically separate computers running conventional OSes are still independently vulnerable to most conventional attacks due to their monolithic nature. - * Malware which can bridge air gaps has existed for several years now and is becoming increasingly common. +- Physical separation can be cumbersome and expensive, since we may have to obtain and set up a separate physical machine for each security level we need. +- There's generally no secure way to transfer data between physically separate computers running conventional OSes. + (Qubes has a secure inter-VM file transfer system to handle this.) +- Physically separate computers running conventional OSes are still independently vulnerable to most conventional attacks due to their monolithic nature. +- Malware which can bridge air gaps has existed for several years now and is becoming increasingly common. (For more on this topic, please see the paper [Software compartmentalization vs. physical separation][paper-compart].) - ### What is the main concept behind Qubes? To build security on the "Security by Compartmentalization (or Isolation)" principle. @@ -210,25 +207,25 @@ See the [XSA Tracker]. Whenever starting a discussion about another (micro)kernel or hypervisor in relation to Qubes, we strongly suggest including answers to the following questions first: -1. What kinds of containers does it use for isolation? Processes? PV VMs? Fully virtualized VMs (HVMs)? And what underlying h/w technology is used (ring0/3, VT-x)? -2. Does it require specially written/built applications (e.g. patched Firefox)? -3. Does it require custom drivers, or can it use Linux/Windows ones? -4. Does it support VT-d, and does it allow for the creation of untrusted driver domains? -5. Does it support S3 sleep? -6. Does it work on multiple CPUs/Chipsets? -7. What are the performance costs, more or less? (e.g. "XYZ prevents concurrent execution of two domains/processes on shared cores of a single processor", etc.) -8. Other special features? E.g. eliminates cooperative covert channels between VMs? +1. What kinds of containers does it use for isolation? Processes? PV VMs? Fully virtualized VMs (HVMs)? And what underlying h/w technology is used (ring0/3, VT-x)? +2. Does it require specially written/built applications (e.g. patched Firefox)? +3. Does it require custom drivers, or can it use Linux/Windows ones? +4. Does it support VT-d, and does it allow for the creation of untrusted driver domains? +5. Does it support S3 sleep? +6. Does it work on multiple CPUs/Chipsets? +7. What are the performance costs, more or less? (e.g. "XYZ prevents concurrent execution of two domains/processes on shared cores of a single processor", etc.) +8. Other special features? E.g. eliminates cooperative covert channels between VMs? Here are the answers for Xen 4.1 (which we use as of 2014-04-28): -1. PV and HVM Virtual Machines (ring0/3 for PV domains, VT-x/AMD-v for HVMs). -2. Runs unmodified usermode apps (binaries). -3. Runs unmodified Linux drivers (dom0 and driver domains). PV VMs require special written pvdrivers. -4. Full VT-d support including untrusted driver domains. -5. S3 sleep supported well. -6. Works on most modern CPUs/Chipsets. -7. Biggest performance hit on disk operations (especially in Qubes when complex 2-layer mapping used for Linux qubes). No GPU virtualization. -8. Mostly WorksTM :) +1. PV and HVM Virtual Machines (ring0/3 for PV domains, VT-x/AMD-v for HVMs). +2. Runs unmodified usermode apps (binaries). +3. Runs unmodified Linux drivers (dom0 and driver domains). PV VMs require special written pvdrivers. +4. Full VT-d support including untrusted driver domains. +5. S3 sleep supported well. +6. Works on most modern CPUs/Chipsets. +7. Biggest performance hit on disk operations (especially in Qubes when complex 2-layer mapping used for Linux qubes). No GPU virtualization. +8. Mostly WorksTM :) ### Which virtualization modes do VMs use? @@ -255,6 +252,7 @@ Please refer to [this page]. ### Why is dom0 so old? Please see: + - [Installing and updating software in dom0] - [Note on dom0 and EOL] @@ -317,7 +315,6 @@ So, if feature X isn't enabled, it's most likely for one of three reasons: If it seems like a feature that we can and should enable, please [let us know][reporting-bugs]! - ## Users ### Can I watch YouTube videos in qubes? @@ -333,8 +330,8 @@ However, Qubes does allow for the use of accelerated graphics (OpenGL) in Dom0 For further discussion about the potential for GPU passthrough on Xen/Qubes, please see the following threads: -- [GPU passing to HVM] -- [Clarifications on GPU security] +- [GPU passing to HVM] +- [Clarifications on GPU security] ### Is Qubes a multi-user system? @@ -347,7 +344,6 @@ See [here] for details. However, in Qubes 4.x we will be implementing management functionality. See [Admin API] and [Core Stack] for more details. - ### What are the system requirements for Qubes OS? See the [System Requirements]. @@ -442,7 +438,6 @@ You shouldn't do that, because it poses a security risk for your Qubes OS instal But if you understand the risk and accept it, read [documentation on multibooting]. It begins with an explanation of the risks with such a setup. - ### Which version of Qubes am I running? See [here][version]. @@ -497,16 +492,18 @@ This is an intended feature. A device which was previously assigned to a less trusted qube could attack dom0 if it were automatically reassigned there. In order to re-enable the device in dom0, either: - * Reboot the physical machine. +- Reboot the physical machine. or - * Go to the sysfs (`/sys/bus/pci`), find the right device, detach it from the pciback driver and attach back to the original driver. Replace `` with your device, for example `00:1c.2`: +- Go to the sysfs (`/sys/bus/pci`), find the right device, detach it from the pciback driver and attach back to the original driver. Replace `` with your device, for example `00:1c.2`: - echo 0000: > /sys/bus/pci/drivers/pciback/unbind - MODALIAS=`cat /sys/bus/pci/devices/0000:/modalias` - MOD=`modprobe -R $MODALIAS | head -n 1` - echo 0000: > /sys/bus/pci/drivers/$MOD/bind + ``` + echo 0000: > /sys/bus/pci/drivers/pciback/unbind + MODALIAS=`cat /sys/bus/pci/devices/0000:/modalias` + MOD=`modprobe -R $MODALIAS | head -n 1` + echo 0000: > /sys/bus/pci/drivers/$MOD/bind + ``` See also [here][assign_devices]. @@ -534,7 +531,9 @@ For Debian: 1. (Recommended) Clone an existing Debian TemplateVM 2. Install VLC in that TemplateVM: - $ sudo apt install vlc + ```bash_session + $ sudo apt install vlc + ``` 3. Use VLC to play your video files. @@ -544,7 +543,9 @@ For Fedora: 2. [Enable the appropriate RPMFusion repos in the desired Fedora TemplateVM][Enable RPMFusion]. 3. Install VLC in that TemplateVM: - $ sudo dnf install vlc + ```bash_session + $ sudo dnf install vlc + ``` 4. Use VLC to play your video files. @@ -609,7 +610,9 @@ I see a screen popup with SeaBios and 4 lines, last one being `Probing EDD (edd= From a `dom0` prompt, enter: - qvm-prefs kernel "" +``` +qvm-prefs kernel "" +``` ### When I try to install a TemplateVM, it says no match is found. @@ -634,11 +637,11 @@ Usually, this is due to network problems (especially if downloading updates over Often, the problem can be resolved by trying again on a different connection (a different Tor circuit, if using Tor) or waiting and trying again later. Here are some examples of non-Qubes reports about this problem: - - - - - - - - - - +- +- +- +- +- More examples can be found by searching for "Failed to synchronize cache for repo" (with quotation marks) on your preferred search engine. @@ -650,6 +653,7 @@ The full message looks like: [FAILED] Failed to start Load Kernel Modules. See 'systemctl status systemd-modules-load.service' for details. ``` + This is cosmetic only, and can safely be ignored. ### Why is Qubes so slow and how can I make it faster? @@ -669,7 +673,6 @@ There is no particular configuration that will be ideal for everyone (despite ho Please don't ask for your favorite program to be installed by default or for some setting that obviously varies by user preference to be changed so that it matches *your* preference. This is an incredibly selfish attitude that demonstrates a complete lack of consideration for the thousands of other Qubes users who don't happen to share your preferences. - ## Developers ### Are there restrictions on the software that the Qubes developers are willing to use? @@ -678,10 +681,10 @@ Yes. In general, the Qubes developers will not use a piece of software unless there is an *easy* way to verify both its **integrity** and **authenticity**, preferably via PGP signatures (see [Verifying Signatures](/security/verifying-signatures/)). Specifically: - * If PGP signatures are used, the signing key(s) should have well-publicized fingerprint(s) verifiable via multiple independent channels or be accessible to the developers through a web of trust. - * If the software is security-sensitive and requires communication with the outside world, a "split" implementation is highly preferred (for examples, see [Split GPG](/doc/split-gpg/) and [Split Bitcoin](/doc/split-bitcoin/)). - * If the software has dependencies, these should be packaged and available in repos for a [current, Qubes-supported version](/doc/supported-versions/#templatevms) of Fedora (preferred) or Debian (unless all the insecure dependencies can run in an untrusted VM in a "split" implementation). - * If the software must be built from source, the source code and any builders must be signed. +- If PGP signatures are used, the signing key(s) should have well-publicized fingerprint(s) verifiable via multiple independent channels or be accessible to the developers through a web of trust. +- If the software is security-sensitive and requires communication with the outside world, a "split" implementation is highly preferred (for examples, see [Split GPG](/doc/split-gpg/) and [Split Bitcoin](/doc/split-bitcoin/)). +- If the software has dependencies, these should be packaged and available in repos for a [current, Qubes-supported version](/doc/supported-versions/#templatevms) of Fedora (preferred) or Debian (unless all the insecure dependencies can run in an untrusted VM in a "split" implementation). +- If the software must be built from source, the source code and any builders must be signed. (Practically speaking, the more cumbersome and time-consuming it is to build from source, the less likely the developers are to use it.) ### Why does dom0 need to be 64-bit? @@ -714,11 +717,11 @@ See the discussion on issue [#1014](https://github.com/QubesOS/qubes-issues/issu The policy is there mostly to ease maintenance, on several levels: - * Less modifications means easier migration to new upstream distribution +- Less modifications means easier migration to new upstream distribution releases. - * The upstream documentation matches the distribution running in the Qubes VM. - * We're less likely to introduce Qubes-specific issues. - * Each officially supported distribution (ideally) should offer the same set of +- The upstream documentation matches the distribution running in the Qubes VM. +- We're less likely to introduce Qubes-specific issues. +- Each officially supported distribution (ideally) should offer the same set of Qubes-specific features - a change in one supported distribution should be followed also in others, including new future distributions. diff --git a/en/_doc/introduction/reporting-bugs.md b/en/_doc/introduction/reporting-bugs.md index 17c3f67ada..c3c429dc41 100644 --- a/en/_doc/introduction/reporting-bugs.md +++ b/en/_doc/introduction/reporting-bugs.md @@ -123,7 +123,6 @@ If the issue is closed without one of these specific resolutions, then it means, - [Package Contributions] - [Documentation Guidelines] - [qubes-issues-all]: https://github.com/QubesOS/qubes-issues/issues?utf8=%E2%9C%93&q=is%3Aissue [qubes-issues-bug-up-desc]: https://github.com/QubesOS/qubes-issues/issues?q=label%3Abug+sort%3Aupdated-desc [qubes-issues-labels]: https://github.com/QubesOS/qubes-issues/labels diff --git a/en/_doc/introduction/screenshots.md b/en/_doc/introduction/screenshots.md index 83822cd88f..f3df96bf02 100644 --- a/en/_doc/introduction/screenshots.md +++ b/en/_doc/introduction/screenshots.md @@ -64,6 +64,7 @@ Qubes is all about seamless integration from the user’s point of view. Here yo [![r4.1-manager-and-sysnet-network-prompt.png](/attachment/wiki/QubesScreenshots/r4.1-manager-and-sysnet-network-prompt.png)](/attachment/wiki/QubesScreenshots/r4.1-manager-and-sysnet-network-prompt.png) All the networking runs in a special, unprivileged NetVM. (Notice the red frame around the Network Manager dialog box on the screen above.) This means that in the event that your network card driver, Wi-Fi stack, or DHCP client is compromised, the integrity of the rest of the system will not be affected! This feature requires Intel VT-d or AMD IOMMU hardware (e.g., Core i5/i7 systems) + * * * * * [![r4.1-software-update.png](/attachment/wiki/QubesScreenshots/r4.1-software-update.png)](/attachment/wiki/QubesScreenshots/r4.1-software-update.png) diff --git a/en/_doc/introduction/statistics.md b/en/_doc/introduction/statistics.md index b46cc7b8c8..4bc069f5f5 100644 --- a/en/_doc/introduction/statistics.md +++ b/en/_doc/introduction/statistics.md @@ -14,8 +14,7 @@ title: Statistics
-FAQ ---- +## FAQ ### How often is this graph updated? @@ -41,10 +40,11 @@ tor_users = tor_requests * (plain_users / plain_requests) ``` Where: - - `tor_users` is the estimated number of Qubes users who download updates via Tor each month. - - `tor_requests` is the total number of requests the Qubes update servers receive from Tor exit nodes each month. - - `plain_users` is the number of unique clearnet IPv4 addresses that connect to the Qubes update servers each month. - - `plain_requests` is the total number of requests the Qubes update servers receive from clearnet IPv4 addresses each month. + +- `tor_users` is the estimated number of Qubes users who download updates via Tor each month. +- `tor_requests` is the total number of requests the Qubes update servers receive from Tor exit nodes each month. +- `plain_users` is the number of unique clearnet IPv4 addresses that connect to the Qubes update servers each month. +- `plain_requests` is the total number of requests the Qubes update servers receive from clearnet IPv4 addresses each month. We cross-reference the list of connecting IP addresses with [TorDNSEL's exit lists] in order to distinguish Tor and clearnet IPs and requests. For this purpose, we count an IP address as belonging to a Tor exit node if there was a Tor exit node active for that address within the 24-hour periods before or after it connected to the Qubes update servers. @@ -53,9 +53,9 @@ For this purpose, we count an IP address as belonging to a Tor exit node if ther We collect: - - The IPv4 addresses that connect to the Qubes update servers - - The number of requests from each IPv4 address - - Standard server access and error logs +- The IPv4 addresses that connect to the Qubes update servers +- The number of requests from each IPv4 address +- Standard server access and error logs We do not collect any other kinds of data about Qubes users. @@ -66,7 +66,6 @@ The raw data is available [here][raw-data]. Please note that the format of this data is not documented and may change any time if the developers feel the need to include something else. The source code is available [here][source-code]. - [tor-methodology]: #how-has-the-methodology-for-counting-tor-users-changed [TorDNSEL's exit lists]: https://metrics.torproject.org/collector.html#type-tordnsel [raw-data]: https://tools.qubes-os.org/counter/stats.json diff --git a/en/_doc/introduction/support.md b/en/_doc/introduction/support.md index 7319841d1b..510f25c5f7 100644 --- a/en/_doc/introduction/support.md +++ b/en/_doc/introduction/support.md @@ -26,7 +26,6 @@ see the [issue tracker]. These issues are constantly being updated and may contain workarounds for problems that you're experiencing, so it's worth [searching the issue tracker] as a first step. - ## Staying safe ## The Qubes mailing lists and forum are open to the public. The contents are @@ -63,7 +62,6 @@ every contribution to the Qubes OS Project is publicly visible and cryptographically signed, anyone would be in a position to [verify] that these came from the same keyholder. - ## Discussion guidelines ## Qubes discussions mainly take place on `qubes-users`, `qubes-devel`, and our @@ -144,7 +142,6 @@ Likewise, if you see that something in the documentation should be changed, don't simply point it out in a discussion venue. Instead, [submit the change][contributing to the documentation]. - ### Specific mailing list rules and notes ### #### Use the correct list #### @@ -225,13 +222,11 @@ example, we encourage discussants to use [Split GPG] to sign all of their messages to the lists, but we do not endorse the use of these Google Groups as web forums. For that, we have a separate, dedicated [forum]. - ## Mailing lists ## This section covers each of our individual [mailing lists][wiki-ml], with details about the purpose of each list and how to use it. - ### qubes-announce ### This is a read-only list for those who wish to receive only very important, @@ -245,26 +240,25 @@ required. Any email address will work.) To unsubscribe, send a blank email to `qubes-announce+unsubscribe@googlegroups.com`. This list also has an optional [Google Groups web interface][qubes-announce-web]. - ### qubes-users ### This list is for helping users solve various daily problems with Qubes OS. Examples of topics or questions suitable for this list include: - * [HCL] reports - * Installation problems - * Hardware compatibility problems - * Questions of the form: "How do I...?" +* [HCL] reports +* Installation problems +* Hardware compatibility problems +* Questions of the form: "How do I...?" Please try searching both the Qubes website and the archives of the mailing lists before sending a question. In addition, please make sure that you have read and understood the following basic documentation prior to posting to the list: - * The [Installation Guide], [System Requirements], and [HCL] (for problems - related to installing Qubes OS) - * The [User FAQ] - * The [documentation] (for questions about how to use Qubes OS) +* The [Installation Guide], [System Requirements], and [HCL] (for problems + related to installing Qubes OS) +* The [User FAQ] +* The [documentation] (for questions about how to use Qubes OS) You don't have to subscribe in order to post to this list. However, subscribing makes your messages less likely to be marked as spam and allows you to receive @@ -277,20 +271,19 @@ send a blank email to `qubes-users+unsubscribe@googlegroups.com`. This list also has an optional [Google Groups web interface][qubes-users-web] and [traditional mail archive][qubes-users-archive]. - ### qubes-devel ### This list is primarily intended for people who are interested in contributing to Qubes or who are willing to learn more about its architecture and implementation. Examples of topics and questions suitable for this list include: - * Questions about why we made certain architecture or implementation decisions. - * For example: "Why did you implement XYZ this way and not the other way?" - * Questions about code layout and where code is for certain functionality. - * Discussions about proposed new features, patches, etc. - * For example: "I would like to implement feature XYZ." - * Contributed code and patches. - * Security discussions which are relevant to Qubes in some way. +* Questions about why we made certain architecture or implementation decisions. + * For example: "Why did you implement XYZ this way and not the other way?" +* Questions about code layout and where code is for certain functionality. +* Discussions about proposed new features, patches, etc. + * For example: "I would like to implement feature XYZ." +* Contributed code and patches. +* Security discussions which are relevant to Qubes in some way. You must be subscribed in order to post to this list. To subscribe, send a blank email to `qubes-devel+subscribe@googlegroups.com`. (Note: A Google @@ -301,7 +294,6 @@ unsubscribe, send a blank email to `qubes-devel+unsubscribe@googlegroups.com`. This list also has an optional [Google Groups web interface][qubes-devel-web] and [traditional mail archive][qubes-devel-archive]. - ### qubes-project ### This list is for non-technical discussion and coordination around the @@ -309,10 +301,10 @@ Qubes OS project. Examples of topics or question suitable for this list include: - * Participation (talks, workshops, etc.) at upcoming events - * Project funding applications and strategies - * FOSS governance discussions - * Most Github issues tagged "[business]" +* Participation (talks, workshops, etc.) at upcoming events +* Project funding applications and strategies +* FOSS governance discussions +* Most Github issues tagged "[business]" You don't have to subscribe in order to post to this list. However, subscribing makes your messages less likely to be marked as spam and allows you to receive @@ -324,7 +316,6 @@ immediately, please allow time for moderation to occur. To unsubscribe, send a blank email to `qubes-project+unsubscribe@googlegroups.com`. This list also also has an optional [Google Groups web interface][qubes-project-web]. - ### qubes-translation ### This list is for discussion around the localization and translation of Qubes OS, @@ -332,9 +323,9 @@ its documentation, and the website. Examples of topics or question suitable for this list include: - * Questions about or issues with [Transifex], the translation platform we use - * Who is managing localization for a given language - * Most Github issues tagged "[localization]" +* Questions about or issues with [Transifex], the translation platform we use +* Who is managing localization for a given language +* Most Github issues tagged "[localization]" You don't have to subscribe in order to post to this list. However, subscribing makes your messages less likely to be marked as spam and allows you to receive @@ -347,7 +338,6 @@ unsubscribe, send a blank email to `qubes-translation+unsubscribe@googlegroups.com`. This list also has an optional [Google Groups web interface][qubes-translation-web]. - ## Forum ## We have a community forum for Qubes OS users: @@ -397,14 +387,13 @@ addition, we fully expect that many community members -- especially the most active ones -- will choose to participate in both venues. (Again, for those who still prefer interacting via email, Discourse supports that too!) - ## Unofficial chat channels ## The following unofficial chat channels are maintained by the community: - * Matrix, Qubes-related: - * Matrix, strictly Qubes: - * `#qubes` channel on freenode.net via traditional IRC clients or: +* Matrix, Qubes-related: +* Matrix, strictly Qubes: +* `#qubes` channel on freenode.net via traditional IRC clients or: [mailing lists]: #mailing-lists [wiki-ml]: https://en.wikipedia.org/wiki/Electronic_mailing_list From 6704e0be87e6233bc6b54c37f5214bf68065d0f3 Mon Sep 17 00:00:00 2001 From: dd Date: Mon, 16 Nov 2020 22:43:00 +0100 Subject: [PATCH 119/663] linted docs in project security --- en/_doc/project-security/canary-checklist.md | 25 +- .../security-bulletins-checklist.md | 27 +- en/_doc/project-security/security-pack.md | 215 +++++----- en/_doc/project-security/security.md | 35 +- .../project-security/verifying-signatures.md | 368 +++++++++--------- en/_doc/project-security/xsa.md | 2 +- 6 files changed, 339 insertions(+), 333 deletions(-) diff --git a/en/_doc/project-security/canary-checklist.md b/en/_doc/project-security/canary-checklist.md index 707817a3f0..b000d5e372 100644 --- a/en/_doc/project-security/canary-checklist.md +++ b/en/_doc/project-security/canary-checklist.md @@ -6,20 +6,17 @@ ref: 216 title: Canary Checklist --- -Canary Checklist -================ +# Canary Checklist -Preparation ------------ +## Preparation - * Draft canary and push to private repository - * Finalize canary, sign, and add signed tags - -Announcement ------------- +* Draft canary and push to private repository +* Finalize canary, sign, and add signed tags - * Push canary to public repository - * Publish a [news post](/news/) using the [Canary Template](/security/canaries/template/) - * Send the content of the news post to the appropriate [mailing lists](/support/) - * Share link to news post on social media - * Set a reminder for the next canary +## Announcement + +* Push canary to public repository +* Publish a [news post](/news/) using the [Canary Template](/security/canaries/template/) +* Send the content of the news post to the appropriate [mailing lists](/support/) +* Share link to news post on social media +* Set a reminder for the next canary diff --git a/en/_doc/project-security/security-bulletins-checklist.md b/en/_doc/project-security/security-bulletins-checklist.md index dc1d3b76e8..77d4b0567f 100644 --- a/en/_doc/project-security/security-bulletins-checklist.md +++ b/en/_doc/project-security/security-bulletins-checklist.md @@ -7,21 +7,18 @@ ref: 215 title: Security Bulletin Checklist --- -Security Bulletin Checklist -=========================== +# Security Bulletin Checklist -Preparation ------------ +## Preparation - * Draft QSB and push to private repository - * Build fixed packages - * Finalize QSB, sign, and add signed tags - -Announcement ------------- +* Draft QSB and push to private repository +* Build fixed packages +* Finalize QSB, sign, and add signed tags - * Upload packages to `security-testing` and `current-testing` repositories - * Push QSB to public repository - * Publish a [news post](/news/) using the [QSB Template](/security/bulletins/template/) - * Send the content of the news post to the appropriate [mailing lists](/support/) - * Share link to news post on social media +## Announcement + +* Upload packages to `security-testing` and `current-testing` repositories +* Push QSB to public repository +* Publish a [news post](/news/) using the [QSB Template](/security/bulletins/template/) +* Send the content of the news post to the appropriate [mailing lists](/support/) +* Share link to news post on social media diff --git a/en/_doc/project-security/security-pack.md b/en/_doc/project-security/security-pack.md index 8394dc6e17..32d507e226 100644 --- a/en/_doc/project-security/security-pack.md +++ b/en/_doc/project-security/security-pack.md @@ -22,18 +22,17 @@ Qubes Security Pack The **Qubes Security Pack** (`qubes-secpack`) is a Git repository that contains: - * [Qubes PGP keys](https://keys.qubes-os.org/keys/) - * [Qubes Security Bulletins (QSBs)](/security/bulletins/) - * [Qubes warrant canaries](https://github.com/QubesOS/qubes-secpack/tree/master/canaries) - * [Qubes Bitcoin fund information](https://github.com/QubesOS/qubes-secpack/tree/master/fund) - * Security-related information and announcements (e.g., key revocations) +* [Qubes PGP keys](https://keys.qubes-os.org/keys/) +* [Qubes Security Bulletins (QSBs)](/security/bulletins/) +* [Qubes warrant canaries](https://github.com/QubesOS/qubes-secpack/tree/master/canaries) +* [Qubes Bitcoin fund information](https://github.com/QubesOS/qubes-secpack/tree/master/fund) +* Security-related information and announcements (e.g., key revocations) While `qubes-secpack` itself is independent of any particular host, its current official location is: - History and Rationale --------------------- @@ -42,6 +41,7 @@ rationale in an [email](https://groups.google.com/d/msg/qubes-devel/twkOEaMLtNI/lZyGx6_jFCEJ) to the Qubes mailing lists: +``` Hello, A new Qubes Security Bulletin has been just released and is available here: @@ -128,6 +128,7 @@ to the Qubes mailing lists: [3] Deterministic builds are required because it's the only way we can implement multiple signature scheme for distributed binaries. +``` How to Obtain, Verify, and Read ------------------------------- @@ -135,125 +136,135 @@ How to Obtain, Verify, and Read The following example demonstrates one method of obtaining the `qubes-secpack`, verifying its contents, and reading them. - 1. Clone the `qubes-secpack` repo. +1. Clone the `qubes-secpack` repo. - $ git clone https://github.com/QubesOS/qubes-secpack.git - Cloning into 'qubes-secpack'... - remote: Counting objects: 195, done. - remote: Total 195 (delta 0), reused 0 (delta 0) - Receiving objects: 100% (195/195), 130.94 KiB | 207.00 KiB/s, done. - Resolving deltas: 100% (47/47), done. - Checking connectivity... done. + ```shell_session + $ git clone https://github.com/QubesOS/qubes-secpack.git + Cloning into 'qubes-secpack'... + remote: Counting objects: 195, done. + remote: Total 195 (delta 0), reused 0 (delta 0) + Receiving objects: 100% (195/195), 130.94 KiB | 207.00 KiB/s, done. + Resolving deltas: 100% (47/47), done. + Checking connectivity... done. + ``` - 2. Import the included PGP keys. +2. Import the included PGP keys. - $ gpg --import qubes-secpack/keys/*/* - gpg: directory `/home/user/.gnupg' created - gpg: new configuration file `/home/user/.gnupg/gpg.conf' created - gpg: WARNING: options in `/home/user/.gnupg/gpg.conf' are not yet active during this run - gpg: keyring `/home/user/.gnupg/secring.gpg' created - gpg: keyring `/home/user/.gnupg/pubring.gpg' created - gpg: /home/user/.gnupg/trustdb.gpg: trustdb created - gpg: key C37BB66B: public key "Joanna Rutkowska (Qubes OS signing key) " imported - gpg: key 1E30A75D: public key "Joanna Rutkowska (Qubes OS signing key) " imported - gpg: key 74EADABC: public key "Joanna Rutkowska (Qubes OS signing key) " imported - gpg: key 65EF29CA: public key "Joanna Rutkowska (Qubes OS Signing Key) " imported - gpg: key 34898310: public key "Joanna Rutkowska (Qubes OS Signing Key) " imported - gpg: key B298547C: public key "Marek Marczykowski (Qubes OS signing key) " imported - gpg: key AB5EEF90: public key "Marek Marczykowski (Qubes OS signing key) " imported - gpg: key A603BCB6: public key "Marek Marczykowski (Qubes OS signing key) " imported - gpg: key 42CFA724: public key "Marek Marczykowski-Górecki (Qubes OS signing key) " imported - gpg: key 15CE40BF: public key "Wojciech Zygmunt Porczyk (Qubes OS signing key) " imported - gpg: key 36879494: public key "Qubes Master Signing Key" imported - gpg: key 211093A7: public key "Qubes OS Release 1 Signing Key" imported - gpg: key 0A40E458: public key "Qubes OS Release 2 Signing Key" imported - gpg: key 03FA5082: public key "Qubes OS Release 3 Signing Key" imported - gpg: key 92C7B3DC: public key "Joanna Rutkowska (Qubes Security Pack Signing Key) " imported - gpg: key 1830E06A: public key "Marek Marczykowski-Górecki (Qubes security pack) " imported - gpg: key 3F48CB21: public key "Qubes OS Security Team " imported - gpg: Total number processed: 17 - gpg: imported: 17 (RSA: 17) - gpg: no ultimately trusted keys found + ```shell_session + $ gpg --import qubes-secpack/keys/*/* + gpg: directory `/home/user/.gnupg' created + gpg: new configuration file `/home/user/.gnupg/gpg.conf' created + gpg: WARNING: options in `/home/user/.gnupg/gpg.conf' are not yet active during this run + gpg: keyring `/home/user/.gnupg/secring.gpg' created + gpg: keyring `/home/user/.gnupg/pubring.gpg' created + gpg: /home/user/.gnupg/trustdb.gpg: trustdb created + gpg: key C37BB66B: public key "Joanna Rutkowska (Qubes OS signing key) " imported + gpg: key 1E30A75D: public key "Joanna Rutkowska (Qubes OS signing key) " imported + gpg: key 74EADABC: public key "Joanna Rutkowska (Qubes OS signing key) " imported + gpg: key 65EF29CA: public key "Joanna Rutkowska (Qubes OS Signing Key) " imported + gpg: key 34898310: public key "Joanna Rutkowska (Qubes OS Signing Key) " imported + gpg: key B298547C: public key "Marek Marczykowski (Qubes OS signing key) " imported + gpg: key AB5EEF90: public key "Marek Marczykowski (Qubes OS signing key) " imported + gpg: key A603BCB6: public key "Marek Marczykowski (Qubes OS signing key) " imported + gpg: key 42CFA724: public key "Marek Marczykowski-Górecki (Qubes OS signing key) " imported + gpg: key 15CE40BF: public key "Wojciech Zygmunt Porczyk (Qubes OS signing key) " imported + gpg: key 36879494: public key "Qubes Master Signing Key" imported + gpg: key 211093A7: public key "Qubes OS Release 1 Signing Key" imported + gpg: key 0A40E458: public key "Qubes OS Release 2 Signing Key" imported + gpg: key 03FA5082: public key "Qubes OS Release 3 Signing Key" imported + gpg: key 92C7B3DC: public key "Joanna Rutkowska (Qubes Security Pack Signing Key) " imported + gpg: key 1830E06A: public key "Marek Marczykowski-Górecki (Qubes security pack) " imported + gpg: key 3F48CB21: public key "Qubes OS Security Team " imported + gpg: Total number processed: 17 + gpg: imported: 17 (RSA: 17) + gpg: no ultimately trusted keys found + ``` - 3. Verify and trust the Qubes Master Signing Key. +3. Verify and trust the Qubes Master Signing Key. - $ gpg --edit-key 36879494 - gpg (GnuPG) 1.4.18; Copyright (C) 2014 Free Software Foundation, Inc. - This is free software: you are free to change and redistribute it. - There is NO WARRANTY, to the extent permitted by law. - + ```shell_session + $ gpg --edit-key 36879494 + gpg (GnuPG) 1.4.18; Copyright (C) 2014 Free Software Foundation, Inc. + This is free software: you are free to change and redistribute it. + There is NO WARRANTY, to the extent permitted by law. - pub 4096R/36879494 created: 2010-04-01 expires: never usage: SC - trust: unknown validity: unknown - [ unknown] (1). Qubes Master Signing Key - gpg> fpr - pub 4096R/36879494 2010-04-01 Qubes Master Signing Key - Primary key fingerprint: 427F 11FD 0FAA 4B08 0123 F01C DDFA 1A3E 3687 9494 + pub 4096R/36879494 created: 2010-04-01 expires: never usage: SC + trust: unknown validity: unknown + [ unknown] (1). Qubes Master Signing Key - gpg> trust - pub 4096R/36879494 created: 2010-04-01 expires: never usage: SC - trust: unknown validity: unknown - [ unknown] (1). Qubes Master Signing Key + gpg> fpr + pub 4096R/36879494 2010-04-01 Qubes Master Signing Key + Primary key fingerprint: 427F 11FD 0FAA 4B08 0123 F01C DDFA 1A3E 3687 9494 + + gpg> trust + pub 4096R/36879494 created: 2010-04-01 expires: never usage: SC + trust: unknown validity: unknown + [ unknown] (1). Qubes Master Signing Key - Please decide how far you trust this user to correctly verify other users' keys - (by looking at passports, checking fingerprints from different sources, etc.) + Please decide how far you trust this user to correctly verify other users' keys + (by looking at passports, checking fingerprints from different sources, etc.) - 1 = I don't know or won't say - 2 = I do NOT trust - 3 = I trust marginally - 4 = I trust fully - 5 = I trust ultimately - m = back to the main menu + 1 = I don't know or won't say + 2 = I do NOT trust + 3 = I trust marginally + 4 = I trust fully + 5 = I trust ultimately + m = back to the main menu - Your decision? 5 - Do you really want to set this key to ultimate trust? (y/N) y + Your decision? 5 + Do you really want to set this key to ultimate trust? (y/N) y - pub 4096R/36879494 created: 2010-04-01 expires: never usage: SC - trust: ultimate validity: unknown - [ unknown] (1). Qubes Master Signing Key - Please note that the shown key validity is not necessarily correct - unless you restart the program. + pub 4096R/36879494 created: 2010-04-01 expires: never usage: SC + trust: ultimate validity: unknown + [ unknown] (1). Qubes Master Signing Key + Please note that the shown key validity is not necessarily correct + unless you restart the program. - gpg> q + gpg> q + ``` - **Important!** + **Important!** - In order to verify the authenticity of the Qubes Master Signing Key prior to - trusting it, you should obtain the Qubes Master Signing Key fingerprint from - a trustworthy source (ideally, multiple sources) *other than* this website - and visually compare it (them) to the fingerprint displayed in the preceding - step, ensuring they match. You can read more about digital signatures and - key verification [here](/security/verifying-signatures/). + In order to verify the authenticity of the Qubes Master Signing Key prior to + trusting it, you should obtain the Qubes Master Signing Key fingerprint from + a trustworthy source (ideally, multiple sources) *other than* this website + and visually compare it (them) to the fingerprint displayed in the preceding + step, ensuring they match. You can read more about digital signatures and + key verification [here](/security/verifying-signatures/). - 4. Verify signed Git tags. +4. Verify signed Git tags. - $ cd qubes-secpack/ - $ git tag -v `git describe` - object 2bb7f0b966593d8ed74e140a04d60c68b96b164e - type commit - tag joanna_sec_2bb7f0b9 - tagger Joanna Rutkowska 1468335706 +0000 + ```shell_session + $ cd qubes-secpack/ + $ git tag -v `git describe` + object 2bb7f0b966593d8ed74e140a04d60c68b96b164e + type commit + tag joanna_sec_2bb7f0b9 + tagger Joanna Rutkowska 1468335706 +0000 - Tag for commit 2bb7f0b966593d8ed74e140a04d60c68b96b164e - gpg: Signature made 2016-07-12T08:01:46 PDT - gpg: using RSA key 0x4E6829BC92C7B3DC - gpg: Good signature from "Joanna Rutkowska (Qubes Security Pack Signing Key) " [full] + Tag for commit 2bb7f0b966593d8ed74e140a04d60c68b96b164e + gpg: Signature made 2016-07-12T08:01:46 PDT + gpg: using RSA key 0x4E6829BC92C7B3DC + gpg: Good signature from "Joanna Rutkowska (Qubes Security Pack Signing Key) " [full] + ``` (The final line of output confirms that the signature is good.) - 5. Verify detached PGP signatures. +5. Verify detached PGP signatures. - $ cd canaries/ - $ gpg --verify canary-001-2015.txt.sig.joanna canary-001-2015.txt - gpg: Signature made Mon Jan 5 20:21:40 2015 UTC using RSA key ID 92C7B3DC - gpg: Good signature from "Joanna Rutkowska (Qubes Security Pack Signing Key) " - $ gpg --verify canary-001-2015.txt.sig.marmarek canary-001-2015.txt - gpg: Signature made Mon Jan 5 20:13:37 2015 UTC using RSA key ID 1830E06A - gpg: Good signature from "Marek Marczykowski-Górecki (Qubes security pack) " + ```shell_session + $ cd canaries/ + $ gpg --verify canary-001-2015.txt.sig.joanna canary-001-2015.txt + gpg: Signature made Mon Jan 5 20:21:40 2015 UTC using RSA key ID 92C7B3DC + gpg: Good signature from "Joanna Rutkowska (Qubes Security Pack Signing Key) " + $ gpg --verify canary-001-2015.txt.sig.marmarek canary-001-2015.txt + gpg: Signature made Mon Jan 5 20:13:37 2015 UTC using RSA key ID 1830E06A + gpg: Good signature from "Marek Marczykowski-Górecki (Qubes security pack) " + ``` - (The fourth and final lines of output confirm that the two signatures are - good.) +(The fourth and final lines of output confirm that the two signatures are + good.) The same procedures can be applied to any directory or file in the `qubes-secpack`. Two methods of verification (signed Git tags and detached PGP diff --git a/en/_doc/project-security/security.md b/en/_doc/project-security/security.md index 4c1f035aa2..79b6916b43 100644 --- a/en/_doc/project-security/security.md +++ b/en/_doc/project-security/security.md @@ -16,8 +16,7 @@ ref: 217 title: Security --- -Qubes OS Project Security Center -================================ +# Qubes OS Project Security Center - [Security FAQ] - [Security Goals] @@ -28,50 +27,46 @@ Qubes OS Project Security Center - [Why and How to Verify Signatures] - [PGP Keys] - -Reporting Security Issues in Qubes OS -------------------------------------- +## Reporting Security Issues in Qubes OS If you believe you have found a security issue affecting Qubes OS, either directly or indirectly (e.g. the issue affects Xen in a configuration that is used in Qubes OS), then we would be more than happy to hear from you! We promise to treat any reported issue seriously and, if the investigation confirms that it affects Qubes, to patch it within a reasonable time and release a public [Qubes Security Bulletin][Security Bulletins] that describes the issue, discusses the potential impact of the vulnerability, references applicable patches or workarounds, and credits the discoverer. -Security Updates ----------------- +## Security Updates Qubes security updates are obtained by [Updating Qubes OS]. -The Qubes Security Team ------------------------ +## The Qubes Security Team The Qubes Security Team (QST) is the subset of the [Qubes Team] that is responsible for ensuring the security of Qubes OS and the Qubes OS Project. In particular, the QST is responsible for: - - Responding to [reported security issues] - - Evaluating whether [XSAs][Xen Security Advisory (XSA) Tracker] affect the security of Qubes OS - - Writing, applying, and/or distributing security patches to fix vulnerabilities in Qubes OS - - Writing, signing, and publishing [Security Bulletins] - - Writing, signing, and publishing [Canaries] - - Generating, safeguarding, and using the project's [PGP Keys] +- Responding to [reported security issues] +- Evaluating whether [XSAs][Xen Security Advisory (XSA) Tracker] affect the security of Qubes OS +- Writing, applying, and/or distributing security patches to fix vulnerabilities in Qubes OS +- Writing, signing, and publishing [Security Bulletins] +- Writing, signing, and publishing [Canaries] +- Generating, safeguarding, and using the project's [PGP Keys] As a security-oriented operating system, the QST is fundamentally important to Qubes, and every Qubes user implicitly trusts the members of the QST by virtue of the actions listed above. The Qubes Security Team can be contacted via email at the following address: - security at qubes-os dot org - +``` +security at qubes-os dot org +``` -### Security Team PGP Key ### +### Security Team PGP Key Please use the [Security Team PGP Key] to encrypt all emails sent to this address. This key is signed by the [Qubes Master Signing Key]. Please see [Why and How to Verify Signatures] for information about how to verify these keys. -### Members of the Security Team ### +### Members of the Security Team - [Marek Marczykowski-Górecki] - [Simon Gaiser (aka HW42)] - [Joanna Rutkowska] ([emeritus, canaries only]) - [Security FAQ]: /faq/#general--security [Security Goals]: /security/goals/ [Security Pack]: /security/pack/ diff --git a/en/_doc/project-security/verifying-signatures.md b/en/_doc/project-security/verifying-signatures.md index b033c53979..a46d92a520 100644 --- a/en/_doc/project-security/verifying-signatures.md +++ b/en/_doc/project-security/verifying-signatures.md @@ -11,11 +11,9 @@ ref: 211 title: Verifying Signatures --- -On Digital Signatures and Key Verification -========================================== +# On Digital Signatures and Key Verification -What Digital Signatures Can and Cannot Prove --------------------------------------------- +## What Digital Signatures Can and Cannot Prove Most people --- even programmers --- are confused about the basic concepts underlying digital signatures. Therefore, most people should read this section, even if it looks trivial at first sight. @@ -41,16 +39,14 @@ Anybody can generate a GPG key pair that purports to belong to "The Qubes Projec The next section explains how to verify the validity of the Qubes signing keys in the process of verifying a Qubes ISO. (However, the same general principles apply to all cases in which you may wish to verify a PGP signature, such as [verifying repos], not just verifying ISOs.) - -How to Verify Qubes ISO Signatures ----------------------------------- +## How to Verify Qubes ISO Signatures This section will guide you through the process of verifying a Qubes ISO by checking its PGP signature. There are three basic steps in this process: - 1. [Get the Qubes Master Signing Key and verify its authenticity][QMSK] - 2. [Get the Release Signing Key][RSK] - 3. [Verify your Qubes ISO][signature file] +1. [Get the Qubes Master Signing Key and verify its authenticity][QMSK] +2. [Get the Release Signing Key][RSK] +3. [Verify your Qubes ISO][signature file] If you run into any problems, please consult the [Troubleshooting FAQ] below. @@ -63,122 +59,139 @@ This Qubes Master Signing Key was generated on and is kept only on a dedicated, There are several ways to get the Qubes Master Signing Key. - - If you have access to an existing Qubes installation, it's available in every VM ([except dom0]): +- If you have access to an existing Qubes installation, it's available in every VM ([except dom0]): - $ gpg2 --import /usr/share/qubes/qubes-master-key.asc + ```shell_session + $ gpg2 --import /usr/share/qubes/qubes-master-key.asc + ``` - - Fetch it with GPG: +- Fetch it with GPG: - $ gpg2 --fetch-keys https://keys.qubes-os.org/keys/qubes-master-signing-key.asc + ```shell_session + $ gpg2 --fetch-keys https://keys.qubes-os.org/keys/qubes-master-signing-key.asc + ``` - - Download it as a [file][Qubes Master Signing Key], then import it with GPG: +- Download it as a [file][Qubes Master Signing Key], then import it with GPG: - $ gpg2 --import ./qubes-master-signing-key.asc + ```shell_session + $ gpg2 --import ./qubes-master-signing-key.asc + ``` - - Get it from a public [keyserver] (specified on first use with `--keyserver `, then saved in `~/.gnupg/gpg.conf`), e.g.: +- Get it from a public [keyserver] (specified on first use with `--keyserver `, then saved in `~/.gnupg/gpg.conf`), e.g.: - $ gpg2 --keyserver pool.sks-keyservers.net --recv-keys 0x427F11FD0FAA4B080123F01CDDFA1A3E36879494 + ```shell_session + $ gpg2 --keyserver pool.sks-keyservers.net --recv-keys 0x427F11FD0FAA4B080123F01CDDFA1A3E36879494 + ``` The Qubes Master Signing Key is also available in the [Qubes Security Pack] and in the archives of the project's [developer][devel-master-key-msg] and [user][user-master-key-msg] [mailing lists]. Once you have obtained the Qubes Master Signing Key, you should verify the fingerprint of this key very carefully by obtaining copies of the fingerprint from multiple independent sources and comparing them to the downloaded key's fingerprint to ensure they match. Here are some ideas: - - Use the PGP Web of Trust. - - Check the key against different keyservers. - - Use different search engines to search for the fingerprint. - - Use Tor to view and search for the fingerprint on various websites. - - Use various VPNs and proxy servers. - - Use different Wi-Fi networks (work, school, internet cafe, etc.). - - Ask people to post the fingerprint in various forums and chat rooms. - - Check against PDFs and photographs in which the fingerprint appears - (e.g., slides from a talk or on a T-shirt). - - Repeat all of the above from different computers and devices. +- Use the PGP Web of Trust. +- Check the key against different keyservers. +- Use different search engines to search for the fingerprint. +- Use Tor to view and search for the fingerprint on various websites. +- Use various VPNs and proxy servers. +- Use different Wi-Fi networks (work, school, internet cafe, etc.). +- Ask people to post the fingerprint in various forums and chat rooms. +- Check against PDFs and photographs in which the fingerprint appears + (e.g., slides from a talk or on a T-shirt). +- Repeat all of the above from different computers and devices. In addition, some operating systems have built-in keyrings containing keys capable of validating the Qubes Master Signing Key. For example, if you have a Debian system, then your keyring may already contain the necessary keys. For additional security, we also publish the fingerprint of the Qubes Master Signing Key here (but [remember not to blindly trust the live version of this website][website-trust]): - pub 4096R/36879494 2010-04-01 - Key fingerprint = 427F 11FD 0FAA 4B08 0123 F01C DDFA 1A3E 3687 9494 - uid Qubes Master Signing Key +``` +pub 4096R/36879494 2010-04-01 + Key fingerprint = 427F 11FD 0FAA 4B08 0123 F01C DDFA 1A3E 3687 9494 +uid Qubes Master Signing Key +``` Once you're confident that you have the legitimate Qubes Master Signing Key, set its trust level to "ultimate" so that it can be used to automatically verify all the keys signed by the Qubes Master Signing Key (in particular, Release Signing Keys). - $ gpg2 --edit-key 0x36879494 - gpg (GnuPG) 1.4.18; Copyright (C) 2014 Free Software Foundation, Inc. - This is free software: you are free to change and redistribute it. - There is NO WARRANTY, to the extent permitted by law. - +```shell_session +$ gpg2 --edit-key 0x36879494 +gpg (GnuPG) 1.4.18; Copyright (C) 2014 Free Software Foundation, Inc. +This is free software: you are free to change and redistribute it. +There is NO WARRANTY, to the extent permitted by law. - pub 4096R/36879494 created: 2010-04-01 expires: never usage: SC - trust: unknown validity: unknown - [ unknown] (1). Qubes Master Signing Key - gpg> fpr - pub 4096R/36879494 2010-04-01 Qubes Master Signing Key - Primary key fingerprint: 427F 11FD 0FAA 4B08 0123 F01C DDFA 1A3E 3687 9494 +pub 4096R/36879494 created: 2010-04-01 expires: never usage: SC + trust: unknown validity: unknown +[ unknown] (1). Qubes Master Signing Key - gpg> trust - pub 4096R/36879494 created: 2010-04-01 expires: never usage: SC - trust: unknown validity: unknown - [ unknown] (1). Qubes Master Signing Key +gpg> fpr +pub 4096R/36879494 2010-04-01 Qubes Master Signing Key +Primary key fingerprint: 427F 11FD 0FAA 4B08 0123 F01C DDFA 1A3E 3687 9494 - Please decide how far you trust this user to correctly verify other users' keys - (by looking at passports, checking fingerprints from different sources, etc.) +gpg> trust +pub 4096R/36879494 created: 2010-04-01 expires: never usage: SC + trust: unknown validity: unknown +[ unknown] (1). Qubes Master Signing Key - 1 = I don't know or won't say - 2 = I do NOT trust - 3 = I trust marginally - 4 = I trust fully - 5 = I trust ultimately - m = back to the main menu +Please decide how far you trust this user to correctly verify other users' keys +(by looking at passports, checking fingerprints from different sources, etc.) - Your decision? 5 - Do you really want to set this key to ultimate trust? (y/N) y + 1 = I don't know or won't say + 2 = I do NOT trust + 3 = I trust marginally + 4 = I trust fully + 5 = I trust ultimately + m = back to the main menu - pub 4096R/36879494 created: 2010-04-01 expires: never usage: SC - trust: ultimate validity: unknown - [ unknown] (1). Qubes Master Signing Key - Please note that the shown key validity is not necessarily correct - unless you restart the program. +Your decision? 5 +Do you really want to set this key to ultimate trust? (y/N) y + +pub 4096R/36879494 created: 2010-04-01 expires: never usage: SC + trust: ultimate validity: unknown +[ unknown] (1). Qubes Master Signing Key +Please note that the shown key validity is not necessarily correct +unless you restart the program. - gpg> q +gpg> q +``` Now, when you import any of the legitimate Qubes developer keys and Release Signing Keys used to sign ISOs, RPMs, TGZs, Git tags, and Git commits, they will already be trusted in virtue of being signed by the Qubes Master Signing Key. - ### 2. Get the Release Signing Key The filename of the Release Signing Key for your version is `qubes-release-X-signing-key.asc`, where `X` is the major version number of your Qubes release. There are several ways to get the Release Signing Key for your Qubes release. - - If you have access to an existing Qubes installation, the release keys are available in dom0 in `/etc/pki/rpm-gpg/`. - These can be [copied][copy-from-dom0] into other VMs for further use. - In addition, every other VM contains the release key corresponding to that installation's release in `/etc/pki/rpm-gpg/`. +- If you have access to an existing Qubes installation, the release keys are available in dom0 in `/etc/pki/rpm-gpg/`. + These can be [copied][copy-from-dom0] into other VMs for further use. + In addition, every other VM contains the release key corresponding to that installation's release in `/etc/pki/rpm-gpg/`. - - Fetch it with GPG: +- Fetch it with GPG: - $ gpg2 --keyserver-options no-self-sigs-only,no-import-clean --fetch-keys https://keys.qubes-os.org/keys/qubes-release-X-signing-key.asc + ```shell_session + $ gpg2 --keyserver-options no-self-sigs-only,no-import-clean --fetch-keys https://keys.qubes-os.org/keys/qubes-release-X-signing-key.asc + ``` - - Download it as a file. - You can find the Release Signing Key for your Qubes version on the [Downloads] page. - You can also download all the currently used developers' signing keys, Release Signing Keys, and the Qubes Master Signing Key from the [Qubes Security Pack] and the [Qubes OS Keyserver]. - Once you've downloaded your Release Signing Key, import it with GPG: +- Download it as a file. + You can find the Release Signing Key for your Qubes version on the [Downloads] page. + You can also download all the currently used developers' signing keys, Release Signing Keys, and the Qubes Master Signing Key from the [Qubes Security Pack] and the [Qubes OS Keyserver]. + Once you've downloaded your Release Signing Key, import it with GPG: - $ gpg2 --keyserver-options no-self-sigs-only,no-import-clean --import ./qubes-release-X-signing-key.asc + ```shell_session + $ gpg2 --keyserver-options no-self-sigs-only,no-import-clean --import ./qubes-release-X-signing-key.asc + ``` The Release Signing Key should be signed by the Qubes Master Signing Key: - $ gpg2 --check-signatures "Qubes OS Release X Signing Key" - pub rsa4096 2017-03-06 [SC] - 5817A43B283DE5A9181A522E1848792F9E2795E9 - uid [ full ] Qubes OS Release X Signing Key - sig!3 1848792F9E2795E9 2017-03-06 Qubes OS Release X Signing Key - sig! DDFA1A3E36879494 2017-03-08 Qubes Master Signing Key +```shell_session +$ gpg2 --check-signatures "Qubes OS Release X Signing Key" +pub rsa4096 2017-03-06 [SC] + 5817A43B283DE5A9181A522E1848792F9E2795E9 +uid [ full ] Qubes OS Release X Signing Key +sig!3 1848792F9E2795E9 2017-03-06 Qubes OS Release X Signing Key +sig! DDFA1A3E36879494 2017-03-08 Qubes Master Signing Key - gpg: 2 good signatures +gpg: 2 good signatures +``` This is just an example, so the output you receive will not look exactly the same. What matters is the line that shows that this key is signed by the Qubes Master @@ -189,7 +202,6 @@ indicate a bad signature and `sig%` would mean that gpg encountered an error while verifying the signature. It is not necessary to independently verify the authenticity of the Release Signing Key. - ### 3. Verify your Qubes ISO Every Qubes ISO is released with a detached PGP signature file, which you can find on the [Downloads] page alongside the ISO. @@ -198,20 +210,20 @@ The signature filename is always the same as the ISO filename followed by `.asc` Once you've downloaded both the ISO and its signature file, you can verify the ISO using GPG: - $ gpg2 -v --verify Qubes-RX-x86_64.iso.asc Qubes-RX-x86_64.iso - gpg: armor header: Version: GnuPG v1 - gpg: Signature made Tue 08 Mar 2016 07:40:56 PM PST using RSA key ID 03FA5082 - gpg: using PGP trust model - gpg: Good signature from "Qubes OS Release X Signing Key" - gpg: binary signature, digest algorithm SHA256 +```shell_session +$ gpg2 -v --verify Qubes-RX-x86_64.iso.asc Qubes-RX-x86_64.iso +gpg: armor header: Version: GnuPG v1 +gpg: Signature made Tue 08 Mar 2016 07:40:56 PM PST using RSA key ID 03FA5082 +gpg: using PGP trust model +gpg: Good signature from "Qubes OS Release X Signing Key" +gpg: binary signature, digest algorithm SHA256 +``` This is just an example, so the output you receive will not look exactly the same. What matters is the line that says `Good signature from "Qubes OS Release X Signing Key"`. This confirms that the signature on the ISO is good. - -How to Verify Qubes ISO Digests -------------------------------- +## How to Verify Qubes ISO Digests Each Qubes ISO is also accompanied by a plain text file ending in `.DIGESTS`. This file contains the output of running several different cryptographic hash functions on the ISO in order to obtain alphanumeric outputs known as "digests" or "hash values." @@ -224,47 +236,51 @@ The digest filename is always the same as the ISO filename followed by `.DIGESTS Since the digest file is a plain text file, you can open it with any text editor. Inside, you should find text that looks similar to this: - -----BEGIN PGP SIGNED MESSAGE----- - Hash: SHA256 +``` +-----BEGIN PGP SIGNED MESSAGE----- +Hash: SHA256 - 3c951138b8b9867d8657f173c1b58b82 *Qubes-RX-x86_64.iso - 1fc9508160d7c4cba6cacc3025165b0f996c843f *Qubes-RX-x86_64.iso - 6b998045a513dcdd45c1c6e61ace4f1b4e7eff799f381dccb9eb0170c80f678a *Qubes-RX-x86_64.iso - de1eb2e76bdb48559906f6fe344027ece20658d4a7f04ba00d4e40c63723171c62bdcc869375e7a4a4499d7bff484d7a621c3acfe9c2b221baee497d13cd02fe *Qubes-RX-x86_64.iso - -----BEGIN PGP SIGNATURE----- - Version: GnuPG v2 - - iQIcBAEBCAAGBQJX4XO/AAoJEMsRyh0D+lCCL9sP/jlZ26zhvlDEX/eaA/ANa/6b - Dpsh/sqZEpz1SWoUxdm0gS+anc8nSDoCQSMBxnafuBbmwTChdHI/P7NvNirCULma - 9nw+EYCsCiNZ9+WCeroR8XDFSiDjvfkve0R8nwfma1XDqu1bN2ed4n/zNoGgQ8w0 - t5LEVDKCVJ+65pI7RzOSMbWaw+uWfGehbgumD7a6rfEOqOTONoZOjJJTnM0+NFJF - Qz5yBg+0FQYc7FmfX+tY801AwSyevj3LKGqZN1GVcU9hhoHH7f2BcbdNk9I5WHHq - doKMnZtcdyadQGwMNB68Wu9+0CWsXvk6E00QfW69M4d6w0gbyoJyUL1uzxgixb5O - qodxrqeitXQSZZvU4kom5zlSjqZs4dGK+Ueplpkr8voT8TSWer0Nbh/VMfrNSt1z - 0/j+e/KMjor7XxehR+XhNWa2YLjA5l5H9rP+Ct/LAfVFp4uhsAnYf0rUskhCStxf - Zmtqz4FOw/iSz0Os+IVcnRcyTYWh3e9XaW56b9J/ou0wlwmJ7oJuEikOHBDjrUph - 2a8AM+QzNmnc0tDBWTtT2frXcotqL+Evp/kQr5G5pJM/mTR5EQm7+LKSl7yCPoCj - g8JqGYYptgkxjQdX3YAy9VDsCJ/6EkFc2lkQHbgZxjXqyrEMbgeSXtMltZ7cCqw1 - 3N/6YZw1gSuvBlTquP27 - =e9oD - -----END PGP SIGNATURE----- +3c951138b8b9867d8657f173c1b58b82 *Qubes-RX-x86_64.iso +1fc9508160d7c4cba6cacc3025165b0f996c843f *Qubes-RX-x86_64.iso +6b998045a513dcdd45c1c6e61ace4f1b4e7eff799f381dccb9eb0170c80f678a *Qubes-RX-x86_64.iso +de1eb2e76bdb48559906f6fe344027ece20658d4a7f04ba00d4e40c63723171c62bdcc869375e7a4a4499d7bff484d7a621c3acfe9c2b221baee497d13cd02fe *Qubes-RX-x86_64.iso +-----BEGIN PGP SIGNATURE----- +Version: GnuPG v2 +iQIcBAEBCAAGBQJX4XO/AAoJEMsRyh0D+lCCL9sP/jlZ26zhvlDEX/eaA/ANa/6b +Dpsh/sqZEpz1SWoUxdm0gS+anc8nSDoCQSMBxnafuBbmwTChdHI/P7NvNirCULma +9nw+EYCsCiNZ9+WCeroR8XDFSiDjvfkve0R8nwfma1XDqu1bN2ed4n/zNoGgQ8w0 +t5LEVDKCVJ+65pI7RzOSMbWaw+uWfGehbgumD7a6rfEOqOTONoZOjJJTnM0+NFJF +Qz5yBg+0FQYc7FmfX+tY801AwSyevj3LKGqZN1GVcU9hhoHH7f2BcbdNk9I5WHHq +doKMnZtcdyadQGwMNB68Wu9+0CWsXvk6E00QfW69M4d6w0gbyoJyUL1uzxgixb5O +qodxrqeitXQSZZvU4kom5zlSjqZs4dGK+Ueplpkr8voT8TSWer0Nbh/VMfrNSt1z +0/j+e/KMjor7XxehR+XhNWa2YLjA5l5H9rP+Ct/LAfVFp4uhsAnYf0rUskhCStxf +Zmtqz4FOw/iSz0Os+IVcnRcyTYWh3e9XaW56b9J/ou0wlwmJ7oJuEikOHBDjrUph +2a8AM+QzNmnc0tDBWTtT2frXcotqL+Evp/kQr5G5pJM/mTR5EQm7+LKSl7yCPoCj +g8JqGYYptgkxjQdX3YAy9VDsCJ/6EkFc2lkQHbgZxjXqyrEMbgeSXtMltZ7cCqw1 +3N/6YZw1gSuvBlTquP27 +=e9oD +-----END PGP SIGNATURE----- +``` + Four digests have been computed for this ISO. The hash functions used, in order from top to bottom, are MD5, SHA1, SHA256, and SHA512. One way to verify that the ISO you downloaded matches any of these hash values is by using the respective `*sum` programs: - $ md5sum -c Qubes-RX-x86_64.iso.DIGESTS - Qubes-RX-x86_64.iso: OK - md5sum: WARNING: 23 lines are improperly formatted - $ sha1sum -c Qubes-RX-x86_64.iso.DIGESTS - Qubes-RX-x86_64.iso: OK - sha1sum: WARNING: 23 lines are improperly formatted - $ sha256sum -c Qubes-RX-x86_64.iso.DIGESTS - Qubes-RX-x86_64.iso: OK - sha256sum: WARNING: 23 lines are improperly formatted - $ sha512sum -c Qubes-RX-x86_64.iso.DIGESTS - Qubes-RX-x86_64.iso: OK - sha512sum: WARNING: 23 lines are improperly formatted +```shell_session +$ md5sum -c Qubes-RX-x86_64.iso.DIGESTS + Qubes-RX-x86_64.iso: OK +md5sum: WARNING: 23 lines are improperly formatted +$ sha1sum -c Qubes-RX-x86_64.iso.DIGESTS +Qubes-RX-x86_64.iso: OK +sha1sum: WARNING: 23 lines are improperly formatted +$ sha256sum -c Qubes-RX-x86_64.iso.DIGESTS +Qubes-RX-x86_64.iso: OK +sha256sum: WARNING: 23 lines are improperly formatted +$ sha512sum -c Qubes-RX-x86_64.iso.DIGESTS +Qubes-RX-x86_64.iso: OK +sha512sum: WARNING: 23 lines are improperly formatted +``` The `OK` response tells us that the hash value for that particular hash function matches. The program also warns us that there are 23 improperly formatted lines, but this is to be expected. @@ -274,14 +290,16 @@ Therefore, it is safe to ignore these warning lines. Another way is to use `openssl` to compute each hash value, then compare them to the contents of the digest file.: - $ openssl dgst -md5 Qubes-RX-x86_64.iso - MD5(Qubes-RX-x86_64.iso)= 3c951138b8b9867d8657f173c1b58b82 - $ openssl dgst -sha1 Qubes-RX-x86_64.iso - SHA1(Qubes-RX-x86_64.iso)= 1fc9508160d7c4cba6cacc3025165b0f996c843f - $ openssl dgst -sha256 Qubes-RX-x86_64.iso - SHA256(Qubes-RX-x86_64.iso)= 6b998045a513dcdd45c1c6e61ace4f1b4e7eff799f381dccb9eb0170c80f678a - $ openssl dgst -sha512 Qubes-RX-x86_64.iso - SHA512(Qubes-RX-x86_64.iso)= de1eb2e76bdb48559906f6fe344027ece20658d4a7f04ba00d4e40c63723171c62bdcc869375e7a4a4499d7bff484d7a621c3acfe9c2b221baee497d13cd02fe +```shell_session +$ openssl dgst -md5 Qubes-RX-x86_64.iso +MD5(Qubes-RX-x86_64.iso)= 3c951138b8b9867d8657f173c1b58b82 +$ openssl dgst -sha1 Qubes-RX-x86_64.iso +SHA1(Qubes-RX-x86_64.iso)= 1fc9508160d7c4cba6cacc3025165b0f996c843f +$ openssl dgst -sha256 Qubes-RX-x86_64.iso +SHA256(Qubes-RX-x86_64.iso)= 6b998045a513dcdd45c1c6e61ace4f1b4e7eff799f381dccb9eb0170c80f678a +$ openssl dgst -sha512 Qubes-RX-x86_64.iso +SHA512(Qubes-RX-x86_64.iso)= de1eb2e76bdb48559906f6fe344027ece20658d4a7f04ba00d4e40c63723171c62bdcc869375e7a4a4499d7bff484d7a621c3acfe9c2b221baee497d13cd02fe +``` (Notice that the outputs match the values from the digest file.) @@ -289,25 +307,25 @@ However, it is possible that an attacker replaced `Qubes-RX-x86_64.iso` with a m Therefore, ideally, we should also verify the authenticity of the listed hash values. Since `Qubes-RX-x86_64.iso.DIGESTS` is a clearsigned PGP file, we can use GPG to verify it from the command line: - 1. [Get the Qubes Master Signing Key and verify its authenticity][QMSK] - 2. [Get the Release Signing Key][RSK] - 3. Verify the signature in the digest file: - - $ gpg2 -v --verify Qubes-RX-x86_64.iso.DIGESTS - gpg: armor header: Hash: SHA256 - gpg: armor header: Version: GnuPG v2 - gpg: original file name='' - gpg: Signature made Tue 20 Sep 2016 10:37:03 AM PDT using RSA key ID 03FA5082 - gpg: using PGP trust model - gpg: Good signature from "Qubes OS Release X Signing Key" - gpg: textmode signature, digest algorithm SHA256 - +1. [Get the Qubes Master Signing Key and verify its authenticity][QMSK] +2. [Get the Release Signing Key][RSK] +3. Verify the signature in the digest file: + + ```shell_session + $ gpg2 -v --verify Qubes-RX-x86_64.iso.DIGESTS + gpg: armor header: Hash: SHA256 + gpg: armor header: Version: GnuPG v2 + gpg: original file name='' + gpg: Signature made Tue 20 Sep 2016 10:37:03 AM PDT using RSA key ID 03FA5082 + gpg: using PGP trust model + gpg: Good signature from "Qubes OS Release X Signing Key" + gpg: textmode signature, digest algorithm SHA256 + ``` + The signature is good. If our copy of the `Qubes OS Release X Signing Key` is being validated by the authentic Qubes Master Signing Key (see [above][QMSK]), we can be confident that these hash values came from the Qubes devs. - -How to Verify Qubes Repos -------------------------- +## How to Verify Qubes Repos Whenever you use one of the [Qubes repositories], you should verify the PGP signature in a tag on the latest commit or on the latest commit itself. (One or both may be present, but only one is required.) @@ -317,19 +335,27 @@ Instead, ask the person who pushed the unsigned commits to sign them. To verify a signature on a Git tag: - $ git tag -v +```shell_session +$ git tag -v +``` or - $ git verify-tag +```shell_session +$ git verify-tag +``` To verify a signature on a Git commit: - $ git log --show-signature +```shell_session +$ git log --show-signature +``` or - $ git verify-commit +```shell_session +$ git verify-commit +``` You should always perform this verification on a trusted local machine with properly validated keys (which are available in the [Qubes Security Pack]) rather than relying on a third party, such as GitHub. While the GitHub interface may claim that a commit has a verified signature from a member of the Qubes team, this is only trustworthy if GitHub has performed the signature check correctly, the account identity is authentic, the user's key has not been replaced by an admin, GitHub's servers have not been compromised, and so on. @@ -337,62 +363,51 @@ Since there's no way for you to be certain that all such conditions hold, you're Also see: [Distrusting the Infrastructure] - -Troubleshooting FAQ -------------------- - +## Troubleshooting FAQ ### Why am I getting "Can't check signature: public key not found"? You don't have the correct [Release Signing Key][RSK]. - ### Why am I getting "BAD signature from 'Qubes OS Release X Signing Key'"? The problem could be one or more of the following: - - You're trying to verify the wrong file(s). - Read this page again carefully. - - You're using the wrong GPG command. - Follow the examples in [Verify your Qubes ISO][signature file] carefully. - - The ISO or [signature file] is bad (e.g., incomplete or corrupt download). - Try downloading the signature file again from a different source, then try verifying again. - If you still get the same result, try downloading the ISO again from a different source, then try verifying again. - +- You're trying to verify the wrong file(s). + Read this page again carefully. +- You're using the wrong GPG command. + Follow the examples in [Verify your Qubes ISO][signature file] carefully. +- The ISO or [signature file] is bad (e.g., incomplete or corrupt download). + Try downloading the signature file again from a different source, then try verifying again. + If you still get the same result, try downloading the ISO again from a different source, then try verifying again. ### I'm getting "bash: gpg2: command not found" You don't have `gpg2` installed. Please install it using the method appropriate for your environement (e.g., via your package manager). - ### Why am I getting "can't open signed data `Qubes-RX-x86_64.iso' / can't hash datafile: file open error"? The correct ISO is not in your working directory. - ### Why am I getting "can't open `Qubes-RX-x86_64.iso.asc' / verify signatures failed: file open error"? The correct [signature file] is not in your working directory. - ### Why am I getting "no valid OpenPGP data found"? Either you don't have the correct [signature file], or you inverted the arguments to `gpg2`. ([The signature file goes first.][signature file]) - ### Why am I getting "WARNING: This key is not certified with a trusted signature! There is no indication that the signature belongs to the owner."? Either you don't have the [Qubes Master Signing Key][QMSK], or you didn't [set its trust level correctly][QMSK]. - ### Why am I getting "X signature not checked due to a missing key"? You don't have the keys that created those signatures in your keyring. For present purposes, you don't need them as long as you have the [Qubes Master Signing Key][QMSK] and the [Release Signing Key][RSK] for your Qubes version. - ### Why am I seeing additional signatures on a key with "[User ID not found]" or from a revoked key? This is just a basic part of how OpenPGP works. @@ -400,43 +415,35 @@ Anyone can sign anyone else's public key and upload the signed public key to key Everyone is also free to revoke their own keys at any time (assuming they possess or can create a revocation certificate). This has no impact on verifying Qubes ISOs, code, or keys. - ### Why am I getting "verify signatures failed: unexpected data"? You're not verifying against the correct [signature file]. - ### Why am I getting "not a detached signature"? You're not verifying against the correct [signature file]. - ### Why am I getting "CRC error; [...] no signature found [...]"? You're not verifying against the correct [signature file], or the signature file has been modified. Try downloading it again or from a different source. - ### Do I have to verify the ISO against both the [signature file] and the [digest file]? No, either method is sufficient by itself. - ### Why am I getting "no properly formatted X checksum lines found"? You're not checking the correct [digest file]. - ### Why am I getting "WARNING: X lines are improperly formatted"? Read [How to Verify Qubes ISO Digests][digest file] again. - ### Why am I getting "WARNING: 1 listed file could not be read"? The correct ISO is not in your working directory. - ### I have another problem that isn't mentioned here. Carefully read this page again to be certain that you didn't skip any steps. @@ -445,7 +452,6 @@ If your question is about GPG, please see the [GPG documentation]. Still have question? Please see [Help, Support, Mailing Lists, and Forum] for places where you can ask! - [website-trust]: /faq/#should-i-trust-this-website [Distrusting the Infrastructure]: /faq/#what-does-it-mean-to-distrust-the-infrastructure [verifying repos]: #how-to-verify-qubes-repos diff --git a/en/_doc/project-security/xsa.md b/en/_doc/project-security/xsa.md index 902896bbed..0fc000c4fd 100644 --- a/en/_doc/project-security/xsa.md +++ b/en/_doc/project-security/xsa.md @@ -18,9 +18,9 @@ Under the "Is Qubes Affected?" column, there are two possible values: **Yes** or * **Yes** means that the *security* of Qubes OS *is* affected. * **No** means that the *security* of Qubes OS is *not* affected. - Important Notes --------------- + * For the purpose of this tracker, we do *not* classify mere [denial-of-service (DoS) attacks][DoS] as affecting the *security* of Qubes OS. Therefore, if an XSA pertains *only* to DoS attacks against Qubes, the value in the "Is Qubes Affected?" column will be **No**. * For simplicity, we use the present tense ("is affected") throughout this page, but this does **not** necessarily mean that up-to-date Qubes installations are *currently* affected by any particular XSA. From 40171d0f6de6fc0023f802fd923e28a5dc04f7a6 Mon Sep 17 00:00:00 2001 From: dd Date: Tue, 17 Nov 2020 15:45:05 +0100 Subject: [PATCH 120/663] linted docs in user advanced-configuration --- .../user/advanced-configuration/awesome.md | 11 +- .../user/advanced-configuration/bind-dirs.md | 7 +- .../advanced-configuration/config-files.md | 32 +-- .../disposablevm-customization.md | 206 +++++++++++------- en/_doc/user/advanced-configuration/i3.md | 36 ++- .../installing-contributed-packages.md | 21 +- en/_doc/user/advanced-configuration/kde.md | 28 +-- .../managing-vm-kernel.md | 71 +++--- .../mount-from-other-os.md | 80 +++---- .../newer-hardware-troubleshooting.md | 1 - .../resize-disk-image.md | 31 ++- en/_doc/user/advanced-configuration/salt.md | 99 +++++---- .../secondary-storage.md | 80 ++++--- .../user/advanced-configuration/usb-qubes.md | 134 ++++++------ 14 files changed, 492 insertions(+), 345 deletions(-) diff --git a/en/_doc/user/advanced-configuration/awesome.md b/en/_doc/user/advanced-configuration/awesome.md index e0dc1555e6..f0a0ea688c 100644 --- a/en/_doc/user/advanced-configuration/awesome.md +++ b/en/_doc/user/advanced-configuration/awesome.md @@ -20,15 +20,19 @@ title: awesome awesome can be installed with the standard dom0 installation mechanisms. - $ sudo qubes-dom0-update awesome - +```shell_session +$ sudo qubes-dom0-update awesome +``` + That's it. After logging out, you can select awesome in the login manager. ## Development To [contribute code](/doc/contributing/) you may clone the awesome repository as follows: - $ git clone https://github.com/QubesOS/qubes-desktop-linux-awesome +```shell_session +$ git clone https://github.com/QubesOS/qubes-desktop-linux-awesome +``` For build instructions please check the repository _README_. @@ -67,6 +71,7 @@ In particular the following events are not meant to cause a focus change: * mouse move without click (sloppy focus) For the below example other requests from applications to the window manager are meant to be ignored in general as well, e.g.: + * windows shouldn't be able to maximize themselves without the user giving a respective command to the WM (simple test: Firefox F11 next to another window) * windows shouldn't be able to change their size themselves * windows shouldn't be able to modify their borders in any way diff --git a/en/_doc/user/advanced-configuration/bind-dirs.md b/en/_doc/user/advanced-configuration/bind-dirs.md index 1edb902cfe..0291142341 100644 --- a/en/_doc/user/advanced-configuration/bind-dirs.md +++ b/en/_doc/user/advanced-configuration/bind-dirs.md @@ -51,8 +51,10 @@ From now on any files within the `/var/lib/tor` folder will persist across reboo You can make make many files or folders persist, simply by making multiple entries in the `50_user.conf` file, each on a separate line. For example, if you added the file `/etc/tor/torrc` to the `binds` variable, any modifications to *that* file will persist across reboots. - binds+=( '/var/lib/tor' ) - binds+=( '/etc/tor/torrc' ) +``` +binds+=( '/var/lib/tor' ) +binds+=( '/etc/tor/torrc' ) +``` ## Other Configuration Folders ## @@ -70,7 +72,6 @@ Creation of the files and folders in `/rw/bind-dirs` should be automatic the fir If you want to circumvent this process, you can create the relevant file structure under `/rw/bind-dirs` and make any changes at the same time that you perform the configuration, before reboot. Note that you must create the full folder structure under `/rw/bind-dirs` - e.g you would have to create `/rw/bind-dirs/var/lib/tor` - ## Limitations ## * Files that exist in the TemplateVM root image cannot be deleted in the TemplateBasedVMs root image using bind-dirs.sh. diff --git a/en/_doc/user/advanced-configuration/config-files.md b/en/_doc/user/advanced-configuration/config-files.md index f303901851..1518efc658 100644 --- a/en/_doc/user/advanced-configuration/config-files.md +++ b/en/_doc/user/advanced-configuration/config-files.md @@ -21,7 +21,7 @@ These files are placed in `/rw`, which survives a VM restart. That way, they can be used to customize a single VM instead of all VMs based on the same template. The scripts here all run as root. -- `/rw/config/rc.local` - script runs at VM startup. +- `/rw/config/rc.local` - script runs at VM startup. Good place to change some service settings, replace config files with its copy stored in `/rw/config`, etc. Example usage: @@ -36,10 +36,10 @@ The scripts here all run as root. echo '127.0.0.1 example.com' >> /etc/hosts ~~~ -- `/rw/config/qubes-ip-change-hook` - script runs in NetVM after every external IP change and on "hardware" link status change. +- `/rw/config/qubes-ip-change-hook` - script runs in NetVM after every external IP change and on "hardware" link status change. -- In ProxyVMs (or AppVMs with `qubes-firewall` service enabled), scripts placed in the following directories will be executed in the listed order followed by `qubes-firewall-user-script` after each firewall update. - Good place to write custom firewall rules. +- In ProxyVMs (or AppVMs with `qubes-firewall` service enabled), scripts placed in the following directories will be executed in the listed order followed by `qubes-firewall-user-script` after each firewall update. + Good place to write custom firewall rules. ~~~ /etc/qubes/qubes-firewall.d @@ -47,11 +47,12 @@ The scripts here all run as root. /rw/config/qubes-firewall-user-script ~~~ -- `/rw/config/suspend-module-blacklist` - list of modules (one per line) to be unloaded before system goes to sleep. - The file is used only in a VM with PCI devices attached. - Intended for use with problematic device drivers. +- `/rw/config/suspend-module-blacklist` - list of modules (one per line) to be unloaded before system goes to sleep. + The file is used only in a VM with PCI devices attached. + Intended for use with problematic device drivers. - In NetVMs/ProxyVMs, scripts placed in `/rw/config/network-hooks.d` will be ran when configuring Qubes interfaces. For each script, the `command`, `vif`, `vif_type` and `ip` is passed as arguments (see `/etc/xen/scripts/vif-route-qubes`). For example, consider a PV AppVM `work` with IP `10.137.0.100` and `sys-firewall` as NetVM. Assuming it's Xen domain id is arbitrary `12` then, the following script located at `/rw/config/network-hooks.d/hook-100.sh` in `sys-firewall`: + ~~~ #!/bin/bash @@ -78,7 +79,6 @@ Note that scripts need to be executable (`chmod +x`) to be used. Also, take a look at [bind-dirs](/doc/bind-dirs) for instructions on how to easily modify arbitrary system files in an AppVM and have those changes persist. - GUI and audio configuration in dom0 ----------------------------------- @@ -117,31 +117,31 @@ VM: { Currently supported settings: -- `allow_fullscreen` - allow VM to request its windows to go fullscreen (without any colorful frame). +- `allow_fullscreen` - allow VM to request its windows to go fullscreen (without any colorful frame). **Note:** Regardless of this setting, you can always put a window into fullscreen mode in Xfce4 using the trusted window manager by right-clicking on a window's title bar and selecting "Fullscreen". This functionality should still be considered safe, since a VM window still can't voluntarily enter fullscreen mode. The user must select this option from the trusted window manager in dom0. To exit fullscreen mode from here, press `alt` + `space` to bring up the title bar menu again, then select "Leave Fullscreen". -- `allow_utf8_titles` - allow the use of UTF-8 in window titles; otherwise, non-ASCII characters are replaced by an underscore. +- `allow_utf8_titles` - allow the use of UTF-8 in window titles; otherwise, non-ASCII characters are replaced by an underscore. -- `secure_copy_sequence` and `secure_paste_sequence` - key sequences used to trigger secure copy and paste. +- `secure_copy_sequence` and `secure_paste_sequence` - key sequences used to trigger secure copy and paste. -- `audio_low_latency` - force low-latency audio mode (about 40ms compared to 200-500ms by default). - Note that this will cause much higher CPU usage in dom0. It's enabled by - default, disabling it may save CPU in dom0. +- `audio_low_latency` - force low-latency audio mode (about 40ms compared to 200-500ms by default). + Note that this will cause much higher CPU usage in dom0. It's enabled by + default, disabling it may save CPU in dom0. - `trayicon_mode` - defines the trayicon coloring mode. Options are - `bg` - color full icon background to the VM color - `border1` - add 1px border at the icon edges - `border2` - add 1px border 1px from the icon edges - `tint` - tinttint icon to the VM color, can be used with additional - modifiers (you can enable multiple of them) + modifiers (you can enable multiple of them) - `tint+border1,tint+border2` - same as tint, but also add a border - `tint+saturation50` - same as tint, but reduce icon saturation by 50% - `tint+whitehack` - same as tint, but change white pixels (0xffffff) to - almost-white (0xfefefe) + almost-white (0xfefefe) - `log level` - defines the log options logs can take. It can have a value of 0 (only errors), 1 (some basic messages), and 2 (debug). diff --git a/en/_doc/user/advanced-configuration/disposablevm-customization.md b/en/_doc/user/advanced-configuration/disposablevm-customization.md index a79c85a100..48b6c13d7b 100644 --- a/en/_doc/user/advanced-configuration/disposablevm-customization.md +++ b/en/_doc/user/advanced-configuration/disposablevm-customization.md @@ -14,19 +14,21 @@ title: DisposableVM Customization # DisposableVM Customization - ## Introduction A DisposableVM (previously known as a "DispVM") in can be based on any TemplateBasedVM. You can also choose to use different DisposableVM Templates for different DisposableVMs. To prepare AppVM to be a DisposableVM Template, you need to set `template_for_dispvms` property, for example: - [user@dom0 ~]$ qvm-prefs fedora-26-dvm template_for_dispvms True +```shell_session +[user@dom0 ~]$ qvm-prefs fedora-26-dvm template_for_dispvms True +``` Additionally, if you want to have menu entries for starting applications in DisposableVM based on this AppVM (instead of in the AppVM itself), you can achieve it with `appmenus-dispvm` feature: - [user@dom0 ~]$ qvm-features fedora-26-dvm appmenus-dispvm 1 - +```shell_session +[user@dom0 ~]$ qvm-features fedora-26-dvm appmenus-dispvm 1 +``` ## Security @@ -36,25 +38,27 @@ In particular, the *default* DisposableVM Template is important because it is us This means that it will have access to everything that you open with this feature. For this reason, it is strongly recommended that you base the default DisposableVM Template on a trusted TemplateVM and refrain from making any risky customizations to it. - ## Creating a new DisposableVM Template In Qubes 4.0, you're no longer restricted to a single DisposableVM Template. Instead, you can create as many as you want. Whenever you start a new DisposableVM, you can choose to base it on whichever DisposableVM Template you like. To create new DisposableVM Template, lets say `custom-disposablevm-template`, based on `debian-9` template, use following commands: - [user@dom0 ~]$ qvm-create --template debian-9 --label red custom-disposablevm-template - [user@dom0 ~]$ qvm-prefs custom-disposablevm-template template_for_dispvms True - [user@dom0 ~]$ qvm-features custom-disposablevm-template appmenus-dispvm 1 +```shell_session +[user@dom0 ~]$ qvm-create --template debian-9 --label red custom-disposablevm-template +[user@dom0 ~]$ qvm-prefs custom-disposablevm-template template_for_dispvms True +[user@dom0 ~]$ qvm-features custom-disposablevm-template appmenus-dispvm 1 +``` Additionally you may want to set it as default DisposableVM Template: - [user@dom0 ~]$ qubes-prefs default_dispvm custom-disposablevm-template +```shell_session +[user@dom0 ~]$ qubes-prefs default_dispvm custom-disposablevm-template +``` The above default is used whenever a qube request starting a new DisposableVM and do not specify which one (for example `qvm-open-in-dvm` tool). This can be also set in qube settings and will affect service calls from that qube. See [qrexec documentation](/doc/qrexec/#specifying-vms-tags-types-targets-etc) for details. If you wish to use a [Minimal TemplateVM](/doc/templates/minimal/) as a DisposableVM Template, please see the [Minimal TemplateVM](/doc/templates/minimal/) page. - ## Customization of DisposableVM _**Note:** If you are trying to customize Tor Browser in a Whonix DisposableVM, please consult the [Whonix documentation](https://www.whonix.org/wiki/Tor_Browser/Advanced_Users#DVM_Template_Customization)._ @@ -62,17 +66,18 @@ _**Note:** If you are trying to customize Tor Browser in a Whonix DisposableVM, It is possible to change the settings for each new DisposableVM. This can be done by customizing the DisposableVM Template on which it is based: -1. Start a terminal in the `fedora-26-dvm` qube (or another DisposableVM Template) by running the following command in a dom0 terminal. (If you enable `appmenus-dispvm` feature (as explained at the top), applications menu for this VM (`fedora-26-dvm`) will be "Disposable: fedora-26-dvm" (instead of "Domain: fedora-26-dvm") and entries there will start new DisposableVM based on that VM (`fedora-26-dvm`). Not in that VM (`fedora-26-dvm`) itself). - - [user@dom0 ~]$ qvm-run -a fedora-26-dvm gnome-terminal +1. Start a terminal in the `fedora-26-dvm` qube (or another DisposableVM Template) by running the following command in a dom0 terminal. (If you enable `appmenus-dispvm` feature (as explained at the top), applications menu for this VM (`fedora-26-dvm`) will be "Disposable: fedora-26-dvm" (instead of "Domain: fedora-26-dvm") and entries there will start new DisposableVM based on that VM (`fedora-26-dvm`). Not in that VM (`fedora-26-dvm`) itself). -2. Change the qube's settings and/or applications, as desired. Some examples of changes you may want to make include: - - Changing Firefox's default startup settings and homepage. - - Changing default editor, image viewer. In Debian-based templates this can be done with the `mimeopen` command. - - Changing the DisposableVM's default NetVM. For example, you may wish to set the NetVM to "none." Then, whenever you start a new DisposableVM, you can choose your desired ProxyVM manually (by changing the newly-started DisposableVMs settings). This is useful if you sometimes wish to use a DisposableVM with a Whonix Gateway, for example. It is also useful if you sometimes wish to open untrusted files in a network-disconnected DisposableVM. + ```shell_session + [user@dom0 ~]$ qvm-run -a fedora-26-dvm gnome-terminal + ``` -4. Shutdown the qube (either by `poweroff` from qube's terminal, or `qvm-shutdown` from dom0 terminal). +2. Change the qube's settings and/or applications, as desired. Some examples of changes you may want to make include: + - Changing Firefox's default startup settings and homepage. + - Changing default editor, image viewer. In Debian-based templates this can be done with the `mimeopen` command. + - Changing the DisposableVM's default NetVM. For example, you may wish to set the NetVM to "none." Then, whenever you start a new DisposableVM, you can choose your desired ProxyVM manually (by changing the newly-started DisposableVMs settings). This is useful if you sometimes wish to use a DisposableVM with a Whonix Gateway, for example. It is also useful if you sometimes wish to open untrusted files in a network-disconnected DisposableVM. +4. Shutdown the qube (either by `poweroff` from qube's terminal, or `qvm-shutdown` from dom0 terminal). ## Using static DisposableVMs for sys-* @@ -131,7 +136,6 @@ qvm-prefs sys-firewall netvm sys-net2 qubes-prefs clockvm sys-net2 ~~~ - ## Adding programs to DisposableVM Application Menu For added convenience, arbitrary programs can be added to the Application Menu of the DisposableVM. @@ -140,27 +144,27 @@ In order to do that, select "Qube settings" entry in selected base AppVM, go to Note that currently only applications whose main process keeps running until you close the application (i.e. do not start a background process instead) will work. One of known examples of incompatible applications is GNOME Terminal (shown on the list as "Terminal"). Choose different terminal emulator (like XTerm) instead. - ## Create Custom sys-net sys-firewall and sys-usb DisposableVMs Users have the option of creating customized DisposableVMs for the `sys-net`, `sys-firewall` and `sys-usb` VMs. In this configuration, a fresh VM instance is created each time a DisposableVM is launched. Functionality is near-identical to the default VMs created following a new Qubes’ installation, except the user benefits from a non-persistent filesystem. Functionality is not limited, users can: - * Set custom firewall rule sets and run Qubes VPN scripts. - * Set DisposableVMs to autostart at system boot. - * Attach PCI devices with the `--persistent` option. +- Set custom firewall rule sets and run Qubes VPN scripts. +- Set DisposableVMs to autostart at system boot. +- Attach PCI devices with the `--persistent` option. Using DisposableVMs in this manner is ideal for untrusted qubes which require persistent PCI devices, such as USB VMs and NetVMs. >_**Note:**_ Users who want customized VPN or firewall rule sets must create a separate DisposableVM Template for use by each DisposableVM. If DisposableVM Template customization is not needed, then a single DisposableVM Template is used as a template for all DisposableVMs. - ### Create and configure the DisposableVM Template on which the DisposableVM will be based 1. Create the DisposableVM Template: - [user@dom0 ~]$ qvm-create --class AppVM --label gray + ```shell_session + [user@dom0 ~]$ qvm-create --class AppVM --label gray + ``` 2. _(optional)_ In the DisposableVM Template, add custom firewall rule sets, Qubes VPN scripts, etc. @@ -168,46 +172,65 @@ Using DisposableVMs in this manner is ideal for untrusted qubes which require pe 3. Set the DisposableVM Template as template for DisposableVMs: - [user@dom0 ~]$ qvm-prefs template_for_dispvms true - + ```shell_session + [user@dom0 ~]$ qvm-prefs template_for_dispvms true + ``` ### Create the sys-net DisposableVM 1. Create `sys-net` DisposableVM based on the DisposableVM Template: - [user@dom0 ~]$ qvm-create --template --class DispVM --label red disp-sys-net + ```shell_session + [user@dom0 ~]$ qvm-create --template --class DispVM --label red disp-sys-net + ``` 2. Set `disp-sys-net` virtualization mode to [hvm](/doc/hvm/): - [user@dom0 ~]$ qvm-prefs disp-sys-net virt_mode hvm + ```shell_session + [user@dom0 ~]$ qvm-prefs disp-sys-net virt_mode hvm + ``` 3. Set `disp-sys-net` to provide network for other VMs: - [user@dom0 ~]$ qvm-prefs disp-sys-net provides_network true + ```shell_session + [user@dom0 ~]$ qvm-prefs disp-sys-net provides_network true + ``` 4. Set `disp-sys-net` NetVM to none: - [user@dom0 ~]$ qvm-prefs disp-sys-net netvm "" + ```shell_session + [user@dom0 ~]$ qvm-prefs disp-sys-net netvm "" + ``` 5. List all available PCI devices to determine the correct _backend:BDF_ address(es) to assign to `disp-sys-net`: - [user@dom0 ~]$ qvm-pci + ```shell_session + [user@dom0 ~]$ qvm-pci + ``` 6. Attach the network PCI device(s) to `disp-sys-net` (finding and assigning PCI devices can be found [here](/doc/pci-devices/): - [user@dom0 ~]$ qvm-pci attach --persistent disp-sys-net : + ```shell_session + [user@dom0 ~]$ qvm-pci attach --persistent disp-sys-net : + ``` 7. _(recommended)_ Set `disp-sys-net` to start automatically when Qubes boots: - [user@dom0 ~]$ qvm-prefs disp-sys-net autostart true - + ```shell_session + [user@dom0 ~]$ qvm-prefs disp-sys-net autostart true + ``` + 8. _(recommended)_ Disable the `appmenus-dispvm` feature, as disp-sys-net is not itself a DisposableVM template (Note: this is only necessary if you enabled the `appmenus-dispvm` feature for the DisposableVM template): - [user@dom0 ~]$ qvm-features disp-sys-net appmenus-dispvm '' - + ```shell_session + [user@dom0 ~]$ qvm-features disp-sys-net appmenus-dispvm '' + ``` + 9. _(optional)_ Set `disp-sys-net` as the dom0 time source: - [user@dom0 ~]$ qubes-prefs clockvm disp-sys-net + ```shell_session + [user@dom0 ~]$ qubes-prefs clockvm disp-sys-net + ``` 10. _(recommended)_ Allow templates to be updated via `disp-sys-net`. In dom0, edit `/etc/qubes-rpc/policy/qubes.UpdatesProxy` to change the target from `sys-net` to `disp-sys-net`. @@ -215,109 +238,146 @@ Using DisposableVMs in this manner is ideal for untrusted qubes which require pe 1. Create `sys-firewall` DisposableVM: - [user@dom0 ~]$ qvm-create --template --class DispVM --label green disp-sys-firewall + ```shell_session + [user@dom0 ~]$ qvm-create --template --class DispVM --label green disp-sys-firewall + ``` 2. Set `disp-sys-firewall` to provide network for other VMs: - [user@dom0 ~]$ qvm-prefs disp-sys-firewall provides_network true + ```shell_session + [user@dom0 ~]$ qvm-prefs disp-sys-firewall provides_network true + ``` 3. Set `disp-sys-net` as the NetVM for `disp-sys-firewall`: - [user@dom0 ~]$ qvm-prefs disp-sys-firewall netvm disp-sys-net + ```shell_session + [user@dom0 ~]$ qvm-prefs disp-sys-firewall netvm disp-sys-net + ``` 4. Set `disp-sys-firewall` as NetVM for other AppVMs: - [user@dom0 ~]$ qvm-prefs netvm disp-sys-firewall + ```shell_session + [user@dom0 ~]$ qvm-prefs netvm disp-sys-firewall + ``` 5. _(recommended)_ Set `disp-sys-firewall` to auto-start when Qubes boots: - [user@dom0 ~]$ qvm-prefs disp-sys-firewall autostart true - + ```shell_session + [user@dom0 ~]$ qvm-prefs disp-sys-firewall autostart true + ``` + 6. _(recommended)_ Disable the `appmenus-dispvm` feature, as disp-sys-firewall is not itself a DisposableVM template (Note: this is only necessary if you enabled the `appmenus-dispvm` feature for the DisposableVM template): - [user@dom0 ~]$ qvm-features disp-sys-firewall appmenus-dispvm '' + ```shell_session + [user@dom0 ~]$ qvm-features disp-sys-firewall appmenus-dispvm '' + ``` 7. _(optional)_ Set `disp-sys-firewall` as the default NetVM: - [user@dom0 ~]$ qubes-prefs default_netvm disp-sys-firewall - + ```shell_session + [user@dom0 ~]$ qubes-prefs default_netvm disp-sys-firewall + ``` ### Create the sys-usb DisposableVM 1. Create the `disp-sys-usb`: - [user@dom0 ~]$ qvm-create --template --class DispVM --label red disp-sys-usb + ```shell_session + [user@dom0 ~]$ qvm-create --template --class DispVM --label red disp-sys-usb + ``` 2. Set the `disp-sys-usb` virtualization mode to hvm: - [user@dom0 ~]$ qvm-prefs disp-sys-usb virt_mode hvm + ```shell_session + [user@dom0 ~]$ qvm-prefs disp-sys-usb virt_mode hvm + ``` 3. Set `disp-sys-usb` NetVM to none: - [user@dom0 ~]$ qvm-prefs disp-sys-usb netvm "" + ```shell_session + [user@dom0 ~]$ qvm-prefs disp-sys-usb netvm "" + ``` 4. List all available PCI devices: - [user@dom0 ~]$ qvm-pci + ```shell_session + [user@dom0 ~]$ qvm-pci + ``` 5. Attach the USB controller to the `disp-sys-usb`: - - >_**Note:**_ Most of the commonly used USB controllers (all Intel integrated controllers) require the `-o no-strict-reset=True` option to be set. Instructions detailing how this option is set can be found [here](/doc/pci-devices/#no-strict-reset). + >_**Note:**_ Most of the commonly used USB controllers (all Intel integrated controllers) require the `-o no-strict-reset=True` option to be set. Instructions detailing how this option is set can be found [here](/doc/pci-devices/#no-strict-reset). + + ```shell_session + [user@dom0 ~]$ qvm-pci attach --persistent disp-sys-usb : + ``` - [user@dom0 ~]$ qvm-pci attach --persistent disp-sys-usb : - 6. _(optional)_ Set `disp-sys-usb` to auto-start when Qubes boots: - - [user@dom0 ~]$ qvm-prefs disp-sys-usb autostart true - + + ```shell_session + [user@dom0 ~]$ qvm-prefs disp-sys-usb autostart true + ``` + 7. _(recommended)_ Disable the `appmenus-dispvm` feature, as disp-sys-usb is not itself a DisposableVM template (Note: this is only necessary if you enabled the `appmenus-dispvm` feature for the DisposableVM template): - [user@dom0 ~]$ qvm-features disp-sys-usb appmenus-dispvm '' + ```shell_session + [user@dom0 ~]$ qvm-features disp-sys-usb appmenus-dispvm '' + ``` 8. Users should now follow instructions on [How to hide USB controllers from dom0](/doc/usb-qubes/#how-to-hide-all-usb-controllers-from-dom0). 9. At this point, your mouse may not work. Edit the `qubes.InputMouse` policy file in dom0, which is located here: - /etc/qubes-rpc/policy/qubes.InputMouse + ``` + /etc/qubes-rpc/policy/qubes.InputMouse + ``` Add a line like this to the top of the file: - disp-sys-usb dom0 allow,user=root - + ``` + disp-sys-usb dom0 allow,user=root + ``` ### Starting the DisposableVMs Prior to starting the new VMs, users should ensure that no other VMs such as the old `sys-net` and `sys-usb` VMs are running. This is because no two VMs can share the same PCI device while both running. It is recommended that users detach the PCI devices from the old VMs without deleting them. This will allow users to reattach the PCI devices if the newly created DisposableVMs fail to start. - Detach PCI device from VM: - - [user@dom0~]$ qvm-pci detach : +Detach PCI device from VM: +```shell_session +[user@dom0~]$ qvm-pci detach : +``` ### Troubleshooting If the `disp-sys-usb` does not start, it could be due to a PCI passthrough problem. For more details on this issue along with possible solutions, users can look [here](/doc/pci-troubleshooting/#pci-passthrough-issues). - ## Deleting DisposableVMs While working in a DisposableVM, you may want to open a document in another DisposableVM. For this reason, the property `default_dispvm` may be set to the name of your DisposableVM in a number of VMs: - [user@dom0 ~]$ qvm-prefs workvm | grep default_dispvm - default_dispvm - custom-disposablevm-template +```shell_session +[user@dom0 ~]$ qvm-prefs workvm | grep default_dispvm +default_dispvm - custom-disposablevm-template +``` This will prevent the deletion of the DisposableVM Template. In order to fix this you need to unset the `default_dispvm` property: - [user@dom0 ~]$ qvm-prefs workvm default_dispvm "" +```shell_session +[user@dom0 ~]$ qvm-prefs workvm default_dispvm "" +``` You can then delete the DisposableVM Template: - [user@dom0 ~]$ qvm-remove custom-disposablevm-template - This will completely remove the selected VM(s) - custom-disposablevm-template +```shell_session +[user@dom0 ~]$ qvm-remove custom-disposablevm-template +``` + +This will completely remove the selected VM(s) `custom-disposablevm-template` If you still encounter the issue, you may have forgot to clean an entry. Looking at the system logs will help you: - [user@dom0 ~]$ journalctl | tail +```shell_session +[user@dom0 ~]$ journalctl | tail +``` diff --git a/en/_doc/user/advanced-configuration/i3.md b/en/_doc/user/advanced-configuration/i3.md index 63ba4edd3e..43e1edccd7 100644 --- a/en/_doc/user/advanced-configuration/i3.md +++ b/en/_doc/user/advanced-configuration/i3.md @@ -16,7 +16,9 @@ i3 is part of the stable repository (as of Qubes R3.1) and can be installed by using the [dom0 update mechanism](/doc/software-update-dom0/). To install the i3 window manager and the its Qubes specific configuration: - $ sudo qubes-dom0-update i3 i3-settings-qubes +```shell_session +$ sudo qubes-dom0-update i3 i3-settings-qubes +``` The Qubes-specific configuration (package `i3-settings-qubes`) can be installed optionally in case you would prefer writing your own configuration (see @@ -44,7 +46,9 @@ installed through the package manager. Clone the i3-qubes repository here: - $ git clone https://github.com/QubesOS/qubes-desktop-linux-i3 +```shell_session +$ git clone https://github.com/QubesOS/qubes-desktop-linux-i3 +``` In this case, the most interesting file is probably `i3/0001-Show-qubes-domain-in-non-optional-colored-borders.patch` It's the patch @@ -60,15 +64,19 @@ it. You'll need to install the build dependencies, which are listed in build-deps.list. You can verify them and then install them with: - $ sudo dnf install -y $(cat build-deps.list) +```shell_session +$ sudo dnf install -y $(cat build-deps.list) +``` This used to be more complicated, but I finally redid this and use the same buildsystem that's used by Qubes OS for XFCE. It's just a Makefile that helps you get the sources and start off the build: - $ make get-sources - $ make verify-sources - $ make rpms +```shell_session +$ make get-sources +$ make verify-sources +$ make rpms +``` ### Installing @@ -80,17 +88,23 @@ next step. Now in dom0, copy in the rpm: - $ qvm-run --pass-io 'cat ' > i3.rpm +```shell_session +$ qvm-run --pass-io 'cat ' > i3.rpm +``` Now that the rpm is in dom0 we can proceed with installing it. i3 has some dependencies that we can easily install with: - $ sudo qubes-dom0-update perl-AnyEvent-I3 xorg-x11-apps \\ - rxvt-unicode xcb-util-wm perl-JSON-XS xcb-util-cursor \\ - dzen2 dmenu xorg-x11-fonts-misc libev +```shell_session +$ sudo qubes-dom0-update perl-AnyEvent-I3 xorg-x11-apps \\ + rxvt-unicode xcb-util-wm perl-JSON-XS xcb-util-cursor \\ + dzen2 dmenu xorg-x11-fonts-misc libev +``` After that you can just install the generated rpm like any other local package: - $ sudo yum localinstall i3.rpm +```shell_session +$ sudo yum localinstall i3.rpm +``` Log out, select i3, then log in again. diff --git a/en/_doc/user/advanced-configuration/installing-contributed-packages.md b/en/_doc/user/advanced-configuration/installing-contributed-packages.md index 6a4fd6c1ce..fceed5bfb7 100644 --- a/en/_doc/user/advanced-configuration/installing-contributed-packages.md +++ b/en/_doc/user/advanced-configuration/installing-contributed-packages.md @@ -11,7 +11,6 @@ title: Installing contributed packages _This page is for users who wish to install contributed packages. If you want to contribute a package, please see [package contributions]._ - Qubes OS contributed packages are available under the [QubesOS-contrib] GitHub Project. This is a place where our community can [contribute Qubes OS related packages, additions and various customizations][package contributions]. @@ -21,20 +20,28 @@ If you want to install one of these packages, first you need to enable the repos In dom0, use `qubes-dom0-update`: - sudo qubes-dom0-update qubes-repo-contrib +```bash_session +sudo qubes-dom0-update qubes-repo-contrib +``` In a Fedora-based template, use `dnf`: - sudo dnf install qubes-repo-contrib +```bash_session +sudo dnf install qubes-repo-contrib +``` In a Debian-based template, use `apt`: - sudo apt update && sudo apt install qubes-repo-contrib +```bash_session +sudo apt update && sudo apt install qubes-repo-contrib +``` The new repository definition will be in the usual location for your distro, and it will follow the naming pattern `qubes-contrib-*`, depending on your Qubes release and whether it is in dom0 or a TemplateVM. For example, in a Fedora TemplateVM on Qubes 4.0, the new repository definition would be: - /etc/yum.repos.d/qubes-contrib-vm-r4.0.repo +``` +/etc/yum.repos.d/qubes-contrib-vm-r4.0.repo +``` ## Installing packages @@ -44,7 +51,9 @@ After you've installed the repositories, you can install contributed packages. For example, to install `qvm-screenshot-tool` in dom0: - sudo qubes-dom0-update --clean qvm-screenshot-tool +```bash_session +sudo qubes-dom0-update --clean qvm-screenshot-tool +``` Please see the package's README for specific installation and setup instructions. diff --git a/en/_doc/user/advanced-configuration/kde.md b/en/_doc/user/advanced-configuration/kde.md index 1aa1e59d9f..84eb845fac 100644 --- a/en/_doc/user/advanced-configuration/kde.md +++ b/en/_doc/user/advanced-configuration/kde.md @@ -17,30 +17,32 @@ Prior to R3.2, KDE was the default desktop environment in Qubes. Beginning with R3.2, however, [XFCE is the new default desktop environment](/doc/releases/3.2/release-notes/). Nonetheless, it is still possible to install KDE by issuing this command in dom0: - $ sudo qubes-dom0-update @kde-desktop-qubes +```shell_session +$ sudo qubes-dom0-update @kde-desktop-qubes +``` You can also change your default login manager (lightdm) to the new KDE default: sddm - * first you need to edit the `/etc/sddm.conf` to make sure if the custom X parameter is set according to Qubes needs: +* first you need to edit the `/etc/sddm.conf` to make sure if the custom X parameter is set according to Qubes needs: -~~~ + ~~~ [XDisplay] ServerArguments=-nolisten tcp -background none -~~~ + ~~~ - * disable the lightdm service: +* disable the lightdm service: -~~~ + ~~~ $ sudo systemctl disable lightdm -~~~ + ~~~ - * enable the sddm service: +* enable the sddm service: -~~~ + ~~~ $ sudo systemctl enable sddm -~~~ + ~~~ - * reboot +* reboot If you encounter performance issues with KDE, try switching back to LightDM. @@ -79,12 +81,12 @@ Removal If you decide to remove KDE do **not** use `dnf remove @kde-desktop-qubes`. You will almost certainly break your system. The safest way to remove (most of) KDE is: + ~~~ sudo dnf remove kdelibs,plasma-workspace ~~~ - Mailing List Threads -------------------- - * [Nalu's KDE customization thread](https://groups.google.com/d/topic/qubes-users/KhfzF19NG1s/discussion) +* [Nalu's KDE customization thread](https://groups.google.com/d/topic/qubes-users/KhfzF19NG1s/discussion) diff --git a/en/_doc/user/advanced-configuration/managing-vm-kernel.md b/en/_doc/user/advanced-configuration/managing-vm-kernel.md index c7a924ec33..1d4f531b38 100644 --- a/en/_doc/user/advanced-configuration/managing-vm-kernel.md +++ b/en/_doc/user/advanced-configuration/managing-vm-kernel.md @@ -8,8 +8,7 @@ ref: 173 title: Managing VM kernel --- -VM kernel managed by dom0 -========================= +# VM kernel managed by dom0 By default, VMs kernels are provided by dom0. (See [here][dom0-kernel-upgrade] for information about upgrading kernels in dom0.) @@ -60,8 +59,7 @@ nopat [user@dom0 ~]$ qvm-prefs -s work kernelopts "nopat apparmor=1 security=apparmor" ~~~ -Installing different kernel using Qubes kernel package ----------------------------------- +## Installing different kernel using Qubes kernel package VM kernels are packages by Qubes team in `kernel-qubes-vm` packages. Generally, the system will keep the three newest available versions. @@ -152,8 +150,7 @@ Installation of the new package is unaffected by this event. The newly installed package is set as the default VM kernel. -Installing different VM kernel based on dom0 kernel ---------------------------------------------------- +## Installing different VM kernel based on dom0 kernel It is possible to package a kernel installed in dom0 as a VM kernel. This makes it possible to use a VM kernel which is not packaged by Qubes team. @@ -219,20 +216,18 @@ mke2fs 1.42.12 (29-Aug-2014) --> Done. ~~~ -Kernel files structure ------------------------ +## Kernel files structure Kernel for a VM is stored in `/var/lib/qubes/vm-kernels/KERNEL_VERSION` directory (`KERNEL_VERSION` replaced with actual version). Qubes 4.x supports the following files there: -- `vmlinuz` - kernel binary (may not be a Linux kernel) -- `initramfs` - initramfs for the kernel to load -- `modules.img` - ext4 filesystem image containing Linux kernel modules (to be mounted at `/lib/modules`); additionally it should contain a copy of `vmlinuz` and `initramfs` in its root directory (for loading by qemu inside stubdomain) -- `default-kernelopts-common.txt` - default kernel options, in addition to those specified with `kernelopts` qube property (can be disabled with `no-default-kernelopts` feature) +* `vmlinuz` - kernel binary (may not be a Linux kernel) +* `initramfs` - initramfs for the kernel to load +* `modules.img` - ext4 filesystem image containing Linux kernel modules (to be mounted at `/lib/modules`); additionally it should contain a copy of `vmlinuz` and `initramfs` in its root directory (for loading by qemu inside stubdomain) +* `default-kernelopts-common.txt` - default kernel options, in addition to those specified with `kernelopts` qube property (can be disabled with `no-default-kernelopts` feature) All the files besides `vmlinuz` are optional in Qubes R4.1 or newer. In Qubes R4.0, `vmlinuz` and `initramfs` are both required to be present. -Using kernel installed in the VM --------------------------------- +## Using kernel installed in the VM Both debian-9 and fedora-26 templates already have grub and related tools preinstalled so if you want to use one of the distribution kernels, all you need to do is clone either template to a new one, then: @@ -280,6 +275,7 @@ If you require `PV` mode, install `grub2-xen` in dom0 and change the template's Booting to a kernel inside the template is not supported under `PVH`. ### Installing kernel in Debian VM + #### Distribution kernel Apply the following instruction in a Debian TemplateVM or in a Debian StandaloneVM. @@ -294,7 +290,6 @@ sudo apt install linux-image-amd64 linux-headers-amd64 grub2 qubes-kernel-vm-sup If you are doing that on a qube based on "Debian Minimal" template, a grub gui will popup during the installation, asking you where you want to install the grub loader. You must select /dev/xvda (check the box using the space bar, and validate your choice with "Enter".) - You can safely ignore this error message: `grub2-probe: error: cannot find a GRUB drive for /dev/mapper/dmroot. Check your device.map` @@ -322,42 +317,50 @@ Start the VM. The process of using Qubes VM kernel with distribution kernel is complete. #### Custom kernel + Any kernel can be installed. Just make sure to install kernel headers as well. If you are building the kernel manually, do this using `dkms` and `initramfs-tools`. Run DKMS. Replace this with actual kernel version. - sudo dkms autoinstall -k - +```bash_session +sudo dkms autoinstall -k +``` + For example. - - sudo dkms autoinstall -k 4.19.0-6-amd64 - + +```bash_session +sudo dkms autoinstall -k 4.19.0-6-amd64 +``` + Update initramfs. - - sudo update-initramfs -u + +```bash_session +sudo update-initramfs -u +``` The output should look like this: - $ sudo dkms autoinstall -k 3.16.0-4-amd64 +```shell_session +$ sudo dkms autoinstall -k 3.16.0-4-amd64 - u2mfn: - Running module version sanity check. - - Original module - - No original module exists within this kernel - - Installation - - Installing to /lib/modules/3.16.0-4-amd64/updates/dkms/ +u2mfn: +Running module version sanity check. + - Original module + - No original module exists within this kernel + - Installation + - Installing to /lib/modules/3.16.0-4-amd64/updates/dkms/ - depmod.... +depmod.... - DKMS: install completed. - $ sudo update-initramfs -u - update-initramfs: Generating /boot/initrd.img-3.16.0-4-amd64 + DKMS: install completed. +$ sudo update-initramfs -u +update-initramfs: Generating /boot/initrd.img-3.16.0-4-amd64 +``` #### Troubleshooting In case of problems, visit the [VM Troubleshooting guide](/doc/vm-troubleshooting/#vm-kernel-troubleshooting) to learn how to access the VM console, view logs and fix a VM kernel installation. - [dom0-kernel-upgrade]: /doc/software-update-dom0/#kernel-upgrade diff --git a/en/_doc/user/advanced-configuration/mount-from-other-os.md b/en/_doc/user/advanced-configuration/mount-from-other-os.md index 894fca86b1..f41ba87fab 100644 --- a/en/_doc/user/advanced-configuration/mount-from-other-os.md +++ b/en/_doc/user/advanced-configuration/mount-from-other-os.md @@ -26,33 +26,34 @@ Decrypting the Disk ----------------- 1. Find the disk to be accessed: - 1. Open a Linux terminal in either dom0 or the AppVM the disk was passed through to and enter `lsblk`, which will result in an output similar to the following. - In this example, the currently booted Qubes system is installed on `sda` and the qubes system to be accessed is on `nvme0n1p2`. -``` - sda 8:0 0 111.8G 0 disk - ├─sda1 8:1 0 200M 0 part /boot/efi - ├─sda2 8:2 0 1G 0 part /boot - └─sda3 8:3 0 110.6G 0 part - └─luks-fed62fc2-2674-266d-2667-2667259cbdec 253:0 0 110.6G 0 crypt - ├─qubes_dom0-pool00_tmeta 253:1 0 88M 0 lvm - │ └─qubes_dom0-pool00-tpool 253:3 0 84.4G 0 lvm - │ ├─qubes_dom0-root 253:4 0 84.4G 0 lvm / - │ ├─qubes_dom0-pool00 253:6 0 84.4G 0 lvm - │ ├─qubes_dom0-vm--fedora--30--dvm--private--1576749131--back 253:7 0 2G 0 lvm - ├─qubes_dom0-pool00_tdata 253:2 0 84.4G 0 lvm - │ └─qubes_dom0-pool00-tpool 253:3 0 84.4G 0 lvm - │ ├─qubes_dom0-root 253:4 0 84.4G 0 lvm / - │ ├─qubes_dom0-pool00 253:6 0 84.4G 0 lvm - │ ├─qubes_dom0-vm--fedora--30--dvm--private--1576749131--back 253:7 0 2G 0 lvm - └─qubes_dom0-swap 253:5 0 4G 0 lvm [SWAP] - sdb 8:16 0 447.1G 0 disk - ├─sdb1 8:17 0 549M 0 part - └─sdb2 8:18 0 446.6G 0 part - sr0 11:0 1 1024M 0 rom - nvme0n1 259:0 0 465.8G 0 disk - ├─nvme0n1p1 259:1 0 1G 0 part - └─nvme0n1p2 259:2 0 464.8G 0 part -``` + 1. Open a Linux terminal in either dom0 or the AppVM the disk was passed through to and enter `lsblk`, which will result in an output similar to the following. + In this example, the currently booted Qubes system is installed on `sda` and the qubes system to be accessed is on `nvme0n1p2`. + + ``` + sda 8:0 0 111.8G 0 disk + ├─sda1 8:1 0 200M 0 part /boot/efi + ├─sda2 8:2 0 1G 0 part /boot + └─sda3 8:3 0 110.6G 0 part + └─luks-fed62fc2-2674-266d-2667-2667259cbdec 253:0 0 110.6G 0 crypt + ├─qubes_dom0-pool00_tmeta 253:1 0 88M 0 lvm + │ └─qubes_dom0-pool00-tpool 253:3 0 84.4G 0 lvm + │ ├─qubes_dom0-root 253:4 0 84.4G 0 lvm / + │ ├─qubes_dom0-pool00 253:6 0 84.4G 0 lvm + ├─qubes_dom0-vm--fedora--30--dvm--private--1576749131--back 253:7 0 2G 0 lvm + ├─qubes_dom0-pool00_tdata 253:2 0 84.4G 0 lvm + │ └─qubes_dom0-pool00-tpool 253:3 0 84.4G 0 lvm + │ ├─qubes_dom0-root 253:4 0 84.4G 0 lvm / + │ ├─qubes_dom0-pool00 253:6 0 84.4G 0 lvm + │ ├─qubes_dom0-vm--fedora--30--dvm--private--1576749131--back 253:7 0 2G 0 lvm + └─qubes_dom0-swap 253:5 0 4G 0 lvm [SWAP] + sdb 8:16 0 447.1G 0 disk + ├─sdb1 8:17 0 549M 0 part + └─sdb2 8:18 0 446.6G 0 part + sr0 11:0 1 1024M 0 rom + nvme0n1 259:0 0 465.8G 0 disk + ├─nvme0n1p1 259:1 0 1G 0 part + └─nvme0n1p2 259:2 0 464.8G 0 part + ``` 2. Decrypt the disk using the command `cryptsetup luksOpen /dev/`. @@ -60,13 +61,13 @@ Accessing LVM Logical Volumes ----------------------------- 3. If using an AppVM or standard Linux, LVM should automatically discover the Qubes LVM configuration. In this case, continue to step 4. - 1. Qubes uses the default name `qubes_dom0` for it's LVM VG. - This will conflict with the name of the VG of the currently installed system. - To read both, you will have to rename the VG. - *Note:* If this is not reversed, the Qubes install being accessed will not be bootable. - 2. Find the UUID of the vg to be accessed using the command `vgdisplay`. - This will be the VG named `qubes_dom0` which is not marked active. - 3. The command `vgrename other_install` will rename the VG. + 1. Qubes uses the default name `qubes_dom0` for it's LVM VG. + This will conflict with the name of the VG of the currently installed system. + To read both, you will have to rename the VG. + *Note:* If this is not reversed, the Qubes install being accessed will not be bootable. + 2. Find the UUID of the vg to be accessed using the command `vgdisplay`. + This will be the VG named `qubes_dom0` which is not marked active. + 3. The command `vgrename other_install` will rename the VG. 4. Run the command `vgscan` to add any new VGs to the device list. Mounting the disk @@ -74,12 +75,12 @@ Mounting the disk 5. Find the disk to be accessed. The `lsblk` command above may be of use. The following rules apply by default: -| Disk name | Data type | Explination | +| Disk name | Data type | Explanation | | ----------------------------- | ----------------- | ------------------------------------------- | -| other\_install/root | dom0 root | The root partition of dom0. | -| other\_install/-private | VM | The /rw partition of the named VM. | -| other\_install/-root | templateVM root | The root partition of the named TemplateVM. | -| other\_install/pool00\_tmeta | LVM Metadata | The metadata LV of this disk. | +| other\_install/root | dom0 root | The root partition of dom0. | +| other\_install/-private | VM | The /rw partition of the named VM. | +| other\_install/-root | templateVM root | The root partition of the named TemplateVM. | +| other\_install/pool00\_tmeta | LVM Metadata | The metadata LV of this disk. | 6. Mount the disk using the command `mount /dev/other_install/ `. *Note:* Any compromised data which exists in the volume to be mounted will be accessible here. @@ -89,6 +90,7 @@ At this point, all files are available in the chosen mountpoint. Reverting Changes ----------------------------------------- + Any changes which were made to the system in the above steps will need to be reverted before the disk will properly boot. However, LVM will not allow an VG to be renamed to a name already in use. Thes steps must occur either in an AppVM or using recovery media. diff --git a/en/_doc/user/advanced-configuration/newer-hardware-troubleshooting.md b/en/_doc/user/advanced-configuration/newer-hardware-troubleshooting.md index 8e13cde861..cd1710e569 100644 --- a/en/_doc/user/advanced-configuration/newer-hardware-troubleshooting.md +++ b/en/_doc/user/advanced-configuration/newer-hardware-troubleshooting.md @@ -26,5 +26,4 @@ Compare this with the output of `rpm -q kernel`. If the start of `uname -r` matches one of the versions printed by `rpm`, then you're still using the Linux LTS kernel, and you'll probably need to manually fix your boot settings. If `uname -r` reports a higher version number, then you've successfully booted with the kernel shipped by `kernel-latest`. - [dom0-kernel-upgrade]: /doc/software-update-dom0/#kernel-upgrade diff --git a/en/_doc/user/advanced-configuration/resize-disk-image.md b/en/_doc/user/advanced-configuration/resize-disk-image.md index 7b84a521f9..b3ad91cc72 100644 --- a/en/_doc/user/advanced-configuration/resize-disk-image.md +++ b/en/_doc/user/advanced-configuration/resize-disk-image.md @@ -13,8 +13,7 @@ ref: 182 title: Resize Disk Image --- -Resizing Disk Images ------------------ +## Resizing Disk Images By default Qubes uses thin volumes for the disk images. This means that space is not actually allocated for the volume until it is used. @@ -26,8 +25,7 @@ You should keep an eye on the disk-space widget to see how much free space you a It is easy to increase the size of disk images. There are risks attached to reducing the size of an image, and in general you should not need to do this. -Increasing the size of Disk Images ----------------------------------- +## Increasing the size of Disk Images There are several disk images which can be easily extended, but pay attention to the overall consumed space of your sparse/thin disk images. In most cases, the GUI tool Qube Settings (available for every qube from the Start menu, and also in the Qube Manager) will allow you to easily increase maximum disk image size. @@ -47,7 +45,9 @@ Maximum size which can be assigned through Qube Settings is 1048576 MiB - if you ~~~ qvm-volume extend :root ~~~ + OR + ~~~ qvm-volume extend :private ~~~ @@ -60,17 +60,17 @@ It is recommended that you restart (or start and then shutdown, if it is not run If you are **not** using Linux in the qube, you will also need to: -1. Start the template. -2. Resize the filesystem using OS appropriate tools. -3. Verify available space in the template using `df -h` or OS specific tools. -4. Shutdown the template. +1. Start the template. +2. Resize the filesystem using OS appropriate tools. +3. Verify available space in the template using `df -h` or OS specific tools. +4. Shutdown the template. -#### Windows 7 #### +#### Windows 7 -1. Click Start -2. type "diskmgmt.msc" - this takes you to Disk Management -3. Right-click on your existing volume, select "Extend Volume..." -4. Click through the wizard. +1. Click Start +2. type "diskmgmt.msc" - this takes you to Disk Management +3. Right-click on your existing volume, select "Extend Volume..." +4. Click through the wizard. No reboot required. @@ -89,8 +89,7 @@ Qubes will automatically grow the filesystem for you on all AppVMs with Qubes pa Otherwise, you will see that there is unallocated free space at the end of your primary disk. You can use standard linux tools like `fdisk` and `resize2fs` to make this space available. -Decreasing the size of Disk Images ----------------------------------- +## Decreasing the size of Disk Images The number shown for "storage max size" does not mean that the storage is really using that amount. In most cases you need not worry about the size shown. If you have increased the max size, and do not need it, then you *can* reduce the allocated size, but there is a risk of data loss. @@ -98,10 +97,10 @@ Remember you really dont need to do this. You can create a new qube, copy your files in to the new qube, and delete the old qube. (Simple and effective.) - Or you can take the risk of reducing the size of the disk. For example, to reduce the private storage of qube1 to 1GiB: Open a terminal in dom0: + ``` qvm-shutdown qube1 sudo lvresize --size 1024M /dev/qubes_dom0/vm-qube1-private diff --git a/en/_doc/user/advanced-configuration/salt.md b/en/_doc/user/advanced-configuration/salt.md index 674e748ef7..5168d3ec93 100644 --- a/en/_doc/user/advanced-configuration/salt.md +++ b/en/_doc/user/advanced-configuration/salt.md @@ -87,10 +87,10 @@ The module used defines which parameters can be passed to it. There is a list of [officially available states][salt-doc-states]. There are many very useful states: -* For [managing files][salt-doc-states-file]: Use this to create files or +- For [managing files][salt-doc-states-file]: Use this to create files or directories and change them (append lines, replace text, set their content etc.) -* For [installing and uninstalling][salt-doc-states-pkg] packages. -* For [executing shell commands][salt-doc-states-cmd]. +- For [installing and uninstalling][salt-doc-states-pkg] packages. +- For [executing shell commands][salt-doc-states-cmd]. With these three states you can define most of the configuration of a VM. @@ -159,19 +159,27 @@ with a `.` in their name. Now, because we use custom extensions to manage top files (instead of just enabling them all), to enable a particular top file you should issue command: - $ qubesctl top.enable my-new-vm +``` +$ qubesctl top.enable my-new-vm +``` To list all enabled top files: - $ qubesctl top.enabled +``` +$ qubesctl top.enabled +``` And to disable one: - $ qubesctl top.disable my-new-vm +``` +$ qubesctl top.disable my-new-vm +``` To apply the states to dom0 and all VMs: - $ qubesctl --all state.highstate +``` +$ qubesctl --all state.highstate +``` (More information on the `qubesctl` command further down.) @@ -230,7 +238,6 @@ If you do so, then you need to pass additional arguments to the `qubesctl` tool: --app Target all AppVMs --all Target all non-disposable VMs (TemplateVMs and AppVMs) - To apply a state to all templates, call `qubesctl --templates state.highstate`. The actual configuration is applied using `salt-ssh` (running over `qrexec` @@ -275,14 +282,14 @@ Let's start with a quick example: It uses the Qubes-specific `qvm.present` state, which ensures that the domain is present (if not, it creates it). -* The `name` flag informs Salt that the domain should be named `salt-test` (not +- The `name` flag informs Salt that the domain should be named `salt-test` (not `my new and shiny VM`). -* The `template` flag informs Salt which template should be used for the domain. -* The `label` flag informs Salt what color the domain should be. -* The `mem` flag informs Salt how much RAM should be allocated to the domain. -* The `vcpus` flag informs Salt how many Virtual CPUs should be allocated to the +- The `template` flag informs Salt which template should be used for the domain. +- The `label` flag informs Salt what color the domain should be. +- The `mem` flag informs Salt how much RAM should be allocated to the domain. +- The `vcpus` flag informs Salt how many Virtual CPUs should be allocated to the domain -* The `proxy` flag informs Salt that the domain should be a ProxyVM. +- The `proxy` flag informs Salt that the domain should be a ProxyVM. As you will notice, the options are the same (or very similar) to those used in `qvm-prefs`. @@ -299,11 +306,15 @@ without the `.sls` extension. To enable the particular top file you should issue the command: - $ qubesctl top.enable my-new-vm +``` +$ qubesctl top.enable my-new-vm +``` To apply the state: - $ qubesctl state.highstate +``` +$ qubesctl state.highstate +``` ### Example of Configuring a VM's System from Dom0 @@ -323,11 +334,15 @@ Then the appropriate top file (`/srv/salt/mc-everywhere.top`): Now you need to enable the top file: - $ qubesctl top.enable mc-everywhere +``` +$ qubesctl top.enable mc-everywhere +``` And apply the configuration: - $ qubesctl --all state.highstate +``` +$ qubesctl --all state.highstate +``` ## All Qubes-specific States @@ -371,15 +386,16 @@ Ensures the specified domain is running: qvm.running: - name: salt-test4 - ## Virtual Machine Formulae You can use these formulae to download, install, and configure VMs in Qubes. These formulae use pillar data to define default VM names and configuration details. The default settings can be overridden in the pillar data located in: + ``` /srv/pillar/base/qvm/init.sls ``` + In dom0, you can apply a single state with `sudo qubesctl state.sls STATE_NAME`. For example, `sudo qubesctl state.sls qvm.personal` will create a `personal` VM (if it does not already exist) with all its dependencies (TemplateVM, `sys-firewall`, and `sys-net`). @@ -474,16 +490,18 @@ Updates dom0 Updates domUs. Example to update all TemplateVMs: - sudo qubesctl --skip-dom0 --templates state.sls update.qubes-vm +``` +sudo qubesctl --skip-dom0 --templates state.sls update.qubes-vm +``` Useful options: - - `--max-concurrency` --- Limits how many templates are updated at the same time. - Adjust to your available RAM. - The default is 4, and the GUI updater sets it to 1. - - `--targets=vm1,vm2,...` --- Limit to specific VMs, instead of all of them. - (Use instead of `--templates` or `--standalones`.) - - `--show-output` --- Show an update summary instead of just OK/FAIL. +- `--max-concurrency` --- Limits how many templates are updated at the same time. + Adjust to your available RAM. + The default is 4, and the GUI updater sets it to 1. +- `--targets=vm1,vm2,...` --- Limit to specific VMs, instead of all of them. + (Use instead of `--templates` or `--standalones`.) +- `--show-output` --- Show an update summary instead of just OK/FAIL. For other options, see `qubesctl --help`. @@ -497,10 +515,10 @@ Additional pillar data is available to ease targeting configurations (for exampl VM type. Possible values: - - `admin` - Administration domain (`dom0`) - - `template` - Template VM - - `standalone` - Standalone VM - - `app` - Template based AppVM +- `admin` - Administration domain (`dom0`) +- `template` - Template VM +- `standalone` - Standalone VM +- `app` - Template based AppVM ### `qubes:template` @@ -510,7 +528,6 @@ Template name on which a given VM is based (if any). VM which provides network to the given VM - ## Debugging The output for each VM is logged in `/var/log/qubes/mgmt-VM_NAME.log`. @@ -523,8 +540,10 @@ If the log does not contain useful information: executed in the management VM. 5. Get the last two lines: + ```shell_session $ export PATH="/usr/lib/qubes-vm-connector/ssh-wrapper:$PATH" $ salt-ssh "$target_vm" $salt_command + ``` Adjust $target_vm (VM_NAME) and $salt_command (state.highstate). 6. Execute them, fix problems, repeat. @@ -536,8 +555,10 @@ If the log does not contain useful information: The fedora-24-minimal package is missing the `sudo` package. You can install it via: - $ qvm-run -p -u root fedora-24-minimal-template 'dnf install -y sudo' - +```shell_session +$ qvm-run -p -u root fedora-24-minimal-template 'dnf install -y sudo' +``` + The `-p` will cause the execution to wait until the package is installed. Having the `-p` flag is important when using a state with `cmd.run`. @@ -552,13 +573,13 @@ The solution is to shut down the updateVM between each install: ## Further Reading -* [Salt documentation][salt-doc] -* [Salt states][salt-doc-states] ([files][salt-doc-states-file], [commands][salt-doc-states-cmd], +- [Salt documentation][salt-doc] +- [Salt states][salt-doc-states] ([files][salt-doc-states-file], [commands][salt-doc-states-cmd], [packages][salt-doc-states-pkg], [ordering][salt-doc-states-order]) -* [Top files][salt-doc-top] -* [Jinja templates][jinja] -* [Qubes specific modules][salt-qvm-doc] -* [Formulas for default Qubes VMs][salt-virtual-machines-states] +- [Top files][salt-doc-top] +- [Jinja templates][jinja] +- [Qubes specific modules][salt-qvm-doc] +- [Formulas for default Qubes VMs][salt-virtual-machines-states] [salt-doc]: https://docs.saltstack.com/en/latest/ [salt-qvm-doc]: https://github.com/QubesOS/qubes-mgmt-salt-dom0-qvm/blob/master/README.rst diff --git a/en/_doc/user/advanced-configuration/secondary-storage.md b/en/_doc/user/advanced-configuration/secondary-storage.md index fbc41e026c..d4587c8ac3 100644 --- a/en/_doc/user/advanced-configuration/secondary-storage.md +++ b/en/_doc/user/advanced-configuration/secondary-storage.md @@ -10,13 +10,12 @@ ref: 187 title: Secondary Storage --- -Storing AppVMs on Secondary Drives -================================== +# Storing AppVMs on Secondary Drives Suppose you have a fast but small primary SSD and a large but slow secondary HDD. You want to store a subset of your AppVMs on the HDD. -## Instructions ## +## Instructions Qubes 4.0 is more flexible than earlier versions about placing different VMs on different disks. For example, you can keep templates on one disk and AppVMs on another, without messy symlinks. @@ -26,69 +25,94 @@ See also [this example](https://www.linux.com/blog/how-full-encrypt-your-linux-s First, collect some information in a dom0 terminal: - sudo pvs - sudo lvs +``` +sudo pvs +sudo lvs +``` Take note of the VG and thin pool names for your HDD, then register it with Qubes: - # is a freely chosen pool name - # is LVM volume group name - # is LVM thin pool name - qvm-pool --add lvm_thin -o volume_group=,thin_pool=,revisions_to_keep=2 - +```shell_session +# is a freely chosen pool name +# is LVM volume group name +# is LVM thin pool name +qvm-pool --add lvm_thin -o volume_group=,thin_pool=,revisions_to_keep=2 +``` + Now, you can create qubes in that pool: - qvm-create -P --label red +``` +qvm-create -P --label red +``` It isn't possible to directly migrate an existing qube to the new pool, but you can clone it there, then remove the old one: - qvm-clone -P - qvm-remove +``` +qvm-clone -P +qvm-remove +``` If that was a template, or other qube referenced elsewhere (NetVM or such), you will need to adjust those references manually after moving. For example: - qvm-prefs template +``` +qvm-prefs template +``` In theory, you can still use file-based disk images ("file" pool driver), but it lacks some features such as you won't be able to do backups without shutting down the qube. -### Example HDD setup ### +### Example HDD setup Assuming the secondary hard disk is at /dev/sdb (it will be completely erased), you can set it up for encryption by doing in a dom0 terminal (use the same passphrase as the main Qubes disk to avoid a second password prompt at boot): - sudo cryptsetup luksFormat --hash=sha512 --key-size=512 --cipher=aes-xts-plain64 --verify-passphrase /dev/sdb - sudo blkid /dev/sdb - +``` +sudo cryptsetup luksFormat --hash=sha512 --key-size=512 --cipher=aes-xts-plain64 --verify-passphrase /dev/sdb +sudo blkid /dev/sdb +``` + Note the device's UUID (in this example "b209..."), we will use it as its luks name for auto-mounting at boot, by doing: - sudo nano /etc/crypttab +``` +sudo nano /etc/crypttab +``` And adding this line (change both "b209..." for your device's UUID from blkid) to crypttab: - luks-b20975aa-8318-433d-8508-6c23982c6cde UUID=b20975aa-8318-433d-8508-6c23982c6cde none +``` +luks-b20975aa-8318-433d-8508-6c23982c6cde UUID=b20975aa-8318-433d-8508-6c23982c6cde none +``` Reboot the computer so the new luks device appears at /dev/mapper/luks-b209... and we can then create its pool, by doing this on a dom0 terminal (substitute the b209... UUIDs with yours): First create the physical volume - sudo pvcreate /dev/mapper/luks-b20975aa-8318-433d-8508-6c23982c6cde - +``` +sudo pvcreate /dev/mapper/luks-b20975aa-8318-433d-8508-6c23982c6cde +``` + Then create the LVM volume group, we will use for example "qubes" as the : - sudo vgcreate qubes /dev/mapper/luks-b20975aa-8318-433d-8508-6c23982c6cde +``` +sudo vgcreate qubes /dev/mapper/luks-b20975aa-8318-433d-8508-6c23982c6cde +``` And then use "poolhd0" as the (LVM thin pool name): - sudo lvcreate -T -n poolhd0 -l +100%FREE qubes - +``` +sudo lvcreate -T -n poolhd0 -l +100%FREE qubes +``` + Finally we will tell Qubes to add a new pool on the just created thin pool - qvm-pool --add poolhd0_qubes lvm_thin -o volume_group=qubes,thin_pool=poolhd0,revisions_to_keep=2 +``` +qvm-pool --add poolhd0_qubes lvm_thin -o volume_group=qubes,thin_pool=poolhd0,revisions_to_keep=2 +``` By default VMs will be created on the main Qubes disk (i.e. a small SSD), to create them on this secondary HDD do the following on a dom0 terminal: - qvm-create -P poolhd0_qubes --label red unstrusted-hdd - +``` +qvm-create -P poolhd0_qubes --label red unstrusted-hdd +``` [Qubes Backup]: /doc/BackupRestore/ [TemplateVM]: /doc/Templates/ diff --git a/en/_doc/user/advanced-configuration/usb-qubes.md b/en/_doc/user/advanced-configuration/usb-qubes.md index cffcc1bbbe..3caf19d7da 100644 --- a/en/_doc/user/advanced-configuration/usb-qubes.md +++ b/en/_doc/user/advanced-configuration/usb-qubes.md @@ -18,7 +18,6 @@ If during installation you enabled the creation of a USB-qube, your system shoul **Caution:** If you want to use a USB-keyboard, please beware of the possibility to lock yourself out! To avoid this problem [enable your keyboard for login]! - ## Creating and Using a USB qube ## **Warning:** This has the potential to prevent you from connecting a keyboard to Qubes via USB. @@ -31,31 +30,32 @@ The USB controller may be assigned on the **Devices** tab of a qube's settings p For guidance on finding the correct USB controller, see the [according passage on PCI-devices][usb-controller]. You can create a USB qube using the management stack by performing the following steps as root in dom0: - sudo qubesctl state.sls qvm.sys-usb +``` +sudo qubesctl state.sls qvm.sys-usb +``` Alternatively, you can create a USB qube manually as follows: - 1. Read the [PCI Devices] page to learn how to list and identify your USB controllers. - Carefully check whether you have a USB controller that would be appropriate to assign to a USB qube. - Note that it should be free of input devices, programmable devices, and any other devices that must be directly available to dom0. - If you find a free controller, note its name and proceed to step 2. - 2. Create a new qube. - Give it an appropriate name and color label (recommended: `sys-usb`, red). - 3. In the qube's settings, go to the "Devices" tab. - Find the USB controller that you identified in step 1 in the "Available" list. - Move it to the "Selected" list by highlighting it and clicking the single arrow `>` button. +1. Read the [PCI Devices] page to learn how to list and identify your USB controllers. + Carefully check whether you have a USB controller that would be appropriate to assign to a USB qube. + Note that it should be free of input devices, programmable devices, and any other devices that must be directly available to dom0. + If you find a free controller, note its name and proceed to step 2. +2. Create a new qube. + Give it an appropriate name and color label (recommended: `sys-usb`, red). +3. In the qube's settings, go to the "Devices" tab. + Find the USB controller that you identified in step 1 in the "Available" list. + Move it to the "Selected" list by highlighting it and clicking the single arrow `>` button. - **Caution:** By assigning a USB controller to a USB qube, it will no longer be available to dom0. - This can make your system unusable if, for example, you have only one USB controller, and you are running Qubes off of a USB drive. + **Caution:** By assigning a USB controller to a USB qube, it will no longer be available to dom0. + This can make your system unusable if, for example, you have only one USB controller, and you are running Qubes off of a USB drive. - 4. Click `OK`. - Restart the qube. - 5. Recommended: Check the box on the "Basic" tab which says "Start VM automatically on boot". - (This will help to mitigate attacks in which someone forces your system to reboot, then plugs in a malicious USB device.) +4. Click `OK`. + Restart the qube. +5. Recommended: Check the box on the "Basic" tab which says "Start VM automatically on boot". + (This will help to mitigate attacks in which someone forces your system to reboot, then plugs in a malicious USB device.) If the USB qube will not start, please have a look at the [faq]. - ## Enable a USB keyboard for login ## **Caution:** Please carefully read the [Security Warning about USB Input Devices] before proceeding! @@ -64,12 +64,13 @@ If you use USB keyboard, automatic USB qube creation during installation is disa Additional steps are required to avoid locking you out from the system. Those steps are not performed by default, because of risk explained in [Security Warning about USB Input Devices]. - ### Automatic setup ### To allow USB keyboard usage (including early boot for LUKS passphrase), make sure you have the latest `qubes-mgmt-salt-dom0-virtual-machines` package (simply [install dom0 updates]) and execute in dom0: - sudo qubesctl state.sls qvm.usb-keyboard +``` +sudo qubesctl state.sls qvm.usb-keyboard +``` The above command will take care of all required configuration, including creating USB qube if not present. Note that it will expose dom0 to USB devices while entering LUKS passphrase. @@ -79,17 +80,20 @@ To undo these changes, please follow the section on [**Removing a USB qube**][re If you wish to perform only a subset of this configuration (for example do not enable USB keyboard during boot), see manual instructions below. - ### Manual setup ### In order to use a USB keyboard, you must first attach it to a USB qube, then give that qube permission to pass keyboard input to dom0. Edit the `qubes.InputKeyboard` policy file in dom0, which is located here: - /etc/qubes-rpc/policy/qubes.InputKeyboard +``` +/etc/qubes-rpc/policy/qubes.InputKeyboard +``` Add a line like this one to the top of the file: - sys-usb dom0 allow +``` +sys-usb dom0 allow +``` (Change `sys-usb` to your desired USB qube.) @@ -97,14 +101,15 @@ You can now use your USB keyboard to login and for LUKS decryption during boot. For a confirmation dialog each time the USB keyboard is connected, *which will effectively disable your USB keyboard for login and LUKS decryption*, change this line to: - sys-usb dom0 ask,default_target=dom0 +``` +sys-usb dom0 ask,default_target=dom0 +``` *Don't do that if you want to unlock your device with a USB keyboard!* Additionally, if you want to use USB keyboard to enter LUKS passphrase, it is incompatible with [hiding USB controllers from dom0]. You need to revert that procedure (remove `rd.qubes.hide_all_usb` option from files mentioned there) and employ alternative protection during system boot - disconnect other devices during startup. - ## Auto Enabling A USB Mouse ## **Caution:** Please carefully read the [Security Warning about USB Input Devices] before proceeding. @@ -113,20 +118,25 @@ Handling a USB mouse isn't as critical as handling a keyboard, since you can log If you want to attach the USB mouse automatically anyway, you have to edit the `qubes.InputMouse` policy file in dom0, located at: - /etc/qubes-rpc/policy/qubes.InputMouse +``` +/etc/qubes-rpc/policy/qubes.InputMouse +``` The first line should read similar to: - sys-usb dom0 ask,default_target=dom0 +``` +sys-usb dom0 ask,default_target=dom0 +``` which will ask for conformation each time a USB mouse is attached. If the file is empty or does not exist, maybe something went wrong during setup, try to rerun `qubesctl state.sls qvm.sys-usb` in dom0. In case you are absolutely sure you do not want to confirm mouse access from `sys-usb` to `dom0`, you may add the following line on top of the file: - sys-usb dom0 allow - -(Change `sys-usb` to your desired USB qube.) +``` +sys-usb dom0 allow +``` +(Change `sys-usb` to your desired USB qube.) ## How to hide all USB controllers from dom0 ## @@ -151,49 +161,47 @@ If dom0 cannot read your USB AEM device, AEM will hang. The procedure to hide all USB controllers from dom0 is as follows: - * GRUB2 +* GRUB2 - 1. Open the file `/etc/default/grub` in dom0. - 2. Find the line that begins with `GRUB_CMDLINE_LINUX`. - 3. Add `rd.qubes.hide_all_usb` to that line. - 4. Save and close the file. - 5. Run the command `grub2-mkconfig -o /boot/grub2/grub.cfg` in dom0. - 6. Reboot. + 1. Open the file `/etc/default/grub` in dom0. + 2. Find the line that begins with `GRUB_CMDLINE_LINUX`. + 3. Add `rd.qubes.hide_all_usb` to that line. + 4. Save and close the file. + 5. Run the command `grub2-mkconfig -o /boot/grub2/grub.cfg` in dom0. + 6. Reboot. - * EFI +* EFI - 1. Open the file `/boot/efi/EFI/qubes/xen.cfg` in dom0. - 2. Find the lines that begin with `kernel=`. There may be more than one. - 3. Add `rd.qubes.hide_all_usb` to those lines. - 4. Save and close the file. - 5. Reboot. - + 1. Open the file `/boot/efi/EFI/qubes/xen.cfg` in dom0. + 2. Find the lines that begin with `kernel=`. There may be more than one. + 3. Add `rd.qubes.hide_all_usb` to those lines. + 4. Save and close the file. + 5. Reboot. ## Removing a USB qube ## **Warning:** This procedure will result in your USB controller(s) being attached directly to dom0. - * GRUB2 +* GRUB2 - 1. Shut down the USB qube. - 2. In Qubes Manager, right-click on the USB qube and select "Remove VM." - 3. Open the file `/etc/default/grub` in dom0. - 4. Find the line(s) that begins with `GRUB_CMDLINE_LINUX`. - 5. If `rd.qubes.hide_all_usb` appears anywhere in those lines, remove it. - 6. Save and close the file. - 7. Run the command `grub2-mkconfig -o /boot/grub2/grub.cfg` in dom0. - 8. Reboot. - - * EFI + 1. Shut down the USB qube. + 2. In Qubes Manager, right-click on the USB qube and select "Remove VM." + 3. Open the file `/etc/default/grub` in dom0. + 4. Find the line(s) that begins with `GRUB_CMDLINE_LINUX`. + 5. If `rd.qubes.hide_all_usb` appears anywhere in those lines, remove it. + 6. Save and close the file. + 7. Run the command `grub2-mkconfig -o /boot/grub2/grub.cfg` in dom0. + 8. Reboot. + +* EFI - 1. Shut down the USB qube. - 2. In Qubes Manager, right-click on the USB qube and select "Remove VM." - 3. Open the file `/boot/efi/EFI/qubes/xen.cfg` in dom0. - 4. Find the line(s) that begins with `kernel=`. - 5. If `rd.qubes.hide_all_usb` appears anywhere in those lines, remove it. - 6. Save and close the file. - 7. Reboot. - + 1. Shut down the USB qube. + 2. In Qubes Manager, right-click on the USB qube and select "Remove VM." + 3. Open the file `/boot/efi/EFI/qubes/xen.cfg` in dom0. + 4. Find the line(s) that begins with `kernel=`. + 5. If `rd.qubes.hide_all_usb` appears anywhere in those lines, remove it. + 6. Save and close the file. + 7. Reboot. [remove your USB-qube]: #removing-a-usb-qube [security implications]: /doc/device-handling-security/#usb-security From 43a89a7db9c133bb285e5b8da546c967815303c8 Mon Sep 17 00:00:00 2001 From: dd Date: Tue, 17 Nov 2020 15:45:53 +0100 Subject: [PATCH 121/663] linted docs in user common tasks --- .../backup-emergency-restore-v2.md | 24 +-- .../backup-emergency-restore-v4.md | 2 - en/_doc/user/common-tasks/backup-restore.md | 26 +-- en/_doc/user/common-tasks/block-devices.md | 193 ++++++++++-------- en/_doc/user/common-tasks/copy-from-dom0.md | 27 ++- en/_doc/user/common-tasks/copy-paste.md | 15 +- en/_doc/user/common-tasks/copying-files.md | 2 - en/_doc/user/common-tasks/device-handling.md | 72 +++---- en/_doc/user/common-tasks/disposablevm.md | 50 ++--- en/_doc/user/common-tasks/full-screen-mode.md | 1 - en/_doc/user/common-tasks/getting-started.md | 66 +++--- .../common-tasks/managing-appvm-shortcuts.md | 4 +- en/_doc/user/common-tasks/pci-devices.md | 84 ++++---- .../user/common-tasks/software-update-dom0.md | 52 +++-- .../user/common-tasks/software-update-domu.md | 59 ++---- .../user/common-tasks/updating-qubes-os.md | 7 +- en/_doc/user/common-tasks/usb-devices.md | 90 ++++---- .../user/common-tasks/volume-backup-revert.md | 12 +- 18 files changed, 396 insertions(+), 390 deletions(-) diff --git a/en/_doc/user/common-tasks/backup-emergency-restore-v2.md b/en/_doc/user/common-tasks/backup-emergency-restore-v2.md index 679f20e8aa..2c18b48558 100644 --- a/en/_doc/user/common-tasks/backup-emergency-restore-v2.md +++ b/en/_doc/user/common-tasks/backup-emergency-restore-v2.md @@ -23,7 +23,7 @@ any GNU/Linux system with the following procedure. **Note:** In the following example, the backup file is assumed to be both encrypted and compressed. -1. Untar the main backup file. +1. Untar the main backup file. ~~~ [user@restore ~]$ tar -i -xvf qubes-backup-2013-12-26-123456 @@ -43,7 +43,7 @@ encrypted and compressed. dom0-home/dom0user.000.hmac ~~~ -2. Verify the integrity of the `private.img` file which houses your data. +2. Verify the integrity of the `private.img` file which houses your data. ~~~ [user@restore ~]$ cd vm1/ @@ -61,14 +61,14 @@ encrypted and compressed. complete list of supported message digest algorithms can be found with `openssl list-message-digest-algorithms`. -3. Decrypt the `private.img` file. +3. Decrypt the `private.img` file. ~~~ [user@restore vm1]$ openssl enc -d -pass pass:your_passphrase -aes-256-cbc -in private.img.000 -out private.img.dec.000 ~~~ **Note:** For multi-part files, a loop can be used: - + ~~~ find -name 'private.img.*' | sort -V | while read f; do openssl enc -d -pass pass:your_passphrase -aes-256-cbc -in $f -out @@ -81,7 +81,7 @@ encrypted and compressed. list of supported cipher algorithms can be found with `openssl list-cipher-algorithms`. -4. Decompress the decrypted `private.img` file. +4. Decompress the decrypted `private.img` file. ~~~ [user@restore vm1]$ zforce private.img.dec.* @@ -91,7 +91,7 @@ encrypted and compressed. **Note:** If your backup was compressed with a program other than `gzip`, you must substitute the correct compression program. -5. Untar the decrypted and decompressed `private.img` file. +5. Untar the decrypted and decompressed `private.img` file. ~~~ [user@restore vm1]$ tar -M -xvf private.img.dec.000 @@ -100,7 +100,7 @@ encrypted and compressed. **Note:** For multi-part files, a script is required: - 1. Create a `new-volume-script`: + 1. Create a `new-volume-script`: ~~~ #!/bin/sh @@ -109,11 +109,11 @@ encrypted and compressed. echo $name.$suffix >&$TAR_FD ~~~ - 2. `chmod +x new-volume-script`. - 3. `tar --new-volume-script=./new-volume-script -xvf private.img.dec.000`. + 2. `chmod +x new-volume-script`. + 3. `tar --new-volume-script=./new-volume-script -xvf private.img.dec.000`. (The `--new-volume-script` option enables multi-volume untaring.) -6. Mount the private.img file and access your data. +6. Mount the private.img file and access your data. ~~~ [user@restore vm1]$ sudo mkdir /mnt/img @@ -125,6 +125,4 @@ encrypted and compressed. **Note:** You may wish to store a plain text copy of these instructions with your Qubes backups in the event that you fail to recall the above procedure while this web page is inaccessible. You may obtain a plaintext version of - this file in Git repository housing all the documentation at: - - https://github.com/QubesOS/qubes-doc.git + this file in Git repository housing all the documentation on [Github](https://github.com/QubesOS/qubes-doc.git) diff --git a/en/_doc/user/common-tasks/backup-emergency-restore-v4.md b/en/_doc/user/common-tasks/backup-emergency-restore-v4.md index b45076b551..90a48120c1 100644 --- a/en/_doc/user/common-tasks/backup-emergency-restore-v4.md +++ b/en/_doc/user/common-tasks/backup-emergency-restore-v4.md @@ -20,7 +20,6 @@ mind. No special Qubes-specific tools are required to access data backed up by Qubes. In the event a Qubes system is unavailable, you can access your data on any GNU/Linux system with the following procedure. - Required `scrypt` Utility ------------------------- @@ -73,7 +72,6 @@ any GNU/Linux system. [user@restore ~]$ alias scrypt="scrypt-*/usr/bin/scrypt" - Emergency Recovery Instructions ------------------------------- diff --git a/en/_doc/user/common-tasks/backup-restore.md b/en/_doc/user/common-tasks/backup-restore.md index 5b9495437c..7361dc2d8b 100644 --- a/en/_doc/user/common-tasks/backup-restore.md +++ b/en/_doc/user/common-tasks/backup-restore.md @@ -23,7 +23,6 @@ This is true of all computing, not just the use of Qubes. Data loss can and does occur in myriad and unexpected ways. A standard recommendation is to make backups at least weekly: three copies in two different formats, one off-site. - Creating a Backup ----------------- @@ -70,7 +69,6 @@ Creating a Backup This step is optional but strongly recommended. A backup is useless if you can't restore your data from it, and you can't be sure that your backup is good until you try to restore. - Restoring from a Backup ----------------------- @@ -88,10 +86,10 @@ This brings up the **Qubes Restore VMs** window. Once you've located the backup file, double-click it or select it and hit **OK**. 3. There are three options you may select when restoring from a backup: - 1. **ignore missing templates and net VMs**: If any of the VMs in your backup depended upon a NetVM or TemplateVM that is not present in (i.e., "missing from") the current system, checking this box will ignore the fact that they are missing and restore the VMs anyway and set them to use the default NetVM and system default template. - 2. **ignore username mismatch**: This option applies only to the restoration of dom0's home directory. + 1. **ignore missing templates and net VMs**: If any of the VMs in your backup depended upon a NetVM or TemplateVM that is not present in (i.e., "missing from") the current system, checking this box will ignore the fact that they are missing and restore the VMs anyway and set them to use the default NetVM and system default template. + 2. **ignore username mismatch**: This option applies only to the restoration of dom0's home directory. If your backup was created on a Qubes system which had a different dom0 username than the dom0 username of the current system, then checking this box will ignore the mismatch between the two usernames and proceed to restore the home directory anyway. - 3. **Verify backup integrity, do not restore the data**: This will scan the backup file for corrupted data. + 3. **Verify backup integrity, do not restore the data**: This will scan the backup file for corrupted data. However, it does not currently detect if it is missing data as long as it is a correctly structured, non-corrupted backup file. See [issue #3498](https://github.com/QubesOS/qubes-issues/issues/3498) for more details. @@ -109,7 +107,6 @@ If there are any issues preventing the restore, they will be listed here and the Qubes will proceed to restore from your backup. Once the progress bar has completed, you may click **Finish**. - Emergency Backup Recovery without Qubes --------------------------------------- @@ -119,10 +116,9 @@ In the event a Qubes system is unavailable, you can access your data on any GNU/ Refer to the following for emergency restore of a backup created on: - * [Qubes R4 or newer](/doc/backup-emergency-restore-v4/) - * [Qubes R3](/doc/backup-emergency-restore-v3/) - * [Qubes R2 or older](/doc/backup-emergency-restore-v2/) - +- [Qubes R4 or newer](/doc/backup-emergency-restore-v4/) +- [Qubes R3](/doc/backup-emergency-restore-v3/) +- [Qubes R2 or older](/doc/backup-emergency-restore-v2/) Migrating Between Two Physical Machines --------------------------------------- @@ -135,17 +131,17 @@ Choosing a Backup Passphrase Here are some things to consider when selecting a passphrase for your backups: - * If you plan to store the backup for a long time or on third-party servers, you should make sure to use a very long, high-entropy passphrase. +- If you plan to store the backup for a long time or on third-party servers, you should make sure to use a very long, high-entropy passphrase. (Depending on the decryption passphrase you use for your system drive, this may necessitate selecting a stronger passphrase. If your system drive decryption passphrase is already sufficiently strong, it may not.) - * An adversary who has access to your backups may try to substitute one backup for another. +- An adversary who has access to your backups may try to substitute one backup for another. For example, when you attempt to retrieve a recent backup, the adversary may instead give you a very old backup containing a compromised VM. If you're concerned about this type of attack, you may wish to use a different passphrase for each backup, e.g., by appending a number or date to the passphrase. - * If you're forced to enter your system drive decryption passphrase in plain view of others (where it can be shoulder-surfed), then you may want to use a different passphrase for your backups (even if your system drive decryption passphrase is already maximally strong). +- If you're forced to enter your system drive decryption passphrase in plain view of others (where it can be shoulder-surfed), then you may want to use a different passphrase for your backups (even if your system drive decryption passphrase is already maximally strong). On the other hand, if you're careful to avoid shoulder-surfing and/or have a passphrase that's difficult to detect via shoulder-surfing, then this may not be a problem for you. Notes ----- - * For the technical details of the backup system, please refer to [this thread](https://groups.google.com/d/topic/qubes-devel/TQr_QcXIVww/discussion). - * If working with symlinks, note the issues described in [this thread](https://groups.google.com/d/topic/qubes-users/EITd1kBHD30/discussion). +- For the technical details of the backup system, please refer to [this thread](https://groups.google.com/d/topic/qubes-devel/TQr_QcXIVww/discussion). +- If working with symlinks, note the issues described in [this thread](https://groups.google.com/d/topic/qubes-users/EITd1kBHD30/discussion). diff --git a/en/_doc/user/common-tasks/block-devices.md b/en/_doc/user/common-tasks/block-devices.md index 438fb27623..0078ccfefc 100644 --- a/en/_doc/user/common-tasks/block-devices.md +++ b/en/_doc/user/common-tasks/block-devices.md @@ -11,14 +11,13 @@ ref: 193 title: Block (Storage) Devices --- -# Block (Storage) Devices # +# Block (Storage) Devices *This page is part of [device handling in qubes].* If you don't know what a "block device" is, just think of it as a fancy way to say "something that stores data". - -## Using The GUI to Attach a Drive ## +## Using The GUI to Attach a Drive (**Note:** In the present context, the term "USB drive" denotes any [USB mass storage device][mass-storage]. In addition to smaller flash memory sticks, this includes things like USB external hard drives.) @@ -41,15 +40,16 @@ Click on one and your USB drive will be attached! However, it often means the AppVM won't detect the new partition and you will need to manually mount it inside the AppVM. See below for more detailed steps. - -## Block Devices in VMs ## +## Block Devices in VMs If not specified otherwise, block devices will show up as `/dev/xvdi*` in a linux VM, where `*` may be the partition-number. If a block device isn't automatically mounted after attaching, open a terminal in the VM and execute: - cd ~ - mkdir mnt - sudo mount /dev/xvdi2 mnt +``` +cd ~ +mkdir mnt +sudo mount /dev/xvdi2 mnt +``` where `xvdi2` needs to be replaced with the partition you want to mount. This will make your drive content accessible under `~/mnt`. @@ -60,8 +60,7 @@ If several different block-devices are attached to a single VM, the last letter To specify this device node name, you need to use the command line tool and its [`frontend-dev`-option][frontend-dev]. - -## Command Line Tool Guide ## +## Command Line Tool Guide The command-line tool you may use to mount whole USB drives or their partitions is `qvm-block`, a shortcut for `qvm-device block`. @@ -71,100 +70,114 @@ So make sure you have the drive available in the sourceVM, then list the availab In case of a USB-drive, make sure it's attached to your computer. If you don't see anything that looks like your drive, run `sudo udevadm trigger --action=change` in your USB-qube (typically `sys-usb`) - 1. In a dom0 console (running as a normal user), list all available block devices: - - qvm-block - - This will list all available block devices in your system across all VMs. - The name of the qube hosting the block device is displayed before the colon in the device ID. - The string after the colon is the ID of the device used within the qube, like so: +1. In a dom0 console (running as a normal user), list all available block devices: - sourceVM:sdb Cruzer () 4GiB - sourceVM:sdb1 Disk () 2GiB + ``` + qvm-block + ``` - 2. Assuming your block device is attached to `sys-usb` and its device node is `sdb`, we attach the device to a qube with the name `work` like so: - - qvm-block attach work sys-usb:sdb - - This will attach the device to the qube as `/dev/xvdi` if that name is not already taken by another attached device, or `/dev/xvdj`, etc. - - You may also mount one partition at a time by using the same command with the partition number, e.g. `sdb1`. +This will list all available block devices in your system across all VMs. +The name of the qube hosting the block device is displayed before the colon in the device ID. +The string after the colon is the ID of the device used within the qube, like so: - 3. The block device is now attached to the qube. - If using a default qube, you may open the Nautilus file manager in the qube, and your drive should be visible in the **Devices** panel on the left. - If you've attached a single partition (e.g. `sdb2` instead of `sdb` in our example), you may need to manually mount before it becomes visible: - - cd ~ - mkdir mnt - sudo mount /dev/xvdi mnt +``` + sourceVM:sdb Cruzer () 4GiB + sourceVM:sdb1 Disk () 2GiB +``` + +2. Assuming your block device is attached to `sys-usb` and its device node is `sdb`, we attach the device to a qube with the name `work` like so: + + ``` + qvm-block attach work sys-usb:sdb + ``` + +This will attach the device to the qube as `/dev/xvdi` if that name is not already taken by another attached device, or `/dev/xvdj`, etc. +You may also mount one partition at a time by using the same command with the partition number, e.g. `sdb1`. - 4. When you finish using the block device, click the eject button or right-click and select **Unmount**. +3. The block device is now attached to the qube. + If using a default qube, you may open the Nautilus file manager in the qube, and your drive should be visible in the **Devices** panel on the left. + If you've attached a single partition (e.g. `sdb2` instead of `sdb` in our example), you may need to manually mount before it becomes visible: - If you've manually mounted a single partition in the above step, use: + ``` + cd ~ + mkdir mnt + sudo mount /dev/xvdi mnt + ``` - sudo umount mnt +4. When you finish using the block device, click the eject button or right-click and select **Unmount**. - 5. In a dom0 console, detach the device + If you've manually mounted a single partition in the above step, use: - qvm-block detach work sys-usb:sdb + ``` + sudo umount mnt + ``` - 6. You may now remove the device or attach it to another qube. +5. In a dom0 console, detach the device + ``` + qvm-block detach work sys-usb:sdb + ``` -## Recovering From Premature Device Destruction ## +6. You may now remove the device or attach it to another qube. + +## Recovering From Premature Device Destruction If the you fail to detach the device before it's destroyed in the sourceVM (e.g. by physically detaching the thumbdrive), [there will be problems][premature removal]. To recover from this error state, in dom0 run - virsh detach-disk targetVM xvdi +``` +virsh detach-disk targetVM xvdi +``` (where `targetVM` is to be replaced with the VM name you attached the device to and `xvdi` is to be replaced with the used [frontend device node][frontend-dev].) However, if the block device originated in dom0, you will have to refer to the next section. - -### What if I removed the device before detaching it from the VM? ### +### What if I removed the device before detaching it from the VM? Currently (until issue [1082] gets implemented), if you remove the device before detaching it from the qube, Qubes OS (more precisely, `libvirtd`) will think that the device is still attached to the qube and will not allow attaching further devices under the same name. The easiest way to recover from such a situation is to reboot the qube to which the device was attached. If this isn't an option, you can manually recover from the situation by following these steps: - 1. Physically connect the device back. - You can use any device as long as it will be detected under the same name (for example, `sdb`). - - 2. Attach the device manually to the same VM using the `xl block-attach` command. - It is important to use the same "frontend" device name (by default, `xvdi`). - You can get it from the `qvm-block` listing: +1. Physically connect the device back. + You can use any device as long as it will be detected under the same name (for example, `sdb`). - [user@dom0 ~]$ qvm-block - sys-usb:sda DataTraveler_2.0 () 246 MiB (attached to 'testvm' as 'xvdi') - [user@dom0 ~]$ sudo xl block-attach testvm phy:/dev/sda backend=sys-usb xvdi +2. Attach the device manually to the same VM using the `xl block-attach` command. + It is important to use the same "frontend" device name (by default, `xvdi`). + You can get it from the `qvm-block` listing: - In above example, all `xl block-attach` parameters can be deduced from the output of `qvm-block`. - In order: + ```shell_session + [user@dom0 ~]$ qvm-block + sys-usb:sda DataTraveler_2.0 () 246 MiB (attached to 'testvm' as 'xvdi') + [user@dom0 ~]$ sudo xl block-attach testvm phy:/dev/sda backend=sys-usb xvdi + ``` - * `testvm` - name of target qube to which device was attached - listed in brackets by `qvm-block` command - * `phy:/dev/sda` - physical path at which device appears in source qube (just after source qube name in `qvm-block` output) - * `backend=sys-usb` - name of source qube, can be omitted in the case of dom0 - * `xvdi` - "frontend" device name (listed at the end of line in `qvm-block` output) +In above example, all `xl block-attach` parameters can be deduced from the output of `qvm-block`. +In order: - 3. Now properly detach the device, either using Qubes VM Manager or the `qvm-block -d` command. +* `testvm` - name of target qube to which device was attached - listed in brackets by `qvm-block` command +* `phy:/dev/sda` - physical path at which device appears in source qube (just after source qube name in `qvm-block` output) +* `backend=sys-usb` - name of source qube, can be omitted in the case of dom0 +* `xvdi` - "frontend" device name (listed at the end of line in `qvm-block` output) +3. Now properly detach the device, either using Qubes VM Manager or the `qvm-block -d` command. -## Attaching a File ## +## Attaching a File To attach a file as block device to another qube, first turn it into a loopback device inside the sourceVM. - 1. In the linux sourceVM run +1. In the linux sourceVM run - sudo losetup -f --show /path/to/file + ``` + sudo losetup -f --show /path/to/file + ``` - [This command][losetup] will create the device node `/dev/loop0` or, if that is already in use, increase the trailing integer until that name is still available. - Afterwards it prints the device-node-name it found. +[This command][losetup] will create the device node `/dev/loop0` or, if that is already in use, increase the trailing integer until that name is still available. +Afterwards it prints the device-node-name it found. - 2. If you want to use the GUI, you're done. +2. If you want to use the GUI, you're done. Click the Device Manager ![device manager icon] and select the `loop0`-device to attach it to another qube. If you rather use the command line, continue: @@ -172,26 +185,30 @@ To attach a file as block device to another qube, first turn it into a loopback In dom0, run `qvm-block` to display known block devices. The newly created loop device should show up: - ~]$ qvm-block - BACKEND:DEVID DESCRIPTION USED BY - sourceVM:loop0 /path/to/file + ```shell_session + ~]$ qvm-block + BACKEND:DEVID DESCRIPTION USED BY + sourceVM:loop0 /path/to/file + ``` - 3. Attach the `loop0`-device using qvm-block as usual: +3. Attach the `loop0`-device using qvm-block as usual: - qvm-block a targetVM sourceVM:loop0 + ``` + qvm-block a targetVM sourceVM:loop0 + ``` - 4. After detaching, destroy the loop-device inside the sourceVM as follows: +4. After detaching, destroy the loop-device inside the sourceVM as follows: - sudo losetup -d /dev/loop0 + ``` + sudo losetup -d /dev/loop0 + ``` - -## Additional Attach Options ## +## Additional Attach Options Attaching a block device through the command line offers additional customisation options, specifiable via the `--option`/`-o` option. (Yes, confusing wording, there's an [issue for that](https://github.com/QubesOS/qubes-issues/issues/4530).) - -### frontend-dev ### +### frontend-dev This option allows you to specify the name of the device node made available in the targetVM. This defaults to `xvdi` or, if already occupied, the first available device node name in alphabetical order. @@ -199,12 +216,13 @@ This defaults to `xvdi` or, if already occupied, the first available device node usage example: - qvm-block a work sys-usb:sda1 -o frontend-dev=xvdz +``` +qvm-block a work sys-usb:sda1 -o frontend-dev=xvdz +``` This command will attach the partition `sda1` to `work` as `/dev/xvdz`. - -### read-only ### +### read-only Attach device in read-only mode. Protects the block device in case you don't trust the targetVM. @@ -213,28 +231,31 @@ If the device is a read-only device, this option is forced true. usage example: - qvm-block a work sys-usb:sda1 -o read-only=true +``` +qvm-block a work sys-usb:sda1 -o read-only=true +``` There exists a shortcut to set read-only `true`, `--ro`: - qvm-block a work sys-usb:sda1 --ro +``` +qvm-block a work sys-usb:sda1 --ro +``` The two commands are equivalent. - -### devtype ### +### devtype Usually, a block device is attached as disk. In case you need to attach a block device as cdrom, this option allows that. usage example: - qvm-block a work sys-usb:sda1 -o devtype=cdrom +``` +qvm-block a work sys-usb:sda1 -o devtype=cdrom +``` This option accepts `cdrom` and `disk`, default is `disk`. - - [device handling in qubes]: /doc/device-handling/ [mass-storage]: https://en.wikipedia.org/wiki/USB_mass_storage_device_class [device manager icon]:/attachment/wiki/Devices/media-removable.png diff --git a/en/_doc/user/common-tasks/copy-from-dom0.md b/en/_doc/user/common-tasks/copy-from-dom0.md index e34473eb4e..9c80fa4e3a 100644 --- a/en/_doc/user/common-tasks/copy-from-dom0.md +++ b/en/_doc/user/common-tasks/copy-from-dom0.md @@ -11,11 +11,9 @@ ref: 198 title: Copying from (and to) dom0 --- -Copying from (and to) dom0 -========================== +# Copying from (and to) dom0 -Copying **from** dom0 ---------------------- +## Copying **from** dom0 To copy a file from dom0 to a VM (domU), simply use `qvm-copy-to-vm`: @@ -25,34 +23,33 @@ qvm-copy-to-vm The file will arrive in your destination VM in the `~/QubesIncoming/dom0/` directory. -### Copying logs from dom0 ### +### Copying logs from dom0 In order to easily copy/paste the contents of logs from dom0 to the inter-VM clipboard, you can simply: -1. Right-click on the desired VM in the Qubes VM Manager. -2. Click "Logs." -3. Click on the desired log. -4. Click "Copy to Qubes clipboard." +1. Right-click on the desired VM in the Qubes VM Manager. +2. Click "Logs." +3. Click on the desired log. +4. Click "Copy to Qubes clipboard." You may now paste the log contents to any VM as you normally would (i.e., Ctrl-Shift-V, then Ctrl-V). -### Copy/paste from dom0 ### +### Copy/paste from dom0 For data other than logs, there are several options: -1. Use the **Qubes Clipboard** widget: +1. Use the **Qubes Clipboard** widget: - Copy text to the clipboard normally in dom0. - Click the **Qubes Clipboard** icon in the Notification Area. - Click "Copy dom0 clipboard". - Receive a notification that text has been copied to the inter-qube clipboard. - Press Ctrl + Shift + V in a qube to paste into the desired qube's clipboard. - Paste normally within that qube. -2. Copy it as a file (see above) -3. Write the data you wish to copy into `/var/run/qubes/qubes-clipboard.bin`, then `echo -n dom0 > /var/run/qubes/qubes-clipboard.bin.source`. +2. Copy it as a file (see above) +3. Write the data you wish to copy into `/var/run/qubes/qubes-clipboard.bin`, then `echo -n dom0 > /var/run/qubes/qubes-clipboard.bin.source`. Then use Ctrl-Shift-V to paste the data to the desired VM. -Copying **to** dom0 -------------------- +## Copying **to** dom0 Copying anything into dom0 is not advised, since doing so can compromise the security of your Qubes system. For this reason, there is no simple means of copying anything into dom0, unlike [copying from dom0](#copying-from-dom0) and [copying files between VMs](/doc/copying-files/). diff --git a/en/_doc/user/common-tasks/copy-paste.md b/en/_doc/user/common-tasks/copy-paste.md index c679f3a9e2..fe474f476b 100644 --- a/en/_doc/user/common-tasks/copy-paste.md +++ b/en/_doc/user/common-tasks/copy-paste.md @@ -16,13 +16,13 @@ Copy and Paste between domains Qubes fully supports secure copy and paste operation between domains. In order to copy a clipboard from domain A to domain B, follow those steps: -1. Click on the application window in domain A where you have selected text for copying. - Then use the *app-specific* hot-key (or menu option) to copy this into domain's local clipboard (in other words: do the copy operation as usual, in most cases by pressing Ctrl-C). -2. Then (when the app in domain A is still in focus) press Ctrl-Shift-C magic hot-key. - This will tell Qubes that we want to select this domain's clipboard for *global copy* between domains. -3. Now select the destination app, running in domain B, and press Ctrl-Shift-V, another magic hot-key that will tell Qubes to make the clipboard marked in the previous step available to apps running in domain B. - This step is necessary because it ensures that only domain B will get access to the clipboard copied from domain A, and not any other domain that might be running in the system. -4. Now, in the destination app use the app-specific key combination (usually Ctrl-V) for pasting the clipboard. +1. Click on the application window in domain A where you have selected text for copying. + Then use the *app-specific* hot-key (or menu option) to copy this into domain's local clipboard (in other words: do the copy operation as usual, in most cases by pressing Ctrl-C). +2. Then (when the app in domain A is still in focus) press Ctrl-Shift-C magic hot-key. + This will tell Qubes that we want to select this domain's clipboard for *global copy* between domains. +3. Now select the destination app, running in domain B, and press Ctrl-Shift-V, another magic hot-key that will tell Qubes to make the clipboard marked in the previous step available to apps running in domain B. + This step is necessary because it ensures that only domain B will get access to the clipboard copied from domain A, and not any other domain that might be running in the system. +4. Now, in the destination app use the app-specific key combination (usually Ctrl-V) for pasting the clipboard. Note that the global clipboard will be cleared after step \#3, to prevent accidental leakage to another domain, if the user accidentally pressed Ctrl-Shift-V later. @@ -81,5 +81,4 @@ If you edit a line in this file, you must uncomment it (by removing the initial VMs need to be restarted in order for changes in `/etc/qubes/guid.conf` to take effect. - [RPC policy]: /doc/rpc-policy/ diff --git a/en/_doc/user/common-tasks/copying-files.md b/en/_doc/user/common-tasks/copying-files.md index 3b92ded157..216afac978 100644 --- a/en/_doc/user/common-tasks/copying-files.md +++ b/en/_doc/user/common-tasks/copying-files.md @@ -32,7 +32,6 @@ GUI 4. You can now move them whenever you like in the qube B filesystem using the file manager there. - CLI --- @@ -44,7 +43,6 @@ qvm-copy [--without-progress] file [file]+ qvm-move [--without-progress] file [file]+ ``` - On inter-qube file copy security ---------------------------------- diff --git a/en/_doc/user/common-tasks/device-handling.md b/en/_doc/user/common-tasks/device-handling.md index d6d5efea27..2aa9856eab 100644 --- a/en/_doc/user/common-tasks/device-handling.md +++ b/en/_doc/user/common-tasks/device-handling.md @@ -11,7 +11,7 @@ ref: 188 title: Device Handling --- -# Device Handling # +# Device Handling This is an overview of device handling in Qubes OS. For specific devices ([block], [USB] and [PCI] devices), please visit their respective pages. @@ -19,48 +19,43 @@ For specific devices ([block], [USB] and [PCI] devices), please visit their resp **Important security warning:** Device handling comes with many security implications. Please make sure you carefully read and understand the **[security considerations]**. - -## Introduction ## +## Introduction The interface to deal with devices of all sorts was unified in Qubes 4.0 with the `qvm-device` command and the Qubes Devices Widget. In Qubes 3.X, the Qubes VM Manager dealt with attachment as well. This functionality was moved to the Qubes Device Widget, the tool tray icon with a yellow square located in the top right of your screen by default. There are currently four categories of devices Qubes understands: - - Microphones - - Block devices - - USB devices - - PCI devices +- Microphones +- Block devices +- USB devices +- PCI devices Microphones, block devices and USB devices can be attached with the GUI-tool. PCI devices can be attached using the Qube Settings, but require a VM reboot. - -## General Qubes Device Widget Behavior And Handling ## +## General Qubes Device Widget Behavior And Handling When clicking on the tray icon (which looks similar to this): ![SD card and thumbdrive][device manager icon] several device-classes separated by lines are displayed as tooltip. Block devices are displayed on top, microphones one below and USB-devices at the bottom. On most laptops, integrated hardware such as cameras and fingerprint-readers are implemented as USB-devices and can be found here. - -### Attaching Using The Widget ### +### Attaching Using The Widget Click the tray icon. Hover on a device you want to attach to a VM. A list of running VMs (except dom0) appears. Click on one and your device will be attached! - -### Detaching Using The Widget ### +### Detaching Using The Widget To detach a device, click the Qubes Devices Widget icon again. Attached devices are displayed in bold. Hover the one you want to detach. A list of VMs appears, one showing the eject symbol: ![eject icon] - -### Attaching a Device to Several VMs ### +### Attaching a Device to Several VMs Only `mic` should be attached to more than one running VM. You may *assign* a device to more than one VM (using the `--persistent` option), however, only one of them can be started at the same time. @@ -68,33 +63,29 @@ You may *assign* a device to more than one VM (using the `--persistent` option), But be careful: There is a [bug in `qvm-device block` or `qvm-block`][i4692] which will allow you to *attach* a block device to two running VMs. Don't do that! - -## General `qvm-device` Command Line Tool Behavior ## +## General `qvm-device` Command Line Tool Behavior All devices, including PCI-devices, may be attached from the commandline using the `qvm-device`-tools. - -### Device Classes ### +### Device Classes `qvm-device` expects DEVICE_CLASS as first argument. DEVICE_CLASS can be one of - - `pci` - - `usb` - - `block` - - `mic` +- `pci` +- `usb` +- `block` +- `mic` - -### Actions ### +### Actions `qvm-device` supports three actions: - - `list` (ls, l) - list all devices of DEVICE_CLASS - - `attach` (at, a) - attach a specific device of DEVICE_CLASS - - `detach` (dt, d) - detach a specific device of DEVICE_CLASS - +- `list` (ls, l) - list all devices of DEVICE_CLASS +- `attach` (at, a) - attach a specific device of DEVICE_CLASS +- `detach` (dt, d) - detach a specific device of DEVICE_CLASS -### Global Options ### +### Global Options These three options are always available: @@ -109,13 +100,11 @@ DEVICE_CLASS however is required. **SYNOPSIS**: `qvm-device DEVICE_CLASS {action} [action-specific arguments] [options]` - -## Actions ## +## Actions Actions are applicable to every DEVICE_CLASS and expose some additional options. - -### Listing Devices ### +### Listing Devices The `list` action lists known devices in the system. `list` accepts VM-names to narrow down listed devices. @@ -123,16 +112,15 @@ Devices available in, as well as attached to the named VMs will be listed. `list` accepts two options: - - `--all` - equivalent to specifying every VM name after `list`. +- `--all` - equivalent to specifying every VM name after `list`. No VM-name implies `--all`. - - `--exclude` - exclude VMs from `--all`. +- `--exclude` - exclude VMs from `--all`. Requires `--all`. **SYNOPSIS** `qvm-device DEVICE_CLASS {list|ls|l} [--all [--exclude VM [VM [...]]] | VM [VM [...]]]` - -### Attaching Devices ### +### Attaching Devices The `attach` action assigns an exposed device to a VM. This makes the device available in the VM it's attached to. @@ -141,15 +129,14 @@ Required argument are targetVM and sourceVM:deviceID. `attach` accepts two options: - - `--persistent` - attach device on targetVM-boot. +- `--persistent` - attach device on targetVM-boot. If the device is unavailable (physically missing or sourceVM not started), booting the targetVM fails. - - `--option`, `-o` - set additional options specific to DEVICE_CLASS. +- `--option`, `-o` - set additional options specific to DEVICE_CLASS. **SYNOPSIS** `qvm-device DEVICE_CLASS {attach|at|a} targetVM sourceVM:deviceID [options]` - -### Detaching Devices ### +### Detaching Devices The `detach` action removes an assigned device from a targetVM. It won't be available afterwards anymore. @@ -162,7 +149,6 @@ If no specific `sourceVM:deviceID` combination is given, *all devices of that DE **SYNOPSIS** `qvm-device DEVICE_CLASS {detach|dt|d} targetVM [sourceVM:deviceID]` - [block]:/doc/block-devices/ [USB]:/doc/usb-devices/ [PCI]:/doc/pci-devices/ diff --git a/en/_doc/user/common-tasks/disposablevm.md b/en/_doc/user/common-tasks/disposablevm.md index e545e2b728..b2bf200890 100644 --- a/en/_doc/user/common-tasks/disposablevm.md +++ b/en/_doc/user/common-tasks/disposablevm.md @@ -11,7 +11,7 @@ ref: 203 title: DisposableVMs --- -# DisposableVMs # +# DisposableVMs A DisposableVM (previously known as a "DispVM") is a lightweight VM that can be created quickly and will disappear when closed. DisposableVMs are usually created in order to host a single application, like a viewer, editor, or web browser. @@ -26,23 +26,21 @@ While running, DisposableVMs will appear in Qubes VM Manager with the name `disp This diagram provides a general example of how DisposableVMs can be used to safely open untrusted links and attachments in DisposableVMs. See [this article](https://blog.invisiblethings.org/2010/06/01/disposable-vms.html) for more on why one would want to use a DisposableVM. - -## Security ## +## Security If a [DisposableVM Template] becomes compromised, then any DisposableVM based on that DisposableVM Template could be compromised. In particular, the *default* DisposableVM Template is important because it is used by the "Open in DisposableVM" feature. This means that it will have access to everything that you open with this feature. For this reason, it is strongly recommended that you base the default DisposableVM Template on a trusted TemplateVM. -### DisposableVMs and Local Forensics ### +### DisposableVMs and Local Forensics At this time, DisposableVMs should not be relied upon to circumvent local forensics, as they do not run entirely in RAM. For details, see [this thread](https://groups.google.com/d/topic/qubes-devel/QwL5PjqPs-4/discussion). When it is essential to avoid leaving any trace, consider using [Tails](https://tails.boum.org/). - -## DisposableVMs and Networking ## +## DisposableVMs and Networking Similarly to how AppVMs are based on their underlying [TemplateVM](https://www.qubes-os.org/doc/glossary/#templatevm), DisposableVMs are based on their underlying [DisposableVM Template](https://www.qubes-os.org/doc/glossary/#disposablevm-template). R4.0 introduces the concept of multiple DisposableVM Templates, whereas R3.2 was limited to only one. @@ -52,7 +50,9 @@ If you have included the Whonix option in your install, there will also be a `wh You can set any AppVM to have the ability to act as a DisposableVM Template with: - qvm-prefs template_for_dispvms True +``` +qvm-prefs template_for_dispvms True +``` The default system wide DisposableVM Template can be changed with `qubes-prefs default_dispvm`. By combining the two, choosing `Open in DisposableVM` from inside an AppVM will open the document in a DisposableVM based on the default DisposableVM Template you specified. @@ -61,7 +61,9 @@ You can change this behaviour for individual VMs: in the Application Menu, open Here you can edit the "Default DisposableVM" setting to specify which DisposableVM Template will be used to launch DisposableVMs from that VM. This can also be changed from the command line with: - qvm-prefs default_dispvm +``` +qvm-prefs default_dispvm +``` For example, `anon-whonix` has been set to use `whonix-ws-dvm` as its `default_dispvm`, instead of the system default. You can even set an AppVM that has also been configured as a DisposableVM Template to use itself, so DisposableVMs launched from within the AppVM/DisposableVM Template would inherit the same settings. @@ -82,14 +84,17 @@ Different DisposableVM Templates with individual NetVM settings can be added to **Important Notes:** Some DisposableVM Templates will automatically create a menu item to launch a DVM, if you do not see an entry and want to add one please use the command: - qvm-features deb-dvm appmenus-dispvm 1 +``` +qvm-features deb-dvm appmenus-dispvm 1 +``` To launch a DVM from the command line, in dom0 please type the following: - - qvm-run --dispvm=NameOfDVM --service qubes.StartApp+NameOfApp +``` +qvm-run --dispvm=NameOfDVM --service qubes.StartApp+NameOfApp +``` -## Opening a file in a DisposableVM via GUI ## +## Opening a file in a DisposableVM via GUI In an AppVM's file manager, right click on the file you wish to open in a DisposableVM, then choose "Open in DisposableVM". Wait a few seconds and the default application for this file type should appear displaying the file content. @@ -99,8 +104,7 @@ If you have edited the file and saved the changes, the changed file will be save ![r4.1-open-in-dispvm-1.png](/attachment/wiki/DisposableVms/r4.1-open-in-dispvm-1.png) ![r4.1-open-in-dispvm-2.png](/attachment/wiki/DisposableVms/r4.1-open-in-dispvm-2.png) - -## Opening a fresh web browser instance in a new DisposableVM ## +## Opening a fresh web browser instance in a new DisposableVM Sometimes it is desirable to open an instance of Firefox within a new fresh DisposableVM. This can be done easily using the Start Menu: just go to **Application Menu -\> DisposableVM -\> DisposableVM:Firefox web browser**. @@ -109,8 +113,7 @@ Once you close the viewing application the whole DisposableVM will be destroyed. ![r4.1-open-in-dispvm-3.png](/attachment/wiki/DisposableVms/r4.1-open-in-dispvm-3.png) - -## Opening a file in a DisposableVM via command line (from AppVM) ## +## Opening a file in a DisposableVM via command line (from AppVM) Use the `qvm-open-in-dvm` command from a terminal in your AppVM: @@ -120,8 +123,7 @@ Use the `qvm-open-in-dvm` command from a terminal in your AppVM: Note that the `qvm-open-in-dvm` process will not exit until you close the application in the DisposableVM. - -## Starting an arbitrary program in a DisposableVM from an AppVM ## +## Starting an arbitrary program in a DisposableVM from an AppVM Sometimes it can be useful to start an arbitrary program in a DisposableVM. This can be done from an AppVM by running @@ -132,8 +134,7 @@ This can be done from an AppVM by running The created DisposableVM can be accessed via other tools (such as `qvm-copy-to-vm`) using its `disp####` name as shown in the Qubes Manager or `qvm-ls`. - -## Starting an arbitrary application in a DisposableVM via command line from dom0 ## +## Starting an arbitrary application in a DisposableVM via command line from dom0 The Application Launcher has shortcuts for opening a terminal and a web browser in dedicated DisposableVMs, since these are very common tasks. However, it is possible to start an arbitrary application in a DisposableVM directly from dom0 by running: @@ -145,8 +146,7 @@ $ qvm-run --dispvm=dvm-template --service qubes.StartApp+xterm The label color will be inherited from the `dvm-template`. (The DisposableVM Application Launcher shortcut used for starting programs runs a very similar command to the one above.) - -### Opening a link in a DisposableVM based on a non-default DisposableVM Template from a qube ### +### Opening a link in a DisposableVM based on a non-default DisposableVM Template from a qube Suppose that the default DisposableVM Template for your `email` qube has no networking (e.g., so that untrusted attachments can't phone home). However, sometimes you want to open email links in DisposableVMs. @@ -162,9 +162,11 @@ This will create a new DisposableVM based on `online-dvm-template`, open the def #### Example of RPC policies to allow this behavior In dom0, add the following line at the beginning of the file `/etc/qubes-rpc/policy/qubes.OpenURL` + ~~~ @anyvm @dispvm:online-dvm-template allow ~~~ + This line means: - FROM: Any VM - TO: A DisposableVM based on the `online-dvm-template` TemplateVM @@ -174,13 +176,11 @@ In other words, any VM will be allowed to create a new DisposableVM based on `on More information about RPC policies for DisposableVMs can be found [here][qrexec]. - -## Customizing DisposableVMs ## +## Customizing DisposableVMs You can change the template used to generate the DisposableVMs, and change settings used in the DisposableVM savefile. These changes will be reflected in every new DisposableVM based on that template. Full instructions can be found [here](/doc/disposablevm-customization/). - [DisposableVM Template]: /doc/glossary/#disposablevm-template [qrexec]: /doc/qrexec/#qubes-rpc-administration diff --git a/en/_doc/user/common-tasks/full-screen-mode.md b/en/_doc/user/common-tasks/full-screen-mode.md index 1d6762c8d9..281b5a8345 100644 --- a/en/_doc/user/common-tasks/full-screen-mode.md +++ b/en/_doc/user/common-tasks/full-screen-mode.md @@ -67,7 +67,6 @@ global: { Be sure to restart the VM(s) after modifying this file, for the changes to take effect. - **Note:** Regardless of the settings above, you can always put a window into fullscreen mode in Xfce4 using the trusted window manager by right-clicking on a window's title bar and selecting "Fullscreen" or pressing `alt` + `f11`. This functionality should still be considered safe, since a VM window still can't voluntarily enter fullscreen mode. The user must select this option from the trusted window manager in dom0. diff --git a/en/_doc/user/common-tasks/getting-started.md b/en/_doc/user/common-tasks/getting-started.md index 62841452d1..98d026e5c6 100644 --- a/en/_doc/user/common-tasks/getting-started.md +++ b/en/_doc/user/common-tasks/getting-started.md @@ -29,10 +29,10 @@ So, creating a large number of qubes is cheap: each one needs only as much disk If you've installed Qubes OS using the default options, a few qubes have already been created for you: - - work - - personal - - untrusted - - vault +- work +- personal +- untrusted +- vault Each qube, apart from having a distinct name, is also assigned a **label**, which is one of several predefined colors. The trusted window manager uses these colors in order to draw colored borders around the windows of applications running in each qube. @@ -59,31 +59,29 @@ Dom0 shouldn't be used for anything else. In particular, [you should never run user applications in dom0][dom0-precautions]. (That's what your qubes are for!) - GUI and command-line tools -------------------------- All aspects of Qubes OS can be controlled using command-line tools run in a dom0 terminal. Opening a terminal in dom0 can be done in several ways: - - Go to the Application Launcher and click **Terminal Emulator**. - - Press `Alt+F3`, type `xfce terminal` and press Enter twice. - - Right-click on the desktop and select **Open Terminal Here**. +- Go to the Application Launcher and click **Terminal Emulator**. +- Press `Alt+F3`, type `xfce terminal` and press Enter twice. +- Right-click on the desktop and select **Open Terminal Here**. Various command-line tools are described as part of this guide, and the whole reference can be found [here][tools]. Alternatively, you can use a suite of GUI tools, most of which are available through desktop widgets: - - The **Domains Widget** allows you to manage running qubes, turn them on and off, and monitor memory usage. - - The **Devices Widget** allows you to attach and detach devices -- such as USB drives and cameras -- to qubes. - - The **Disk Space Widget** will notify you if you're ever running out of disk space. - - The **Updates Widget** will inform you when template updates are available. +- The **Domains Widget** allows you to manage running qubes, turn them on and off, and monitor memory usage. +- The **Devices Widget** allows you to attach and detach devices -- such as USB drives and cameras -- to qubes. +- The **Disk Space Widget** will notify you if you're ever running out of disk space. +- The **Updates Widget** will inform you when template updates are available. ![q40_widgets.png](/attachment/wiki/GettingStarted/r4.1-q40_widgets.png) For an overview of the entire system, you can use the **Qube Manager** (go to the Application Launcher → System Tools → Qube Manager), which displays the states of all the qubes in your system. - Starting apps ------------- @@ -102,14 +100,17 @@ If you'd like to add more, enter the qube's **Qube Settings** and add them on th To start apps from the terminal in dom0, type: - $ qvm-run [arguments] +```shell_session +$ qvm-run [arguments] +``` e.g.: - $ qvm-run untrusted firefox - -This command will start the qube if it is not already running. +```shell_session +$ qvm-run untrusted firefox +``` +This command will start the qube if it is not already running. Adding, removing, and listing qubes ----------------------------------- @@ -119,10 +120,9 @@ If you need to add or remove qubes, simply use the Qube Manager's **Add** and ** You can also add, remove, and list qubes from the command line using the following tools: - - `qvm-create` - - `qvm-remove` - - `qvm-ls` - +- `qvm-create` +- `qvm-remove` +- `qvm-ls` How many qubes do I need? ------------------------- @@ -138,11 +138,9 @@ You'll also be able to easily [copy][copy-files] any files you need to the newly Still not sure? You might find it helpful to read [this article][partitioning], which describes how one of the Qubes OS architects partitions her digital life into security domains. - Important tasks --------------- - It's very important to [keep Qubes updated][update] to ensure you have the latest security updates. Frequently updating is one of the best ways to remain secure against new threats. @@ -152,28 +150,30 @@ The [Qubes backup system] allows you to do this securely and easily. Here are some other tasks you're likely to want to perform. (A full list is available in the [Common Tasks] section of the documentation.) - * [Copying and Pasting Text Between Domains][copy-paste] - * [Copying and Moving Files Between Domains][copy-files] - * [Copying from (and to) dom0] - * [Fullscreen Mode] - * [DisposableVMs] - * [Device Handling] (block, USB, and PCI devices) +- [Copying and Pasting Text Between Domains][copy-paste] +- [Copying and Moving Files Between Domains][copy-files] +- [Copying from (and to) dom0] +- [Fullscreen Mode] +- [DisposableVMs] +- [Device Handling] (block, USB, and PCI devices) If you encounter any problems, please visit the [Help, Support, and Mailing Lists] page. -## Compatible Hardware +Compatible Hardware +------------------- Make sure your hardware is [compatible](/hcl/), as Qubes OS cannot run on every type of computer. Also, check out [Qubes-certified Laptops](/doc/certified-laptops/). -## Downloads +Downloads +--------- [Download](/downloads/) an ISO, learn how to verify its authenticity and integrity, and follow our guides to install Qubes OS. Looking for the source code? You'll find it on [GitHub](https://github.com/QubesOS). -## Documentation +Documentation +------------- Peruse our extensive library of [documentation](/doc/) for users and developers of Qubes OS. You can even help us [improve](/doc/doc-guidelines/) it! - [getting-started-32]: /getting-started-32/ [downloading]: /downloads/ [installing]: /doc/installation-guide/ diff --git a/en/_doc/user/common-tasks/managing-appvm-shortcuts.md b/en/_doc/user/common-tasks/managing-appvm-shortcuts.md index c183b6227a..42f294cb72 100644 --- a/en/_doc/user/common-tasks/managing-appvm-shortcuts.md +++ b/en/_doc/user/common-tasks/managing-appvm-shortcuts.md @@ -41,6 +41,7 @@ To do this: 2. Create a custom `.desktop` file in `/usr/share/applications` (you may need to first create the subdirectory). Look in `/usr/share/applications` for existing examples, or see the full [file specification](https://specifications.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html). It will be something like: + ``` [Desktop Entry] Version=1.0 @@ -53,6 +54,7 @@ To do this: Categories=Office;Scanning; Exec=vuescan ``` + 3. In dom0, run `qvm-sync-appmenus `. 4. Go to VM Settings of the AppVM(s) to which you want to add the new shortcut, then the Applications tab. Move the newly created shortcut to the right under selected. @@ -80,7 +82,6 @@ What about applications in DispVMs? [See here](/doc/disposablevm-customization/). - Fixing shortcuts ---------------- @@ -99,7 +100,6 @@ In dom0: $ rm -i ~/.local/share/applications/my-old-vm-* ``` - Behind the scenes ----------------- diff --git a/en/_doc/user/common-tasks/pci-devices.md b/en/_doc/user/common-tasks/pci-devices.md index b406336cc9..5164955635 100644 --- a/en/_doc/user/common-tasks/pci-devices.md +++ b/en/_doc/user/common-tasks/pci-devices.md @@ -11,7 +11,7 @@ ref: 197 title: PCI Devices --- -# PCI Devices # +# PCI Devices *This page is part of [device handling in qubes].* @@ -21,8 +21,7 @@ You may end up with an unusable system by attaching the wrong PCI device to a VM PCI passthrough should be safe by default, but non-default options may be required. Please make sure you carefully read and understand the **[security considerations]** before deviating from default behavior. - -## Introduction ## +## Introduction Unlike other devices ([USB], [block], mic), PCI devices need to be attached on VM-bootup. Similar to how you can't attach a new sound-card after your computer booted (and expect it to work properly), attaching PCI devices to already booted VMs isn't supported. @@ -39,53 +38,56 @@ While PCI device can only be used by one powered on VM at a time, it *is* possib This means that you can use the device in one VM, shut that VM down, start up a different VM (to which the same device is now attached), then use the device in that VM. This can be useful if, for example, you have only one USB controller, but you have multiple security domains which all require the use of different USB devices. - -## Attaching Devices Using the GUI ## +## Attaching Devices Using the GUI The qube settings for a VM offers the "Devices"-tab. There you can attach PCI-devices to a qube. - 1. To reach the settings of any qube either +1. To reach the settings of any qube either - - Press Alt+F3 to open the application finder, type in the VM name, select the "![appmenu]\[VM-name\]: Qube Settings" menu entry and press enter or click "Launch"! - - Select the VM in Qube Manager and click the settings-button or right-click the VM and select `Qube settings`. - - Click the Domain Manager, hover the VM you want to attach a device to and select "settings" in the additional menu. (only running VMs!) + - Press Alt+F3 to open the application finder, type in the VM name, select the "![appmenu]\[VM-name\]: Qube Settings" menu entry and press enter or click "Launch"! + - Select the VM in Qube Manager and click the settings-button or right-click the VM and select `Qube settings`. + - Click the Domain Manager, hover the VM you want to attach a device to and select "settings" in the additional menu. (only running VMs!) - 2. Select the "Devices" tab on the top bar. - 3. Select a device you want to attach to the qube and click the single arrow right! (`>`) - 4. You're done. - If everything worked out, once the qube boots (or reboots if it's running) it will start with the pci device attached. - 5. In case it doesn't work out, first try disabling memory-balancing in the settings ("Advanced" tab). - If that doesn't help, read on to learn how to disable the strict reset requirement! +2. Select the "Devices" tab on the top bar. +3. Select a device you want to attach to the qube and click the single arrow right! (`>`) +4. You're done. + If everything worked out, once the qube boots (or reboots if it's running) it will start with the pci device attached. +5. In case it doesn't work out, first try disabling memory-balancing in the settings ("Advanced" tab). + If that doesn't help, read on to learn how to disable the strict reset requirement! - -## `qvm-pci` Usage ## +## `qvm-pci` Usage The `qvm-pci` tool allows PCI attachment and detachment. It's a shortcut for [`qvm-device pci`][qvm-device]. To figure out what device to attach, first list the available PCI devices by running (as user) in dom0: - qvm-pci +``` +qvm-pci +``` This will show you the `backend:BDF` (Bus_Device.Function) address of each PCI device. It will look something like `dom0:00_1a.0`. Once you've found the address of the device you want to attach, then attach it like this: - qvm-pci attach targetVM sourceVM:[BDF] --persistent +``` +qvm-pci attach targetVM sourceVM:[BDF] --persistent +``` Since PCI devices have to be attached on bootup, attaching has to happen with the `--persistant` option. For example, if `00_1a.0` is the BDF of the device you want to attach to the "work" domain, you would do this: - qvm-pci attach work dom0:00_1a.0 --persistent - +``` +qvm-pci attach work dom0:00_1a.0 --persistent +``` -## Possible Issues ## +## Possible Issues Visit the [PCI Troubleshooting guide](/doc/pci-troubleshooting/) to see issues that may arise due to PCI devices and how to troubleshoot them. -## Additional Attach Options ## +## Additional Attach Options Attaching a PCI device through the commandline offers additional options, specifiable via the `--option`/`-o` option. (Yes, confusing wording, there's an [issue for that](https://github.com/QubesOS/qubes-issues/issues/4530).) @@ -93,28 +95,29 @@ Attaching a PCI device through the commandline offers additional options, specif `qvm-pci` exposes two additional options. Both are intended to fix device or driver specific issues, but both come with [heavy security implications][security considerations]! **Make sure you understand them before continuing!** - -### no-strict-reset ### +### no-strict-reset Do not require PCI device to be reset before attaching it to another VM. This may leak usage data even without malicious intent! usage example: - qvm-pci a work dom0:00_1a.0 --persistent -o no-strict-reset=true - +``` +qvm-pci a work dom0:00_1a.0 --persistent -o no-strict-reset=true +``` -### permissive ### +### permissive Allow write access to full PCI config space instead of whitelisted registers. This increases attack surface and possibility of [side channel attacks]. usage example: - qvm-pci a work dom0:00_1a.0 --persistent -o permissive=true +``` +qvm-pci a work dom0:00_1a.0 --persistent -o permissive=true +``` - -## Bringing PCI Devices Back to dom0 ## +## Bringing PCI Devices Back to dom0 By default, when a device is detached from a VM (or when a VM with an attached PCI device is shut down), the device is *not* automatically attached back to dom0. @@ -124,20 +127,21 @@ A device which was previously attached to a VM less trusted than dom0 (which, in In order to re-enable the device in dom0, either: - * Reboot the physical machine. (Best practice) +- Reboot the physical machine. (Best practice) or - * Go to the sysfs (`/sys/bus/pci`), find the right device, detach it from the pciback driver, and attach it back to the original driver. - Replace `` with your full device, for example `0000:00:1c.2`: - - echo > /sys/bus/pci/drivers/pciback/unbind - MODALIAS=`cat /sys/bus/pci/devices//modalias` - MOD=`modprobe -R $MODALIAS | head -n 1` - echo > /sys/bus/pci/drivers/$MOD/bind +- Go to the sysfs (`/sys/bus/pci`), find the right device, detach it from the pciback driver, and attach it back to the original driver. + Replace `` with your full device, for example `0000:00:1c.2`: - It is **strongly discouraged to reattach PCI devices to dom0**, especially if they don't support resetting! + ``` + echo > /sys/bus/pci/drivers/pciback/unbind + MODALIAS=`cat /sys/bus/pci/devices//modalias` + MOD=`modprobe -R $MODALIAS | head -n 1` + echo > /sys/bus/pci/drivers/$MOD/bind + ``` +It is **strongly discouraged to reattach PCI devices to dom0**, especially if they don't support resetting! [device handling in qubes]: /doc/device-handling/ [security considerations]: /doc/device-handling-security/#pci-security diff --git a/en/_doc/user/common-tasks/software-update-dom0.md b/en/_doc/user/common-tasks/software-update-dom0.md index 6ee1b44ef6..9fad323618 100644 --- a/en/_doc/user/common-tasks/software-update-dom0.md +++ b/en/_doc/user/common-tasks/software-update-dom0.md @@ -44,13 +44,17 @@ In order to update dom0 from the command line, start a console in dom0 and then To check and install updates for dom0 software: - $ sudo qubes-dom0-update +``` +$ sudo qubes-dom0-update +``` ## How to install a specific package To install additional packages in dom0 (usually not recommended): - $ sudo qubes-dom0-update anti-evil-maid +``` +$ sudo qubes-dom0-update anti-evil-maid +``` You may also pass the `--enablerepo=` option in order to enable optional repositories (see yum configuration in dom0). However, this is only for advanced users who really understand what they are doing. @@ -60,7 +64,7 @@ You can also pass commands to `dnf` using `--action=...`. **WARNING:** Downgrading a package can expose your system to security vulnerabilities. -1. Download an older version of the package: +1. Download an older version of the package: ~~~ sudo qubes-dom0-update package-version @@ -68,7 +72,7 @@ You can also pass commands to `dnf` using `--action=...`. Dnf will say that there is no update, but the package will nonetheless be downloaded to dom0. -2. Downgrade the package: +2. Downgrade the package: ~~~ sudo dnf downgrade package-version @@ -78,7 +82,7 @@ You can also pass commands to `dnf` using `--action=...`. You can re-install in a similar fashion to downgrading. -1. Download the package: +1. Download the package: ~~~ sudo qubes-dom0-update package @@ -86,7 +90,7 @@ You can re-install in a similar fashion to downgrading. Dnf will say that there is no update, but the package will nonetheless be downloaded to dom0. -2. Re-install the package: +2. Re-install the package: ~~~ sudo dnf reinstall package @@ -99,17 +103,19 @@ You can re-install in a similar fashion to downgrading. If you've installed a package such as anti-evil-maid, you can remove it with the following command: - sudo dnf remove anti-evil-maid - +``` +sudo dnf remove anti-evil-maid +``` + ## Testing repositories There are three Qubes dom0 [testing] repositories: -* `qubes-dom0-current-testing` -- testing packages that will eventually land in the stable +- `qubes-dom0-current-testing` -- testing packages that will eventually land in the stable (`current`) repository -* `qubes-dom0-security-testing` -- a subset of `qubes-dom0-current-testing` that contains packages +- `qubes-dom0-security-testing` -- a subset of `qubes-dom0-current-testing` that contains packages that qualify as security fixes -* `qubes-dom0-unstable` -- packages that are not intended to land in the stable (`qubes-dom0-current`) +- `qubes-dom0-unstable` -- packages that are not intended to land in the stable (`qubes-dom0-current`) repository; mostly experimental debugging packages To temporarily enable any of these repos, use the `--enablerepo=` option. @@ -137,12 +143,14 @@ This section describes upgrading the kernel in dom0 and domUs. The packages `kernel` and `kernel-latest` are for dom0. In the `current` repository: - - `kernel`: an older LTS kernel that has passed Qubes [testing] (the default dom0 kernel) - - `kernel-latest`: the latest release from kernel.org that has passed Qubes [testing] (useful for [troubleshooting newer hardware]) + +- `kernel`: an older LTS kernel that has passed Qubes [testing] (the default dom0 kernel) +- `kernel-latest`: the latest release from kernel.org that has passed Qubes [testing] (useful for [troubleshooting newer hardware]) In the `current-testing` repository: - - `kernel`: the latest LTS kernel from kernel.org at the time it was built. - - `kernel-latest`: the latest release from kernel.org at the time it was built. + +- `kernel`: the latest LTS kernel from kernel.org at the time it was built. +- `kernel-latest`: the latest release from kernel.org at the time it was built. ### domU @@ -162,11 +170,13 @@ from the update command), you may need to manually rebuild the EFI or grub confi your system uses. *EFI*: Replace the example version numbers with the one you are upgrading to. + ~~~ sudo dracut -f /boot/efi/EFI/qubes/initramfs-4.14.35-1.pvops.qubes.x86_64.img 4.14.35-1.pvops.qubes.x86_64 ~~~ *Grub2* + ~~~ sudo grub2-mkconfig -o /boot/grub2/grub.cfg ~~~ @@ -185,16 +195,20 @@ The procedure varies depending on if you are booting with UEFI or grub. On the next kernel update, the default will revert to the newest. *EFI* + ~~~ sudo nano /boot/efi/EFI/qubes/xen.cfg ~~~ + In the `[global]` section at the top, change the `default=` line to match one of the three boot entries listed below. For example, + ~~~ default=4.19.67-1.pvops.qubes.x86_64 ~~~ *Grub2* + ~~~ sudo nano /etc/default/grub [update the following two lines, add if needed] @@ -203,12 +217,13 @@ GRUB_SAVEDEFAULT=true [save and exit nano] sudo grub2-mkconfig -o /boot/grub2/grub.cfg ~~~ + Then, reboot. Once the grub menu appears, choose "Advanced Options for Qubes (with Xen hypervisor)". Next, the top menu item (for example, "Xen hypervisor, version 4.8.5-9.fc25"). Select the kernel you want as default, and it will be remembered for next boot. -## Updating over Tor ### +## Updating over Tor Requires installed [Whonix](/doc/privacy/whonix/). @@ -217,8 +232,9 @@ See the UpdateVM setting. Choose your desired Whonix-Gateway ProxyVM from the list. For example: sys-whonix. - Qubes VM Manager -> System -> Global Settings -> UpdateVM -> sys-whonix - +` +Qubes VM Manager -> System -> Global Settings -> UpdateVM -> sys-whonix +` [Updating Qubes OS]: /doc/updating-qubes-os/ [security]: /security/ diff --git a/en/_doc/user/common-tasks/software-update-domu.md b/en/_doc/user/common-tasks/software-update-domu.md index 17cc707095..aa493b4fc9 100644 --- a/en/_doc/user/common-tasks/software-update-domu.md +++ b/en/_doc/user/common-tasks/software-update-domu.md @@ -17,17 +17,15 @@ Updating [domUs], especially [TemplateVMs] and [StandaloneVMs][StandaloneVM] are It is very import to keep domUs up-to-date with the latest [security] updates. Updating these VMs also allows you to receive various non-security bug fixes and enhancements both from the Qubes OS Project and from your upstream distro maintainer. - ## Installing software in TemplateVMs To permanently install new software in a TemplateVM: - 1. Start the TemplateVM. - 2. Start either a terminal (e.g. `gnome-terminal`) or a dedicated software management application, such as `gpk-application`. - 3. Install software as normally instructed inside that operating system (e.g. using `dnf`, or the dedicated GUI application). - 4. Shut down the TemplateVM. - 5. Restart all [TemplateBasedVMs] based on the TemplateVM. - +1. Start the TemplateVM. +2. Start either a terminal (e.g. `gnome-terminal`) or a dedicated software management application, such as `gpk-application`. +3. Install software as normally instructed inside that operating system (e.g. using `dnf`, or the dedicated GUI application). +4. Shut down the TemplateVM. +5. Restart all [TemplateBasedVMs] based on the TemplateVM. ## Updating software in TemplateVMs @@ -40,7 +38,6 @@ You can also update TemplateVMs individually. In the Qube Manager, select the desired TemplateVM, then click **Update qube**. Advanced users can execute the standard update command for that operating system from the command line, e.g. `dnf update` in Fedora and `apt-get update` in Debian. - ## Testing repositories If you wish to install updates that are still in [testing], you must enable the appropriate testing repositories. @@ -49,9 +46,9 @@ If you wish to install updates that are still in [testing], you must enable the There are three Qubes VM testing repositories (where `*` denotes the Release): -* `qubes-vm-*-current-testing` -- testing packages that will eventually land in the stable (`current`) repository -* `qubes-vm-*-security-testing` -- a subset of `qubes-vm-*-current-testing` that contains packages that qualify as security fixes -* `qubes-vm-*-unstable` -- packages that are not intended to land in the stable (`qubes-vm-*-current`) repository; mostly experimental debugging packages +- `qubes-vm-*-current-testing` -- testing packages that will eventually land in the stable (`current`) repository +- `qubes-vm-*-security-testing` -- a subset of `qubes-vm-*-current-testing` that contains packages that qualify as security fixes +- `qubes-vm-*-unstable` -- packages that are not intended to land in the stable (`qubes-vm-*-current`) repository; mostly experimental debugging packages To temporarily enable any of these repos, use the `--enablerepo=` option. Example commands: @@ -64,23 +61,20 @@ sudo dnf upgrade --enablerepo=qubes-vm-*-unstable To enable or disable any of these repos permanently, change the corresponding `enabled` value to `1` in `/etc/yum.repos.d/qubes-*.repo`. - ### Debian Debian also has three Qubes VM testing repositories (where `*` denotes the Release): -* `*-testing` -- testing packages that will eventually land in the stable (`current`) repository -* `*-securitytesting` -- a subset of `*-testing` that contains packages that qualify as security fixes -* `*-unstable` -- packages that are not intended to land in the stable repository; mostly experimental debugging packages +- `*-testing` -- testing packages that will eventually land in the stable (`current`) repository +- `*-securitytesting` -- a subset of `*-testing` that contains packages that qualify as security fixes +- `*-unstable` -- packages that are not intended to land in the stable repository; mostly experimental debugging packages To enable or disable any of these repos permanently, uncomment the corresponding `deb` line in `/etc/apt/sources.list.d/qubes-r*.list`. - ## Contributed package repository Please see [installing contributed packages]. - ## StandaloneVMs When you create a [StandaloneVM] from a TemplateVM, the StandaloneVM is a complete clone of the TemplateVM, including the entire filesystem. @@ -89,12 +83,10 @@ Therefore, it will not be updated when the TemplateVM is updated. Rather, it must be updated individually. The process for installing and updating software in StandaloneVMs is the same as described above for TemplateVMs. - ## Advanced The following sections cover advanced topics pertaining to installing and updating software in domUs. - ### RPMFusion for Fedora TemplateVMs If you would like to enable the [RPM Fusion] repositories, open a Terminal of the TemplateVM and type the following commands, depending on which RPM Fusion repositories you wish to enable (see [RPM Fusion] for details): @@ -107,7 +99,6 @@ sudo dnf config-manager --set-enabled rpmfusion-nonfree-updates sudo dnf upgrade --refresh ~~~ - ### Reverting changes to a TemplateVM Perhaps you've just updated your TemplateVM, and the update broke your template. @@ -125,7 +116,6 @@ If you want to undo changes to a TemplateVM, there are three basic methods: This is appropriate for both misconfigurations and security concerns, and it can preserve your customizations. However, it is a bit more complex. - #### Root revert **Important:** This command will roll back any changes made *during the last time the TemplateVM was run, but **not** before.* @@ -138,25 +128,24 @@ Just make sure to **back up** all of your data and changes first! 2. In a dom0 terminal: +``` qvm-volume revert