Git-Mirrors/qubes-doc
1
0
Fork 0
mirror of https://github.com/QubesOS/qubes-doc.git synced 2024-12-25 15:29:29 -05:00
Code Issues Packages Projects Releases Wiki Activity

Remove deprecated R3.2 content; update and organize

Browse Source 
Closes QubesOS/qubes-issues#4936
This commit is contained in:
Andrew David Wong 2019-04-06 18:44:36 -05:00
parent 4deb30f575
commit 6a2594a442
No known key found for this signature in database
GPG Key ID: 8CE137352A019A17
38 changed files with 245 additions and 1614 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
about/screenshots.md
View File

@ -13,7 +13,7 @@ Select Qubes OS Screenshots
[![r32-xfce-desktop.png](/attachment/wiki/QubesScreenshots/r32-xfce-desktop.png)](/attachment/wiki/QubesScreenshots/r32-xfce-desktop.png)
Beginning with Qubes 3.2, the default desktop environment is Xfce4.
The default desktop environment is Xfce4.
* * * * *

96
common-tasks/backup-restore.md
View File

@ -11,17 +11,13 @@ redirect_from:
Qubes Backup, Restoration, and Migration
========================================
**Caution:** The Qubes R3.2 backup system currently relies on a [weak key derivation scheme](https://github.com/QubesOS/qubes-issues/issues/971).
Although resolved in R4.0 and higher with the switch to scrypt, it is *strongly recommended* that users select a *high-entropy* passphrase for use with Qubes backups.
With Qubes, it's easy to back up and restore your whole system, as well as to migrate between two physical machines.
As of Qubes R2B3, these functions are integrated into the Qubes VM Manager GUI.
These functions are integrated into Qube Manager.
There are also two command-line tools available which perform the same functions: `qvm-backup` and `qvm-backup-restore`.
Creating a Backup (R4.0 and later)
Creating a Backup
-----------------
1. Go to **Applications menu -> System Tools -> Backup Qubes**.
@ -62,50 +58,8 @@ If there are any issues preventing the backup, they will be listed here and the
Qubes will proceed to create your backup.
Once the progress bar has completed, you may click **Finish**.
Creating a Backup (R3.2 and earlier)
-----------------
1. In **Qubes VM Manager**, click **System** on the menu bar, then click **Backup VMs** in the drop-down list.
This brings up the **Qubes Backup VMs** window.
2. Move the VMs that you want to back up to the right-hand **Selected** column.
VMs in the left-hand **Available** column will not be backed up.
**Note:** A VM must be shut down in order to be backed up.
Currently running VMs appear in red.
Once you have selected all desired VMs, click **Next**.
3. Select the destination for the backup:
If you wish to send your backup to a (currently running) VM, select the VM in the drop-down box next to **Target AppVM**.
If you wish to send your backup to a [USB mass storage device](/doc/usb/), you can use the directory selection widget to mount a connected device (under "Other locations" item on the left); or first mount the device in a VM, then select the mount point inside that VM as the backup destination.
You must also specify a directory on the device or in the VM, or a command to be executed in the VM as a destination for your backup.
For example, if you wish to send your backup to the `~/backups` folder in the target VM, you would simply browse to it using the convenient directory selection dialog (`...`) at the right.
If it does not exist, you must create it manually prior to backing up.
By specifying the appropriate directory as the destination in a VM, it is possible to send the backup directly to, e.g., a USB mass storage device attached to the VM.
Likewise, it is possible to enter any command as a backup target by specifying the command as the destination in the VM.
This can be used to send your backup directly to, e.g., a remote server using SSH.
At this point, you must also choose whether to encrypt your backup by checking or unchecking the **Encrypt backup** box.
**Note:** It is strongly recommended that you opt to encrypt all backups which will be sent to untrusted destinations!
**Note:** The supplied passphrase is used for **both** encryption/decryption and integrity verification.
If you decide not to encrypt your backup (by unchecking the **Encrypt backup** box), the passphrase you supply will be used **only** for integrity verification.
If you supply a passphrase but do not check the **Encrypt backup** box, your backup will **not** be encrypted!
4. You will now see the summary of VMs to be backed up.
If there are any issues preventing the backup, they will be listed here and the **Next** button grayed out.
5. When you are ready, click **Next**.
Qubes will proceed to create your backup.
Once the progress bar has completed, you may click **Finish**.
Restoring from a Backup (R4.0 and later)
Restoring from a Backup
-----------------------
1. Go to **Applications menu -> System Tools -> Restore Backup**.
@ -143,45 +97,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**.
Restoring from a Backup (R3.2 and earlier)
-----------------------
1. In **Qubes VM Manager**, click **System** on the menu bar, then click **Restore VMs from backup** in the drop-down list.
This brings up the **Qubes Restore VMs** window.
2. Select the source location of the backup to be restored:
- If your backup is located on a [USB mass storage device](/doc/usb/), attach it first to another VM or select `sys-usb` in the next item.
- If your backup is located in a (currently running) VM, select the VM in the drop-down box next to **AppVM**.
You must also specify the directory and filename of the backup (or a command to be executed in a VM) in the **Backup file** field.
If you followed the instructions in the previous section, "Creating a Backup," then your backup is most likely in the location you chose as the destination in step 3.
For example, if you had chosen the `~/backups` directory of a VM as your destination in step 3, you would now select the same VM and again browse to (using `...`) the `backups` folder.
Once you've located the backup file, double-click or select it and hit **OK**.
3. There are three options you may select when restoring from a backup:
1. **ignore missing**: If any of the VMs in your backup depended upon a NetVM, ProxyVM, 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.
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.
4. If your backup is encrypted, you must check the **Encrypted backup** box.
If a passphrase was supplied during the creation of your backup (regardless of whether it is encrypted), then you must supply it here.
**Note:** The passphrase which was supplied when the backup was created was used for **both** encryption/decryption and integrity verification.
If the backup was not encrypted, the supplied passphrase is used only for integrity verification.
**Note:** A VM cannot be restored from a backup if a VM with the same name already exists on the current system.
You must first remove or change the name of any VM with the same name in order to restore such a VM.
5. You will now see the summary of VMs to be restored.
If there are any issues preventing the restore, they will be listed here and the **Next** button grayed out.
6. When you are ready, click **Next**.
Qubes will proceed to restore from your backup.
Once the progress bar has completed, you may click **Finish**.
Emergency Backup Recovery without Qubes
---------------------------------------
@ -220,9 +135,6 @@ Here are some things to consider when selecting a passphrase for your backups:
Notes
-----
* The Qubes R3.2 and earlier backup system relies on `openssl enc`, which is known to use a very weak key derivation scheme.
The Qubes backup system also uses the same passphrase for authentication and for encryption, which is problematic from a security perspective.
Users are advised to use a very high entropy passphrase for Qubes backups.
For a full discussion, see [this ticket](https://github.com/QubesOS/qubes-issues/issues/971) and [this thread](https://groups.google.com/d/msg/qubes-devel/CZ7WRwLXcnk/u_rZPoVxL5IJ).
* 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).

6
common-tasks/copy-from-dom0.md
View File

@ -39,11 +39,7 @@ You may now paste the log contents to any VM as you normally would (i.e., Ctrl-S
For data other than logs, there are several options:
1. Copy it as a file (see above)
2. In Qubes 3.2 you can copy text to the dom0 clipboard (Ctrl-C as normal), then click "Copy Dom0 clipboard" in the Qubes menu:
![copy-dom0-clipboard](/attachment/wiki/QubesScreenshots/r3.2-dom0-copyout.png)
which is equivelant to Ctrl-Shift-C from a normal AppVM.
Then you can use Ctrl-Shift-V and Ctrl-V or Shift-Insert to paste the copied text into an AppVM as normal.
3. In other versions, 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. Wwrite 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.

99
common-tasks/disposablevm.md
View File

@ -38,10 +38,7 @@ For details, see [this thread](https://groups.google.com/d/topic/qubes-devel/QwL
When it is essential to avoid leaving any trace, consider using [Tails](https://tails.boum.org/).
## Qubes 4.0 ##
### 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.
@ -87,7 +84,7 @@ To launch a DVM from the command line, in dom0 please type the following:
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.
@ -98,7 +95,7 @@ If you have edited the file and saved the changes, the changed file will be save
![r1-open-in-dispvm-1.png](/attachment/wiki/DisposableVms/r1-open-in-dispvm-1.png) ![r1-open-in-dispvm-2.png](/attachment/wiki/DisposableVms/r1-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**.
@ -108,7 +105,7 @@ Once you close the viewing application the whole DisposableVM will be destroyed.
![r1-open-in-dispvm-3.png](/attachment/wiki/DisposableVms/r1-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:
@ -119,7 +116,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
@ -130,7 +127,7 @@ Sometimes it can be useful to start an arbitrary program in a DisposableVM. This
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:
@ -143,7 +140,7 @@ 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.
@ -157,87 +154,7 @@ $ qvm-open-in-vm @dispvm:online-dvm-template https://www.qubes-os.org
This will create a new DisposableVM based on `online-dvm-template`, open the default web browser in that DisposableVM, and navigate to `https://www.qubes-os.org`.
### 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/).
## Qubes 3.2 ##
### DisposableVMs and Networking ###
NetVM and firewall rules for DisposableVMs can be set as they can for a normal VM.
By default a DisposableVM will inherit the NetVM and firewall settings of the VM from which it is launched.
Thus if an AppVM uses sys-net as its NetVM, any DisposableVM launched from this AppVM will also have sys-net as its NetVM.
You can change this behaviour for individual VMs: in Qubes VM Manager open VM Settings for the VM in question and go to the "Advanced" tab.
Here you can edit the "NetVM for DisposableVM" setting to change the NetVM of any DisposableVM launched from that VM.
A DisposableVM launched from the Start Menu inherits the NetVM of the [DisposableVM Template](/doc/glossary/#disposablevm-template).
By default the DVM template is called `fedora-XX-dvm` (where `XX` is the Fedora version of the default TemplateVM).
As an "internal" VM it is hidden in Qubes VM Manager, but can be shown by selecting "Show/Hide internal VMs".
Note that changing the "NetVM for DisposableVM" setting for the DisposableVM Template does *not* affect the NetVM of DisposableVMs launched from the Start Menu; only changing the DisposableVM Template's own NetVM does.
### 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.
This app is running in its own dedicated VM -- a DisposableVM created for the purpose of viewing or editing this very file.
Once you close the viewing application the whole DisposableVM will be destroyed.
If you have edited the file and saved the changes, the changed file will be saved back to the original AppVM, overwriting the original.
![r1-open-in-dispvm-1.png](/attachment/wiki/DisposableVms/r1-open-in-dispvm-1.png) ![r1-open-in-dispvm-2.png](/attachment/wiki/DisposableVms/r1-open-in-dispvm-2.png)
### 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**.
Wait a few seconds until a web browser starts.
Once you close the viewing application the whole DisposableVM will be destroyed.
![r1-open-in-dispvm-3.png](/attachment/wiki/DisposableVms/r1-open-in-dispvm-3.png)
### Opening a file in a DisposableVM via command line (from AppVM) ###
Use the `qvm-open-in-dvm` command from a terminal in your AppVM:
~~~
[user@work-pub ~]$ qvm-open-in-dvm Downloads/apple-sandbox.pdf
~~~
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 ###
Sometimes it can be useful to start an arbitrary program in a DisposableVM. This can be done from an AppVM by running
~~~
[user@vault ~]$ qvm-run '$dispvm' xterm
~~~
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) ###
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:
~~~
$ echo xterm | /usr/lib/qubes/qfile-daemon-dvm qubes.VMShell dom0 DEFAULT red
~~~
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.)
### 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.

27
common-tasks/managing-appvm-shortcuts.md
View File

@ -87,25 +87,12 @@ This service enumerates installed applications and sends formatted info back to
For Linux VMs the service script is in `/etc/qubes-rpc/qubes.GetAppMenus`.
In Windows it's a PowerShell script located in `c:\Program Files\Invisible Things Lab\Qubes OS Windows Tools\qubes-rpc-services\get-appmenus.ps1` by default.
* R4.0
The list of installed applications for each AppVM is stored in dom0's `~/.local/share/qubes-appmenus/<vmname>/apps.templates`.
Each menu entry is a file that follows the [.desktop file format](https://standards.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html) with some wildcards (*%VMNAME%*, *%VMDIR%*).
Applications selected to appear in the menu are stored in `~/.local/share/qubes-appmenus/<vmname>/apps`.
Actual command lines for the menu shortcuts involve `qvm-run` command which starts a process in another domain.
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`
The list of installed applications for each AppVM is stored in dom0's `~/.local/share/qubes-appmenus/<vmname>/apps.templates`.
Each menu entry is a file that follows the [.desktop file format](https://standards.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html) with some wildcards (*%VMNAME%*, *%VMDIR%*).
Applications selected to appear in the menu are stored in `~/.local/share/qubes-appmenus/<vmname>/apps`.
Actual command lines for the menu shortcuts involve `qvm-run` command which starts a process in another domain.
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`.
* R3.2
The list of installed applications for each AppVM is stored in dom0's `/var/lib/qubes/vm-templates/<templatename>/apps.templates` (or in case of StandaloneVM: `/var/lib/qubes/appvms/<vmname>/apps.templates`).
Each menu entry is a file that follows the [.desktop file format](https://standards.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html) with some wildcards (*%VMNAME%*, *%VMDIR%*).
Applications selected to appear in the menu are stored in `/var/lib/qubes/appvms/<vmname>/apps`.
Actual command lines for the menu shortcuts involve `qvm-run` command which starts a process in another domain.
Examples: `qvm-run -q --tray -a w7s 'cmd.exe /c "C:\\ProgramData\\Microsoft\\Windows\\Start Menu\\Programs\\Accessories\\Calculator.lnk"'` or `qvm-run -q --tray -a untrusted 'firefox %u'`
Note that you can create a shortcut that points to a .desktop file in your AppVM with e.g. `qvm-run -q --tray -a personal -- 'qubes-desktop-run /home/user/application.desktop'`.
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`.

13
common-tasks/software-update-dom0.md
View File

@ -34,7 +34,7 @@ How to install and update software in dom0
### How to update dom0
In the Qubes VM Manager, simply select dom0 in the VM list, then click the **Update VM system** button (the blue, downward-pointing arrow). In addition, updating dom0 has been made more convenient: You will be prompted on the desktop whenever new dom0 updates are available and given the choice to run the update with a single click.
In the Qube Manager, simply select dom0 in the VM list, then click the **Update VM system** button (the blue, downward-pointing arrow). In addition, updating dom0 has been made more convenient: You will be prompted on the desktop whenever new dom0 updates are available and given the choice to run the update with a single click.
Alternatively, command-line tools are available for accomplishing various update-related tasks (some of which are not available via Qubes VM Manager). In order to update dom0 from the command line, start a console in dom0 and then run one of the following commands:
@ -69,14 +69,6 @@ You can also pass commands to `dnf` using `--action=...`.
sudo dnf downgrade package-version
~~~
For example, to downgrade Xen to a specific older version available for Qubes R3.2, you would:
~~~
sudo qubes-dom0-update xen-libs-4.6.6-36.fc23.x86_64 xen-hypervisor-4.6.6-36.fc23.x86_64 xen-runtime-4.6.6-36.fc23.x86_64 xen-hvm-4.6.6-36.fc23.x86_64 xen-4.6.6-36.fc23.x86_64 xen-license-4.6.6-36.fc23.x86_64
sudo dnf downgrade xen-libs-4.6.6-36.fc23.x86_64 xen-hypervisor-4.6.6-36.fc23.x86_64 xen-runtime-4.6.6-36.fc23.x86_64 xen-hvm-4.6.6-36.fc23.x86_64 xen-4.6.6-36.fc23.x86_64 xen-license-4.6.6-36.fc23.x86_64
~~~
### How to re-install a package
You can re-install in a similar fashion to downgrading.
@ -95,7 +87,7 @@ You can re-install in a similar fashion to downgrading.
sudo dnf reinstall package
~~~
Note that Dnf will only re-install if the installed and downloaded versions match. You can ensure they match by either updating the package to the latest version, or specifying the package version in the first step using the form `package-version`.
Note that `dnf` will only re-install if the installed and downloaded versions match. You can ensure they match by either updating the package to the latest version, or specifying the package version in the first step using the form `package-version`.
### How to uninstall a package
@ -162,3 +154,4 @@ Requires installed [Whonix](/doc/privacy/whonix/).
Go to Qubes VM Manager -> System -> Global Settings. 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

95
common-tasks/software-update-vm.md
View File

@ -21,8 +21,6 @@ Of course the AppVM has only read-access to the template's filesystem -- it cann
In addition to saving on the disk space, and reducing domain creation time, another advantage of such scheme is the possibility for centralized software update.
It's just enough to do the update in the template VM, and then all the AppVMs based on this template get updates automatically after they are restarted.
The default template is called **fedora-23** in Qubes R3.2 and **fedora-26** in Qubes R4.0.
The side effect of this mechanism is, of course, that if you install any software in your AppVM, more specifically in any directory other than `/home`, `/usr/local`, or `/rw` then it will disappear after the AppVM reboots (as the root filesystem for this AppVM will again be "taken" from the TemplateVM).
**This means one normally installs software in the TemplateVM, not in AppVMs.**
@ -80,7 +78,7 @@ 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`
Reverting changes to a TemplateVM (R4.0)
Reverting changes to a TemplateVM
---------------------------------
Perhaps you've just updated your TemplateVM, and the update broke your template.
@ -100,33 +98,6 @@ For example, to revert changes to the `fedora-26` TemplateVM:
qvm-volume revert fedora-26:root
Reverting changes to a TemplateVM (R3.2)
---------------------------------
Perhaps you've just updated your TemplateVM, and the update broke your template.
Or perhaps you've made a terrible mistake, like accidentally confirming the installation of an unsigned package that could be malicious.
Fortunately, it's easy to revert changes to TemplateVMs using the command appropriate to your version of Qubes.
**Important:** This command will roll back any changes made *during the last time the TemplateVM was run, but **not** before.*
This means that if you have already restarted the TemplateVM, using this command is unlikely to help, and you'll likely want to reinstall it from the repository instead.
On the other hand, if the template is already broken or compromised, it won't hurt to try reverting first.
Just make sure to **back up** all of your data and changes first!
For example, to revert changes to the `fedora-23` TemplateVM:
1. Shut down all VMs based on `fedora-23`.
2. Shut down `fedora-23`.
If you've already just shut it down, do **not** start it again (see above).
3. In a dom0 terminal, type:
qvm-revert-template-changes fedora-23
If you want to skip the confirmation check, you can add the `--force` option:
qvm-revert-template-changes --force fedora-23
For the technical details about how this command works and the steps it performs, see [here](/doc/template-implementation/#rollback-template-changes).
Notes on trusting your TemplateVM(s)
-------------------------------------
@ -168,8 +139,7 @@ However, a compromise of a template affects only a subset of all your AppVMs (in
Also, if your AppVMs are network disconnected, even though their filesystems might get compromised due to the corresponding template compromise, it still would be difficult for the attacker to actually leak out the data stolen in an AppVM.
Not impossible (due to existence of cover channels between VMs on x86 architecture), but difficult and slow.
Standalone VMs (R4.0 and later)
Standalone VMs
--------------
Standalone VMs have their own copy of the whole filesystem, and thus can be updated and managed on their own.
But this means that they take a few GBs on disk, and also that centralized updates do not apply to them.
@ -194,30 +164,6 @@ qvm-create --class StandaloneVM --label <label> --property virt_mode=hvm <vmname
(Note: Technically, `virt_mode=hvm` is not necessary for every StandaloneVM. However, it makes sense if you want to use a kernel from within the VM.)
Standalone VMs (R3.2 and earlier)
--------------
Standalone VMs have their own copy of the whole filesystem, and thus can be updated and managed on their own.
But this means that they take a few GBs on disk, and also that centralized updates do not apply to them.
Sometimes it might be convenient to have a VM that has its own filesystem, where you can directly introduce changes, without the need to start/stop the template VM.
Such situations include e.g.:
- VMs used for development (devel environments require a lot of \*-devel packages and specific devel tools)
- VMs used for installing untrusted packages.
Normally you install digitally signed software from Red Hat/Fedora repositories, and it's reasonable that such software has non malicious *installation* scripts (rpm pre/post scripts).
However, when you would like to install some packages from less trusted sources, or unsigned, then using a dedicated (untrusted) standalone VM might be a better way.
In order to create a standalone VM you can use a command line like this (from console in Dom0):
~~~
qvm-create <vmname> --standalone --label <label>
~~~
... or click appropriate options in the Qubes Manager's Create VM window.
Using more than one template
----------------------------
@ -256,17 +202,17 @@ Thanks to such configuration all the VMs can use the same proxy address, and if
If the VM is configured to have access to the updates proxy (2), the startup scripts will automatically configure dnf to really use the proxy (3).
Also access to updates proxy is independent of any other firewall settings (VM will have access to updates proxy, even if policy is set to block all the traffic).
There are two services ([qvm-service](https://www.qubes-os.org/doc/dom0-tools/qvm-service/), [service framework](https://www.qubes-os.org/doc/qubes-service/)):
There are two services (`qvm-service`, [service framework](https://www.qubes-os.org/doc/qubes-service/)):
1. qubes-updates-proxy (and its deprecated name: qubes-yum-proxy) - a service providing a proxy for templates - by default enabled in NetVMs (especially: sys-net)
2. updates-proxy-setup (and its deprecated name: yum-proxy-setup) - use a proxy provided by another VM (instead of downloading updates directly), enabled by default in all templates
This is generally the same in R3.2 and R4.0 - in both cases both the old and new names work.
And in both cases defaults listed above are applied if the service is not explicitly listed in services tab.
Both the old and new names work.
The defaults listed above are applied if the service is not explicitly listed in the services tab.
### Technical details (R4.0)
### Technical details
Instead of using a network connection like in R3.2, R4.0 uses RPC/qrexec.
The updates proxy uses RPC/qrexec.
The proxy is configured in qrexec policy on dom0: `/etc/qubes-rpc/policy/qubes.UpdatesProxy`.
By default this is set to sys-net and/or sys-whonix, depending on firstboot choices.
This new design allows for templates to be updated even when they are not connected to any netvm.
@ -283,33 +229,6 @@ $type:TemplateVM $default allow,target=sys-net
$anyvm $anyvm deny
```
### Technical details (R3.2)
The proxy is running in selected VMs (by default all the NetVMs).
Thanks to such configuration all VMs can use the same proxy address, and if there is a proxy on network path, it will handle the traffic (of course when firewall rules allow that).
The first proxy on the network path according to the template's netvm setting will be used.
If the VM is configured to have access to the updates proxy (1), the startup scripts will automatically configure dnf to use the proxy.
Also access to updates proxy is independent of any other firewall settings (VM will have access to updates proxy, even if the policy is set to block all the traffic).
(1) Firewall tab -\> Allow connections to Updates Proxy; this setting works immediately (once OK is clicked)
1. Updates proxy: It is running as "qubes-updates-proxy" service.
Startup script of this service sets up a firewall rule to intercept traffic directed to 10.137.255.254:8082:
~~~
iptables -t nat -A PR-QBS-SERVICES -d 10.137.255.254/32 -i vif+ -p tcp -m tcp --dport 8082 -j REDIRECT
~~~
2. VMs using the proxy service Startup script (updates-proxy-setup or qubes-misc-post service) configure
dnf using `/etc/yum.conf.d/qubes-proxy.conf` file.
It can either contain
~~~
proxy=http://10.137.255.254:8082/
~~~
line, or be empty. Note that this file is specifically included from main yum.conf, dnf does not support real conf.d configuration style...
Note on treating AppVM's root filesystem non-persistence as a security feature
------------------------------------------------------------------------------

5
configuration/config-files.md
View File

@ -31,7 +31,7 @@ The scripts here all run as root.
- `/rw/config/qubes-ip-change-hook` - script runs in NetVM after every external IP change and on "hardware" link status change.
- (R4.0 only) 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.
- 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 own custom firewall rules.
~~~
@ -40,9 +40,6 @@ The scripts here all run as root.
/rw/config/qubes-firewall-user-script
~~~
- (R3.2 only) `/rw/config/qubes-firewall-user-script` - script runs in ProxyVM (or AppVM with `qubes-firewall` service enabled) after each firewall update.
Good place to write own custom firewall rules.
- `/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.

2
configuration/disk-trim.md
View File

@ -57,7 +57,7 @@ This can be done with either systemd (weekly only) or cron (daily or weekly).
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.
However, inside App and Template qubes, the `discard` mount option is on by default to notify the LVM thin pool driver (R4.0) or sparse file driver (R3.2) that the space is no longer needed and can be zeroed and re-used.
However, inside App and Template qubes, the `discard` mount option is on by default to notify the LVM thin pool driver that the space is no longer needed and can be zeroed and re-used.
If you are using Qubes with LVM, you may also want to set `issue_discards = 1` in `/etc/lvm/lvm.conf`.
Setting this option will permit LVM to issue discards to the SSD when logical volumes are shrunk or deleted.

146
configuration/managing-vm-kernel.md
View File

@ -227,7 +227,7 @@ Kernel for a VM is stored in `/var/lib/qubes/vm-kernels/KERNEL_VERSION` director
All the files besides `vmlinuz` are optional.
Using kernel installed in the VM (R4.0)
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:
@ -239,7 +239,7 @@ qvm-prefs <clonetemplatename> kernel ''
If you'd like to use a different kernel than default, continue reading.
### Installing kernel in Fedora VM (R4.0)
### Installing kernel in Fedora VM
Install whatever kernel you want.
You need to also ensure you have the `kernel-devel` package for the same kernel version installed.
@ -275,7 +275,7 @@ Then shutdown the VM.
If you require `PV` mode, install `grub2-xen` in dom0 and change the template's kernel to `pvgrub2`.
Booting to a kernel inside the template is not supported under `PVH`.
### Installing kernel in Debian VM (R4.0)
### Installing kernel in Debian VM
Install whatever kernel you want, making sure to include the headers.
If you are using a distribution kernel package (`linux-image-amd64` package), the initramfs and kernel modules should be handled automatically.
@ -322,145 +322,6 @@ Then shutdown the VM.
If you require `PV` mode, install `grub2-xen` in dom0 and change the template's kernel to `pvgrub2`.
Booting to a kernel inside the template is not supported under `PVH`.
Using kernel installed in the VM (R3.2)
--------------------------------
**This option is available only in Qubes R3.1 or newer**
It is possible to use a kernel installed in the VM (in most cases - TemplateVM).
This is possible thanks to PV GRUB2 - GRUB2 running in the VM.
To make it happen, at a high level you need to:
1. Install PV GRUB2 (`grub2-xen`) in dom0.
2. Install kernel in the VM (see below for Fedora and Debian steps).
As with all VM software installation - this needs to be done in a TemplateVM (or StandaloneVM if you are using one).
3. Set VM kernel to `pvgrub2` value.
You can use `pvgrub2` in selected VMs, but it's not necessary in all of them, even if its template has a kernel installed.
You can still use a dom0-provided kernel for selected VMs.
**WARNING: When using a kernel from within a VM, the `kernelopts` parameter is ignored.**
### Installing PV GRUB2 (R3.2)
Simply execute:
~~~
sudo qubes-dom0-update grub2-xen
~~~
### Installing kernel in Fedora VM (R3.2)
In a Fedora based VM, you need to install the `qubes-kernel-vm-support` package.
This package includes the additional kernel module and initramfs addition required to start a Qubes VM (for details see [template implementation](/doc/template-implementation/)).
Additionally, you need some GRUB tools to create its configuration.
Note: You don't need an actual grub bootloader as it is provided by dom0, but having one shouldn't hurt.
~~~
sudo dnf install qubes-kernel-vm-support grub2-tools
~~~
Then install whatever kernel you want.
You need to also ensure you have the `kernel-devel` package for the same kernel version installed.
If you are using a distribution kernel package (`kernel` package), the initramfs and kernel modules may be handled automatically.
If you are using a manually built kernel, you need to handle this on your own.
Take a look at the `dkms` documentation, especially the `dkms autoinstall` command may be useful.
If you did not see the `kernel` install rebuild your initramfs, or are using a manually built kernel, you will need to rebuild it yourself.
Replace the version numbers in the example below with the ones appropriate to the kernel you are installing:
~~~
sudo dracut -f /boot/initramfs-4.15.14-200.fc26.x86_64.img 4.15.14-200.fc26.x86_64
~~~
Once the kernel is installed, you need to create a GRUB configuration.
You may want to adjust some settings in `/etc/default/grub`; for example, lower `GRUB_TIMEOUT` to speed up VM startup.
Then, you need to generate the actual configuration:
In Fedora it can be done using the `grub2-mkconfig` tool:
~~~
sudo grub2-mkconfig -o /boot/grub2/grub.cfg
~~~
You can safely ignore this error message:
~~~
grub2-probe: error: cannot find a GRUB drive for /dev/mapper/dmroot. Check your device.map
~~~
Then shutdown the VM.
Now you can set `pvgrub2` as the VM kernel and it will start the kernel configured within your VM.
**Note:** On first boot the VM will automatically allocate swap space.
This can take a while to complete- longer than your `qrexec_timeout` setting, which will make the VM appear to have hung on boot.
To confirm this is the case, see [Troubleshooting](/doc/managing-vm-kernel/#troubleshooting) below or just wait for five minutes and shutdown the VM.
It should respond normally on future boots.
### Installing kernel in Debian VM (R3.2)
In a Debian based VM, you need to install the `qubes-kernel-vm-support` package.
This package includes the additional kernel module and initramfs addition required to start a Qubes VM (for details see [template implementation](/doc/template-implementation/)).
Additionally, you need some GRUB tools to create its configuration.
Note: You don't need an actual grub bootloader as it is provided by dom0, but having one shouldn't hurt.
~~~
sudo apt update
sudo apt install qubes-kernel-vm-support grub2-common
~~~
If prompted for a GRUB install device, choose `/dev/mapper/dmroot`.
You will receive an error about GRUB failed to install to it, but just continue anyways.
Ignore warnings about `version '...' has bad syntax`.
Then install whatever kernel you want.
If you are using a distribution kernel package (`linux-image-amd64` package), the initramfs and kernel modules should be handled automatically.
If not, or you are building the kernel manually, do this using `dkms` and `initramfs-tools`:
sudo dkms autoinstall -k <kernel-version> # replace this <kernel-version> with actual kernel version
sudo update-initramfs -u
The output should look like this:
$ 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/
depmod....
DKMS: install completed.
$ sudo update-initramfs -u
update-initramfs: Generating /boot/initrd.img-3.16.0-4-amd64
When the kernel is installed, you need to create a GRUB configuration.
You may want to adjust some settings in `/etc/default/grub`; for example, lower `GRUB_TIMEOUT` to speed up VM startup.
Then, you need to generate the actual configuration with the `update-grub2` tool:
~~~
sudo mkdir /boot/grub
sudo update-grub2
~~~
You can safely ignore this error message:
~~~
grub2-probe: error: cannot find a GRUB drive for /dev/mapper/dmroot. Check your device.map
~~~
Then shutdown the VM.
Now you can set `pvgrub2` as the VM kernel and it will start the kernel configured within your VM.
When starting the VM you can safely ignore any warnings about a missing module 'dummy-hcd'.
**Note:** on first boot the VM will automatically allocate swap space.
This can take a while to complete- longer than your `qrexec_timeout` setting, which will make the VM appear to have hung on boot.
To confirm this is the case, see [Troubleshooting](/doc/managing-vm-kernel/#troubleshooting) below or just wait for five minutes and shutdown the VM.
It should respond normally on future boots.
### Troubleshooting
In case of problems, you can access the VM console using `sudo xl console VMNAME` in dom0, then access the GRUB menu.
@ -469,3 +330,4 @@ You need to call it just after starting the VM (until `GRUB_TIMEOUT` expires); f
In any case you can later access the VM's logs (especially the VM console log `guest-VMNAME.log`).
You can always set the kernel back to some dom0-provided value to fix a VM kernel installation.

2
configuration/resize-disk-image.md
View File

@ -22,7 +22,7 @@ In most cases, the GUI tool Qube Settings (available for every qube from the Sta
In case of standalone qubes and templates, just change the Disk Storage settings above.
In case of template-based qubes, the private storage (the /home directory and user files) can be changed in the qube's own settings, but the system root image is [inherited from the template](/getting-started/#appvms-qubes-and-templatevms), and so it must be changed in the template settings.
If you are increasing the disk image size for Linux-based qubes installed from Qubes OS repositories in Qubes 4.0 or later, changing the settings above is all you need to do - in other cases, you may need to do more, according to instructions below.
See also [OS Specific Follow-up Instructions](/doc/resize-disk-image/#os-specific-follow-up-instructions) at the end of this page.
See also the OS-specific follow-up instructions below.
### Resize disk image

4
configuration/salt.md
View File

@ -204,7 +204,7 @@ It accepts all the same arguments of the vanilla tool.
## Configuring a VM's System from Dom0
Starting with Qubes R3.2, Salt in Qubes can be used to configure VMs from dom0.
Salt in Qubes can be used to configure VMs from dom0.
Simply set the VM name as the target minion name in the top file.
You can also use the `qubes` pillar module to select VMs with a particular
property (see below).
@ -240,8 +240,6 @@ This way dom0 doesn't directly interact with potentially malicious target VMs;
and in the case of a compromised Salt VM, because they are temporary, the
compromise cannot spread from one VM to another.
In Qubes 3.2, this temporary VM is based on the default template.
Beginning with Qubes 4.0 and after [QSB #45], we implemented two changes:
1. Added the `management_dispvm` VM property, which specifies the DVM

27
configuration/secondary-storage.md
View File

@ -14,7 +14,7 @@ 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.
### R4.0 ###
## 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.
@ -50,7 +50,7 @@ For example:
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):
@ -88,27 +88,6 @@ By default VMs will be created on the main Qubes disk (i.e. a small SSD), to cre
qvm-create -P poolhd0_qubes --label red unstrusted-hdd
### R3.2 ###
In dom0:
mv /var/lib/qubes/appvms/<my-new-appvm> /path/to/secondary/drive/<my-new-appvm>
ln -s /path/to/secondary/drive/<my-new-appvm> /var/lib/qubes/appvms/
Now, `my-new-appvm` will behave as if it were still stored on the primary SSD (except that it will probably be slower, since it's actually stored on the secondary HDD).
* The above procedure does **not** interfere with [Qubes Backup][].
However, attempting to symlink a `private.img` file (rather than the whole AppVM directory) is known to prevent the `private.img` file from being backed up.
The same problem may occur if the above procedure is attempted on a [TemplateVM][]. [[1]]
* After implementing the above procedure, starting `my-new-appvm` will cause dom0 notifications to occur stating that loop devices have been attached to dom0.
This is normal.
(No untrusted devices are actually being mounted to dom0.)
Do not attempt to detach these disks.
(They will automatically be detached when you shut down the AppVM.) [[2]]
[Qubes Backup]: /doc/BackupRestore/
[TemplateVM]: /doc/Templates/
[1]: https://groups.google.com/d/topic/qubes-users/EITd1kBHD30/discussion
[2]: https://groups.google.com/d/topic/qubes-users/nDrOM7dzLNE/discussion

4
configuration/usb-qubes.md
View File

@ -64,7 +64,6 @@ Those steps are not performed by default, because of risk explained in [Security
### Automatic setup ###
R4.0 only! R3.2 users please read the [manual setup] below!
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:
@ -129,7 +128,7 @@ In case you are absolutely sure you do not want to confirm mouse access from `sy
## How to hide all USB controllers from dom0 ##
(Note: Beginning with R3.2, `rd.qubes.hide_all_usb` is set automatically if you opt to create a USB qube during installation.
(Note: `rd.qubes.hide_all_usb` is set automatically if you opt to create a USB qube during installation.
This also occurs automatically if you choose to [create a USB qube] using the `qubesctl` method, which is the
first pair of steps in the linked section.)
@ -202,7 +201,6 @@ The procedure to hide all USB controllers from dom0 is as follows:
[usb-controller]: /doc/usb-devices/#finding-the-right-usb-controller
[faq]: /faq/#i-created-a-usbvm-and-assigned-usb-controllers-to-it-now-the-usbvm-wont-boot
[Security Warning about USB Input Devices]: /doc/device-handling-security/#security-warning-on-usb-input-devices
[manual setup]: #manual-setup
[install dom0 updates]: /doc/software-update-dom0/#how-to-update-dom0
[hiding USB controllers from dom0]: #how-to-hide-all-usb-controllers-from-dom0
[AEM]: /doc/anti-evil-maid/

2
customization/awesome.md
View File

@ -74,7 +74,7 @@ Users may want to adjust their definitions and respective implementations accord
#### Implementation
The implementation may be specific to the awesome version you're running. This guide refers to awesome version 3.5.9 which is available to Qubes 3.2 and Qubes 4.0 users.
The implementation may be specific to the awesome version you're running. This guide refers to awesome version 3.5.9 which is available to Qubes 4.0 users.
Please keep in mind that this guide may not be conclusive. Your mileage may vary.

4
customization/bind-dirs.md
View File

@ -22,10 +22,6 @@ bind-dirs provides a mechanism whereby files usually taken from the template can
For example, in Whonix, [Tor's data dir /var/lib/tor has been made persistent in the TemplateBased ProxyVM sys-whonix](https://github.com/Whonix/qubes-whonix/blob/8438d13d75822e9ea800b9eb6024063f476636ff/usr/lib/qubes-bind-dirs.d/40_qubes-whonix.conf#L5).
In this way sys-whonix can benefit from the Tor anonymity feature 'persistent Tor entry guards' but does not have to be a StandaloneVM.
## Minimum Qubes Version ##
bind-dirs.sh works with Qubes R3.2 and above.
## How to use bind-dirs.sh? ##
Inside your TemplateBasedVM.

144
customization/disposablevm-customization.md
View File

@ -10,22 +10,12 @@ redirect_from:
- /wiki/UserDoc/DispVMCustomization/
---
DisposableVM Customization
============================
# DisposableVM Customization
Security
--------
If a DisposableVM Template becomes compromised, then any DisposableVM based on that DisposableVM Template could be compromised.
Therefore, you should not make any risky customizations (e.g., installing untrusted browser plugins) in important DisposableVM Templates.
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 and refrain from making any risky customizations to it.
## Introduction
Qubes 4.0
----------
A DisposableVM (previously known as a "DispVM") in Qubes 4.0 can be based on any TemplateBasedVM.
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:
@ -35,7 +25,17 @@ Additionally, if you want to have menu entries for starting applications in Disp
[user@dom0 ~]$ qvm-features fedora-26-dvm appmenus-dispvm 1
### Creating a new DisposableVM Template ###
## Security
If a DisposableVM Template becomes compromised, then any DisposableVM based on that DisposableVM Template could be compromised.
Therefore, you should not make any risky customizations (e.g., installing untrusted browser plugins) in important DisposableVM Templates.
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 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:
@ -53,7 +53,7 @@ The above default is used whenever a qube request starting a new DisposableVM an
If you wish to use the `fedora-minimal` template as a DisposableVM Template, see the "DisposableVM Template" use case under [fedora-minimal customization](/doc/templates/fedora-minimal/#customization).
### Customization of DisposableVM ###
## Customization of 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:
@ -70,7 +70,7 @@ This can be done by customizing the DisposableVM Template on which it is based:
4. Shutdown the qube (either by `poweroff` from qube's terminal, or `qvm-shutdown` from dom0 terminal).
### Using static DisposableVMs for sys-* ###
## Using static DisposableVMs for sys-*
You can use a static DisposableVM for `sys-*` as long as it is stateless.
For example, a `sys-net` using DHCP or `sys-usb` will work.
@ -124,7 +124,8 @@ qubes-prefs clockvm sys-net2
Note that these types of DisposableVMs will not show in the Application menu, but you can still get to a terminal if needed with `qvm-run <sys-VMName> gnome-terminal`.
### Adding programs to DisposableVM Application Menu ###
## Adding programs to DisposableVM Application Menu
For added convenience, arbitrary programs can be added to the Application Menu of the DisposableVM.
@ -132,7 +133,8 @@ 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 ###
## 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.
@ -146,7 +148,8 @@ Using DisposableVMs in this manner is ideal for untrusted qubes which require pe
>_**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 ####
### Create and configure the DisposableVM Template on which the DisposableVM will be based
1. Create the DisposableVM Template
@ -160,7 +163,8 @@ Using DisposableVMs in this manner is ideal for untrusted qubes which require pe
[user@dom0 ~]$ qvm-prefs <DisposableVM-Template-Name> template_for_dispvms true
#### Create the sys-net DisposableVM ####
### Create the sys-net DisposableVM
1. Create `sys-net` DisposableVM based on the DisposableVM Template
@ -194,7 +198,8 @@ Using DisposableVMs in this manner is ideal for untrusted qubes which require pe
[user@dom0 ~]$ qubes-prefs clockvm disp-sys-net
#### Create the sys-firewall DisposableVM ####
### Create the sys-firewall DisposableVM
1. Create `sys-firewall` DisposableVM
@ -220,7 +225,8 @@ Using DisposableVMs in this manner is ideal for untrusted qubes which require pe
[user@dom0 ~]$ qubes-prefs default_netvm disp-sys-firewall
#### Create the sys-usb DisposableVM ####
### Create the sys-usb DisposableVM
1. Create the `disp-sys-usb`
@ -260,7 +266,7 @@ Using DisposableVMs in this manner is ideal for untrusted qubes which require pe
disp-sys-usb dom0 allow,user=root
#### Starting the DisposableVMs ####
### 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.
@ -269,16 +275,17 @@ Prior to starting the new VMs, users should ensure that no other VMs such as the
[user@dom0~]$ qvm-pci detach <vm_name> <backend>:<bdf>
#### Troubleshooting ####
### Troubleshooting
The `disp-sys-usb` VM does not start
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-devices/#pci-passthrough-issues)
### Deleting DisposableVM ###
## Deleting DisposableVMs
Deleting disposable VM is slightly peculiar. While working in a VM or disposable VM, you may want to open a document in another disposable VM. For this reason, the property `default_dispvm` may be set to the name of your disposable VM in a number of VMs:
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
@ -297,88 +304,3 @@ If you still encounter the issue, you may have forgot to clean an entry. Looking
[user@dom0 ~]$ journalctl | tail
Qubes 3.2
----------
### Changing the DisposableVM Template ###
You may want to use a non-default template the [DisposableVM Template](/doc/glossary/#disposablevm-template). One example is to use a less-trusted template with some less trusted, third-party, often unsigned, applications installed, such as e.g. third-party printer drivers.
In order to regenerate the DisposableVM "snapshot" (called 'savefile' on Qubes) one can use the following command in Dom0:
[user@dom0 ~]$ qvm-create-default-dvm <custom-template-name>
This would create a new DisposableVM savefile based on the custom template.
For example `<custom-template-name>` could be the name of the existing `debian-8` vm, which creates the disposable vm `debain-8-dvm`.
Now, whenever one opens a file (from any AppVM) in a DisposableVM, a DisposableVM based on this template will be used.
One can easily verify if the new DisposableVM template is indeed based on a custom template (in the example below the template called "f17-yellow" was used as a basis for the DisposableVM):
[user@dom0 ~]$ ll /var/lib/qubes/dvmdata/
total 0
lrwxrwxrwx 1 user user 45 Mar 11 13:59 default_dvm.conf -> /var/lib/qubes/appvms/f17-yellow-dvm/dvm.conf
lrwxrwxrwx 1 user user 49 Mar 11 13:59 default_savefile -> /var/lib/qubes/appvms/f17-yellow-dvm/dvm-savefile
lrwxrwxrwx 1 user user 47 Mar 11 13:59 savefile_root -> /var/lib/qubes/vm-templates/f17-yellow/root.img
If you wish to use the `fedora-minimal` template as a DisposableVM Template, see the "DisposableVM Template" use case under [fedora-minimal customization](/doc/templates/fedora-minimal/#customization).
### Customization of DisposableVM ###
It is possible to change the settings of each new DisposableVM. This can be done by customizing the DisposableVM Template:
1. Start a terminal in the `fedora-23-dvm` TemplateVM by running the following command in a dom0 terminal. (By default, this TemplateVM is not shown in Qubes VM Manager. However, it can be shown by selecting "Show/Hide internal VMs.")
[user@dom0 ~]$ qvm-run -a fedora-23-dvm gnome-terminal
2. Change the VM's settings and/or applications, as desired. Note that currently Qubes supports exactly one DisposableVM Template, so any changes you make here will affect all DisposableVMs. Some examples of changes you may want to make include:
- Changing Firefox's default startup settings and homepage.
- Changing Nautilus' default file preview settings.
- 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 DisposableVM's 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.
3. Create an empty `/home/user/.qubes-dispvm-customized` file in the VM (not in dom0):
[user@fedora-23-dvm ~]$ touch /home/user/.qubes-dispvm-customized
4. Shutdown the VM (either by `poweroff` from VM terminal, or `qvm-shutdown` from dom0 terminal).
5. Regenerate the DisposableVM Template using the default template:
[user@dom0 ~]$ qvm-create-default-dvm --default-template
Or, if you're [using a non-default template](#changing-the-disposablevm-template), regenerate the DisposableVM Template using your custom template:
[user@dom0 ~]$ qvm-create-default-dvm <custom-template-name>
**Note:** All of the above requires at least qubes-core-vm \>= 2.1.2 installed in template.
### Adding arbitrary programs to DisposableVM Application Menu ###
For added convenience, arbitrary programs can be added to the Application Menu of the DisposableVM. In order to do that create (e.g.) `arbitrary.desktop` file in `/usr/local/share/applications` in Dom0. That file will point to the desired program. Use the following template for the file:
[Desktop Entry]
Version=1.0
Type=Application
Exec=sh -c 'echo arbitrary | /usr/lib/qubes/qfile-daemon-dvm qubes.VMShell dom0 DEFAULT red'
Icon=dispvm-red
Terminal=false
Name=DispVM: Arbitrary Name
GenericName=DispVM: Arbitrary Generic Name
StartupNotify=false
Categories=Network;X-Qubes-VM;
Next, the `/etc/xdg/menus/applications-merged/qubes-dispvm.menu` file has to be modified so that it points to the newly-created .desktop file. (If you use i3 you can skip this step; the shortcut gets added to dmenu automatically.)
Add a `<Filename>arbitrary.desktop</Filename>` line so that your modified file looks like this:
<Include>
<Filename>qubes-dispvm-firefox.desktop</Filename>
<Filename>qubes-dispvm-xterm.desktop</Filename>
<Filename>arbitrary.desktop</Filename>
</Include>
After saving the changes the new shortcut should appear in the DisposableVM Applications menu.

59
customization/xfce.md
View File

@ -1,59 +0,0 @@
---
layout: doc
title: XFCE
permalink: /doc/xfce/
redirect_from:
- /en/doc/xfce/
- /doc/XFCE/
- "/doc/UserDoc/XFCE/"
- "/wiki/UserDoc/XFCE/"
---
XFCE installation in dom0
========================
**Disclaimer: The article is obsolete for Qubes OS 3.2 and later.**
Prior to R3.2, KDE was the default desktop environment in Qubes. Beginning with
R3.2 [XFCE is the new default desktop environment](/doc/releases/3.2/release-notes/) and does not require manual installation.
Installation:
sudo qubes-dom0-update @xfce-desktop-qubes
Reboot the system. At system startup, select "Xfce session" in login screen (menu on the right bottom corner of the screen).
Configuration
-------------
Things needed/recommended to be done:
- remove some useless entries from menu and panel, especially file manager, web browser
- create own favorites menu (currently standard XFCE menu isn't modified to use per-VM subsections, which makes it very inconvenient):
1. create `~/.config/menus/favorites.menu`, example content:
~~~
<!DOCTYPE Menu PUBLIC "-//freedesktop//DTD Menu 1.0//EN"
"http://www.freedesktop.org/standards/menu-spec/1.0/menu.dtd">
<Menu>
<Name>Favorites</Name>
<DefaultAppDirs/>
<DefaultDirectoryDirs/>
<Directory>favorites.directory</Directory>
<Include>
<Filename>personal-gnome-terminal.desktop</Filename>
<Filename>personal-firefox.desktop</Filename>
<Filename>work-gnome-terminal.desktop</Filename>
<Filename>work-firefox.desktop</Filename>
<Filename>mail-mozilla-thunderbird.desktop</Filename>
<Filename>mail-gnome-terminal.desktop</Filename>
<Filename>banking-mozilla-firefox.desktop</Filename>
<Filename>untrusted-firefox.desktop</Filename>
</Include>
</Menu>
~~~
2. add it to the panel: right click on panel, "add new items", select "XFCE menu", choose custom menu file - just created one

4
debugging/vm-interface.md
View File

@ -37,12 +37,12 @@ QubesDB
- `/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) (in Qubes 3.2 and later, previously `/qubes-gateway` was used for this purpose)
- `/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 (in Qubes 3.2 and later, previously `/qubes-netvm-gateway` was used for this purpose)
- `/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
#### Firewall rules in 3.x ####

1
doc.md
View File

@ -157,7 +157,6 @@ redirect_from:
* [Customizing Fedora minimal templates](/doc/fedora-minimal-template-customization/)
* [Customizing Windows 7 templates](/doc/windows-template-customization/)
* [Using KDE in dom0](/doc/kde/)
* [Installing XFCE in dom0](/doc/xfce/)
* [Installing i3 in dom0](/doc/i3/)
* [Using awesome in dom0](/doc/awesome/)
* [Language Localization](/doc/language-localization/)

191
installing/custom-install.md
View File

@ -6,15 +6,12 @@ redirect_from:
- /doc/encryption-config/
---
Custom Installation
===================
# Custom Installation
In the present context, "custom installation" refers to things like manual partitioning, setting up LVM and RAID, and manual LUKS encryption configuration.
## Qubes 4.0
### Installer Defaults
## Installer Defaults
For reference, these are the typical defaults for a single disk with legacy boot:
@ -62,7 +59,7 @@ Order Action Type Device Mount po
~~~
### Typical Partition Schemes
## Typical Partition Schemes
If you want your partition/LVM scheme to look like the Qubes default but with a few tweaks, follow this example.
With a single disk, the result should look something like this:
@ -79,7 +76,7 @@ sda disk
~~~
### Encryption Defaults
## Encryption Defaults
By default, `cryptsetup 1.7.5` will create a LUKS/dm-crypt volume as follows:
@ -109,7 +106,7 @@ This means that, by default, Qubes inherits these upstream defaults:
If, instead, you'd like to use AES-256, SHA-512, `/dev/random`, and a longer `iter-time`, for example, you can configure encryption manually by following the instructions below.
### Example: Custom LUKS Configuration
## Example: Custom LUKS Configuration
Boot into the Qubes installer, then press `ctrl`+`alt`+`F2` to get a virtual console.
@ -153,184 +150,6 @@ Decrypt your partition, then assign `/`, `/boot`, and `swap`.
Proceed normally from there.
## Qubes 3.2
### Installer Defaults
For reference, these are the defaults for a single disk:
~~~
Mount Point: /
Desired Capacity: (your choice)
Device Type: LVM
Volume Group: qubes_dom0
File System: ext4
Name: root
Mount Point: /boot
Desired Capacity: 500 MiB (recommended)
Device Type: Standard Partition
File System: ext4
Mount Point: (none)
Desired Capacity: 9.44 GiB (recommended)
Device Type: LVM
Volume Group: qubes_dom0
File System: swap
Name: swap
~~~
### Typical Partition Schemes
If you want your partition/LVM scheme to look like the Qubes default but
with a few tweaks, follow these examples. With a single disk, the result
should look something like this:
~~~
NAME TYPE MOUNTPOINT
sda disk
├──sda1 part /boot
└──sda2 part
└──luks-<UUID> crypt
├──qubes_dom0-root lvm /
└──qubes_dom0-swap lvm [SWAP]
~~~
If you're using `mdadm` software RAID, it should look something like this:
~~~
NAME TYPE MOUNTPOINT
sda disk
├──sda1 part
│ └──md0 raid1 /boot
└──sda2 part
└──md1 raid1
└──luks-<UUID> crypt
├──qubes_dom0-root lvm /
└──qubes_dom0-swap lvm [SWAP]
sdb disk
├──sdb1 part
│ └──md0 raid1 /boot
└──sdb2 part
└──md1 raid1
└──luks-<UUID> crypt
├──qubes_dom0-root lvm /
└──qubes_dom0-swap lvm [SWAP]
~~~
### Example: LVM on LUKS on RAID0
Boot into the Qubes installer, then press `ctrl`+`alt`+`F2` to get a virtual
console.
1. (Optional) Wipe both disks:
# hdparm --user-master u --security-set-pass pass /dev/sda
# time hdparm --user-master u --security-erase-enhanced pass /dev/sda
# hdparm --user-master u --security-set-pass pass /dev/sdb
# time hdparm --user-master u --security-erase-enhanced pass /dev/sdb
2. Create desired partitions:
# fdisk /dev/sda
<create partitions>
# fdisk /dev/sdb
<create partitions>
3. Create RAID devices:
# mdadm --create --verbose /dev/md0 --level=mirror --raid-devices=2 /dev/sda1 /dev/sdb1
# mdadm --create --verbose /dev/md1 --level=mirror --raid-devices=2 /dev/sda2 /dev/sdb2
4. Create LUKS encrypted volume:
# cryptsetup -v --hash sha512 --cipher aes-xts-plain64 --key-size 512 --use-random --iter-time 5000 --verify-passphrase luksFormat /dev/md1
5. Open encrypted volume:
# cryptsetup open /dev/md1 luks
6. Create LVM volumes:
# pvcreate /dev/mapper/luks
# vgcreate qubes_dom0 /dev/mapper/luks
# lvcreate -n swap -L 10G qubes_dom0
# lvcreate -n root -l +100%FREE qubes_dom0
7. Proceed with installer. At the disk selection screen, select:
[x] I will configure partitioning.
[ ] Encrypt my data.
Continue normally from here.
## Qubes 3.1
### Manual Encryption Configuration
Qubes OS uses full disk encryption (FDE) by default. If you are an advanced
user who wishes to customize your encryption parameters during installation,
this page can help.
The Qubes installer uses `cryptsetup` (LUKS/dm-crypt) under the hood. You can
configure the encryption options while installing Qubes as follows:
01. Boot into the installer. Wait for first GUI screen to appear where it asks
about language/localization .
02. Press `Ctrl+Alt+F2` on your keyboard to escape to a shell session. (If you
are on a laptop, and your laptop keyboard does not work properly, you may have
to plug in a USB keyboard.)
03. Check and adjust the partitioning on the drive you plan to install to with
`parted`. For example, you can leave the partition table as `msdos/MBR` type,
then create a 500 MB ext4 boot partition, a 10 GB swap partition, and use the
rest of the drive (minus overprovisioning space for SSDs) for the root
partition.
04. Run to set the LUKS options as you like and set the passphrase:
# cryptsetup <options> luksFormat <partition>
For example:
# cryptsetup -v --hash sha512 --cipher aes-xts-plain64 --key-size 512 --use-random --iter-time 5000 --verify-passphrase luksFormat /dev/sda2
05. (Optional) Make sure the new container works:
# cryptsetup open /dev/sda2 test
# mkfs.ext4 /dev/mapper/test
# mount /dev/mapper/test /mnt/test
# umount /dev/mapper/test
# cryptsetup close test
06. Everything should be set with the preparation, so press `Ctrl+Alt+F7` to go
back to the GUI installer.
07. Continue installing as usual. When you get to the disk
partitioning/allocation part, pay attention.
08. When you select the disk, it may complain about only having a few MB of
space. Uncheck the "Encrypt and ask me about the passphrase later" box and
press the "Custom" button.
09. In this menu, you should see the unencrypted boot partition and the encrypted
LUKS partitions you created earlier. You must unlock the LUKS partition here,
i.e. enter passphrases.
10. Set the mount points on these partitions once they are decrypted. (This part
may be a bit glitchy, but you should be able to get it working after a
reboot.) For example, set the mount point for the primary LUKS partition as
`/`. Make sure the "Encrypted" box stays checked and that you check the
"Format" box (required for the root partition). Similarly, set `/boot` as
the mount point for the unencrypted boot partition and `swap` as the mount
point for the swap partition.
11. Now the install should complete without any other issues. When it's
finished, you'll have LUKS-encrypted partitions with the options you chose
above. You can verify this command in dom0:
# cryptsetup luksDump <partition>
For example:
# cryptsetup luksDump /dev/sda2
[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

16
installing/installation-guide.md
View File

@ -19,14 +19,6 @@ redirect_from:
Installation Guide
==================
Qubes 3.2 Warning
-----------------
There is a set of known upstream bugs in the Fedora installer that affect Qubes 3.2 ([Bug 1170803], [Bug 1374983], and [Bug 1268700]; tracked in Qubes issue [#2835]).
Because of these bugs, the installer will try to access all existing disk partitions, run fsck on them, and mount them.
Therefore, we *strongly* recommended that, prior to starting the Qubes installer, you physically disconnect all disks that you do not want to be modified.
Furthermore, if you are installing Qubes on a potentially compromised system, we *strongly* recommended that you wipe your target installation disk before starting the installer.
Qubes 4.0.1 Warning
-------------------
@ -64,8 +56,6 @@ so, for whatever reason. Always verify the digital signature on the downloaded
ISO. Make sure to read our guide on [verifying signatures] for more info about
how to download and verify our PGP keys and verify the downloaded ISO.
**Note:** The Qubes R4.0 ISO is large, so if you are using R3.2 to download it you may need to [increase the private storage](/doc/resize-disk-image/#expand-disk-image-r32) available to the AppVM.
Copying the ISO onto the installation medium
--------------------------------------------
@ -139,15 +129,11 @@ Getting Help
* If you don't find your answer in the documentation, it may be time to consult
the [mailing lists], as well as the many other available sources of [help].
* Please do not email individual developers (Marek, Joanna, etc.) with
* Please do not email individual developers (Marek, etc.) with
questions about installation or other problems. Please send all such
questions to the appropriate mailing list.
[Bug 1170803]: https://bugzilla.redhat.com/show_bug.cgi?id=1170803
[Bug 1374983]: https://bugzilla.redhat.com/show_bug.cgi?id=1374983
[Bug 1268700]: https://bugzilla.redhat.com/show_bug.cgi?id=1268700
[#2835]: https://github.com/QubesOS/qubes-issues/issues/2835
[QSB #46]: /news/2019/01/23/qsb-46/
[system requirements]: /doc/system-requirements/
[Hardware Compatibility List]: /hcl/

41
managing-os/hvm.md
View File

@ -1,6 +1,6 @@
---
layout: doc
title: Creating and Using HVM Domains
title: HVM
permalink: /doc/hvm/
redirect_from:
- /doc/hvm-create/
@ -9,32 +9,22 @@ redirect_from:
- /wiki/HvmCreate/
---
Creating and using HVM (fully virtualized) domains
==================================================
HVM
===
What are HVM domains?
---------------------
A **Hardware-assisted Virtual Machine (HVM)**, also known as a **Fully-Virtualized Virtual Machine**, utilizes the virtualization extensions of the host CPU.
These are typically contrasted with **Paravirtualized (PV)** VMs.
HVM domains (Hardware VM), in contrast to PV domains (Paravirtualized domains), allow one to create domains based on any OS for which one has an installation ISO. For example, this allows one to have Windows-based VMs in Qubes.
HVMs allow you to create domains based on any OS for which you have an installation ISO.
This allows you to have Windows-based VMs in Qubes.
By default, every Qubes VM runs in **PVH** mode (which has security advantages over both PV and HVM) except for those with attached PCI devices, which run in HVM mode.
See [here](https://blog.invisiblethings.org/2017/07/31/qubes-40-rc1.html) for a discussion of the switch from PV to HVM and [here](/news/2018/01/11/qsb-37/) for the announcement about changing the default to PVH.
Interested readers might want to check [this article](https://blog.invisiblethings.org/2012/03/03/windows-support-coming-to-qubes.html) to learn why it took so long for Qubes OS to support HVM domains (Qubes 1 only supported Linux based PV domains). As of Qubes 4, every VM is PVH by default, except those with attached PCI devices which are HVM. [See here](https://blog.invisiblethings.org/2017/07/31/qubes-40-rc1.html) for a discussion of the switch to HVM from R3.2's PV, and [here](/news/2018/01/11/qsb-37/) for changing the default to PVH.
Creating an HVM domain
----------------------
### R3.2 ###
With a GUI: in Qubes Manager VM creation dialog box choose the "Standalone qube not based on a template" type.
If "install system from device" is selected (which is by default), then `virt_mode` will be set to `hvm` automatically.
Otherwise, open the newly created VM's Qube Settings GUI and in the "Advanced" tab select "HVM" in the virtualization mode drop-down list.
Command line (the VM's name and label color are for illustration purposes):
~~~
qvm-create my-new-vm --hvm --label green
~~~
### R4.0 ###
With a GUI: in Qubes Manager VM creation dialog box choose the "Standalone qube not based on a template" type.
If "install system from device" is selected (which is by default), then `virt_mode` will be set to `hvm` automatically.
Otherwise, open the newly created VM's Qube Settings GUI and in the "Advanced" tab select `HVM` in the virtualization mode drop-down list.
@ -52,6 +42,7 @@ If you receive an error like this one, then you must first enable VT-x in your B
libvirt.libvirtError: invalid argument: could not find capabilities for arch=x86_64
~~~
Installing an OS in an HVM domain
---------------------------------
@ -74,6 +65,7 @@ For security reasons you should *never* copy untrusted data to dom0. Qubes doesn
Next, the VM will start booting from the attached installation media. Depending on the OS being installed in the VM, one might be required to start the VM several times (as is the case with Windows 7 installations) because whenever the installer wants to "reboot the system" it actually shuts down the VM and Qubes won't automatically start it. Several invocations of `qvm-start` command (as shown above) might be needed.
Setting up networking for HVM domains
-------------------------------------
@ -89,15 +81,16 @@ In order to manually configure networking in a VM, one should first find out the
Alternatively, one can use the `qvm-ls -n` command to obtain the same information and configure the networking within the HVM according to those settings (IP/netmask/gateway).
DNS servers: in R3.2 the DNS addresses are the same as the gateway's IP. In R4.0, the DNS ips are `10.139.1.1` and `10.139.1.2`.
The DNS IP addresses are `10.139.1.1` and `10.139.1.2`.
There is [opt-in support](/doc/networking/#ipv6) for IPv6 forwarding.
Qubes R3.2 only supports IPv4. Qubes R4.0 has [opt-in support](https://www.qubes-os.org/doc/networking/#ipv6) for IPv6 forwarding.
Using Template-based HVM domains
--------------------------------
Please see our dedicated page on [installing and using Windows-based AppVMs](/doc/windows-appvms/).
Cloning HVM domains
-------------------
@ -198,11 +191,13 @@ drive : None
timezone : localtime
~~~
Installing Qubes support tools in Windows 7 VMs
-----------------------------------------------
Windows specific steps are described on [separate page](/doc/windows-appvms/).
Assigning PCI devices to HVM domains
------------------------------------
@ -212,6 +207,7 @@ One problem at the moment however, is that after the whole system gets suspended
![r2b1-win7-usb-disable.png](/attachment/wiki/HvmCreate/r2b1-win7-usb-disable.png)
Converting VirtualBox VM to HVM
-------------------------------
@ -289,3 +285,4 @@ Other documents related to HVM:
- [Windows VMs](/doc/windows-vm/)
- [LinuxHVMTips](/doc/linux-hvm-tips/)

154
managing-os/templates.md
View File

@ -9,8 +9,7 @@ redirect_from:
- /wiki/Templates/
---
TemplateVMs
===========
# TemplateVMs
Every TemplateBasedVM in Qubes is, as the name implies, based on some TemplateVM.
The TemplateVM is where all the software available to TemplateBasedVMs is installed.
@ -24,8 +23,30 @@ In particular, some template "flavors" are available in source code form only.
Take a look at the [Qubes Builder documentation](/doc/qubes-builder/) for instructions on how to compile them.
How to install, uninstall, reinstall, and switch
------------------------------------------------
## Official templates
These are the official Qubes OS Project templates.
We build and release updates for these templates.
We guarantee that the binary updates are compiled from exactly the same source code as we publish.
* [Fedora](/doc/templates/fedora/) (default base template)
* [Fedora - Minimal](/doc/templates/fedora-minimal)
* [Debian](/doc/templates/debian/)
## Community templates
These templates are supported by the Qubes community. Some of them are available in ready-to-use binary package form (built by the Qubes developers), while others are available only in source code form. In all cases, the Qubes OS Project does not provide updates for these templates. However, such updates may be provided by the template maintainer.
By installing these templates, you are trusting not only the Qubes developers and the distribution maintainers, but also the template maintainer. In addition, these templates may be somewhat less stable, since the Qubes developers do not test them.
* [Whonix](/doc/templates/whonix/)
* [Ubuntu](/doc/templates/ubuntu/)
* [Archlinux](/doc/templates/archlinux/)
## How to install, uninstall, reinstall, and switch
### How to install
@ -36,6 +57,7 @@ Usually, the installation method is to execute the following type of command in
(where `qubes-template-<name>` is the name of your TemplateVM package)
### How to uninstall
To uninstall a TemplateVM, execute the following type of command in dom0:
@ -46,37 +68,21 @@ To uninstall a TemplateVM, execute the following type of command in dom0:
If this doesn't work, you can [remove it manually](/doc/remove-vm-manually/).
If the Applications Menu entry doesn't go away after you uninstall a TemplateVM, execute the following type of command in dom0:
$ rm ~/.local/share/applications/<template-vm-name>
### How to reinstall
To reinstall a currently installed TemplateVM, see [here](/doc/reinstall-template/).
### How to switch templates (3.2)
### How to switch templates
When you install a new template or upgrade a clone of a template, it is recommended that you switch everything that was set to the old template to the new template:
1. Make the new template the default template:
Qubes Manager --> Global settings --> Default template
2. Base AppVMs on the new template.
In Qubes Manager, for each VM that is currently based on `old-template` that you would like to base on `new-template`, enter its VM settings and change the Template selection:
Qubes Manager --> (Select a VM) --> VM settings --> Template
3. Base the [DisposableVM Template](/doc/glossary/#disposablevm-template) on the new template.
If you have set the new template as your default template:
[user@dom0 ~]$ qvm-create-default-dvm --default-template
Otherwise:
[user@dom0 ~]$ qvm-create-default-dvm new-template
### How to switch templates (4.0)
When you install a new template or upgrade a clone of a template, it is recommended that you switch everything that was set to the old template to the new template:
1. Make the new template the default template:
1. Make the new template the default template.
Applications Menu --> System Tools --> Qubes Global Settings --> Default template
@ -92,41 +98,13 @@ When you install a new template or upgrade a clone of a template, it is recommen
[user@dom0 ~]$ qubes-prefs default-dispvm new-template-dvm
Invisible Things Lab (ITL) Supported templates
-----------------------
## Inheritance and Persistence
These are the templates ITL builds and releases updates for.
ITL guarantees that the binary updates are compiled from exactly the same source code as we publish.
Whenever a TemplateBasedVM is created, the contents of the `/home` directory of its parent TemplateVM are *not* copied to the child TemplateBasedVM's `/home`.
The child TemplateBasedVM's `/home` is always independent from its parent TemplateVM's `/home`, which means that any subsequent changes to the parent TemplateVM's `/home` will not affect the child TemplateBasedVM's `/home`.
* [Fedora](/doc/templates/fedora/) (default base template)
* [Fedora - Minimal](/doc/templates/fedora-minimal)
* [Debian](/doc/templates/debian/)
Community Supported templates
-----------------------------
These templates are supported by the Qubes community. Some of them are available in ready-to-use binary package form (built by ITL), while others are available only in source code form. In all cases, ITL does not provide updates for these templates. However, such updates may be provided by the template maintainer.
By installing these templates, you are trusting not only ITL and the distribution maintainers, but also the template maintainer. In addition, these templates may be somewhat less stable, since ITL does not test them.
* [Whonix](/doc/templates/whonix/)
* [Ubuntu](/doc/templates/ubuntu/)
* [Archlinux](/doc/templates/archlinux/)
Important Notes (R4.0)
---------------
* Whenever a TemplateBasedVM is created, the contents of the `/home`
directory of its parent TemplateVM are *not* copied to the child TemplateBasedVM's
`/home`. The child TemplateBasedVM's `/home`
is always independent from its parent TemplateVM's `/home`, which means that any
subsequent changes to the parent TemplateVM's `/home` will not affect
the child TemplateBasedVM's `/home`.
* `qvm-trim-template` is not necessary. All VMs are created in a thin pool
and trimming is handled automatically. No user action is required.
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.
| | Inheritance (1) | Persistence (2)
|--------------------|-----------------------------------------------------------|------------------------------------------
@ -138,54 +116,20 @@ Important Notes (R4.0)
(2) Following shutdown
(3) Including [DisposableVM Templates](/doc/glossary/#disposablevm-template)
Important Notes (R3.2 and earlier)
---------------
* 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`.
## Updating TemplateVMs
* Template VMs can occupy more space on the dom0 filesystem than necessary
because they cannot employ automatic TRIM/discard on the root fs. The
`qvm-trim-template` command in dom0 is used to recover this unused space.
Templates are not automatically updated when [updating dom0](/doc/software-update-dom0/).
This is by design, since doing so would cause all user modifications to templates to be lost.
Instead, you should update your templates [from within each template](/doc/software-update-vm/).
Conversely, the root filesystems in Standalone VMs *can* employ
TRIM/discard on the root fs using normal tools and configuration options.
When you create a StandaloneVM from a TemplateVM, the StandaloneVM is independent from the TemplateVM.
It will not be updated when the TemplateVM is updated.
Rather, it must be updated individually from inside the StandaloneVM.
Important Notes (all versions)
---------------
* 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.
## Important Notes
* Templates are not automatically updated when
[updating dom0](/doc/software-update-dom0/). This is by design, since doing
so would cause all user modifications to templates to be lost. Instead, you
should update your templates
[from within each template](/doc/software-update-vm/). If you *do* want to
update a template from dom0 (and thereby lose any user modifications in the
existing template), you must first uninstall the existing template from dom0:
$ sudo dnf remove qubes-template-fedora-25
* Standalone VMs using Template VMs as a basis can be created easily. These
VMs receive a *copy* of the operating system and do not get automatically
updated when Template VMs are updated--they must be updated individually.
* On XFCE based Dom0, a manual action may be required to remove the "Start Menu"
sub-menu of the removed TemplateVM. For example, to remove a dangling sub-menu
for a removed "fedora-25" template, open a Dom0 Terminal and type:
$ rm ~/.local/share/applications/fedora-25-*
Just make sure there are no other TemplateVMs whose names start with "fedora-25"
or else their menu items will be removed too.
* `qvm-trim-template` is not necessary. All VMs are created in a thin pool
and trimming is handled automatically. No user action is required.

122
managing-os/templates/fedora-minimal.md
View File

@ -1,6 +1,6 @@
---
layout: doc
title: Fedora Minimal Template
title: The Fedora Minimal TemplateVM
permalink: /doc/templates/fedora-minimal/
redirect_from:
- /doc/fedora-minimal/
@ -9,92 +9,93 @@ redirect_from:
- /wiki/Templates/FedoraMinimal/
---
Fedora - minimal
================
The Fedora Minimal TemplateVM
=============================
The Fedora Minimal TemplateVM (`fedora-minimal`) only weighs about 600 MB compressed (1.6 GB on disk) and has only the most vital packages installed, including a minimal X and xterm installation.
The sections below contain instructions for using the template and provide some examples for common use cases.
The template only weighs about 600 MB compressed (1.6 GB on disk) and has only the most vital packages installed, including a minimal X and xterm installation.
The minimal template, however, can be easily extended to fit your requirements.
The sections below contain the instructions on duplicating the template and provide some examples for commonly desired use cases.
Important
---------
1. The Fedora minimal template is intended only for advanced users.
If you encounter problems with the Fedora minimal template, we recommend that you use the [default Fedora template] instead.
1. The Fedora Minimal template is intended only for advanced users.
If you encounter problems with the Fedora Minimal template, we recommend that you use the [default Fedora template] instead.
2. If something works with the default Fedora template but not the minimal template, this is most likely due to user error (e.g., a missing package or misconfiguration) rather than a bug.
2. If something works with the default Fedora template but not the Fedora Minimal template, this is most likely due to user error (e.g., a missing package or misconfiguration) rather than a bug.
In such cases, you should write to [qubes-users] to ask for help rather than filing a bug report, then [contribute what you learn to the documentation][doc-guidelines].
3. The Fedora minimal template is intentionally *minimal*.
3. The Fedora Minimal template is intentionally *minimal*.
[Do not ask for your favorite package to be added to the minimal template by default.][pref-default]
Installation
------------
The Fedora minimal template can be installed with the following command:
The Fedora Minimal template can be installed with the following command (where `XX` is your desired version number):
~~~
[user@dom0 ~]$ sudo qubes-dom0-update qubes-template-fedora-29-minimal
[user@dom0 ~]$ sudo qubes-dom0-update qubes-template-fedora-XX-minimal
~~~
The download may take a while depending on your connection speed.
Duplication and first steps
---------------------------
It is highly recommended to clone the original template, and make any changes in the clone instead of the original template. The following command clones the template. Replace `your-new-clone` with your desired name.
~~~
[user@dom0 ~]$ qvm-clone fedora-29-minimal your-new-clone
~~~
You must start the template in order to customize it.
Customization
-------------
Customizing the template for specific use cases normally only requires installing additional packages.
The following table provides an overview of which packages are needed for which purpose.
It is highly recommended to clone the original template and make any changes in the clone instead of the original template.
The following command clones the template.
Replace `XX` with your installed Fedora Minimal version number and `your-new-clone` with your desired clone name.
As expected, the required packages are to be installed in the running template with the following command. Replace "packages` with a space-delimited list of packages to be installed.
~~~
[user@dom0 ~]$ qvm-clone fedora-XX-minimal your-new-clone
~~~
You must start the clone in order to customize it.
Customizing the template for specific use cases normally only requires installing additional packages.
The following list provides an overview of which packages are needed for which purpose.
As usual, the required packages are to be installed in the running template with the following command (replace `packages` with a space-delimited list of packages to be installed):
~~~
[user@your-new-clone ~]$ sudo dnf install packages
~~~
### Package table for Qubes 3.2
- Commonly used utilities: `pciutils` `vim-minimal` `less` `psmisc` `gnome-keyring`.
- Audio: `pulseaudio-qubes`.
- [FirewallVM](/doc/firewall/), such as the template for `sys-firewall`: at least `qubes-core-agent-networking` and `iproute`, and also `qubes-core-agent-dom0-updates` if you want to use it as the `UpdateVM` (which is normally `sys-firewall`).
- NetVM, such as the template for `sys-net`: `qubes-core-agent-networking` `qubes-core-agent-network-manager` `NetworkManager-wifi` `network-manager-applet` `wireless-tools` `dejavu-sans-fonts` `notification-daemon` `gnome-keyring` `polkit` `@hardware-support`.
If your network devices need extra packages for the template to work as a network VM, use the `lspci` command to identify the devices, then run `dnf search firmware` (replace `firmware` with the appropriate device identifier) to find the needed packages and then install them.
If you need utilities for debugging and analyzing network connections, install `tcpdump` `telnet` `nmap` `nmap-ncat`.
- [USB qube](/doc/usb-qubes/), such as the template for `sys-usb`: `qubes-input-proxy-sender`.
- [VPN qube](/doc/vpn/): Use the `dnf search "NetworkManager VPN plugin"` command to look up the VPN packages you need, based on the VPN technology you'll be using, and install them.
Some GNOME related packages may be needed as well.
After creation of a machine based on this template, follow the [VPN instructions](/doc/vpn/#set-up-a-proxyvm-as-a-vpn-gateway-using-networkmanager) to configure it.
Use case | Description | Required steps
--- | --- | ---
**Standard utilities** | If you need the commonly used utilities | Install the following packages: `pciutils` `vim-minimal` `less` `psmisc` `gnome-keyring`
**FirewallVM** | You can use the minimal template as a [FirewallVM](/doc/firewall/), such as the basis template for `sys-firewall` | No extra packages are needed for the template to work as a firewall.
**NetVM** | You can use this template as the basis for a NetVM such as `sys-net` | Install the following packages: `NetworkManager-wifi` `wireless-tools` `dejavu-sans-fonts` `notification-daemon`.
**NetVM (extra firmware)** | If your network devices need extra packages for the template to work as a network VM | Use the `lspci` command to identify the devices, then run `dnf search firmware` (replace `firmware` with the appropriate device identifier) to find the needed packages and then install them.
**Network utilities** | If you need utilities for debugging and analyzing network connections | Install the following packages: `tcpdump` `telnet` `nmap` `nmap-ncat`
**USB** | If you want USB input forwarding to use this template as the basis for a [USB](/doc/usb/) qube such as `sys-usb` | Install `qubes-input-proxy-sender`
**VPN** | You can use this template as basis for a [VPN](/doc/vpn/) qube | Use the `dnf search "NetworkManager VPN plugin"` command to look up the VPN packages you need, based on the VPN technology you'll be using, and install them. Some GNOME related packages may be needed as well. After creation of a machine based on this template, follow the [VPN howto](/doc/vpn/#set-up-a-proxyvm-as-a-vpn-gateway-using-networkmanager) to configure it.
**DisposableVM Template** | If you want to use this VM as a [DisposableVM Template](/doc/glossary/#disposablevm-template) | Install `perl-Encode`
You may also wish to consider additional packages from the `qubes-core-agent` suite:
### Package table for Qubes 4.0
- `qubes-core-agent-qrexec`: Qubes qrexec agent. Installed by default.
- `qubes-core-agent-systemd`: Qubes unit files for SystemD init style. Installed by default.
- `qubes-core-agent-passwordless-root`, `polkit`: By default, the Fedora Minimal template doesn't have passwordless root. These two packages enable this feature.
- `qubes-core-agent-nautilus`: This package provides integration with the Nautilus file manager (without it things like "copy to VM/open in disposable VM" will not be shown in Nautilus).
- `qubes-core-agent-sysvinit`: Qubes unit files for SysV init style or upstart.
- `qubes-core-agent-networking`: Networking support. Required for general network access and particularly if the template is to be used for a `sys-net` or `sys-firewall` VM.
- `qubes-core-agent-network-manager`: Integration for NetworkManager. Useful if the template is to be used for a `sys-net` VM.
- `network-manager-applet`: Useful (together with `dejavu-sans-fonts` and `notification-daemon`) to have a system tray icon if the template is to be used for a `sys-net` VM.
- `qubes-core-agent-dom0-updates`: Script required to handle `dom0` updates. Any template which the VM responsible for 'dom0' updates (e.g. `sys-firewall`) is based on must contain this package.
- `qubes-usb-proxy`: Required if the template is to be used for a USB qube (`sys-usb`) or for any destination qube to which USB devices are to be attached (e.g `sys-net` if using USB network adapter).
- `pulseaudio-qubes`: Needed to have audio on the template VM.
Use case | Description | Required steps
--- | --- | ---
**Standard utilities** | If you need the commonly used utilities | Install the following packages: `pciutils` `vim-minimal` `less` `psmisc` `gnome-keyring`
**Audio** | If you want sound from your VM | Install `pulseaudio-qubes`
**FirewallVM** | You can use the minimal template as a [FirewallVM](/doc/firewall/), such as the basis template for `sys-firewall` | Install at least `qubes-core-agent-networking` and `iproute`, and also `qubes-core-agent-dom0-updates` if you want to use it as the updatevm (which is normally sys-firewall).
**NetVM** | You can use this template as the basis for a NetVM such as `sys-net` | Install the following packages: `qubes-core-agent-networking` `qubes-core-agent-network-manager` `NetworkManager-wifi` `network-manager-applet` `wireless-tools` `dejavu-sans-fonts` `notification-daemon` `gnome-keyring` `polkit` `@hardware-support`.
**NetVM (extra firmware)** | If your network devices need extra packages for the template to work as a network VM | Use the `lspci` command to identify the devices, then run `dnf search firmware` (replace `firmware` with the appropriate device identifier) to find the needed packages and then install them.
**Network utilities** | If you need utilities for debugging and analyzing network connections | Install the following packages: `tcpdump` `telnet` `nmap` `nmap-ncat`
**USB** | If you want USB input forwarding to use this template as the basis for a [USB](/doc/usb/) qube such as `sys-usb` | Install `qubes-input-proxy-sender`
**VPN** | You can use this template as basis for a [VPN](/doc/vpn/) qube | Use the `dnf search "NetworkManager VPN plugin"` command to look up the VPN packages you need, based on the VPN technology you'll be using, and install them. Some GNOME related packages may be needed as well. After creation of a machine based on this template, follow the [VPN howto](/doc/vpn/#set-up-a-proxyvm-as-a-vpn-gateway-using-networkmanager) to configure it.
A comprehensive guide to customizing the minimal template is available [here][GUIDE]
See [here][customization] for further information on customizing `fedora-minimal`.
Qubes 4.0
---------
Passwordless root
-----------------
In Qubes R4.0 the minimal template is not configured for passwordless root. To update or install packages to it, from a dom0 terminal window:
It is an intentional design choice for passwordless to be optional.
Since the Fedora Minimal template is *minimal*, it is not configured for passwordless root by default.
To update or install packages to it, from a dom0 terminal window:
~~~
[user@dom0 ~]$ qvm-run -u root fedora-29-minimal xterm
@ -116,21 +117,6 @@ Optionally check this worked: from the gui open the minimal template's xterm and
which should give you output that includes the NOPASSWD keyword.
In Qubes 4.0, additional packages from the `qubes-core-agent` suite may be needed to make the customized minimal template work properly. These packages are:
- `qubes-core-agent-qrexec`: Qubes qrexec agent. Installed by default.
- `qubes-core-agent-systemd`: Qubes unit files for SystemD init style. Installed by default.
- `qubes-core-agent-passwordless-root`, `polkit`: By default the 'fedora-29-minimal' template doesn't have passwordless root. These two packages enable this feature. (Note from R4.0 a design choice was made that passwordless should be optional, so is left out of the minimal templates)
- `qubes-core-agent-nautilus`: This package provides integration with the Nautilus file manager (without it things like "copy to VM/open in disposable VM" will not be shown in Nautilus).
- `qubes-core-agent-sysvinit`: Qubes unit files for SysV init style or upstart.
- `qubes-core-agent-networking`: Networking support. Required for general network access and particularly if the template is to be used for a `sys-net` or `sys-firewall` VM.
- `qubes-core-agent-network-manager`: Integration for NetworkManager. Useful if the template is to be used for a `sys-net` VM.
- `network-manager-applet`: Useful (together with `dejavu-sans-fonts` and `notification-daemon`) to have a system tray icon if the template is to be used for a `sys-net` VM.
- `qubes-core-agent-dom0-updates`: Script required to handle `dom0` updates. Any template which the VM responsible for 'dom0' updates (e.g. `sys-firewall`) is based on must contain this package.
- `qubes-usb-proxy`: Required if the template is to be used for a USB qube (`sys-usb`) or for any destination qube to which USB devices are to be attached (e.g `sys-net` if using USB network adapter).
- `pulseaudio-qubes`: Needed to have audio on the template VM.
Logging
-------
@ -144,5 +130,5 @@ To access the `journald` log, use the `journalctl` command.
[qubes-users]: /support/#qubes-users
[doc-guidelines]: /doc/doc-guidelines/
[pref-default]: /faq/#could-you-please-make-my-preference-the-default
[GUIDE]: /doc/fedora-minimal-template-customization/
[customization]: /doc/fedora-minimal-template-customization/

15
managing-os/templates/fedora.md
View File

@ -38,16 +38,9 @@ After installing a fresh Fedora TemplateVM, we recommend performing the followin
1. [Update the TemplateVM].
2. Switch any [TemplateBasedVMs] that are based on the old TemplateVM to the new one:
2. [Switch any TemplateBasedVMs that are based on the old TemplateVM to the new one][switch-templates].
* [How to switch templates (3.2)](/doc/templates/#how-to-switch-templates-32)
* [How to switch templates (4.0)](/doc/templates/#how-to-switch-templates-40)
3. If desired, remove the old TemplateVM by running the following command in dom0:
$ sudo dnf remove qubes-template-fedora-XX
(Replace `XX` with the Fedora version number of the template you wish to remove.)
3. If desired, [uninstall the old TemplateVM].
Upgrading
@ -72,6 +65,6 @@ To upgrade your Fedora TemplateVM, please consult the guide that corresponds to
[supported]: /doc/supported-versions/#templatevms
[How to Reinstall a TemplateVM]: /doc/reinstall-template/
[Update the TemplateVM]: /doc/software-update-vm/
[TemplateBasedVMs]: /doc/glossary/#templatebasedvm
[remove the old TemplateVM]: /doc/templates/#important-notes
[switch-templates]: /doc/templates/#how-to-switch-templates
[uninstall the old TemplateVM]: /doc/templates/#how-to-uninstall

5
managing-os/windows.md
View File

@ -15,10 +15,7 @@ Qubes Windows Tools are then usually installed to provide integration with the r
For more information about Windows VMs in Qubes OS, please see the specific guides below:
* [Installing and Using Windows-based VMs](/doc/windows-vm/)
* [Installing and Using Qubes Windows Tools (Qubes R2 Beta 3 up to R3.2)](/doc/windows-tools/)
* [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)
* [Advanced options and troubleshooting of Qubes Tools for Windows (R3)](/doc/windows-tools-3/)
* [Advanced options and troubleshooting of Qubes Tools for Windows (R2)](/doc/windows-tools-2/)
* [Uninstalling Qubes Tools for Windows 2.x](/doc/uninstalling-windows-tools-2/)

126
managing-os/windows/uninstalling-windows-tools-2.md
View File

@ -1,126 +0,0 @@
---
layout: doc
title: Uninstalling Windows Tools 2
permalink: /doc/uninstalling-windows-tools-2/
redirect_from:
- /en/doc/uninstalling-windows-tools-2/
- /doc/UninstallingWindowsTools2/
- /wiki/UninstallingWindowsTools2/
---
Uninstalling Qubes Windows Tools v2.x
=====================================
**Do not try to uninstall Qubes Windows Tools (QWT) 2.x from Windows Control Panel. It will render your HVM unbootable and will require manual fixing.**
Preface
-------
Version 2.x of QWT (used for Windows HVMs in Qubes R2) is difficult to uninstall due to issues with the Xen GPL PV drivers package that is used. However, uninstalling QWT version 2.x is required to migrate the HVM to Qubes R3.
HVMs with QWT 2.x *will not boot normally in Qubes R3* due to Xen drivers failing. They will boot in Safe Mode. It's easier to uninstall QWT 2.x from Qubes R2, but if that's not an option it's also possible in Qubes R3 (just a bit more complicated). Details below.
Uninstalling QWT 2.x in Qubes R2
--------------------------------
1. Copy the uninstall script posted at the end of this document and save it in the HVM as a .BAT file.
2. Reboot the HVM in Safe Mode: type `bcdedit /set safeboot minimal` in a command prompt with admin privileges then restart normally. The OS will now always start in Safe Mode until the setting is reverted.
3. In Safe Mode execute the uninstall script from step 1.
4. Open Device Manager. Manually uninstall Qubes Video device (in 'Display adapters') and Xen PCI driver (in 'System devices'). This will prevent the (already removed) devices from showing up.
5. Type `bcdedit /deletevalue safeboot` in a command prompt to disable Safe Mode boot.
6. Reboot. Open Device Manager and verify that there are no active Xen PV devices:
- There should be one unidentified PCI device in System devices (this is the Xen PV device, not functioning because PV drivers are inactive).
- Disk drives should be QEMU (emulated).
- Network adapter should be Realtek (emulated).
Now you can backup the HVM, migrate it to Qubes R3 and install QWT 3.x there.
Uninstalling QWT 2.x in Qubes R3
--------------------------------
HVMs with QWT 2.x will not boot normally in Qubes R3 due to the old Xen drivers failing. If removing QWT from Qubes R2 is not an option (see above) then you will need to boot the HVM in Safe Mode.
### Preparation in dom0
Disable VM tools in VM's preferences:
* `qvm-prefs -s vmname qrexec_installed false`
* `qvm-prefs -s vmname guiagent_installed false`
### Enabling Safe Mode
* If you're quick you can mash F8 just as the HVM boots to access Windows' advanced boot options. The timing for it is very tight though. If you manage to get the boot menu, select Safe Mode boot.
* Alternatively, allow the HVM to (try to) boot. It will crash with a BSOD.
* After the crash start the HVM again. Now Windows will display the recovery menu which, for some unknown reason, does not include Safe Mode boot option. We need to try harder.
* Select **Launch Startup Repair**.
* If you're prompted to try System Restore, **don't**. Hit cancel.
* Grab a drink or read a book while Windows tries to do something but ultimately the repair process fails.
* *Now* you're presented with a choice of *advanced options* that include a command prompt. Why isn't this available from the start?
* Launch the command prompt, log in and type `bcdedit /set {default} safeboot minimal`. The OS will now always start in Safe Mode until the setting is reverted.
* Reboot and proceed with the uninstallation instructions from the previous paragraph (*Uninstalling QWT 2.x in Qubes R2*).
If you need network access to copy the uninstall script to the HVM, use *Safe Mode with Networking* instead of pure Safe Mode (replace `minimal` with `network` in the bcdedit commands above). Disable the Xen PV network device first. You may need to manually configure IP settings for the emulated Realtek adapter.
The uninstall script
--------------------
Save it as a .BAT file in the HVM and run in Safe Mode.
~~~
@echo off
:: This batch file uninstalls Qubes Windows Tools version 2.x
:: Needs to be run in safe mode
:: Registry cleanup
reg delete "HKLM\Software\Invisible Things Lab" /f
:: services/drivers
reg delete HKLM\System\CurrentControlSet\Services\ShutdownMon /f
reg delete HKLM\System\CurrentControlSet\Services\QrexecAgent /f
reg delete HKLM\System\CurrentControlSet\Services\QTWHelper /f
reg delete HKLM\System\CurrentControlSet\Services\QubesNetworkSetup /f
reg delete HKLM\System\CurrentControlSet\Services\QVideo /f
reg delete HKLM\System\CurrentControlSet\Services\XenNet /f
reg delete HKLM\System\CurrentControlSet\Services\XenPCI /f
reg delete HKLM\System\CurrentControlSet\Services\XenVbd /f
:: xenpci filter entries
reg delete HKLM\SYSTEM\CurrentControlSet\Control\Class\{4D36E96A-E325-11CE-BFC1-08002BE10318} /v UpperFilters /f
reg delete HKLM\SYSTEM\CurrentControlSet\Control\Class\{4D36E972-E325-11CE-BFC1-08002bE10318} /v UpperFilters /f
reg delete HKLM\SYSTEM\CurrentControlSet\Control\Class\{4D36E97B-E325-11CE-BFC1-08002BE10318} /v UpperFilters /f
:: files
rmdir /q /s "%ProgramFiles%\Invisible Things Lab"
rmdir /q /s "%ProgramFiles%\Xen PV Drivers"
del /q /s "%windir%\system32\move-profiles.exe"
del /q /s "%windir%\system32\windows-utils.dll"
del /q /s "%windir%\system32\qvgdi.dll"
del /q /s "%windir%\system32\drivers\qvmini.sys"
del /q /s "%windir%\system32\drivers\xennet.sys"
del /q /s "%windir%\system32\drivers\xenpci.sys"
del /q /s "%windir%\system32\drivers\xenvbd.sys"
:: driver store entries
FOR /F "delims=. tokens=1" %%I IN ('DIR /B "%SYSTEMROOT%\INF\OEM*.INF"') DO (
TYPE "%SYSTEMROOT%\INF\%%I.inf" | FIND /c /i "Xen GPL PV" >%TEMP%\qtwuninstall
FOR /f %%c IN (%TEMP%\qtwuninstall) DO (
IF /I %%c NEQ 0 (
DEL "%SYSTEMROOT%\INF\%%I.inf"
DEL "%SYSTEMROOT%\INF\%%I.pnf"
)
)
)
FOR /F "delims=. tokens=1" %%I IN ('DIR /B "%SYSTEMROOT%\INF\OEM*.INF"') DO (
TYPE "%SYSTEMROOT%\INF\%%I.inf" | FIND /c /i "Qubes" >%TEMP%\qtwuninstall
FOR /f %%c IN (%TEMP%\qtwuninstall) DO (
IF /I %%c NEQ 0 (
DEL "%SYSTEMROOT%\INF\%%I.inf"
DEL "%SYSTEMROOT%\INF\%%I.pnf"
)
)
)
echo.
echo Cleanup finished. Please manually uninstall Qubes Video and Xen devices from the Device Manager.
~~~

104
managing-os/windows/windows-tools-2.md
View File

@ -1,104 +0,0 @@
---
layout: doc
title: Windows Tools 2
permalink: /doc/windows-tools-2/
redirect_from:
- /en/doc/windows-tools-2/
- /doc/WindowsTools2/
- /wiki/WindowsTools2/
---
Qubes Windows Tools: advanced settings and troubleshooting
==========================================================
**This document only applies to Qubes R2 (tools version 2.x)**
*Only 64-bit Windows 7 (any edition) is supported currently.*
Installable components
----------------------
Qubes Windows Tools (QWT for short) contain several components than can be enabled or disabled during installation:
- Xen GPL PV drivers (required): drivers for the hardware exposed by Xen.
- Core Windows Agent: qrexec agent and services. Needed for proper integration with Qubes.
- Move user profiles: User profiles directory (c:\\Users) will be moved into the private disk backed by private.img. This disk will be initialized/formatted automatically if needed. This feature is useful for Windows-based HVM templates, so child AppVMs can have their separate user profiles.
- GUI Windows Agent: video driver and gui agent that enable seamless showing of Windows applications on the secure Qubes desktop.
- Disable UAC: disables User Account Control prompts. *Is this still needed/wanted? Gui agent can handle UAC prompts now.*
**In testing VMs only** it's probably a good idea to install a VNC server before installing QWT. If something goes very wrong with the Qubes gui agent, a VNC server should still allow access to the OS.
Verbose installation
--------------------
If the install process fails you can retry it using the command line below to get a detailed installation log (and send that to us):
`msiexec /i path-to-qubes-tools.msi /lv path-to-log-file.txt`
Uninstalling
------------
See [this page](/doc/uninstalling-windows-tools-2/).
Configuration
-------------
Starting from version 2.2.\* various aspects of Qubes Windows Tools can be configured through registry. Main configuration key is located in `HKEY_LOCAL_MACHINE\SOFTWARE\Invisible Things Lab\Qubes Tools`. Configuration values set on this level are global to all QWT components. It's possible to override global values with component-specific keys, this is useful mainly for setting log verbosity for troubleshooting. Possible configuration values are:
|**Name**|**Type**|**Description**|**Default value**|
|:-------|:-------|:--------------|:----------------|
|LogDir|String|Directory where logs are created|c:\\Program Files\\Invisible Things Lab\\Qubes OS Windows Tools\\log|
|LogLevel|DWORD|Log verbosity (see below)|2 (INFO)|
|LogRetention|DWORD|Maximum age of log files (in seconds), older logs are automatically deleted|604800 (7 days)|
Possible log levels:
||
|0|Error|Serious errors that most likely cause irrecoverable failures|
|1|Warning|Unexpected but non-fatal events|
|2|Info|Useful information|
|3|Debug|Internal state dumps for troubleshooting|
|4|Verbose|Trace most function calls|
Debug and Verbose levels can generate large volume of logs and are intended for development/troubleshooting only.
To override global settings for a specific component, create a new key under the root key mentioned above and name it as the executable name, without `.exe` extension. For example, to change qrexec-agent's log level to Debug, set it like this:
![qtw-log-level.png](/attachment/wiki/WindowsTools/qtw-log-level.png)
Component-specific settings currently available:
|**Component**|**Setting**|**Type**|**Description**|**Default value**|
|:------------|:----------|:-------|:--------------|:----------------|
|wga|UseDirtyBits|DWORD|Enable experimental feature of the gui agent/qvideo driver: use page table dirty bits to determine changed display regions. This can improve performance but may impact display responsiveness (some changes may not be detected resulting in "stale" image). Needs VM restart to apply change.|0|
|wga|DisableCursor|DWORD|Disable cursor in the VM. Useful for integration with Qubes desktop so you don't see two cursors. Can be disabled if you plan to use the VM through a remote desktop connection of some sort. Needs gui agent restart to apply change (locking OS/logoff should be enough since wga is restarted on desktop change).|1|
Troubleshooting
---------------
If the VM is inaccessible (doesn't respond to qrexec commands, gui is not functioning), try to boot it in safe mode:
- `qvm-start --debug vmname`
- mash F8 on the boot screen to enable boot options and select Safe Mode (optionally with networking)
Safe Mode should at least give you access to logs (see above).
**Please include appropriate logs when reporting bugs/problems.** Starting from version 2.4.2 logs contain QWT version, but if you're using an earlier version be sure to mention which one. If the OS crashes (BSOD) please include the BSOD code and parameters in your bug report. The BSOD screen should be visible if you run the VM in debug mode (`qvm-start --debug vmname`). If it's not visible or the VM reboots automatically, try to start Windows in safe mode (see above) and 1) disable automatic restart on BSOD (Control Panel - System - Advanced system settings - Advanced - Startup and recovery), 2) check the system event log for BSOD events.
If a specific component is malfunctioning, you can increase it's log verbosity as explained above to get more troubleshooting information. Below is a list of components:
||
|qrexec-agent|Responsible for most communication with Qubes (dom0 and other domains), secure clipboard, file copying, qrexec services.|
|qrexec-client-vm|Used for communications by the qrexec protocol.|
|wga|Gui agent.|
|QTWHelper|Service that monitors session/desktop changes (logon/logoff/locking/UAC...) and simulates SAS sequence (ctrl-alt-del).|
|prepare-volume|Utility that initializes and formats the disk backed by `private.img` file. It's registered to run on next system boot during QWT setup, if that feature is selected (it can't run *during* the setup because Xen block device drivers are not yet active). It in turn registers move-profiles (see below) to run at early boot.|
|move-profiles|Utility that moves user profiles directory to the private disk. It's registered as an early boot native executable (similar to chkdsk) so it can run before any profile files are opened by some other process. Its log is in a fixed location: `c:\move-profiles.log` (it can't use our common logger library so none of the log settings apply).|
Updates
-------
When we publish new QWT version (which is announced on `qubes-users` Google Group) it's usually pushed to the `current-testing` repository first. To use versions from current-testing, run this in dom0:
`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.

112
managing-os/windows/windows-tools-3.md
View File

@ -1,112 +0,0 @@
---
layout: doc
title: Windows Tools 3
permalink: /doc/windows-tools-3/
redirect_from:
- /en/doc/windows-tools-3/
- /doc/WindowsTools3/
- /doc/WindowsTools/
- /wiki/WindowsTools/
---
Qubes Windows Tools: advanced settings and troubleshooting
==========================================================
**This document only applies to Qubes R3 (tools version 3.x)**
*Only 64-bit Windows 7 (any edition) is supported currently.*
Installable components
----------------------
Qubes Windows Tools (QWT for short) contain several components than can be enabled or disabled during installation:
- Shared components (required): common libraries used by QWT components.
- Xen PV drivers: drivers for the virtual hardware exposed by Xen.
- Base Xen PV Drivers (required): paravirtual bus and interface drivers.
- Xen PV Disk Drivers: paravirtual storage drivers.
- Xen PV Network Drivers: paravirtual network drivers.
- Qubes Core Agent: qrexec agent and services. Needed for proper integration with Qubes.
- Move user profiles: user profile directory (c:\users) is moved to VM's private disk backed by private.img file in dom0 (useful mainly for HVM templates).
- Qubes GUI Agent: video driver and gui agent that enable seamless showing of Windows applications on the secure Qubes desktop.
- Disable UAC: User Account Control may interfere with QWT and doesn't really provide any additional benefits in Qubes environment.
**In testing VMs only** it's probably a good idea to install a VNC server before installing QWT. If something goes very wrong with the Qubes gui agent, a VNC server should still allow access to the OS.
**NOTE**: Xen PV disk drivers are not installed by default. This is because they seem to cause problems (BSOD = Blue Screen Of Death). We're working with upstream devs to fix this. *However*, the BSOD seems to only occur after the first boot and everything works fine after that. **Enable the drivers at your own risk** of course, but we welcome reports of success/failure in any case (backup your VM first!). With disk PV drivers absent `qvm-block` will not work for the VM, but you can still use standard Qubes inter-VM file copying mechanisms.
Xen PV driver components may display a message box asking for reboot during installation -- it's safe to ignore them and defer the reboot.
Installation logs
-----------------
If the install process fails or something goes wrong during it, include the installation logs in your bug report. They are created in the `%TEMP%` directory, by default `<user profile>\AppData\Local\Temp`. There are two text files, one small and one big, with names starting with `Qubes_Windows_Tools`.
Uninstalling QWT is supported from version 3.2.1. Uninstalling previous versions is **not recommended**.
After uninstalling you need to manually enable the DHCP Client Windows service, or set IP settings yourself to restore network access.
Configuration
-------------
Starting from version 2.2.\* various aspects of Qubes Windows Tools can be configured through registry. Main configuration key is located in `HKEY_LOCAL_MACHINE\SOFTWARE\Invisible Things Lab\Qubes Tools`. Configuration values set on this level are global to all QWT components. It's possible to override global values with component-specific keys, this is useful mainly for setting log verbosity for troubleshooting. Possible configuration values are:
|**Name**|**Type**|**Description**|**Default value**|
|:-------|:-------|:--------------|:----------------|
|LogDir|String|Directory where logs are created|c:\\Program Files\\Invisible Things Lab\\Qubes Tools\\log|
|LogLevel|DWORD|Log verbosity (see below)|2 (INFO)|
|LogRetention|DWORD|Maximum age of log files (in seconds), older logs are automatically deleted|604800 (7 days)|
Possible log levels:
||
|1|Error|Serious errors that most likely cause irrecoverable failures|
|2|Warning|Unexpected but non-fatal events|
|3|Info|Useful information (default)|
|4|Debug|Internal state dumps for troubleshooting|
|5|Verbose|Trace most function calls|
Debug and Verbose levels can generate large volume of logs and are intended for development/troubleshooting only.
To override global settings for a specific component, create a new key under the root key mentioned above and name it as the executable name, without `.exe` extension. For example, to change qrexec-agent's log level to Debug, set it like this:
![qtw-log-level.png](/attachment/wiki/WindowsTools/qtw-log-level.png)
Component-specific settings currently available:
|**Component**|**Setting**|**Type**|**Description**|**Default value**|
|:------------|:----------|:-------|:--------------|:----------------|
|qga|DisableCursor|DWORD|Disable cursor in the VM. Useful for integration with Qubes desktop so you don't see two cursors. Can be disabled if you plan to use the VM through a remote desktop connection of some sort. Needs gui agent restart to apply change (locking OS/logoff should be enough since qga is restarted on desktop change).|1|
Troubleshooting
---------------
If the VM is inaccessible (doesn't respond to qrexec commands, gui is not functioning), try to boot it in safe mode:
- `qvm-start --debug vmname`
- mash F8 on the boot screen to enable boot options and select Safe Mode (optionally with networking)
Safe Mode should at least give you access to logs (see above).
**Please include appropriate logs when reporting bugs/problems.** Starting from version 2.4.2 logs contain QWT version, but if you're using an earlier version be sure to mention which one. If the OS crashes (BSOD) please include the BSOD code and parameters in your bug report. The BSOD screen should be visible if you run the VM in debug mode (`qvm-start --debug vmname`). If it's not visible or the VM reboots automatically, try to start Windows in safe mode (see above) and 1) disable automatic restart on BSOD (Control Panel - System - Advanced system settings - Advanced - Startup and recovery), 2) check the system event log for BSOD events. If you can, send the `memory.dmp` dump file from c:\Windows.
Xen logs (/var/log/xen/console/guest-*) are also useful as they contain pvdrivers diagnostic output.
If a specific component is malfunctioning, you can increase its log verbosity as explained above to get more troubleshooting information. Below is a list of components:
||
|qrexec-agent|Responsible for most communication with Qubes (dom0 and other domains), secure clipboard, file copying, qrexec services.|
|qrexec-wrapper|Helper executable that's responsible for launching qrexec services, handling their I/O and vchan communication.|
|qrexec-client-vm|Used for communications by the qrexec protocol.|
|qga|Gui agent.|
|QgaWatchdog|Service that monitors session/desktop changes (logon/logoff/locking/UAC...) and simulates SAS sequence (ctrl-alt-del).|
|qubesdb-daemon|Service for accessing Qubes configuration database.|
|network-setup|Service that sets up network parameters according to VM's configuration.|
|prepare-volume|Utility that initializes and formats the disk backed by `private.img` file. It's registered to run on next system boot during QWT setup, if that feature is selected (it can't run *during* the setup because Xen block device drivers are not yet active). It in turn registers move-profiles (see below) to run at early boot.|
|relocate-dir|Utility that moves user profiles directory to the private disk. It's registered as an early boot native executable (similar to chkdsk) so it can run before any profile files are opened by some other process. Its log is in a fixed location: `c:\move-profiles.log` (it can't use our common logger library so none of the log settings apply).|
Updates
-------
When we publish new QWT version (which is announced on `qubes-users` Google Group) it's usually pushed to the `current-testing` or `unstable` repository first. To use versions from current-testing, run this in dom0:
`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.

4
managing-os/windows/windows-tools.md
View File

@ -9,8 +9,8 @@ redirect_from:
- /wiki/WindowsAppVms/
---
What are Qubes Windows Tools ?
==============================
Qubes Windows Tools
===================
Qubes Windows Tools are a set of programs and drivers that provide integration of Windows AppVMs with the rest of the Qubes system. Currently the following features are available for Windows VMs after installation of those tools:

127
managing-os/windows/windows-vm.md
View File

@ -21,131 +21,8 @@ qvm-prefs VMNAME virt_mode hvm
Note however that you are better off creating a new Windows VM to benefit from the more recent emulated hardware: R3.2 uses a MiniOS based stubdomain with an old and mostly unmaintained 'qemu-traditional' while R4.0 uses a Linux based stubdomain with a recent version of upstream qemu (see [this post](https://groups.google.com/d/msg/qubes-devel/tBqwJmOAJ94/xmFCGJnuAwAJ)).
Qubes 3.2 - Windows VM installation
-----------------------------------
### Summary ###
~~~
qvm-create win7new --hvm --label red
qvm-prefs -s win7new memory 4096
qvm-prefs -s win7new maxmem 4096
qvm-grow-root win7new 25g
qvm-prefs -s win7new debug true
cp /var/lib/qubes/appvms/win7new/win7new.conf /tmp
sed -i "s/<model \+type='xen' \+vram=/<model type='cirrus' vram=/" /tmp/win7new.conf
qvm-start --custom-config=/tmp/win7new.conf --cdrom=untrusted:/home/user/windows_install.iso win7new
# restart after the first part of the windows installation process ends
qvm-start --custom-config=/tmp/win7new.conf win7new
# once Windows is installed and working
qvm-prefs -s win7new memory 2048
qvm-prefs -s win7new maxmem 2048
rm /tmp/win7new.conf
qvm-prefs -s win7new qrexec_timeout 300
# with Qubes Windows Tools installed:
qvm-prefs -s win7new debug false
~~~
### Detailed instructions ###
MS Windows versions considerations:
- The instructions *may* work on other versions than Windows 7 x64 but haven't been tested.
- Qubes Windows Tools (QWT) only supports Windows 7 x64.
Create a VM named win7new in [HVM](/doc/hvm/) mode (Xen's current PVH limitations precludes from using PVH):
~~~
qvm-create win7new --hvm --label red
~~~
Windows' installer requires a significant amount of memory or else the VM will crash with such errors:
`/var/log/xen/console/hypervisor.log`:
> p2m_pod_demand_populate: Dom120 out of PoD memory! (tot=102411 ents=921600 dom120)
> (XEN) domain_crash called from p2m-pod.c:1218
> (XEN) Domain 120 (vcpu#0) crashed on cpu#3:
So, increase the VM's memory to 4096MB (memory = maxmem because we don't use memory balancing).
~~~
qvm-prefs -s win7new memory 4096
qvm-prefs -s win7new maxmem 4096
~~~
A typical Windows 7 installation requires between 15GB up to 19GB of disk space depending on the version (Home/Professional/...). Windows updates also end up using significant space. So, extend the root volume from the default 10GB to 25GB (note: it is straightforward to increase the root volume size after Windows is installed: simply extend the volume again in dom0 and then extend the system partition with Windows's disk manager).
~~~
qvm-grow-root win7new 25g
~~~
Set the debug flag in order to have a graphical console:
~~~
qvm-prefs -s win7new debug true
~~~
The second part of the installation process will crash with the standard VGA video adapter and the VM will stay in "transient" mode with the following error in `guest-win7new-dm.log`:
> qemu: /home/user/qubes-src/vmm-xen-stubdom-linux/build/qemu/exec.c:1187: cpu_physical_memory_snapshot_get_dirty: Assertion `start + length <= snap->end' failed.
To avoid that error we temporarily have to switch the video adapter to 'cirrus'. Backup the VM's configuration file and substitute the video driver from 'xen' to 'cirrus':
~~~
cp /var/lib/qubes/appvms/win7new/win7new.conf /tmp
sed -i "s/<model \+type='xen' \+vram=/<model type='cirrus' vram=/" /tmp/win7new.conf
# or edit the file manually ; either way, make sure the adapter is now cirrus !
~~~
The VM is now ready to be started; the best practice is to use an installation ISO [located in a VM](/doc/hvm/#installing-an-os-in-an-hvm-domain):
~~~
qvm-start --custom-config=/tmp/win7new.conf --cdrom=untrusted:/home/user/windows_install.iso win7new
~~~
Given the higher than usual memory requirements of Windows, you may get a `Not enough memory to start domain 'win7new'` error. In that case try to shutdown unneeded VMs to free memory before starting the Windows VM.
At this point you may open a tab in dom0 for debugging, in case something goes amiss:
~~~
tailf /var/log/qubes/vm-win7new.log \
/var/log/xen/console/hypervisor.log \
/var/log/xen/console/guest-win7new-dm.log
~~~
The VM will shutdown after the installer completes the extraction of Windows installation files. It's a good idea to clone the VM now (eg. `qvm-clone win7new win7newbkp1`). Then, (re)start the VM with
~~~
qvm-start --custom-config=/tmp/win7new.conf win7new
~~~
The second part of Windows' installer should then be able to complete successfully. You may then perform the following post-install steps:
Decrease the VM's memory to a more reasonable value (memory balancing on Windows is unstable so keep `memory` equal to `maxmen`).
~~~
qvm-prefs -s win7new memory 2048
qvm-prefs -s win7new maxmem 2048
~~~
We don't need to use the 'cirrus' video adapter anymore; simply starting the VM with `qvm-start win7new` will use the default XEN adapter, but to avoid any mistakes let's remove the temporary configuration file we created before:
~~~
rm /tmp/win7new.conf
~~~
Finally, increase the VM's `qrexec_timeout`: in case you happen to get a BSOD or a similar crash in the VM, utilities like chkdsk won't complete on restart before qrexec_timeout automatically halts the VM. That can really put the VM in a totally unrecoverable state, whereas with higher qrexec_timeout, chkdsk or the appropriate utility has plenty of time to fix the VM. Note that Qubes Windows Tools also require a larger timeout to move the user profiles to the private volume the first time the VM reboots after the tools' installation.
~~~
qvm-prefs -s win7new qrexec_timeout 300
~~~
At that point you should have a functional and stable Windows VM, although without updates, Xen's PV drivers nor Qubes integration (see sections [Windows Update](#windows-update) and [Xen PV drivers and Qubes Windows Tools](#xen-pv-drivers-and-qubes-windows-tools) below). It is a good time to clone the VM again.
Qubes 4.0 - Windows VM installation
-----------------------------------
Windows VM installation
-----------------------
### Summary ###

2
privacy/anonymizing-your-mac-address.md
View File

@ -11,7 +11,6 @@ Anonymizing your MAC Address
Although it is not the only metadata broadcast by network hardware, changing the default [MAC Address](https://en.wikipedia.org/wiki/MAC_address) of your hardware could be [an important step in protecting privacy](https://tails.boum.org/contribute/design/MAC_address/#index1h1).
Currently, Qubes OS *does not* automatically "anonymize" or spoof the MAC Address, so unless this gets implemented by default you can randomize your MAC Address with the following guide.
The Network Manager method should work with both Qubes R4.0 and R3.2.
## Upgrading and configuring Network Manager in Qubes
@ -67,3 +66,4 @@ Next, create a new NetVM using the edited template and assign network devices to
Finally, shutdown all VMs and change the settings of sys-firewall, etc. to use the new NetVM.
You can check the MAC address currently in use by looking at the status pages of your router device(s), or inside the NetVM with the command `sudo ip link show`.

2
reference/glossary.md
View File

@ -148,7 +148,7 @@ However, paravirtualized VMs require a PV-enabled kernel and PV drivers, so the
HVM
---
Hardware Virtual Machine.
Hardware-assisted Virtual Machine.
Any fully virtualized, or hardware-assisted, [VM](#vm) utilizing the virtualization extensions of the host CPU.
Although HVMs are typically slower than paravirtualized VMs due to the required emulation, HVMs allow the user to create domains based on any operating system.

7
reference/qubes-service.md
View File

@ -8,9 +8,11 @@ redirect_from:
- /wiki/QubesService/
---
Usage documentation is on [qvm-service manual page](/doc/dom0-tools/qvm-service/). There are also described predefined services.
Usage documentation is on `qvm-service` man page. There are also described predefined services.
Under the hood enabled service in VM is signaled by file in /var/run/qubes-service. This can be used to implement almost enable/disable **per-VM** switch controlled by dom0. Adding support for systemd services is pretty simple:
Under the hood enabled service in VM is signaled by file in `/var/run/qubes-service`.
This can be used to implement almost enable/disable **per-VM** switch controlled by dom0.
Adding support for systemd services is pretty simple:
In the VM, create `/etc/systemd/system/<service name>.service.d/30_qubes.conf` file
containing (you may need to create a directory for this file first):
@ -21,3 +23,4 @@ ConditionPathExists=/var/run/qubes-service/<service name>
~~~
This will cause service to be started only when you enable it with qvm-service for this VM.

55
security/firewall.md
View File

@ -9,8 +9,9 @@ redirect_from:
- /wiki/QubesFirewall/
---
Understanding Qubes networking and firewall
===========================================
The Qubes Firewall
==================
Understanding firewalling in Qubes
----------------------------------
@ -24,6 +25,7 @@ For more information, see the following:
- [https://groups.google.com/group/qubes-devel/browse\_thread/thread/9e231b0e14bf9d62](https://groups.google.com/group/qubes-devel/browse_thread/thread/9e231b0e14bf9d62)
- [https://blog.invisiblethings.org/2011/09/28/playing-with-qubes-networking-for-fun.html](https://blog.invisiblethings.org/2011/09/28/playing-with-qubes-networking-for-fun.html)
How to edit rules
-----------------
@ -55,12 +57,13 @@ The limit was removed in R4.0.
It is possible to work around this limit by enforcing the rules on the qube itself
by putting appropriate rules in `/rw/config`.
See the "Where to put firewall rules" sections below for [R4.0](#where-to-put-firewall-rules-r40) and [R3.2](#where-to-put-firewall-rules-r32).
See [Where to put firewall rules](#where-to-put-firewall-rules).
In complex cases, it might be appropriate to load a ruleset using `iptables-restore`
called from `/rw/config/rc.local`.
Reconnecting VMs after a NetVM reboot (R4.0)
----------------------------------------
Reconnecting VMs after a NetVM reboot
-------------------------------------
Normally Qubes doesn't let the user stop a NetVM if there are other qubes
running which use it as their own NetVM. But in case the NetVM stops for
@ -80,28 +83,10 @@ default Qubes installation):
` qvm-prefs sys-firewall netvm sys-net `
Reconnecting VMs after a NetVM reboot (R3.2)
----------------------------------------
Normally Qubes doesn't let the user stop a NetVM if there are other qubes
running which use it as their own NetVM. But in case the NetVM stops for
whatever reason (e.g. it crashes, or the user forces its shutdown via qvm-kill
via terminal in Dom0), then there is an easy way to restore the connection to
the NetVM by issuing:
` qvm-prefs <vm> -s netvm <netvm> `
Normally qubes do not connect directly to the actual NetVM which has networking
devices, but rather to the default sys-firewall first, and in most cases it would
be the NetVM that will crash, e.g. in response to S3 sleep/restore or other
issues with WiFi drivers. In that case it is only necessary to issue the above
command once, for the sys-firewall (this assumes default VM-naming used by the
default Qubes installation):
` qvm-prefs sys-firewall -s netvm sys-net `
Network service qubes
--------------------------------------
---------------------
Qubes does not support running any networking services (e.g. VPN, local DNS server, IPS, ...) directly in a qube that is used to run the Qubes firewall service (usually sys-firewall) for good reasons.
In particular, if one wants to ensure proper functioning of the Qubes firewall, one should not tinker with iptables or nftables rules in such qubes.
@ -117,8 +102,9 @@ The sys-firewall-2 proxy ensures that:
For the VPN service please also look at the [VPN documentation](/doc/vpn).
Enabling networking between two qubes
--------------------------------------
-------------------------------------
Normally any networking traffic between qubes is prohibited for security reasons.
However, in special situations, one might want to selectively allow specific qubes
@ -174,8 +160,9 @@ sudo iptables -I INPUT -s <IP address of A> -j ACCEPT
[root@B user]# chmod +x /rw/config/rc.local
~~~
Port forwarding to a qube from the outside world
--------------------------------------------------
------------------------------------------------
In order to allow a service present in a qube to be exposed to the outside world
in the default setup (where the qube has sys-firewall as network VM, which in
@ -434,7 +421,8 @@ fi
This time testing should allow connectivity to the service as long as the
service is up :-)
Where to put firewall rules (R4.0)
Where to put firewall rules
---------------------------
Implicit in the above example [scripts](/doc/config-files/), but worth
@ -444,14 +432,3 @@ AppVMs supplying networking (`sys-firewall` inclusive),
iptables commands should be added to
`/rw/config/qubes-firewall-user-script`.
Where to put firewall rules (R3.2)
---------------------------
Implicit in the above example [scripts](/doc/config-files/), but worth
calling attention to: for all qubes *except* ProxyVMs, iptables commands
should be added to the `/rw/config/rc.local` script. For ProxyVMs
(`sys-firewall` inclusive), iptables commands should be added to
`/rw/config/qubes-firewall-user-script`. This is because a ProxyVM is
constantly adjusting its firewall, and therefore initial settings from
`rc.local` do not persist.

10
security/u2f-proxy.md
View File

@ -113,10 +113,8 @@ website compromising the browser in an attempt to bypass U2F authentication.
## Installation
The Qubes U2F Proxy tool can be installed in Qubes 3.2 and 4.0. (However, the
[Advanced usage] features are only available in 4.0.) These instructions assume
that there is a `sys-usb` qube that holds the USB stack, which is the default
configuration in most Qubes OS installations.
These instructions assume that there is a `sys-usb` qube that holds the USB
stack, which is the default configuration in most Qubes OS installations.
In dom0:
@ -177,8 +175,8 @@ will have access to your banking key but not your Twitter key, and your
## TemplateVM and browser support
The large number of possible combinations of Qubes version (3.2, 4.0),
TemplateVM (Fedora 27, 28; Debian 8, 9), and browser (multiple Google Chrome
The large number of possible combinations of
TemplateVM (Fedora 27, 28; Debian 8, 9) and browser (multiple Google Chrome
versions, multiple Chromium versions, multiple Firefox versions) made it
impractical for us to test every combination that users are likely to attempt
with the Qubes U2F Proxy. In some cases, you may be the first person to try a

24
troubleshooting/remove-vm-manually.md
View File

@ -8,31 +8,11 @@ How to Remove VMs Manually
==========================
How to Remove a TemplateVM Manually
------------------------------------------
-----------------------------------
Try the [normal method] before resorting to these.
Try the [normal method] before resorting to this.
All of the following commands should be executed in a dom0 terminal.
### R3.2
1. Remove the TemplateVM's directory:
$ rm -rf /var/lib/qubes/vm-templates/<template-name>
2. Remove the TemplateVM from qubes.xml:
$ qvm-remove --just-db <template-name>
3. Remove the TemplateVM's `*.desktop` files from `~/.local/share/applications`:
$ rm ~/.local/share/applications/<template-name>*
4. Remove the TemplateVM's Applications Menu entry:
$ sudo rm /etc/xdg/menus/applications-merged/<template-name>*
### R4.0
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`