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

Merge branch 'master' into vm-troubleshooting

Browse Source
This commit is contained in:
Enjeck Cleopatra 2020-10-19 13:44:19 +01:00 committed by GitHub
commit 23c0523810
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
79 changed files with 2123 additions and 1204 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
.travis.yml
View File

@ -1,5 +1,5 @@
language: ruby
dist: trusty
dist: bionic
rvm:
- 2.5
install: git clone https://github.com/${TRAVIS_REPO_SLUG%%/*}/qubesos.github.io ~/qubesos.github.io

6
developer/building/qubes-builder.md
View File

@ -15,7 +15,7 @@ Building Qubes from scratch
We have a fully automated build system for Qubes, that downloads, builds and
packages all the Qubes components, and finally should spit out a ready-to-use
installation ISO.
installation ISO, all in a [secure](/news/2016/05/30/build-security/) way.
In order to use it, you should use an rpm-based distro, like Fedora :), and should ensure the following packages are installed:
@ -32,14 +32,14 @@ In order to use it, you should use an rpm-based distro, like Fedora :), and shou
- rpm-sign
- dpkg-dev
- debootstrap
- PyYAML
- python3-pyyaml
- devscripts
- perl-Digest-MD5
- perl-Digest-SHA
Usually you can install those packages by just issuing:
sudo dnf install gnupg git createrepo rpm-build make wget rpmdevtools python3-sh dialog rpm-sign dpkg-dev debootstrap PyYAML devscripts perl-Digest-MD5 perl-Digest-SHA
sudo dnf install gnupg git createrepo rpm-build make wget rpmdevtools python3-sh dialog rpm-sign dpkg-dev debootstrap python3-pyyaml devscripts perl-Digest-MD5 perl-Digest-SHA
The build system creates build environments in chroots and so no other packages are needed on the host.
All files created by the build system are contained within the qubes-builder directory.

21
developer/building/qubes-iso-building.md
View File

@ -16,17 +16,17 @@ Building Qubes OS ISO
Build Environment
-----------------
Fedora 30 has been successfully used to build Qubes R4.0 with the below steps.
Fedora 32 has been successfully used to build Qubes R4.0 with the below steps.
Other rpm-based operating systems may also work.
Travis-CI uses Ubuntu 14.04 to perform test builds, except it can not test the `./setup` script.
Travis-CI uses Ubuntu 18.04 to perform test builds, except it can not test the `./setup` script.
In `dom0`, install the Fedora 30 template if you don't already have it.
In `dom0`, install the Fedora 32 template if you don't already have it.
~~~
sudo qubes-dom0-update qubes-template-fedora-30
sudo qubes-dom0-update qubes-template-fedora-32
~~~
Create a standalone AppVM from the Fedora 30 template.
Create a standalone AppVM from the Fedora 32 template.
Set private storage to at least 60 GB if you will be building only the default templates; 100 GB or more if you plan on additional.
It's not required, but if you allocate additional CPU cores, the build process can utilize them at some steps such as the kernel build.
Likewise, more memory (up to 16 GB) can help.
@ -35,7 +35,7 @@ Last, you may want to disable memory balancing, but keep in mind the impact on y
Once you've built the development AppVM, open a Terminal window to it and install the necessary dependencies (see [QubesBuilder](/doc/qubes-builder/) for more info):
~~~
$ sudo dnf install perl-Digest-SHA rpmdevtools rpm-build dialog rpm-sign python2-sh dpkg-dev debootstrap devscripts
$ sudo dnf install git createrepo rpm-build rpm-sign make python3-sh rpmdevtools rpm-sign dialog perl-open python3-pyyaml perl-Digest-MD5 perl-Digest-SHA
~~~
Get the necessary keys to verify the sources (run these and other commands below as a regular user, not root):
@ -81,11 +81,13 @@ cd ~/qubes-builder
# Select Yes to add Qubes OS Signing Key
# Select 4.0 for version
# Stable
# Select Yes for fast Git cloning
# Select Current (if you want the option to use pre-built packages)
# No (we want a full build)
# Select No (we want a full build)
# Select fc30 and buster (for the currently shipping templates)
# Select builder-rpm, builder-debian, template-whonix, mgmt-salt
# Yes (to download)
# Select Yes to add adrelanos's third party key
# Select Yes (to download)
~~~
Once it completes downloading, re-run `setup` to add the Whonix templates:
@ -93,8 +95,7 @@ Once it completes downloading, re-run `setup` to add the Whonix templates:
~~~
./setup
# Choose the same options as above, except at templates select:
# fc30, buster, whonix-gateway-14, whonix-workstation-14
# If prompted, choose Yes to add adrelanos's third party key
# fc30, buster, whonix-gateway-15, whonix-workstation-15
~~~
Continue the build process with:

94
developer/debugging/automated-tests.md
View File

@ -17,18 +17,32 @@ Starting with Qubes R3 we use [python unittest][unittest] to perform automatic t
Despite the name, we use it for both [unit tests](https://en.wikipedia.org/wiki/Unit_tests) and [integration tests](https://en.wikipedia.org/wiki/Integration_tests).
The main purpose is, of course, to deliver much more stable releases.
Integration tests are written with the assumption that they will be called on dedicated hardware.
**Do not run these tests on installations with important data, because you might lose it.**
Since these tests were written with this expectation, all the VMs with a name starting with `test-` on the installation are removed during the process, and all the tests are recklessly started from dom0, even when testing VM components.
The integration tests must be run in dom0, but some unit tests can run inside a VM as well.
Most of the tests are stored in the [core-admin repository](https://github.com/QubesOS/qubes-core-admin/tree/master/qubes/tests) in the `qubes/tests` directory.
To start them you can use standard python unittest runner:
python3 -m unittest -v qubes.tests
Or our custom one:
python3 -m qubes.tests.run -v
### Integration & unit testing in dom0
Our test runner runs mostly the same as the standard one, but it has some nice additional features like color output and not needing the "qubes.test" prefix.
It also has the ability to run lone selected template tests.
Integration tests are written with the assumption that they will be executed on dedicated hardware and must be run in dom0. All other unit tests can also be run in dom0.
**Do not run the tests on installations with important data, because you might lose it.**
All the VMs with a name starting with `test-` on the installation are removed during the process, and all the tests are recklessly started from dom0, even when testing (& possibly breaking) VM components.
First you need to build all packages that you want to test. Please do not mix branches as this will inevitably lead to failures. Then setup Qubes OS with these packages installed.
For testing you'll have to stop the `qubesd` service as the tests will use its own custom variant of the service:
`sudo systemctl stop qubesd`
Don't forget to start it after testing again.
To start testing you can then use the standard python unittest runner:
`sudo -E python3 -m unittest -v qubes.tests`
Alternatively, use the custom Qubes OS test runner:
`sudo -E python3 -m qubes.tests.run -v`
Our test runner runs mostly the same as the standard one, but it has some nice additional features like colored output and not needing the "qubes.test" prefix.
You can use `python3 -m qubes.tests.run -h` to get usage information:
@ -93,28 +107,56 @@ For instance, to run only the tests for the fedora-21 template, you can use the
vm_qrexec_gui/TC_20_DispVM_fedora-21/test_010_simple_dvm_run
vm_qrexec_gui/TC_20_DispVM_fedora-21/test_020_gui_app
vm_qrexec_gui/TC_20_DispVM_fedora-21/test_030_edit_file
[user@dom0 ~]$ python3 -m qubes.tests.run -v `python3 -m qubes.tests.run -l | grep fedora-21`
[user@dom0 ~]$ sudo -E python3 -m qubes.tests.run -v `python3 -m qubes.tests.run -l | grep fedora-21`
Example test run:
![snapshot-tests2.png](/attachment/wiki/developers/snapshot-tests2.png)
### Qubes 4.0
Tests on Qubes 4.0 require stopping `qubesd` service first, because special instance of it is started as part of the test run.
Additionally, tests needs to be started as root. The full command to run the tests is:
sudo systemctl stop qubesd; sudo -E python3 -m qubes.tests.run -v ; sudo systemctl start qubesd
On Qubes 4.0 tests are also compatible with nose2 test runner, so you can use this instead:
Tests are also compatible with nose2 test runner, so you can use this instead:
sudo systemctl stop qubesd; sudo -E nose2 -v --plugin nose2.plugins.loader.loadtests qubes.tests; sudo systemctl start qubesd
This may be especially useful together with various nose2 plugins to store tests results (for example `nose2.plugins.junitxml`), to ease presenting results. This is what we use on [OpenQA].
### Unit testing inside a VM
Many unit tests will also work inside a VM. However all of the tests requiring a dedicated VM to be run (mostly the integration tests) will be skipped.
Whereas integration tests are mostly stored in the [qubes-core-admin](https://github.com/QubesOS/qubes-core-admin) repository, unit tests can be found in each of the Qubes OS repositories.
To for example run the `qubes-core-admin` unit tests, you currently have to clone at least [qubes-core-admin](https://github.com/QubesOS/qubes-core-admin) and
its dependency [qubes-core-qrexec](https://github.com/QubesOS/qubes-core-qrexec) repository in the branches that you want to test.
The below example however will assume that you set up a build environment as described in the [Qubes Builder documentation](/doc/qubes-builder/).
Assuming you cloned the `qubes-builder` repository to your home directory inside a fedora VM, you can use the following commands to run the unit tests:
```{.bash}
cd ~
sudo dnf install python3-pip lvm2 python35 python3-virtualenv
virtualenv -p /usr/bin/python35 python35
source python35/bin/activate
python3 -V
cd ~/qubes-builder/qubes-src/core-admin
pip3 install -r ci/requirements.txt
export PYTHONPATH=../core-qrexec:test-packages
./run-tests
```
To run only the tests related to e.g. `lvm`, you may use:
`./run-tests -v $(python3 -m qubes.tests.run -l | grep lvm)`
You can later re-use the created virtual environment including all of the via `pip3` installed packages with `source ~/python35/bin/activate`.
We recommend to run the unit tests with the Python version that the code is meant to be run with in dom0 (3.5 was just an example above). For instance, the `release4.0` (Qubes 4.0) branch is intended
to be run with Python 3.5 whereas the Qubes 4.1 branch (`master` as of 2020-07) is intended to be run with Python 3.7 or higher. You can always check your dom0 installation for the Python version of
the current stable branch.
### Tests configuration
Test run can be altered using environment variables:
Test runs can be altered using environment variables:
- `DEFAULT_LVM_POOL` - LVM thin pool to use for tests, in `VolumeGroup/ThinPool` format
- `QUBES_TEST_PCIDEV` - PCI device to be used in PCI passthrough tests (for example sound card)
@ -144,10 +186,10 @@ Again, given the hypothetical `example.py` test:
### Testing PyQt applications
When testing (Py)QT application, it's useful to create separate QApplication object for each test.
But QT framework does not allow to have multiple QApplication objects in the same process at the same time.
This means it's critical to reliably cleanup previous instance before creating the new one.
This turns out to be non-trivial task, especially if _any_ test uses event loop.
When testing (Py)QT applications, it's useful to create a separate QApplication object for each test.
But QT framework does not allow multiple QApplication objects in the same process at the same time.
This means it's critical to reliably cleanup the previous instance before creating a new one.
This turns out to be a non-trivial task, especially if _any_ test uses the event loop.
Failure to perform proper cleanup in many cases results in SEGV.
Below you can find steps for the proper cleanup:
@ -205,7 +247,7 @@ Installation Tests with openQA
Manually testing the installation of Qubes OS is a time-consuming process.
We use [openQA] to automate this process.
It works by installing Qubes in KVM and interacting with it as a user would, including simulating mouse clicks and keyboard presses.
Then, it checks the output to see whether various tests were passed, e.g., by comparing the virtual screen output to screenshots of a successful installation.
Then, it checks the output to see whether various tests were passed, e.g. by comparing the virtual screen output to screenshots of a successful installation.
Using openQA to automatically test the Qubes installation process works as of Qubes 4.0-rc4 on 2018-01-26, provided that the versions of KVM and QEMU are new enough and the hardware has VT-x and EPT.
KVM also supports nested virtualization, so HVM should theoretically work.
@ -214,6 +256,6 @@ Nonetheless, PV works well, which is sufficient for automated installation testi
Thanks to an anonymous donor, our openQA system is hosted in a datacenter on hardware that meets these requirements.
[unittest]: https://docs.python.org/2/library/unittest.html
[unittest]: https://docs.python.org/3/library/unittest.html
[OpenQA]: http://open.qa/

14
developer/debugging/profiling.md
View File

@ -11,7 +11,7 @@ redirect_from:
Profiling
=========
This is python profiling primer.
This is a python profiling primer.
For the purpose of this document, `qubes-dev` is name of the domain used for postprocessing profiling stats.
@ -23,7 +23,7 @@ yum install gprof2dot graphviz
git clone http://git.woju.eu/qubes/profiling.git
~~~
If you profile something on dom0, move `Upload.sh` from repository to dom0:
If you profile something in dom0, move `Upload.sh` from the repository to dom0:
~~~
mkdir -p ~/profiling
@ -37,7 +37,7 @@ Workflow
### Identify function responsible for some slow action
You have to select area in which you suspect less than optimal performance. If you do not narrow the area, graphs may be unreadable.
You have to select the area in which you suspect less than optimal performance. If you do not narrow the area, graphs may be unreadable.
### Replace suspect function with probe
@ -59,7 +59,7 @@ with
Beware that some functions may be called often. For example `qubesmanager/main.py:update_table` gets run once per second. This will produce one pstat file per second.
Remember to revert your changes to application afterwards.
Remember to revert your changes to the application afterwards.
### Upload statistics
@ -76,13 +76,13 @@ cd ~/profiling
make
~~~
For every `${basename}.pstats` this will produce `${basename}.txt` and `${basename}.svg`. SVG contains call graph. Text file contains list of all functions sorted by cumulative execution time. You may also try `make all-png`.
For every `${basename}.pstats` this will produce `${basename}.txt` and `${basename}.svg`. SVG files contain call graphs. Text files contain lists of all functions, sorted by cumulative execution time. You may also try `make all-png`.
~~~
make index.html
~~~
This creates `index.html` with all SVG graphics linked to TXT files. Ready for upload.
This creates `index.html` with all SVG graphics linked to TXT files, ready for upload.
~~~
make REMOTE=example.com:public_html/qubes/profiling/ upload
@ -95,4 +95,4 @@ This example is from `qubes-manager` (`qubesmanager/main.py`).
!["update\_table-20140424-170010.svg"](//attachment/wiki/Profiling/update_table-20140424-170010.svg)
It is apparent than problem is around `get_disk_usage` which calls something via `subprocess.call`. It does it 15 times, probably once per VM.
It is apparent that the problem is around `get_disk_usage`, which calls something via `subprocess.call`. It does this 15 times, probably once per VM.

4
developer/debugging/vm-interface.md
View File

@ -162,7 +162,7 @@ Services called by dom0 to provide some VM configuration:
Other Qrexec services installed by default:
- `qubes.Backup` - store Qubes backup. The service receives location chosen by
the user (one line, terminated by '\n'), the backup archive ([description of
the user (one line, terminated by `\n`), the backup archive ([description of
backup format](/doc/BackupEmergencyRestoreV2/))
- `qubes.DetachPciDevice` - service called in reaction to `qvm-pci -d` call on
running VM. The service receives one word - BDF of device to detach. When the
@ -175,7 +175,7 @@ Other Qrexec services installed by default:
This service is used by both `qvm-open-in-vm` and `qvm-open-in-dvm` tools. When
called in DispVM, service termination will trigger DispVM cleanup.
- `qubes.Restore` - retrieve Qubes backup. The service receives backup location
entered by the user (one line, terminated by '\n'), then should output backup
entered by the user (one line, terminated by `\n`), then should output backup
archive in [qfile format](/doc/qfilecopy/) (core-agent-linux component contains
`tar2qfile` utility to do the conversion)
- `qubes.SelectDirectory`, `qubes.SelectFile` - services which should show

3
developer/general/doc-guidelines.md
View File

@ -245,8 +245,7 @@ When making contributions, please try to observe the following style conventions
* Rationale: In the event that a user is required to read the Markdown source directly, this will make it easier to follow, e.g., numbered steps in a set of instructions.
* Use hanging indentations
where appropriate.
* Use underline headings (`=====` and `-----`) if possible.
If this is not possible, use Atx-style headings: (`### H3 ###`).
* Use Atx-style headings: `# h1`, `##h 2`, `### h3`, etc.
* When writing code blocks, use [syntax highlighting](https://github.github.com/gfm/#info-string) where [possible](https://github.com/jneen/rouge/wiki/List-of-supported-languages-and-lexers) and use `[...]` for anything omitted.
* When providing command line examples:
* Tell the reader where to open a terminal (dom0 or a specific domU), and show the command along with its output (if any) in a code block, e.g.:

24
developer/general/gsoc.md
View File

@ -613,6 +613,30 @@ Details, reference: [#2233](https://github.com/QubesOS/qubes-issues/issues/2233)
**Mentor**: Inquire on [qubes-devel][ml-devel].
### Admin API Fuzzer
**Project**: Develop a [Fuzzer](https://en.wikipedia.org/wiki/Fuzzing) for the
[Qubes OS Admin API](https://www.qubes-os.org/doc/admin-api/).
**Brief explanation**: The [Qubes OS Admin API](https://www.qubes-os.org/doc/admin-api/)
enables VMs to execute privileged actions on other VMs or dom0 - if allowed by the Qubes OS RPC policy.
Programming errors in the Admin API however may cause these access rights to be more permissive
than anticipated by the programmer.
Since the Admin API is continuously growing and changing, continuous security assessments are required.
A [Fuzzer](https://en.wikipedia.org/wiki/Fuzzing) would help to automate part of these assessments.
**Expected results**:
- fully automated & extensible Fuzzer for parts of the Admin API
- user & developer documentation
**Prerequisites**:
- basic Python understanding
- some knowledge about fuzzing & existing fuzzing frameworks (e.g. [oss-fuzz](https://github.com/google/oss-fuzz/tree/master/projects/qubes-os))
- a hacker's curiosity
**Mentor**: Inquire on [qubes-devel][ml-devel].
----
We adapted some of the language here about GSoC from the [KDE GSoC page](https://community.kde.org/GSoC).

20
developer/general/gsod.md
View File

@ -107,6 +107,24 @@ This could be helped by writing consolidated guide with with a clear list of sym
**Mentor**: [Marek Marczykowski-Górecki][team]
### Installation Guide for Qubes OS on Virtual Machines
**Project**: Installation Guide for Qubes OS on Virtual Machines.
**Brief explanation**: The Qubes OS is missing an installation guide for virtual machines. Users are installing an outdated and unsupported version of Qubes OS (3.2) instead of the supported version. There is unofficial [existing installation guide] for Qubes OS on a virtual box but it is misleading and lacks documentation. Usually, users face some errors and bugs while installing Qubes OS on a virtual machine.[virtual box issue]
**Expected results**:
-Provide a new option of installation guide for users working on virtual machines.
-Review existing problems and provide solutions to them.
-Giving a warning for using outdated versions.
**Knowledge prerequisite**:
- Experience in virtual boxes and machines.
- Basic Knowledge about Fedora linux architecture.
- [Markdown][markdown]
**Mentor**: [Marek Marczykowski-Górecki][team]
[gsod]: https://developers.google.com/season-of-docs/
[team]: /team/
[gsod-doc]: https://developers.google.com/season-of-docs/docs/
@ -121,3 +139,5 @@ This could be helped by writing consolidated guide with with a clear list of sym
[doc-issues]: https://github.com/QubesOS/qubes-issues/issues?q=is%3Aopen+is%3Aissue+label%3A%22C%3A+doc%22
[2019-qubes-gsod]: https://developers.google.com/season-of-docs/docs/2019/participants/project-qubes
[2019-qubes-report]: https://refre.ch/report-qubesos/
[existing installation guide]: https://www.youtube.com/watch?v=mATI8Lht0Js
[virtual box issue]: https://www.virtualbox.org/ticket/16771

5
developer/general/package-contributions.md
View File

@ -29,7 +29,7 @@ Before you start putting serious work into a package, we recommend that you disc
Once you have a package that's ready to become part of Qubes OS, please follow this procedure:
1. Ensure that your package satisfies the [Inclusion Criteria].
2. If your code isn't already on GitHub, create a GitHub repo that contains your code.
2. If your code isn't already on GitHub, create a GitHub repo that contains your code. You can have a look to an example package called [qubes-skeleton].
3. If you haven't already, [sign your code][sig].
4. Create an issue in [qubes-issues] with the title `[Contribution] your-package-name`.
Include a link to your repo, a brief description of your package, and a brief explanation of why you think it should be included in Qubes.
@ -80,7 +80,7 @@ In all the cases, the first condition to be validated by the QCR's review is to
- Makefiles,
- Package build [reproducible]
and any steps which would result in partial/total compromise of legitimate components.
and any steps which would result in partial/total compromise of legitimate components. For this part, you can have a look to an example package called [qubes-skeleton].
Package Maintainers
-------------------
@ -107,3 +107,4 @@ If you do not act on your maintainer duties for a given package for an extended
[QubesOS-contrib]: https://github.com/QubesOS-contrib
[qubes-issues]: https://github.com/QubesOS/qubes-issues/issues/
[reproducible]: https://reproducible-builds.org/
[qubes-skeleton]: https://github.com/QubesOS-contrib/qubes-skeleton

33
developer/services/admin-api.md
View File

@ -132,6 +132,7 @@ to set the policy using current mechanism.
| `admin.vm.volume.Resize` | vm | volume | size_in_bytes | - | id. |
| `admin.vm.volume.Import` | vm | volume | raw volume data | - | id. |
| `admin.vm.volume.ImportWithSize` | vm | volume | `<size_in_bytes>\n<raw volume data>` | - | new version of `admin.vm.volume.Import`, allows new volume to be different size |
| `admin.vm.volume.Clear` | vm | volume | - | - | clear contents of volume |
| `admin.vm.volume.CloneFrom` | vm | volume | - | token, to be used in `admin.vm.volume.CloneTo` | obtain a token to copy `volume` of `vm`;<br/>the token is one time use only, it's invalidated by `admin.vm.volume.CloneTo`, even if the operation fails |
| `admin.vm.volume.CloneTo` | vm | volume | token, obtained with `admin.vm.volume.CloneFrom` | - | copy volume pointed by a token to `volume` of `vm` |
| `admin.vm.Start` | vm | - | - | - |
@ -305,9 +306,39 @@ destination_path: ncftpput -u my-ftp-username -p my-ftp-pass -c my-ftp-server /d
- closing qrexec connection normally does _not_ interrupt running operation; this is important to avoid leaving the system in inconsistent state
- actual operation starts only after caller send all the parameters (including a payload), signaled by sending EOF mark; there is no support for interactive protocols, to keep the protocol reasonable simple
## Policy admin API
There is also an API to view and update [Qubes RPC policy files](/doc/qrexec) in dom0. All of the following calls have dom0 as destination:
| call | argument | inside | return |
| ---------------------------------------------- | ---- | -------------------- | ----------------------- |
| `policy.List` <br> `policy.include.List` | - | - | `<name1>\n<name2>\n...` |
| `policy.Get` <br> `policy.include.Get` | name | - | `<token>\n<content>` |
| `policy.Replace` <br> `policy.include.Replace` | name | `<token>\n<content>` | - |
| `policy.Remove` <br> `policy.include.Remove` | name | `<token>` | - |
The `policy.*` calls refer to main policy files (`/etc/qubes/policy.d/`), and
the `policy.include.*` calls refer to the include directory
(`/etc/qubes/policy.d/include/`). The `.policy` extension for files in the main
directory is always omitted.
The responses do not follow admin API protocol, but signal error using an exit
code and a message on stdout.
The changes are validated before saving, so that the policy cannot end up in an
invalid state (e.g. syntax error, missing include file).
In addition, there is a mechanism to prevent concurrent modifications of the policy files:
- A `*.Get` call returns a file along with a *token* (currently implemented as
a hash of the file).
- When calling `Replace` or `Remove`, you need to include the current token as
first line. If the token does not match, the modification will fail.
- When adding a new file using `Replace`, pass `new` as token. This will ensure
that the file does not exist before adding.
- To skip the check, pass `any` as token.
## TODO
- something to configure/update policy
- notifications
- how to constrain the events?
- how to pass the parameters? maybe XML, since this is trusted anyway and

5
developer/services/qmemman.md
View File

@ -75,3 +75,8 @@ Whenever *qmemman* is asked to return X megabytes of memory to Xen free pool, th
4. wait BALOON\_DELAY (0.1s)
5. if some domain have not given back any memory, remove it from the donors list, and go to step 2, unless we already did MAX\_TRIES (20) iterations (then return error).
Notes
-----
Conventional means of viewing the memory available to Qubes will give incorrect values for `dom0` since commands such as `free` will only show the memory allocated for `dom0`. Run the `xl info` command in `dom0` and read the `total_memory` field to see the total memory available to Qubes.

48
developer/system/architecture.md
View File

@ -14,11 +14,10 @@ Qubes Architecture Overview
Qubes implements a Security by Isolation approach. To do this, Qubes utilizes virtualization technology in order to isolate various programs from each other and even to sandbox many system-level components, such as networking and storage subsystems, so that the compromise of any of these programs or components does not affect the integrity of the rest of the system.
[![qubes-schema-v2.png](/attachment/wiki/QubesArchitecture/qubes-schema-v2.png)](/attachment/wiki/QubesArchitecture/qubes-schema-v2.png)
Qubes lets the user define many security domains, which are implemented as lightweight Virtual Machines (VMs), or “AppVMs.” For example, the user can have “personal,” “work,” “shopping,” “bank,” and “random” AppVMs and can use the applications within those VMs just as if they were executing on the local machine. At the same time, however, these applications are well isolated from each other. Qubes also supports secure copy-and-paste and file sharing between the AppVMs, of course.
[![qubes-arch-diagram-1.png](/attachment/wiki/QubesArchitecture/qubes-arch-diagram-1.png)](/attachment/wiki/QubesArchitecture/qubes-arch-diagram-1.png)
(Note: In the diagram above, "Storage domain" is actually a USB domain.)
Key Architecture features
-------------------------
@ -33,4 +32,45 @@ Key Architecture features
- Qubes GUI provides isolation between apps sharing the same desktop
- Secure system boot based (optional)
[Architecture Spec v0.3 [PDF]](/attachment/wiki/QubesArchitecture/arch-spec-0.3.pdf) (The original 2009 document that started this all...)
(For those interested in the history of the project, [Architecture Spec v0.3 [PDF]](/attachment/wiki/QubesArchitecture/arch-spec-0.3.pdf) is the original 2009 document that started this all.
Please note that this document is for historical interest only.
For the latest information, please see the rest of the [System Documentation](/doc/#system).)
Qubes Core Stack
----------------
Qubes Core Stack is, as the name implies, the core component of Qubes OS. It's
the glue that connects all the other components together, and which allows users
and admins to interact with and configure the system. The other components of
the Qubes system include:
- VM-located core agents (implementing e.g. qrexec endpoints used by various
Qubes services)
- VM-customizations (making the VMs lightweight and working well with seamless
GUI virtualization)
- Qubes GUI virtualization (the protocol, VM-located agents, and daemons
located in the GUI domain which, for now, happens to be the same as dom0),
- GUI domain customizations (Desktop Environment customizations, decoration
coloring plugin, etc)
- The AdminVM distribution (various customizations, special services, such as
for receiving and verifying updates, in the future: custom distro)
- The Xen hypervisor (with a bunch of customization patches, occasional
hardening) or - in the future - some other virtualising or containerizing
software or technology
- Multiple "Qubes Apps" (various services built on top of Qubes qrexec
infrastructure, such as: trusted PDF and Image converters, Split GPG, safe
USB proxies for HID devices, USB proxy for offering USB devices (exposed via
qvm-usb), Yubikey support, USB Armory support, etc)
- Various ready-to-use templates (e.g. Debian-, Whonix-based), which are used
to create actual VMs, i.e. provide the root filesystem to the VMs
- Salt Stack integration
And all these components are "glued together" by the Qubes Core Stack.
[![Qubes system components](/attachment/wiki/QubesArchitecture/qubes-components.png)](/attachment/wiki/QubesArchitecture/qubes-components.png)
This diagram illustrates the location of all these components in the overall
system architecture. Unlike the other Qubes architecture diagram above, this one
takes an AppVM-centric approach.

44
doc.md
View File

@ -1,5 +1,5 @@
---
layout: doc-index
layout: doc
title: Documentation
permalink: /doc/
redirect_from:
@ -13,33 +13,10 @@ redirect_from:
- /en/community/
- /community/
---
## Table of Contents
1. [Introduction](#introduction)
2. [Project Security](#project-security)
3. [User Documentation](#user-documentation)
3.1. [Choosing Your Hardware](#choosing-your-hardware)
3.2. [Downloading, Installing, and Upgrading Qubes](#downloading-installing-and-upgrading-qubes)
3.3. [Common Tasks](#common-tasks)
3.4. [Managing Operating Systems within Qubes](#managing-operating-systems-within-qubes)
3.5. [Security in Qubes](#security-in-qubes)
3.6. [Advanced Configuration](#advanced-configuration)
3.7. [Reference Pages](#reference-pages)
4. [Developer Documentation](#developer-documentation)
4.1. [General](#general)
4.2. [Code](#code)
4.3. [System](#system)
4.4. [Services](#services)
4.5. [Debugging](#debugging)
4.6. [Building](#building)
4.7. [Releases](#releases)
5. [External Documentation](#external-documentation)
5.1. [Operating System Guides](#operating-system-guides)
5.2. [Security Guides](#security-guides)
5.3. [Privacy Guides](#privacy-guides)
5.4. [Configuration Guides](#configuration-guides)
5.5. [Customization Guides](#customization-guides)
5.6. [Troubleshooting](#troubleshooting)
5.7. [Building Guides](#building-guides)
# Qubes OS Documentation
Welcome to the Qubes OS documentation!
## Introduction
@ -48,7 +25,7 @@ redirect_from:
* [Screenshots](/screenshots/)
* [User FAQ](/faq/#users)
* [Reporting Bugs and Other Issues](/doc/reporting-bugs/)
* [Help, Support, and Mailing Lists](/support/)
* [Help, Support, Mailing Lists, and Forum](/support/)
* [How to Contribute](/doc/contributing/)
## Project Security
@ -135,7 +112,6 @@ Core documentation for Qubes users.
* [Making Any File Persistent Using `bind-dirs`](/doc/bind-dirs/)
* [GUI Configuration](/doc/gui-configuration/)
* [Resizing Disk Images](/doc/resize-disk-image/)
* [Troubleshooting UEFI](/doc/uefi-troubleshooting/)
* [Troubleshooting Newer Hardware](/doc/newer-hardware-troubleshooting/)
* [Mounting and Decrypting Qubes Partitions from Outside Qubes](/doc/mount-from-other-os/)
* [KDE](/doc/kde/)
@ -144,6 +120,9 @@ Core documentation for Qubes users.
### Troubleshooting
* [Installation Troubleshooting](/doc/installation-troubleshooting)
* [UEFI Troubleshooting](/doc/uefi-troubleshooting/)
* [Suspend/Resume Troubleshooting](/doc/suspend-resume-troubleshooting/)
* [VM Troubleshooting](/doc/vm-troubleshooting/)
### Reference Pages
@ -181,7 +160,6 @@ Core documentation for Qubes developers and advanced users.
### System
* [Qubes OS Architecture Overview](/doc/architecture/)
* [Qubes OS Architecture Spec v0.3 [PDF]](/attachment/wiki/QubesArchitecture/arch-spec-0.3.pdf)
* [Security-critical Code in Qubes OS](/doc/security-critical-code/)
* [Qubes Core Admin](https://dev.qubes-os.org/projects/core-admin/en/latest/)
* [Qubes Core Admin Client](https://dev.qubes-os.org/projects/core-admin-client/en/latest/)
@ -230,8 +208,7 @@ Core documentation for Qubes developers and advanced users.
## External Documentation
Unofficial, third-party documentation from the Qubes community and others.
* [Qubes Community Documentation](https://github.com/Qubes-Community/Contents/tree/master/docs)
For more, please see [Qubes Community Documentation](https://github.com/Qubes-Community/Contents/tree/master/docs).
### Operating System Guides
@ -298,7 +275,6 @@ Unofficial, third-party documentation from the Qubes community and others.
* [Lenovo ThinkPad Troubleshooting](/doc/thinkpad-troubleshooting/)
* [Apple MacBook Troubleshooting](/doc/macbook-troubleshooting/)
* [Getting Sony Vaio Z laptop to work with Qubes](/doc/sony-vaio-tinkering/)
* [Fixing wireless on suspend & resume](/doc/wireless-troubleshooting/)
* [Intel Integrated Graphics Troubleshooting](/doc/intel-igfx-troubleshooting/)
### Building Guides

2
external/building-guides/building-archlinux-template.md vendored
View File

@ -163,6 +163,7 @@ $ make linux-utils-vm
$ make core-agent-linux-vm
$ make gui-common-vm
$ make gui-agent-linux-vm
$ make app-linux-split-gpg-vm
$ make vmm-xen-vm
$ make core-vchan-xen-vm
$ make core-qubesdb-vm
@ -170,6 +171,7 @@ $ make linux-utils-vm
$ make core-agent-linux-vm
$ make gui-common-vm
$ make gui-agent-linux-vm
$ make app-linux-split-gpg-vm
```
8: Make the actual Archlinux template

14
external/configuration-guides/fetchmail.md vendored
View File

@ -90,4 +90,18 @@ for rc in /usr/local/etc/fetchmail/*.rc; do
done
~~~
Make sure the folder '/rw/config/qubes-bind-dirs.d' exists.
~~~
sudo mkdir -p /rw/config/qubes-bind-dirs.d
~~~
Create the file '/rw/config/qubes-bind-dirs.d/50_user.conf' with root rights.
Now edit it to append the '/var/spool/mail/' directory to the binds variable.
~~~
binds+=( '/var/spool/mail' )
~~~
Now reboot your AppVM and you are done.

10
external/configuration-guides/mutt.md vendored
View File

@ -206,21 +206,21 @@ In `.mailcap`:
### also would be convenient to use mailcap's TEST feature to
### show some html in mutt pager (e.g. with w3m, links or html2text),
### else open others in dispvm
# MS Word documents
application/msword; qvm-open-in-dvm %s
application/vnd.oasis.opendocument.spreadsheet; qvm-open-in-dvm %s
application/vnd.oasis.opendocument.text; qvm-open-in-dvm %s
# Images
image/jpg; qvm-open-in-dvm %s
image/jpeg; qvm-open-in-dvm %s
image/png; qvm-open-in-dvm %s
image/gif; qvm-open-in-dvm %s
# PDFs
application/pdf; qvm-open-in-dvm %s
# HTML
text/html; w3m -T text/html '%s' | cat --squeeze-blank; nametemplate=%s.html; copiousoutput
text/html; qvm-open-in-dvm %s

6
external/configuration-guides/vpn.md vendored
View File

@ -12,6 +12,12 @@ redirect_from:
How To make a VPN Gateway in Qubes
==================================
<div class="alert alert-info" role="alert">
<i class="fa fa-info-circle"></i>
<b>Note:</b> If you seek to enhance your privacy, you may also wish to consider <a href="/doc/whonix/">Whonix</a>.
You should also be aware of <a href="https://www.whonix.org/wiki/Tunnels/Introduction">the potential risks of VPNs</a>.
</div>
Although setting up a VPN connection is not by itself Qubes specific, Qubes includes a number of tools that can make the client-side setup of your VPN more versatile and secure. This document is a Qubes-specific outline for choosing the type of VM to use, and shows how to prepare a ProxyVM for either NetworkManager or a set of fail-safe VPN scripts.
Please refer to your guest OS and VPN service documentation when considering the specific steps and parameters for your connection(s); The relevant documentation for the Qubes default guest OS (Fedora) is [Establishing a VPN Connection.](https://docs.fedoraproject.org/en-US/Fedora/23/html/Networking_Guide/sec-Establishing_a_VPN_Connection.html)

5
external/customization-guides/language-localization.md vendored
View File

@ -11,6 +11,11 @@ redirect_from:
Language Localization
=====================
Enable UTF-8 in dom0 title bars
-------------------------
You can enable UTF-8 characters in the title bar for all qubes or on a per-qube basis. Follow the instructions [here](https://www.qubes-os.org/doc/config-files/#gui-and-audio-configuration-in-dom0) for further information.
How to set up pinyin input in Qubes
-----------------------------------

12
external/os-guides/centos.md vendored
View File

@ -6,16 +6,14 @@ permalink: /doc/templates/centos/
# CentOS Template
If you would like to use a stable, predictable, manageable and reproducible distribution in your AppVMs, you can install the CentOS template, provided by Qubes in ready to use binary package.
For the minimal version, please see [Minimal TemplateVMs](/doc/templates/minimal/)
If you would like to use a stable, predictable, manageable and reproducible distribution in your AppVMs, you can install the CentOS template, provided by Qubes in ready to use binary package. For the minimal and Xfce versions, please see the [Minimal TemplateVMs] and [Xfce TemplateVMs] pages.
## Installation
CentOS-7 can be installed with the following command:
The standard CentOS TemplateVM can be installed with the following command in dom0, where `X` is the desired version number:
[user@dom0 ~]$ sudo qubes-dom0-update --enablerepo=qubes-templates-community qubes-template-centos-7
[user@dom0 ~]$ sudo qubes-dom0-update --enablerepo=qubes-templates-community qubes-template-centos-X
To switch, reinstall and uninstall a CentOS TemplateVM that is already installed in your system, see *How to [switch], [reinstall] and [uninstall]*.
@ -32,5 +30,5 @@ After a fresh install, we recommend to [Update the TemplateVM](/doc/software-upd
[switch]: /doc/templates/#switching
[reinstall]: /doc/reinstall-template/
[uninstall]: /doc/templates/#uninstalling
[Minimal TemplateVMs]: /doc/templates/minimal/
[Xfce TemplateVMs]: /doc/templates/xfce/

35
external/os-guides/gentoo.md vendored Normal file
View File

@ -0,0 +1,35 @@
---
layout: doc
title: Gentoo Template
permalink: /doc/templates/gentoo/
---
# Gentoo Template
If you would like to use a stable, predictable, manageable and reproducible distribution in your AppVMs, you can install the Gentoo template, provided by Qubes in ready to use binary package. For the minimal and Xfce versions, please see the [Minimal TemplateVMs] and [Xfce TemplateVMs] pages.
## Installation
The standard Gentoo TemplateVM can be installed with the following command in dom0:
[user@dom0 ~]$ sudo qubes-dom0-update --enablerepo=qubes-templates-community qubes-template-gentoo
To switch, reinstall and uninstall a Gentoo TemplateVM that is already installed in your system, see *How to [switch], [reinstall] and [uninstall]*.
#### After Installing
After a fresh install, we recommend to [Update the TemplateVM](/doc/software-update-vm/). We highlight that the template memory/CPU allocation certainly need to be adjusted in some cases. As Gentoo is a *linux source distribution*, the template needs resources to perform updates or installing any packages. By default, each TemplateVM has *2 VCPUs* for *4000 MB Max memory* allocated. If needed, double those values, *4 VCPUs* for *8000 MB Max memory*. For example, it has been observed failing updates or builds with *4 VCPUs* for *4000 MB Max memory* due to out of memory issue. For more general considerations, we refer to the official [Gentoo Handbook].
## Want to contribute?
* [How can I contribute to the Qubes Project?](/doc/contributing/)
* [Guidelines for Documentation Contributors](/doc/doc-guidelines/)
[switch]: /doc/templates/#switching
[reinstall]: /doc/reinstall-template/
[uninstall]: /doc/templates/#uninstalling
[Minimal TemplateVMs]: /doc/templates/minimal/
[Xfce TemplateVMs]: /doc/templates/xfce/
[Gentoo Handbook]: https://wiki.gentoo.org/wiki/Handbook:AMD64

117
external/os-guides/windows/windows-tools.md vendored
View File

@ -19,22 +19,34 @@ 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:
- Seamless GUI mode that integrates apps windows onto the common Qubes trusted desktop
- Support for [secure clipboard copy/paste](/doc/copy-paste/) between the Windows VM and other AppVMs
- Support for [secure file exchange](/doc/copying-files/) between the Windows VM and other AppVMs
- Support for qvm-run and generic qrexec for the Windows VM (e.g. ability to run custom service within/from the Windows VM)
- Xen PV drivers for Windows that increase performance compared to qemu emulated devices
- **Qubes Video Driver** - provides for the Seamless GUI mode that integrates apps windows onto the common Qubes trusted desktop
- **File sender/receiver** - Support for [secure clipboard copy/paste](/doc/copy-paste/) between the Windows VM and other AppVMs
- ***File sender/receiver** - Support for [secure file exchange](/doc/copying-files/) between the Windows VM and other AppVMs
- **Copy/Edit in Disposable VM** - Support for editing files in DisposableVMs as well as for qvm-run and generic qrexec for the Windows VM (e.g. ability to run custom service within/from the Windows VM)
- **Xen PV drivers** for Windows that increase performance compared to qemu emulated devices
Below is a breakdown of the feature availability depending on the windows version:
| Feature | Windows 7 x64 | Windows 10 x64 |
| ------------------------------------ | :------------: | :------------: |
| Qubes Video Driver | + | - |
| Qubes Network Setup | + | + |
| Private Volume Setup (move profiles) | + | + |
| File sender/receiver | + | + |
| Clipboard Copy/Paste | + | + |
| Application shortcuts | + | + |
| Copy/Edit in Disposable VM | + | + |
| Block device | + | + |
| USB device | - | - |
| Audio | - | - |
Qubes Windows Tools are open source and are distributed under a GPL license.
NOTES:
- Qubes Windows Tools are currently unmaintained
- Currently only 64-bit versions of Windows 7 are supported by Qubes Windows Tools. Only emulated SVGA GPU is supported (although [there has been reports](https://groups.google.com/forum/#!topic/qubes-users/cmPRMOkxkdA) on working GPU passthrough).
- There is currently no audio support for Windows HVMs.
- There is currently no USB pass-through support for Windows HVMs.
- Currently only 64-bit versions of Windows 7 and Windows 10 are supported by Qubes Windows Tools. Only emulated SVGA GPU is supported (although [there has been reports](https://groups.google.com/forum/#!topic/qubes-users/cmPRMOkxkdA) on working GPU passthrough).
- __This page documents the process of installing Qubes Windows Tools on versions up to R3.2.__. Installation on Qubes R4.0 is possible but is a work in progress and there are limitations/bugs (see [issue #3585](https://github.com/QubesOS/qubes-issues/issues/3585)).
Installing Windows OS in a Qubes VM
-----------------------------------
@ -42,6 +54,51 @@ Please refer to [this page](/doc/windows-vm/) for instructions on how to install
NOTE: It is strongly suggested to enable autologon for any Windows HVMs that will have Qubes Tools installed. To do so, run `netplwiz` command from the `Win+R`/Start menu and uncheck the *Users must enter a user name and password to use this computer* option.
Installing Qubes guest tools in Windows 10 VMs
----------------------------------------------
This will allow you to install the Qubes Windows Tools on Windows 10 both as a StandaloneVM as well as a Template VM and a corresponding AppVM. But some features are not available:
> **Note:** seamless mode is currently not available for windows. Please check the top of this document for the full feature availability breakdown.
1. In the Windows 10 VM, download from the [XEN website](https://xenproject.org/downloads/windows-pv-drivers/windows-pv-drivers-9-series/windows-pv-drivers-9-0-0/) the installation kits for Xen bus (`xenbus`) and storage drivers (`xenvbd`) Version 9.0.0 (two files`xenvbd.tar`and `xenbus.tar`).
2. Use an archive extractor like [7-zip](https://www.7-zip.org/) to extract the contents of the `.tar` files.
3. Install `xenvbd` and `xenbus` by starting the file `dpinst.exe` from the `x64` directories of the extracted tar-files. If during installation, the Xen driver requests a reboot, select "No" and let the installation continue.
4. After installation, reboot.
5. Download the Qubes Windows Tools (`qubes-tools-4.0.1.3.exe`) from [the qubes FTP server](https://ftp.qubes-os.org/qubes-windows-tools/) and move it to `C:\`.
6. Check the integrity of the file `qubes-tools-4.0.1.3.exe`by comparing its hash checksum. This can be done using the Windows command `certutil` on the windows command prompt (`cmd.exe`) and specifying an appropriate hash algorithm like:
certutil --hashfile C:\qubes-tools-4.0.1.3.exe SHA256
And compare it the value to `148A2A993F0C746B48FA6C5C9A5D1B504E09A7CFBA3FB931A4DCF86FDA4EC9B1` (**it has to exactly match for security reasons**). If it matches, feel free to continue the installation. If not, repeat the download to make sure it was not corrupted due to a network problem. If keeps on not matching it might be an attacker attempting to do something nasty to your system -- Ask for support.
> **Note**: this is a workaround for installing the qubes windows tools on windows 10 since the standard way is broken.
7. Install Qubes Windows Tools 4.0.1.3 by starting `qubes-tools-4.0.1.3.exe`, not selecting the `Xen PV disk drivers` and the `Move user profiles` (which would probably lead to problems in Windows, anyhow). If during installation, the Xen driver requests a reboot, select "No" and let the installation continue - the system will be rebooted later.
8. Shut down Windows.
9. On a `dom0` terminal write: *(where `<VMname>` is the name of your Windows 10 VM)*
qvm-features <VMname> gui 1
10. Reboot Windows. If the VM starts, but does not show any window then shutdown Windows from the Qube manager and reboot Windows once more.
11. Now the system should be up, with QWT running correctly.
12. Lastly to enable file copy operations to a Windows 10 VM the `default_user` property should be set the `<username>` that you use to login to the Windows VM. This can be done via the following command on a `dom0` terminal: *(where `<VMname>` is the name of your Windows 10 VM)*
`qvm-prefs <VMname> default_user <username>`
> **Note:** If this property is not set or set to a wrong value, files copied to this VM are stored in the folder `C:\Windows\System32\config\systemprofile\Documents\QubesIncoming\<source_VM>`.
> If the target VM is an AppVM, this has the consequence that the files are stored in the corresponding TemplateVM and so are lost on AppVM shutdown.
Installing Qubes guest tools in Windows 7 VMs
---------------------------------------------
@ -91,9 +148,36 @@ NOTE: it is recommended to increase the default value of Windows VM's `qrexec_ti
qvm-prefs -s <vm-name> qrexec_timeout 300
~~~
Xen PV drivers and Qubes Windows Tools
--------------------------------------
Installing Xen's PV drivers in the VM will lower its resources usage when using network and/or I/O intensive applications, but *may* come at the price of system stability (although Xen's PV drivers on a Win7 VM are usually very stable). There are two ways of installing the drivers:
1. installing the drivers independently, from Xen's [official site](https://www.xenproject.org/developers/teams/windows-pv-drivers.html)
2. installing Qubes Windows Tools (QWT), which bundles Xen's PV drivers.
Notes about using Xen's VBD (storage) PV driver:
- **Windows 7:** installing the driver requires a fully updated VM or else you'll likely get a BSOD and a VM in a difficult to fix state. Updating Windows takes *hours* and for casual usage there isn't much of a performance between the disk PV driver and the default one; so there is likely no need to go through the lengthy Windows Update process if your VM doesn't have access to untrusted networks and if you don't use I/O intensive apps. If you plan to update your newly installed Windows VM it is recommended that you do so *before* installing Qubes Windows Tools (QWT). If QWT are installed, you should temporarily re-enable the standard VGA adapter in Windows and disable Qubes' (see the section above).
- the option to install the storage PV driver is disabled by default in Qubes Windows Tools
- in case you already had QWT installed without the storage PV driver and you then updated the VM, you may then install the driver from Xen's site (xenvbd.tar).
**Caution:** Installing the version 9.0.0 Xen drivers on Windows 7 (a system without QWT - QWT uninstalled) leads to an unbootable system. The drivers install without error, but after reboot, the system aborts the reboot saying `Missing driver xenbus.sys`.
- **Windows 10:** The version 9.0.0 Xen drivers have to be installed before installing Qubes Windows Tools. Installing them on a system with QWT installed is likely to produce a system which crashes or has the tools in a non-functional state. Even if the tools were installed and then removed before installing the Xen drivers, they probably will not work as expected.
With Qubes Windows Tools installed the early graphical console provided in debugging mode isn't needed anymore since Qubes' display driver will be used instead of the default VGA driver:
~~~
qvm-prefs -s win7new debug false
~~~
Using Windows AppVMs in seamless mode
-------------------------------------
> **Note:** This feature is only available for Windows 7
Once you start a Windows-based AppVM with Qubes Tools installed, you can easily start individual applications from the VM (note the `-a` switch used here, which will auto-start the VM if it is not running):
~~~
@ -133,7 +217,7 @@ Qubes allows HVM VMs to share a common root filesystem from a select Template VM
In order to create a HVM TemplateVM one can use the following command, suitably adapted:
~~~
qvm-create --class TemplateVM win7-x64-template --property virt_mode=HVM --property kernel='' -l green
qvm-create --class TemplateVM win-template --property virt_mode=HVM --property kernel='' -l green
~~~
... , set memory as appropriate, and install Windows OS (or other OS) into this template the same way as you would install it into a normal HVM -- please see instructions on [this page](/doc/hvm-create/).
@ -143,7 +227,7 @@ If you use this Template as it is, then any HVMs that use it will effectively be
If you want to retain the User directory between reboots, then it would make sense to store the `C:\Users` directory on the 2nd disk which is automatically exposed by Qubes to all HVMs.
This 2nd disk is backed by the `private.img` file in the AppVMs' and is not reset upon AppVMs reboot, so the user's directories and profiles would survive the AppVMs reboot, unlike the "root" filesystem which will be reverted to the "golden image" from the Template VM automatically.
To facilitate such separation of user profiles, Qubes Windows Tools provide an option to automatically move `C:\Users` directory to the 2nd disk backed by `private.img`.
It's a selectable feature of the installer, enabled by default.
It's a selectable feature of the installer, enabled by default, but working only for Windows 7.
If that feature is selected during installation, completion of the process requires two reboots:
- The private disk is initialized and formatted on the first reboot after tools installation. It can't be done **during** the installation because Xen mass storage drivers are not yet active.
@ -152,8 +236,13 @@ Reboot is required because the "mover utility" runs very early in the boot proce
This can take some time depending on the profiles' size and because the GUI agent is not yet active dom0/Qubes Manager may complain that the AppVM failed to boot.
That's a false alarm (you can increase AppVM's default boot timeout using `qvm-prefs`), the VM should appear "green" in Qubes Manager shortly after.
It also makes sense to disable Automatic Updates for all the template-based AppVMs -- of course this should be done in the Template VM, not in individual AppVMs, because the system-wide settings are stored in the root filesystem (which holds the system-wide registry hives).
Then, periodically check for updates in the Template VM and the changes will be carried over to any child AppVMs.
For Windows 10, the user directories have to be moved manually, because the automatic transfer during QWT installation is bound to crash due to undocumented new features of NTFS, and a system having the directory `users`on another disk than `C:` will break on Windows update. So the following steps should be taken:
- The Windows disk manager may be used to add the private volume as disk `D:`, and you may, using the documented Windows operations, move the user directories `C:\users\<username>\Documents` to this new disk, allowing depending AppVMs to have their own private volumes. Moving the hidden application directories `AppData`, however, is likely to invite trouble - the same trouble that occurs if, during QWT installation, the option `Move user profiles` is selected.
- Configuration data like those stored in directories like `AppData` still remain in the TemplateVM, such that their changes are lost each time the AppVM shuts down. In order to make permanent changes to these configuration data, they have to be changed in the TemplateVM, meaning that applications have to be started there, which violates and perhaps even endangers the security of the TemplateVM. Such changes should be done only if absolutely necessary and with great care. It is a good idea to test them first in a cloned TemplateVM before applying them in the production VM.
It also makes sense to disable Automatic Updates for all the template-based AppVMs -- of course this should be done in the Template VM, not in individual AppVMs, because the system-wide settings are stored in the root filesystem (which holds the system-wide registry hives). Then, periodically check for updates in the Template VM and the changes will be carried over to any child AppVMs.
Once the template has been created and installed it is easy to create AppVMs based on it:
@ -251,7 +340,7 @@ If a specific component is malfunctioning, you can increase its log verbosity as
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:
When we publish new QWT version, 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`

61
external/os-guides/windows/windows-vm.md vendored
View File

@ -111,7 +111,7 @@ qvm-prefs win7new qrexec_timeout 300
qvm-prefs win7new debug false
~~~
To install Qubes Windows Tools, follow instructions [below](#xen-pv-drivers-and-qubes-windows-tools).
To install Qubes Windows Tools, follow instructions in [Qubes Windows Tools](/doc/windows-tools/).
### Detailed instructions ###
@ -119,6 +119,7 @@ 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. Note that there are [known issues](https://github.com/QubesOS/qubes-issues/issues/3585) with QWT on Qubes 4.x
- For Windows 10 under Qubes 4.0, a way to install QWT 4.0.1.3, which has worked in several instances, is described in [Qubes Windows Tools](/doc/windows-tools/).
Create a VM named win7new in [HVM](/doc/hvm/) mode (Xen's current PVH limitations precludes from using PVH):
@ -208,9 +209,39 @@ Finally, increase the VM's `qrexec_timeout`: in case you happen to get a BSOD or
qvm-prefs 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.
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](/doc/windows-tools/#xen-pv-drivers-and-qubes-windows-tools)). It is a good time to clone the VM again.
Windows as TemplateVM
---------------------
Windows 7 and 10 can be installed as TemplateVM by selecting
~~~
qvm-create --class TemplateVM --property virt_mode=HVM --property kernel='' --label black Windows-template
~~~
when creating the VM. To have the user data stored in AppVMs depending on this template, Windows 7 and 10 have to be treated differently:
- For Windows 7, the option to move the user directories from drive `C` to drive `D` works and causes any user data to be stored in the AppVMs based on this template, and not in the template itself.
- After installation of Windows 10 as a TemplateVM, the Windows disk manager may be used to add the private volume as disk `D:`, and you may, using the documented Windows operations, move the user directories `C:\users\<username>\Documents` to this new disk, allowing depending AppVMs to have their own private volumes. Moving the hidden application directories `AppData`, however, is likely to invite trouble - the same trouble that occurs if, during QWT installation, the option `Move user profiles` is selected.
For Windows 10, configuration data like those stored in directories like `AppData` still remain in the TemplateVM, such that their changes are lost each time the AppVM shuts down. In order to make permanent changes to these configuration data, they have to be changed in the TemplateVM, meaning that applications have to be started there, which violates and perhaps even endangers the security of the TemplateVM. Such changes should be done only if absolutely necessary and with great care. It is a good idea to test them first in a cloned TemplateVM before applying them in the production VM.
AppVMs based on these templates can be created the normal way by using the Qube Manager or by specifying
~~~
qvm-create --class=AppVM --template=<VMname>
~~~
On starting the AppVM, sometimes a message is displayed that the Xen PV Network Class needs to restart the system. This message can be safely ignored and closed by selecting "No".
**Caution:** These AppVMs must not be started while the corresponding TemplateVM is running, because they share the TemplateVM's license data. Even if this could work sometimes, it would be a violation of the license terms.
### Windows 10 Usage According to GDPR
If Windows 10 is used in the EU to process personal data, according to GDPR no automatic data transfer to countries outside the EU is allowed without explicit consent of the person(s) concerned, or other legal consent, as applicable. Since no reliable way is found to completely control the sending of telemetry from Windows 10, the system containing personal data must be completely shielded from the internet.
This can be achieved by installing Windows 10 on a TemplateVM with the user data directory moved to a separate drive (usually `D:`). Personal data must not be stored within the TemplateVM, but only in AppVMs depending on this TemplateVM. Network access by these AppVMs must be restricted to the local network and perhaps additional selected servers within the EU. Any data exchange of the AppVMs must be restricted to file and clipboard operations to and from other VMs in the same Qubes system.
Windows update
--------------
@ -220,32 +251,6 @@ Note: if you already have Qubes Windows Tools installed the video adapter in Win
To avoid guessing the VM's state enable debugging (`qvm-prefs -s win7new debug true`) and in Windows' device manager (My computer -> Manage / Device manager / Display adapters) temporarily re-enable the standard VGA adapter and disable "Qubes video driver". You can disable debugging and revert to Qubes' display once the VM is updated.
Xen PV drivers and Qubes Windows Tools
------------------------------------
Installing Xen's PV drivers in the VM will lower its resources usage when using network and/or I/O intensive applications, but *may* come at the price of system stability (although Xen's PV drivers on a Win7 VM are usually very stable). There are two ways of installing the drivers:
1. installing the drivers independently, from Xen's [official site](https://www.xenproject.org/developers/teams/windows-pv-drivers.html)
2. installing Qubes Windows Tools (QWT), which bundles Xen's PV drivers.
Notes about using Xen's VBD (storage) PV driver:
- Windows 7: installing the driver requires a fully updated VM or else you'll likely get a BSOD and a VM in a difficult to fix state. Updating Windows takes *hours* and for casual usage there isn't much of a performance between the disk PV driver and the default one; so there is likely no need to go through the lengthy Windows Update process if your VM doesn't have access to untrusted networks and if you don't use I/O intensive apps. If you plan to update your newly installed Windows VM it is recommended that you do so *before* installing Qubes Windows Tools (QWT). If QWT are installed, you should temporarily re-enable the standard VGA adapter in Windows and disable Qubes' (see the section above).
- the option to install the storage PV driver is disabled by default in Qubes Windows Tools
- in case you already had QWT installed without the storage PV driver and you then updated the VM, you may then install the driver from Xen's site (xenvbd.tar).
Installing Qubes Windows Tools:
- on R3.2: see [this page](/doc/windows-tools/)
- R4.0: you'll have to install QWT for Qubes R3.2. Be warned that QWT on R4.0 is a work in progress though (see [issue #3585](https://github.com/QubesOS/qubes-issues/issues/3585) for instructions and known issues).
With Qubes Windows Tools installed the early graphical console provided in debugging mode isn't needed anymore since Qubes' display driver will be used instead of the default VGA driver:
~~~
qvm-prefs -s win7new debug false
~~~
Further customization
---------------------

12
external/privacy-guides/signal.md vendored
View File

@ -30,27 +30,27 @@ How to install Signal in Qubes
This website cannot guarantee that any PGP key you download from the Internet is authentic.
Always obtain a trusted key fingerprint via other channels, and always check any key you download against your trusted copy of the fingerprint.
1. (Optional)Create a TemplateVM (Debian 9)
1. (Optional)Create a TemplateVM (Debian, 9 is used as an example but feel free to use any more updated by changing the 9 to a 10, etc.)
[user@dom0 ~]$ sudo qubes-dom0-update qubes-template-debian-9
2. Open a terminal in Debian 9
2. Open a terminal in Debian 9 (Or your previously chosen template)
[user@dom0 ~]$ qvm-run -a debian-9 gnome-terminal
3. Use these commands in your terminal
3. Use these commands in your terminal (If you chose a different distribution, such as buster, substitute that for xenial in the 3rd command)
(Optional)[user@debian-8 ~]$ sudo apt-get install curl
[user@debian-8 ~]$ curl -s https://updates.signal.org/desktop/apt/keys.asc | sudo apt-key add -
[user@debian-8 ~]$ curl -s -x 127.0.0.1:8082 https://updates.signal.org/desktop/apt/keys.asc | sudo apt-key add -
[user@debian-8 ~]$ echo "deb [arch=amd64] https://updates.signal.org/desktop/apt xenial main" | sudo tee -a /etc/apt/sources.list.d/signal-xenial.list
[user@debian-8 ~]$ sudo apt update && sudo apt install signal-desktop
5. Shutdown the TemplateVM :
5. Shutdown the TemplateVM (substitute your template name if needed) :
[user@dom0 ~]$ qvm-shutdown debian-9
6. Create an AppVM based on this TemplateVM
7. With your mouse select the `Q` menu -> `Domain: "AppVM Name"` -> `"AppVM Name": Add more shortcuts`
7. With your mouse select the `Q` menu -> `Domain: "AppVM Name"` -> 'AppVM name: Qube Settings' -> OK -> 'Applications'
(or `"AppVM Name": VM Settings` -> `Applications`).
Select `Signal` from the left `Available` column, move it to the right `Selected` column by clicking the `>` button and then `OK` to apply the changes and close the window.

2
external/security-guides/security-guidelines.md vendored
View File

@ -141,7 +141,7 @@ See [here](/doc/usb/).
Dom0 Precautions
----------------
As explained [here](/getting-started/#appvms-qubes-and-templatevms), dom0 should not be used for any user operations. There are several reasons for this:
As explained [here](/getting-started/), dom0 should not be used for any user operations. There are several reasons for this:
1. Secure isolation among domUs (i.e., AppVMs, StandaloneVMs, HVMs, etc.) is the *raison d'être* of Qubes. This is the primary reason that we recommend the delegation of all user activities to some number of AppVMs. In the event that any given VM is compromised, only that particular VM is compromised. (TemplateVMs are the exception to this. If a TemplateVM were compromised, then every AppVM based on it might also be compromised. Even in this case, however, the entire system would not necessarily have been compromised, since StandaloneVM(s), HVM(s), and/or multiple TemplateVMs might be in use.) By contrast, if dom0 were ever compromised, the entire system would thereby be compromised.
2. Due to the absence of convenience mechanisms in dom0 such as the inter-VM clipboard and inter-VM file copying, it is significantly less convenient to attempt to use dom0 for user operations (e.g., password management) in conjunction with AppVMs than it is to use another dedicated AppVM (e.g., a "vault" VM).

4
introduction/code-of-conduct.md
View File

@ -35,7 +35,7 @@ Examples of unacceptable behavior by participants include:
- Publishing others' private information, such as a physical or electronic address, without explicit permission
- Other conduct which could reasonably be considered inappropriate in a professional setting
(Please also see our [mailing list discussion guidelines].)
(Please also see our [discussion guidelines].)
## Our Responsibilities
@ -65,7 +65,7 @@ The initial published version of this Code of Conduct was adapted from the [Cont
[history of changes]: https://github.com/QubesOS/qubes-doc/commits/master/about/code-of-conduct.md
[discussion]: https://github.com/QubesOS/qubes-issues/issues/2163
[Citizen Code of Conduct]: http://citizencodeofconduct.org/
[mailing list discussion guidelines]: /support/#discussion-list-guidelines
[discussion guidelines]: /support/#discussion-guidelines
[Contributor Covenant, version 1.4]: http://contributor-covenant.org/version/1/4
[Rust Code of Conduct]: https://www.rust-lang.org/en-US/conduct.html
[Marek Marczykowski-Górecki]: https://www.qubes-os.org/team/#marek-marczykowski-g%C3%B3recki

56
introduction/faq.md
View File

@ -61,12 +61,40 @@ In this way, Qubes allows you to do everything on the same physical computer wit
Moreover, all of these isolated qubes are integrated into a single, usable system.
Programs are isolated in their own separate qubes, but all windows are displayed in a single, unified desktop environment with unforgeable colored window borders so that you can easily identify windows from different security levels.
Common attack vectors like network cards and USB controllers are isolated in their own hardware qubes while their functionality is preserved through secure [networking][network] , [firewalls], and [USB device management][USB].
Common attack vectors like network cards and USB controllers are isolated in their own hardware qubes while their functionality is preserved through secure [networking][network], [firewalls], and [USB device management][USB].
Integrated [file] and [clipboard] copy and paste operations make it easy to work across various qubes without compromising security.
The innovative [Template] system separates software installation from software use, allowing qubes to share a root filesystem without sacrificing security (and saving disk space, to boot).
Qubes even allows you to sanitize PDFs and images in a few clicks.
Users concerned about privacy will appreciate the [integration of Whonix][Qubes-Whonix] with Qubes, which makes it easy to use [Tor] securely, while those concerned about physical hardware attacks will benefit from [Anti Evil Maid].
Those concerned about physical hardware attacks will benefit from [Anti Evil Maid].
### How does Qubes OS provide privacy?
There can be no privacy without security, since security vulnerabilities allow privacy measures to be circumvented.
This makes Qubes exceptionally well-suited for implementing effective privacy tools.
Users concerned about privacy will appreciate the integration of [Whonix][Qubes-Whonix] into Qubes, which makes it easy to use [Tor] securely.
For more information about how to use this powerful tool correctly and safely, please see [Whonix][Qubes-Whonix].
### What about privacy in non-Whonix qubes?
Qubes OS does not claim to provide special privacy (as opposed to security) properties in non-[Whonix][Qubes-Whonix] qubes.
This includes [DisposableVMs][disposable].
For example, a standard [Fedora](/doc/templates/fedora/) qube is expected to have basically the same privacy properties as that upstream Fedora distribution, enhanced to some degree by the control Qubes provides over that qube.
For most users, this level of privacy may be good enough for many common activities.
However, users seeking more advanced privacy features should use [Whonix][Qubes-Whonix] qubes.
Privacy is far more difficult than is commonly understood.
In addition to the [web browser](https://www.torproject.org/projects/torbrowser/design/), there is also [VM fingerprinting](https://www.whonix.org/wiki/VM_Fingerprinting) and [advanced deanonymization attacks](https://www.whonix.org/wiki/Advanced_Deanonymization_Attacks) that most users have never considered (and this is just to mention a few examples).
The [Whonix Project](https://www.whonix.org/) specializes in [protecting against these risks](https://www.whonix.org/wiki/Protocol-Leak-Protection_and_Fingerprinting-Protection).
In order to achieve the same results in non-Whonix qubes (including DisposableVMs), one would have to reinvent Whonix.
Such duplication of effort makes no sense when Whonix already exists and is already integrated into Qubes OS.
Therefore, when you need privacy, you should use Whonix qubes.
Remember, though, that privacy is difficult to achieve and maintain.
Whonix is a powerful tool, but no tool is perfect.
Read the [documentation](https://www.whonix.org/wiki/Documentation) thoroughly and exercise care when using it.
### How does Qubes OS compare to using a "live CD" OS?
@ -250,7 +278,7 @@ This website is hosted on [GitHub Pages][] ([why?][]).
Therefore, it is largely outside of our control.
We don't consider this a problem, however, since we explicitly [distrust the infrastructure].
For this reason, we don't think that anyone should place undue trust in the live version of this site on the Web.
Instead, if you want to obtain your own, trustworthy copy of this website in a secure way, you should clone our [website repo], [verify the PGP signatures on the commits and/or tags] signed by the [doc-signing keys], then either [render the site on your local machine][render] or simply read the source, the vast majority of which was [intentionally written in Markdown so as to be readable as plain text for this very reason][Markdown].
Instead, if you want to obtain your own trustworthy copy of this website in a secure way, you should clone our [website repo], [verify the PGP signatures on the commits and/or tags] signed by the [doc-signing keys], then either [render the site on your local machine][render] or simply read the source, the vast majority of which was [intentionally written in Markdown so as to be readable as plain text for this very reason][Markdown].
We've gone to special effort to set all of this up so that no one has to trust the infrastructure and so that the contents of this website are maximally available and accessible.
### What does it mean to "distrust the infrastructure"?
@ -279,12 +307,13 @@ Also see: [Should I trust this website?]
### Why doesn't this website have security feature X?
Although we caution users against [placing undue trust in this website][Should I trust this website?] because we [distrust the infrastructure], we have no objection to enabling website security features when doing so is relatively costless and provides some marginal benefit to website visitors.
So, if feature X isn't enabled, it's most likely for one of three reasons
So, if feature X isn't enabled, it's most likely for one of three reasons:
1. Our GitHub Pages platform doesn't support it.
2. Our platform supports it, but we've decided not to enable it.
3. Our platform supports it, but we're not aware that we can enable it or have forgotten to do so.
(If it seems like this is the case, let us know!)
If it seems like a feature that we can and should enable, please [let us know][reporting-bugs]!
## Users
@ -616,6 +645,22 @@ From a `dom0` prompt, enter:
qvm-prefs <HVMname> kernel ""
### When I try to install a TemplateVM, it says no match is found.
For example:
```
[user@dom0 ~]$ sudo qubes-dom0-update --enablerepo=qubes-templates-itl qubes-template-debian-10
Using sys-whonix as UpdateVM to download updates for Dom0; this may take some time...
No Match for argument qubes-template-debian-10
Nothing to download
```
This normally means you already have the template installed.
It may be that you have the matching package installed, but you removed or renamed the template.
Check `rpm -q qubes-template-<name>`.
If it lists the package, but you don't really have the template present (`qvm-ls` doesn't list it), you need to clean up leftovers of the package with `rpm -e --noscripts qubes-template-<name>`, then install it normally.
### I keep getting "Failed to synchronize cache for repo" errors when trying to update my Fedora templates
This is general Fedora issue, not a Qubes-specific issue.
@ -796,3 +841,4 @@ There is also the unofficial [ansible-qubes toolkit][ansible].
[why?]: #why-do-you-use-github
[Xen]: https://www.xenproject.org/
[XSA Tracker]: /security/xsa/
[reporting-bugs]: /doc/reporting-bugs/

339
introduction/intro.html Normal file
View File

@ -0,0 +1,339 @@
---
layout: default
title: Introduction
permalink: /intro/
redirect_from:
- /tour/
- /en/tour/
- /tour/#what-is-qubes-os
- /about/
- /en/about/
---
<h2>What is Qubes OS?</h2>
<div class="row">
<div class="col-lg-12 col-md-12">
<p>
Qubes OS is a free and open-source, security-oriented operating system for
single-user desktop computing. Qubes OS leverages
<a href="https://wiki.xen.org/wiki/Xen_Project_Software_Overview">
Xen-based virtualization</a> to allow for the creation and management of
isolated compartments called <a href="/doc/glossary#qube">qubes</a>.
</p>
</div>
</div>
<div class="row">
<div class="col-lg-3 col-md-3 text-left">
<p>
These qubes, which are implemented as <a href="/doc/glossary#vm">virtual
machines (VMs)</a>, have specific:
<ul>
<li class="more-bottom">
<b>Purposes:</b> with a predefined set of one or many isolated
applications, for personal or professional projects, to manage the
<a href="/doc/networking/">network stack</a>,
<a href="/doc/firewall/">the firewall</a>, or to fulfill other
user-defined purposes.
</li>
<li class="more-bottom">
<b>Natures:</b> <a href="/doc/standalone-and-hvm/">full-fledged</a> or
<a href="/getting-started/">
stripped-down</a> virtual machines based on popular operating systems,
such as <a href="/doc/templates/fedora">Fedora</a>,
<a href="/doc/templates/debian">Debian</a>, and
<a href="/doc/windows/">Windows</a>.
</li>
<li class="more-bottom">
<b>Levels of trust:</b> from complete to non-existent. All windows are
displayed in a unified desktop environment with
<a href="/getting-started/">unforgeable colored window borders</a> so
that different security levels are easily identifiable.
</li>
</ul>
</p>
</div>
<div class="col-lg-9 col-md-9">
<a href="/attachment/site/qubes-trust-level-architecture.png">
<img src="/attachment/site/qubes-trust-level-architecture.png"
class="center-block more-bottom" alt="Qubes system diagram">
</a>
</div>
</div>
<div class="alert alert-info more-bottom" role="alert">
<i class="fa fa-info-circle"></i>
<b>Note:</b> See our <a href="/doc/glossary/">glossary</a> and
<a href="/faq/">FAQ</a> for more information.
</div>
<h2 class="more-bottom">Features</h2>
<div class="row">
<div class="col-lg-4 col-md-4 col-xs-12">
<h3>Strong isolation</h3>
<p>
Isolate different pieces of software as if they were installed on separate
physical machines using <a href="/doc/glossary/#pv">PV</a> or
<a href="/doc/glossary/#hvm">HVM</a> virtualization techniques.
</p>
</div>
<div class="col-lg-4 col-md-4 col-xs-12">
<h3>Template system</h3>
<p>
Use <a href="/getting-started/">AppVMs</a> to
share a root file system without sacrificing security using the innovative
<a href="/doc/templates/">Template system</a>.
</p>
</div>
<div class="col-lg-4 col-md-4 col-xs-12">
<h3>Multiple operating systems</h3>
<p>
Use multiple operating systems at the same time, including
<a href="/doc/templates/fedora">Fedora</a>,
<a href="/doc/templates/debian">Debian</a>, and
<a href="/doc/windows/">Windows.</a>
</p>
</div>
</div>
<hr>
<div class="row">
<div class="col-lg-4 col-md-4 col-xs-12">
<h3>DisposableVMs</h3>
<p>
Create <a href="/doc/disposablevm/">DisposableVMs</a> on the fly that
self-destruct when shut down.
</p>
</div>
<div class="col-lg-4 col-md-4 col-xs-12">
<h3>Whonix integration</h3>
<p>
Run <a href="https://www.torproject.org/">Tor</a> securely system-wide
using <a href="/doc/whonix/">Whonix with Qubes</a>.
</p>
</div>
<div class="col-lg-4 col-md-4 col-xs-12">
<h3>Device isolation</h3>
<p>
Secure <a href="/doc/device-handling/">device handling</a> through
isolation of network cards and USB controllers.
</p>
</div>
</div>
<hr>
<div class="row">
<div class="col-lg-4 col-md-4 col-xs-12">
<h3>Split GPG</h3>
<p>
Utilize <a href="/doc/split-gpg/">Split GPG</a> to keep your private keys
safe.
</p>
</div>
<div class="col-lg-4 col-md-4 col-xs-12">
<h3>U2F proxy</h3>
<p>
Operate <a href="/doc/u2f-proxy/">Qubes U2F proxy</a> to use your
two-factor authentication devices without exposing your web browser to the
full USB stack.
</p>
</div>
<div class="col-lg-4 col-md-4 col-xs-12">
<h3>Open-source</h3>
<p>
Users are free to use, copy, and modify Qubes OS and
<a href="/doc/contributing/">are encouraged to do so!</a>
</p>
</div>
</div>
<div class="alert alert-info more-bottom" role="alert">
<i class="fa fa-info-circle"></i>
<b>Note:</b> Given the technical nature of Qubes OS, prior experience with
Linux can be helpful.
</div>
<h2 class="more-bottom">Why Qubes OS?</h2>
<h3>Physical isolation is a given safeguard that the digital world lacks</h3>
<div class="row">
<div class="col-lg-6 col-md-6 text-left">
<p>
Throughout our lives, we engage in various activities, such as going to
school, working, voting, taking care of our families, and visiting with
friends. These activities are spatially and temporally bound: They happen
in isolation from one another, in their own compartments, which often
represent an essential safeguard, as in the case of voting.
</p>
<p>
In our digital lives, the situation is quite different: All of our
activities typically happen on a single device. This causes us to worry
about whether it's safe to click on a link or install an app, since being
hacked imperils our entire digital existence.
</p>
<p>
Qubes eliminates this concern by allowing us to divide a device into many
compartments, much as we divide a physical building into many rooms.
Better yet, it allows us to create new compartments whenever we need them,
and it gives us sophisticated tools for securely managing our activities
and data across these compartments.
</p>
</div>
<div class="col-lg-6 col-md-6">
<a href="/attachment/wiki/GettingStarted/r2b1-qubes-manager-2.png">
<img src="/attachment/wiki/GettingStarted/r2b1-qubes-manager-2.png"
class="center-block more-bottom" alt="Qube Manager">
</a>
</div>
</div>
<h3>Qubes allows you to compartmentalize your digital life</h3>
<div class="row">
<div class="col-lg-6 col-md-6">
<a href="/attachment/site/qubes-partition-data-flows.jpg">
<img src="/attachment/site/qubes-partition-data-flows.jpg"
class="center-block more-bottom" alt="Compartmentalization example">
</a>
</div>
<div class="col-lg-6 col-md-6 text-left center-block">
<p>
Many of us are initially surprised to learn that our devices do not
support the kind of secure compartmentalization that our lives demand, and
we're disappointed that software vendors rely on generic defenses that
repeatedly succumb to new attacks.
</p>
<p>
In building Qubes, our working assumption is that all software contains
bugs. Not only that, but in their stampeding rush to meet deadlines, the
world's stressed-out software developers are pumping out new code at a
staggering rate &mdash; far faster than the comparatively smaller
population of security experts could ever hope to analyze it for
vulnerabilities, much less fix everything. Rather than pretend that we can
prevent these inevitable vulnerabilities from being exploited, we've
designed Qubes under the assumption that they <em>will</em> be exploited.
It's only a matter of time until the next zero-day attack.
</p>
<p>
In light of this sobering reality, Qubes takes an eminently practical
approach: confine, control, and contain the damage. It allows you to keep
valuable data separate from risky activities, preventing
cross-contamination. This means you you can do everything on the same
physical computer without having to worry about a single successful
cyberattack taking down your entire digital life in one fell swoop. In
fact, Qubes has
<a href="https://invisiblethingslab.com/resources/2014/Software_compartmentalization_vs_physical_separation.pdf">
distinct advantages over physical air gaps</a>.
</p>
</div>
</div>
<h3>Made to support vulnerable users and power users alike</h3>
<div class="row">
<div class="col-lg-6 col-md-6 text-left">
<p>
Qubes provides practical, usable security to vulnerable and
actively-targeted individuals, such as journalists, activists,
whistleblowers, and researchers. Qubes is designed with the understanding
that people make mistakes, and it allows you to protect yourself from your
own mistakes. It's a place where you can click on links, open attachments,
plug in devices, and install software free from worry. It's a place where
<em>you</em> have control over your software, not the other way around.
</p>
<p>
Qubes is also powerful. Organizations like the
<a href="/partners/#freedom-of-the-press-foundation">Freedom of the Press
Foundation</a>, <a href="/partners/#mullvad">Mullvad</a>, and
<a href="https://twitter.com/letsencrypt/status/1239934557710737410">Let's
Encrypt</a> rely on Qubes as they build and maintain critical privacy and
security internet technologies that are in turn relied upon by countless
users around the world every day. Renowned security
<a href="/experts/">experts</a> like Edward Snowden, Daniel J. Bernstein,
Micah Lee, Christopher Soghoian, Isis Agora Lovecruft, Peter Todd, Bill
Budington, and Kenn White use and recommend Qubes.
</p>
<p>
Qubes is one of the few operating systems that places the security of
its users above all else. It is, and always will be, free and open-source
software, because the fundamental operating system that constitutes the
core infrastructure of our digital lives <em>must</em> be free and
open-source in order to be trustworthy.
</p>
</div>
<div class="col-lg-6 col-md-6">
<a href="/attachment/wiki/GettingStarted/snapshot12.png">
<img src="/attachment/wiki/GettingStarted/snapshot12.png"
class="center-block more-bottom" alt="Qubes desktop screenshot">
</a>
</div>
</div>
<hr class="add-top more-bottom">
<div class="row more-bottom">
<div class="col-lg-4 col-md-4 col-xs-12">
<h3>Video Tours</h3>
<p>
Want to see Qubes OS in action? Sit back and watch a guided tour!
</p>
<a href="/video-tours/" class="btn btn-primary more-bottom">
<i class="fa fa-play-circle"></i> Video Tours
</a>
</div>
<div class="col-lg-4 col-md-4 col-xs-12">
<h3>Screenshots</h3>
<p>
See what using Qubes actually looks like with these screenshots of various
applications running in Qubes.
</p>
<a href="/screenshots/" class="btn btn-primary more-bottom">
<i class="fa fa-picture-o"></i> Screenshots
</a>
</div>
<div class="col-lg-4 col-md-4 col-xs-12">
<h3>Getting Started</h3>
<p>
Ready to get started with Qubes? Here's what you need to know after
installing.
</p>
<a href="/getting-started/" class="btn btn-primary more-bottom">
<i class="fa fa-cubes"></i> Getting Started
</a>
</div>
</div>
<h2>More information</h2>
<p>
This page is just a brief introduction to what Qubes is all about, and many
technical details have been omitted here for the sake of presentation.
<ul>
<li>
If you're a current or potential Qubes user, you may want to check out the
<a href="/doc/">documentation</a> and the
<a href="/faq/#users">user FAQ</a>.
</li>
<li>
If you're a developer, there's dedicated
<a href="/doc/#developer-documentation">developer documentation</a> and a
<a href="/faq/#developers">developer FAQ</a> just for you.
</li>
<li>
Ready to give Qubes a try? Head on over to the
<a href="/downloads/">downloads</a> page, and read the
<a href="/doc/installation-guide">installation guide</a>.
</li>
<li>
Need help, or just want to join the conversation? Learn more about
<a href="/support/">help, support, the mailing lists, and the forum</a>.
</li>
</ul>
</p>

194
introduction/intro.md
View File

@ -1,194 +0,0 @@
---
layout: intro
title: An Introduction to Qubes OS
permalink: /intro/
redirect_from:
- /tour/
- /en/tour/
- /tour/#what-is-qubes-os
- /about/
- /en/about/
---
What is Qubes OS?
-----------------
<div class="row">
<div class="col-lg-3 col-md-3 text-left">
<p>Qubes OS is a free and open-source security-oriented operating system meant for single-user desktop computing.</p>
<p>Qubes OS leverages <a href="https://wiki.xen.org/wiki/Xen_Project_Software_Overview">xen-based virtualization</a> to allow for the creation and management of isolated virtual machines called <a href="/doc/glossary#qube">qubes</a>.
Qubes, which are also referred to as <a href="/doc/glossary#domain">domains</a> or compartments, have specific :</p>
<ul>
<li><b>Purposes</b> : with a predefined set of one or many isolated applications, for personal or professional projects, to manage the <a href="/doc/networking/">network stack</a>, <a href="/doc/firewall/">the firewall</a>, or to fulfill other user-defined purposes.</li>
<li><b>Natures</b> : <a href="/doc/standalone-and-hvm/">full-fledged</a> or <a href="/getting-started/#appvms-qubes-and-templatevms">stripped-down</a> virtual machines which are based on popular operating systems such as <a href="/doc/templates/fedora">Fedora</a>, <a href="/doc/templates/debian">Debian</a> or <a href="/doc/windows/">Windows</a>.</li>
<li><b>Levels of trust</b> : from complete to non-existent. All windows are displayed in a unified desktop environment with <a href="https://www.qubes-os.org/getting-started/">unforgeable colored window borders</a> so different security levels are easily identifiable.</li>
</ul>
</div>
<div class="col-lg-9 col-md-9">
<h3 class="text-center add-bottom">Qubes OS Overview Example</h3>
<img src="/attachment/site/qubesosdiagram.png" class="center-block">
</div>
</div>
<div class="alert alert-info" role="alert">
<i class="fa fa-question-circle"></i>
<b>Note : </b> Head over to the <a href="/doc/glossary/">glossary</a> or the <a href="/faq">FAQ</a> for more information.
</div>
<h2>Features</h2>
<div class="row more-bottom">
<div class="col-lg-4 col-md-4 col-xs-12">
<h3>Strong isolation</h3>
<p>Isolate software as if they were installed on separate physical machines using <a href="/doc/glossary/#pv">PV</a> or <a href="/doc/glossary/#hvm">HVM</a> virtualization techniques</p>
</div>
<div class="col-lg-4 col-md-4 col-xs-12">
<h3>Template system</h3>
<p> Allow qubes called <a href="/getting-started/#appvms-qubes-and-templatevms">AppVMs</a> to share a root file system without sacrificing security using the innovative <a href="/doc/templates/">Template system</a></p>
</div>
<div class="col-lg-4 col-md-4 col-xs-12">
<h3>Multiple operating systems</h3>
<p> Use multiple operating systems at the same time, including <a href="/doc/templates/fedora">Fedora</a>, <a href="/doc/templates/debian">Debian</a>, or <a href="/doc/windows/">Windows</a></p>
</div>
</div>
<hr class="add-top more-bottom">
<div class="row more-bottom">
<div class="col-lg-4 col-md-4 col-xs-12">
<h3>Disposable VMs</h3>
<p>Create <a href="/doc/disposablevm/">disposable VMs</a> which are spawned quickly and destroyed when closed</p>
</div>
<div class="col-lg-4 col-md-4 col-xs-12">
<h3>Whonix integration</h3>
<p> Run <a href="https://www.torproject.org/">Tor</a> securely system-wide using <a href="/doc/whonix/">Whonix with Qubes</a></p>
</div>
<div class="col-lg-4 col-md-4 col-xs-12">
<h3>Controller isolation</h3>
<p>Secure <a href="/doc/device-handling/">device handling</a> through isolation of network cards and USB controllers</p>
</div>
</div>
<hr class="add-top more-bottom">
<div class="row more-bottom">
<div class="col-lg-4 col-md-4 col-xs-12">
<h3>Split GPG</h3>
<p>Utilize <a href="/doc/split-gpg/">Split GPG</a> to store private GPG keys in an AppVM</p>
</div>
<div class="col-lg-4 col-md-4 col-xs-12">
<h3>U2F proxy</h3>
<p>Operate <a href="/doc/u2f-proxy/">Qubes U2F proxy</a> to use two-factor authentication</p>
</div>
<div class="col-lg-4 col-md-4 col-xs-12">
<h3>Open-source</h3>
<p>Users are free to use, copy and modify Qubes OS and <a href="/doc/contributing/">are encouraged to do so!</a></p>
</div>
</div>
<div class="alert alert-info" role="alert">
<i class="fa fa-question-circle"></i>
<b>Note : </b> Given the technical nature of Qubes OS, prior experience with a Linux distribution such as Ubuntu, Debian or Fedora is advisable.
</div>
Why Qubes OS ?
--------------
<h3>Physical isolation is a given safeguard that the digital world lacks</h3>
<div class="row">
<div class="col-lg-6 col-md-6 text-left">
<p>Throughout their lives, individuals engage in various activities such as going to school, working, voting, taking care of their families or visiting with friends. </p>
<p>These activities are spatially and temporally bound : they happen in isolation of one another, in their own compartments, which often represent an essential safeguard, such as in the case of voting.</p>
<p>In one's digital life, the situation is quite different : each activity, often intertwined with its real-life counterpart, tends to happen on a single computing device.</p>
</div>
<div class="col-lg-6 col-md-6">
<img src="/attachment/wiki/GettingStarted/r2b1-qubes-manager-2.png" height="300" class="center-block">
</div>
</div>
<h3>Qubes OS compartmentalizes one's digital life</h3>
<div class="row">
<div class="col-lg-3 col-md-3">
<img src="/attachment/icons/128x128/apps/qubes-logo-icon.png" height="128" class="center-block">
</div>
<div class="col-lg-9 col-md-9 text-left">
<p> Surprisingly, personal computing devices are not designed to offer means to enforce the same kind of isolation that people enjoy in the physical world.</p>
<p>What if there were an operating system that provided a kind of digital compartmentalization almost as strong as physical isolation?</p>
<p>Qubes OS allows users to compartmentalize various parts of their digital lives into well-isolated compartments.</p>
</div>
</div>
<h3>Made to support vulnerable users</h3>
<div class="row">
<div class="col-lg-12 col-md-12 text-left">
<p>Thanks to Qubes OS, vulnerable or actively targeted individuals such as journalists, political activists, whistleblowers or researchers can enjoy the same benefits of using multiple computing devices at a fraction of the cost and without the associated loss of usability.</p>
<p> It allows users to do everything on the same physical computer without having to worry about a single successful cyberattack taking down their entire digital life in one fell swoop.</p>
<p>Computing should remain an activity where mistakes can be made and where users can explore the web freely, downloading attachments and clicking on links without having to constantly evaluate a myriad of risk factors.</p>
<p>Qubes OS strives to bring back this experience. It creates a place where users can feel safe.</p>
</div>
</div>
<p><img src="/attachment/wiki/GettingStarted/snapshot12.png" alt="snapshot12.png"/></p>
<hr class="add-top more-bottom">
<div class="row more-bottom">
<div class="col-lg-4 col-md-4 col-xs-12">
<h3>Video Tours</h3>
<p>Want to see Qubes OS in action? Sit back and watch a guided tour!</p>
<a href="/video-tours/" class="btn btn-primary">
<i class="fa fa-play-circle"></i> Video Tours
</a>
</div>
<div class="col-lg-4 col-md-4 col-xs-12">
<h3>Screenshots</h3>
<p>See what using Qubes actually looks like with these screenshots of various applications running in Qubes.</p>
<a href="/screenshots/" class="btn btn-primary">
<i class="fa fa-picture-o"></i> Screenshots
</a>
</div>
<div class="col-lg-4 col-md-4 col-xs-12">
<h3>Getting Started</h3>
<p>Ready to get started with Qubes? Here's what you need to know after installing.</p>
<a href="/getting-started/" class="btn btn-primary">
<i class="fa fa-cubes"></i> Getting Started
</a>
</div>
</div>
More information
----------------
This page is just a brief introduction to what Qubes is all about, and many
technical details have been omitted here for the sake of presentation.
* If you're a current or potential Qubes user, you may want to check out the
[documentation][doc] and the [FAQ][user-faq].
* If you're a developer, there's dedicated [documentation][system-doc]
and an [FAQ][devel-faq] just for you.
* Ready to give Qubes a try? Head on over to the [downloads] page or the [installation guide].
[disposable qube]: /doc/disposablevm/
[networking]: /doc/networking/
[firewalls]: /doc/firewall/
[USB]: /doc/usb/
[file]: /doc/copying-files/
[clipboard]: /doc/copy-paste/
[Template]: /doc/templates/
[Qubes-Whonix]: /doc/whonix/
[Whonix]: https://www.whonix.org/
[Tor]: https://www.torproject.org/
[Anti Evil Maid]: /doc/anti-evil-maid/
[Tails]: https://tails.boum.org/
[Xen]: https://www.xenproject.org
[paper-compart]: https://invisiblethingslab.com/resources/2014/Software_compartmentalization_vs_physical_separation.pdf
[doc]: /doc/
[user-faq]: /faq/#users
[system-doc]: /doc/system-doc/
[devel-faq]: /faq/#developers
[downloads]: /downloads/
[getting started]: /getting-started/
[installation guide]: /doc/installation-guide/

11
introduction/reporting-bugs.md
View File

@ -16,6 +16,7 @@ redirect_from:
# Reporting bugs and other issues #
All issues pertaining to the Qubes OS Project (including auxiliary infrastructure such as the [website]) are tracked in [qubes-issues], our GitHub issue tracker.
If you're looking for help, please see [Help, Support, Mailing Lists, and Forum].
## Important ##
@ -43,12 +44,12 @@ Issues may have additional labels, if applicable (e.g., `crypto`, `ux`).
[qubes-issues] is not the place to ask questions.
This includes, but is not limited to, troubleshooting questions and questions about how to do things with Qubes.
These questions should instead be asked in [qubes-users].
Instead, see [Help, Support, Mailing Lists, and Forum] for appropriate place to ask questions.
By contrast, [qubes-issues] is meant for tracking more general bugs, enhancements, and tasks that affect a broad range of Qubes users.
### Every issue must be about a single, actionable thing ###
If your issue is not actionable, please send it to the appropriate [mailing list][Help, Support, and Mailing Lists] instead.
If your issue is not actionable, please see [Help, Support, Mailing Lists, and Forum] for the appropriate place to post it.
If your issue would be about more than one thing, file them as separate issues instead.
### New issues should not be duplicates of existing issues ###
@ -113,7 +114,7 @@ If the issue is closed without one of these specific resolutions, then it means,
## See also ##
- [Help, Support, and Mailing Lists]
- [Help, Support, Mailing Lists, and Forum]
- [Testing New Releases and Updates][testing]
- [How to Contribute]
- [Contributing Code]
@ -134,9 +135,7 @@ If the issue is closed without one of these specific resolutions, then it means,
[documentation]: /doc/
[website]: /
[qubes-issues]: https://github.com/QubesOS/qubes-issues/issues
[Help, Support, and Mailing Lists]: /support/
[qubes-users]: /support/#qubes-users
[qubes-devel]: /support/#qubes-devel
[Help, Support, Mailing Lists, and Forum]: /support/
[updates-status]: https://github.com/QubesOS/updates-status/issues
[how to copy information out of dom0]: /doc/copy-from-dom0/
[testing]: /doc/testing/

6
introduction/statistics.md
View File

@ -6,8 +6,10 @@ redirect_from:
- /counter/
---
<div style="text-align: center; margin-bottom: 3em;">
<img src="https://tools.qubes-os.org/counter/stats.png" alt="Estimated Qubes OS userbase graph"/>
<div class="center-block more-bottom">
<a href="https://tools.qubes-os.org/counter/stats.png">
<img src="https://tools.qubes-os.org/counter/stats.png" alt="Estimated Qubes OS userbase graph"/>
</a>
</div>
FAQ

275
introduction/support.md
View File

@ -1,6 +1,6 @@
---
layout: sidebar
title: Help, Support, and Mailing Lists
title: Help, Support, Mailing Lists, and Forum
permalink: /support/
redirect_from:
- /help/
@ -13,11 +13,11 @@ redirect_from:
- /wiki/QubesLists/
---
# Help, Support, and Mailing Lists #
# Help, Support, Mailing Lists, and Forum #
Help and support for Qubes OS is available from the [documentation] and the
[mailing lists], which are explained below. The Qubes OS Project does not offer
paid support services.
Help and support for Qubes OS is available from the [documentation], the
[mailing lists], and our [forum] which are explained below. The Qubes OS
Project does not offer paid support services.
If you're looking for known issues or would like to file a bug report, please
see the [issue tracker]. These issues are constantly being updated and may
@ -27,11 +27,11 @@ contain workarounds for problems that you're experiencing, so it's worth
## Staying safe ##
The Qubes mailing lists are open to the public. The contents of the list are
The Qubes mailing lists and forum are open to the public. The contents are
crawled by search engines and archived by third-party services outside of our
control. Please do not send anything to the mailing lists that you are not
comfortable seeing discussed in public. If confidentiality is a concern, please
use PGP encryption in an off-list email.
control. Please do not send or post anything that you are not comfortable seeing
discussed in public. If confidentiality is a concern, please use PGP encryption
in an off-list email.
The Qubes community includes people from all walks of life and from around the
world. Individuals differ in areas of experience and technical expertise. You
@ -41,11 +41,12 @@ Everyone is free to write what they please, as long as it doesn't violate our
read. Use good judgment, and be especially careful when following instructions
(e.g., copying commands) given by others on the lists.
All official announcements from the [Qubes team] will be signed by the PGP key
belonging to the team member who sends the announcement. However, anyone on the
list can choose to sign their messages, so the presence of a PGP signature does
not indicate authority. How, then, should you sort the good advice from the bad?
This is up to each individual to decide, but it helps to know that many members
All official announcements from the [Qubes team] to a mailing list will be
signed by the PGP key belonging to the team member who sends the announcement.
However, anyone on a mailing list can choose to sign their messages, so the
presence of a PGP signature does not indicate authority. How, then, should you
sort the good advice from the bad?
This is up to each individual to decide, but it helps to know that many members
of our community have proven themselves knowledgeable through their
[contributions] to the project. Typically, these individuals sign their messages
with the same key as (or another key authenticated by) the one they use to
@ -61,17 +62,16 @@ cryptographically signed, anyone would be in a position to [verify] that these
came from the same keyholder.
## Discussion list guidelines ##
## Discussion guidelines ##
Qubes discussions mainly take place on two mailing lists: `qubes-users` and
`qubes-devel`, both of which are explained below. Please send all questions
regarding Qubes to one of these two lists. **Please do not send questions to
individual Qubes developers.** By sending a message to the appropriate mailing
list, you are not only giving others a chance to help you, but you may also be
helping others by starting a public discussion about a shared problem or
interest.
Qubes discussions mainly take place on `qubes-users`, `qubes-devel`, and our
[forum], all of which are explained below. Most questions should be directed to
`qubes-users` or the [forum]. **Please do not send questions to individual
Qubes developers.** By sending a message to the appropriate mailing list, you
are not only giving others a chance to help you, but you may also be helping
others by starting a public discussion about a shared problem or interest.
These are open mailing lists where people freely come together to discuss Qubes
These are open venues where people freely come together to discuss Qubes
and voluntarily help each other out of mutual interest and good will. They are
*not* your personal, paid support service. **No one owes you a reply.** No one
here is responsible for solving your problems for you. Nonetheless, there are
@ -86,7 +86,7 @@ guidelines.
Remember, no one here is under any obligation
to reply to you. Think about your readers. Most of them are coming home after
a long, hard day at work. The last thing they need is someone's temper
tantrum in their inboxes. If you are rude and disrespectful, you are very
tantrum. If you are rude and disrespectful, you are very
likely to be ignored.
### Be concise ###
@ -116,35 +116,34 @@ to answer questions on the mailing lists once every several days.
### Be a good community member ###
As with any social community, members of the
mailing list earn different reputations for themselves over time. We want the
mailing lists to be a friendly, productive place where information and ideas
are exchanged for the mutual benefit of all. We understand that the best way
to achieve this is to encourage and cultivate other like-minded individuals.
Those who have shown themselves to be good community members through their
past contributions have earned our good will, and we will be especially eager
to help them and collaborate with them. If you are new to the community, you
should understand that it will take time for you to earn the good will of
others. This does not mean that you will not receive help. On the contrary,
we are fortunate to have such a helpful and understanding community that many
of them spend hours of their personal time helping complete strangers,
including many who post to the lists anonymously. (Given the integration of
Qubes with [Whonix], we understand better than most the complexities of
privacy and anonymity, and we know that many users have no other choice but
to post anonymously.) You can read our project's [Code of Conduct][coc] for
more information.
As with any social community, members earn different reputations for themselves
over time. We want these discussion venues to be friendly, productive places
where information and ideas are exchanged for the mutual benefit of all. We
understand that the best way to achieve this is to encourage and cultivate
other like-minded individuals. Those who have shown themselves to be good
community members through their past contributions have earned our good will,
and we will be especially eager to help them and collaborate with them. If you
are new to the community, you should understand that it may take time for you
to earn the good will of others. This does not mean that you will not receive
help. On the contrary, we are fortunate to have such a helpful and
understanding community that many of them spend hours of their personal time
helping complete strangers, including many who post anonymously. (Given the
integration of Qubes with [Whonix], we understand better than most the
complexities of privacy and anonymity, and we know that many users have no
other choice but to post anonymously.) You can read our project's [Code of
Conduct][coc] for more information.
### Report issues and submit changes in the right places ###
The mailing lists a good place to ask questions and discuss bugs and feature
requests. However, if you're submitting a more formal report, we'd prefer
that you submit it to our [issue tracker] so that it doesn't get overlooked.
The mailing lists and [forum] are good places to ask questions and discuss
things. However, if you're submitting a more formal report, we'd prefer that
you submit it to our [issue tracker] so that it doesn't get overlooked.
Likewise, if you see that something in the documentation should be changed,
don't simply point it out in an email to one of the mailing lists. Instead,
[submit the change][contributing to the documentation].
don't simply point it out in a discussion venue. Instead, [submit the
change][contributing to the documentation].
### Specific rules and notes ###
### Specific mailing list rules and notes ###
#### Use the correct list ####
@ -212,38 +211,40 @@ Please note, however, that it's always a good idea to field a discussion of
your idea on the `qubes-devel` list before putting in a lot of hard work on
something that we may not be able or willing to accept.
#### Mailing lists vs. forums ####
#### Google Groups ####
While the mailing lists are implemented as Google Group web forums, a Google
account is in no way required, expected, or encouraged. Many discussants
(including most members of the Qubes team) treat these lists as conventional
[mailing lists], interacting with them solely through plain text email with
[MUAs] like [Thunderbird] and [Mutt]. The Google Groups service is just
[mailing lists][wiki-ml], interacting with them solely through plain text email
with [MUAs] like [Thunderbird] and [Mutt]. The Google Groups service is just
free infrastructure, and we [distrust the infrastructure]. This is why, for
example, we encourage discussants to use [Split GPG] to sign all of their
messages to the lists, but we do not endorse the use of these Google Groups
as web forums. Some users prefer to interact with the mailing lists through
their optional web interfaces. This has the advantage that it allows you to
search and reply to messages which were sent prior to your subscription to
the list. However, a Google account is required in order to post through the
web interfaces. (Note: There have been many discussions about why the Qubes
OS Project does not maintain an official forum. The curious can find these
by searching the list archives.)
as web forums. For that, we have a separate, dedicated [forum].
## qubes-announce ##
## Mailing lists ##
This is a read-only list for those who wish to receive only very important, infrequent messages.
Only the core Qubes team can post to this list.
Only [Qubes Security Bulletins (QSBs)][qsb], new stable releases, and end-of-life notices are announced here.
To subscribe, send a blank email to `qubes-announce+subscribe@googlegroups.com`.
(Note: A Google account is *not* required. Any email address will work.)
To unsubscribe, send a blank email to `qubes-announce+unsubscribe@googlegroups.com`.
This list also has an optional [Google Groups web interface][qubes-announce-web].
This section covers each of our individual [mailing lists][wiki-ml], with
details about the purpose of each list and how to use it.
## qubes-users ##
### qubes-announce ###
This is a read-only list for those who wish to receive only very important,
infrequent messages. Only the core Qubes team can post to this list. Only
[Qubes Security Bulletins (QSBs)][qsb], new stable releases, and end-of-life
notices are announced here.
To subscribe, send a blank email to
`qubes-announce+subscribe@googlegroups.com`. (Note: A Google account is *not*
required. Any email address will work.) To unsubscribe, send a blank email to
`qubes-announce+unsubscribe@googlegroups.com`. This list also has an optional
[Google Groups web interface][qubes-announce-web].
### qubes-users ###
This list is for helping users solve various daily problems with Qubes OS.
Examples of topics or questions suitable for this list include:
@ -263,17 +264,19 @@ list:
* The [User FAQ]
* The [documentation] (for questions about how to use Qubes OS)
You don't have to subscribe in order to post to this list.
However, subscribing makes your messages less likely to be marked as spam and allows you to receive messages sent directly to the list.
To subscribe to the list, send a blank email to `qubes-users+subscribe@googlegroups.com`.
(Note: A Google account is *not* required. Any email address will work.)
To post a message to the list, address your email to `qubes-users@googlegroups.com`.
If your post does not appear immediately, please allow time for moderation to occur.
To unsubscribe, send a blank email to `qubes-users+unsubscribe@googlegroups.com`.
This list also has an optional [Google Groups web interface][qubes-users-web] and [traditional mail archive][qubes-users-archive].
You don't have to subscribe in order to post to this list. However, subscribing
makes your messages less likely to be marked as spam and allows you to receive
messages sent directly to the list. To subscribe to the list, send a blank
email to `qubes-users+subscribe@googlegroups.com`. (Note: A Google account is
*not* required. Any email address will work.) To post a message to the list,
address your email to `qubes-users@googlegroups.com`. If your post does not
appear immediately, please allow time for moderation to occur. To unsubscribe,
send a blank email to `qubes-users+unsubscribe@googlegroups.com`. This list
also has an optional [Google Groups web interface][qubes-users-web] and
[traditional mail archive][qubes-users-archive].
## qubes-devel ##
### qubes-devel ###
This list is primarily intended for people who are interested in contributing to
Qubes or who are willing to learn more about its architecture and
@ -287,16 +290,17 @@ implementation. Examples of topics and questions suitable for this list include:
* Contributed code and patches.
* Security discussions which are relevant to Qubes in some way.
You must be subscribed in order to post to this list.
To subscribe, send a blank email to `qubes-devel+subscribe@googlegroups.com`.
(Note: A Google account is *not* required. Any email address will work.)
To post a message to the list, address your email to `qubes-devel@googlegroups.com`.
If your post does not appear immediately, please allow time for moderation to occur.
To unsubscribe, send a blank email to `qubes-devel+unsubscribe@googlegroups.com`.
This list also has an optional [Google Groups web interface][qubes-devel-web] and [traditional mail archive][qubes-devel-archive].
You must be subscribed in order to post to this list. To subscribe, send a
blank email to `qubes-devel+subscribe@googlegroups.com`. (Note: A Google
account is *not* required. Any email address will work.) To post a message to
the list, address your email to `qubes-devel@googlegroups.com`. If your post
does not appear immediately, please allow time for moderation to occur. To
unsubscribe, send a blank email to `qubes-devel+unsubscribe@googlegroups.com`.
This list also has an optional [Google Groups web interface][qubes-devel-web]
and [traditional mail archive][qubes-devel-archive].
## qubes-project ##
### qubes-project ###
This list is for non-technical discussion and coordination around the
Qubes OS project.
@ -308,17 +312,18 @@ Examples of topics or question suitable for this list include:
* FOSS governance discussions
* Most Github issues tagged "[business]"
You don't have to subscribe in order to post to this list.
However, subscribing makes your messages less likely to be marked as spam and allows you to receive messages sent directly to the list.
To subscribe, send a blank email to `qubes-project+subscribe@googlegroups.com`.
(Note: A Google account is *not* required. Any email address will work.)
To post a message to the list, address your email to `qubes-project@googlegroups.com`.
If your post does not appear immediately, please allow time for moderation to occur.
To unsubscribe, send a blank email to `qubes-project+unsubscribe@googlegroups.com`.
This list also also has an optional [Google Groups web interface][qubes-project-web].
You don't have to subscribe in order to post to this list. However, subscribing
makes your messages less likely to be marked as spam and allows you to receive
messages sent directly to the list. To subscribe, send a blank email to
`qubes-project+subscribe@googlegroups.com`. (Note: A Google account is *not*
required. Any email address will work.) To post a message to the list, address
your email to `qubes-project@googlegroups.com`. If your post does not appear
immediately, please allow time for moderation to occur. To unsubscribe, send a
blank email to `qubes-project+unsubscribe@googlegroups.com`. This list also
also has an optional [Google Groups web interface][qubes-project-web].
## qubes-translation ##
### qubes-translation ###
This list is for discussion around the localization and translation of Qubes OS,
its documentation, and the website.
@ -329,17 +334,78 @@ Examples of topics or question suitable for this list include:
* Who is managing localization for a given language
* Most Github issues tagged "[localization]"
You don't have to subscribe in order to post to this list.
However, subscribing makes your messages less likely to be marked as spam and allows you to receive messages sent directly to the list.
To subscribe, send a blank email to `qubes-translation+subscribe@googlegroups.com`.
(Note: A Google account is *not* required. Any email address will work.)
To post a message to the list, address your email to `qubes-translation@googlegroups.com`.
If your post does not appear immediately, please allow time for moderation to occur.
To unsubscribe, send a blank email to `qubes-translation+unsubscribe@googlegroups.com`.
This list also has an optional [Google Groups web interface][qubes-translation-web].
You don't have to subscribe in order to post to this list. However, subscribing
makes your messages less likely to be marked as spam and allows you to receive
messages sent directly to the list. To subscribe, send a blank email to
`qubes-translation+subscribe@googlegroups.com`. (Note: A Google account is
*not* required. Any email address will work.) To post a message to the list,
address your email to `qubes-translation@googlegroups.com`. If your post does
not appear immediately, please allow time for moderation to occur. To
unsubscribe, send a blank email to
`qubes-translation+unsubscribe@googlegroups.com`. This list also has an
optional [Google Groups web interface][qubes-translation-web].
[mailing lists]: https://en.wikipedia.org/wiki/Electronic_mailing_list
## Forum ##
We have a community forum for Qubes OS users:
<https://qubes-os.discourse.group>
This is an official user forum where you can ask questions, get help, share
tips and experiences, and more! For a long time, members of our community have
sought a privacy-respecting forum experience with modern features that
traditional mailing lists do not support. The open-source [Discourse] platform
fills this need for us, as it does for many other open-source projects. Thanks
to their generous [free hosting for open source projects], we're pleased to be
able to create this space for our community.
### Why was this forum created? ###
Previously, the only option for a forum-like experience was to interact with
our mailing lists via Google Groups, but we understand all too well that the
privacy implications and user experience were unacceptable for many members of
our community, especially with the recent addition of a sign-in requirement to
view threads. Many of you value the lower barrier to entry, organization,
ease-of-use, and modern social features that today's forums support. Moreover,
Discourse features email integration for those who still prefer the traditional
mailing list format.
### How is this different from our mailing lists? ###
To be clear, this is *not* a replacement for the mailing lists. This forum is
simply an *additional* place for discussion. Certain types of discussions
naturally lend themselves more to mailing lists or to forums, and different
types of users prefer different venues. We've heard from some users who find
the mailing lists to be a bit intimidating or who may feel that their message
isn't important enough to merit creating a new email that lands in thousands of
inboxes. Others want more selective control over topic notifications. Some
users simply appreciate the ability to add a "reaction" to a message instead of
having to add an entirely new reply. Whatever your reasons, it's up to you to
decide where and how you want to join the conversation.
### Does this split the community? ###
Many open-source projects (such as Fedora and Debian) have both mailing lists
and forums (and additional discussion venues). In fact, Qubes already had
non-mailing-list discussion venues such as [IRC] and [Reddit] before this forum
was introduced. We believe that this additional venue fosters the continued
growth of community participation and improves everyone's experience. In
addition, we fully expect that many community members -- especially the most
active ones -- will choose to participate in both venues. (Again, for those who
still prefer interacting via email, Discourse supports that too!)
## Unofficial chat channels ##
The following unofficial chat channels are maintained by the community:
* Matrix, Qubes-related: <https://matrix.to/#/#cybersec-qubes_os:matrix.org>
* Matrix, strictly Qubes: <https://matrix.to/#/#Qubes-OS:matrix.org>
* `#qubes` channel on freenode.net via traditional IRC clients or: <https://webchat.freenode.net/>
[mailing lists]: #mailing-lists
[wiki-ml]: https://en.wikipedia.org/wiki/Electronic_mailing_list
[Qubes team]: /team/
[contributions]: /doc/contributing/
[code-signing]: /doc/code-signing/
@ -377,4 +443,9 @@ This list also has an optional [Google Groups web interface][qubes-translation-w
[Transifex]: https://www.transifex.com/otf/qubes/
[issue tracker]: /doc/reporting-bugs/
[searching the issue tracker]: /doc/reporting-bugs/#search-tips
[forum]: #forum
[Discourse]: https://www.discourse.org/
[free hosting for open source projects]: https://blog.discourse.org/2018/11/free-hosting-for-open-source-v2/
[IRC]: #unofficial-chat-channels
[Reddit]: https://www.reddit.com/r/Qubes/

20
project-security/verifying-signatures.md
View File

@ -169,15 +169,22 @@ There are several ways to get the Release Signing Key for your Qubes release.
The Release Signing Key should be signed by the Qubes Master Signing Key:
$ gpg2 --list-sigs "Qubes OS Release X Signing Key"
$ gpg2 --check-signatures "Qubes OS Release X Signing Key"
pub rsa4096 2017-03-06 [SC]
5817A43B283DE5A9181A522E1848792F9E2795E9
uid [ full ] Qubes OS Release X Signing Key
sig 3 1848792F9E2795E9 2017-03-06 Qubes OS Release X Signing Key
sig DDFA1A3E36879494 2017-03-08 Qubes Master Signing Key
sig!3 1848792F9E2795E9 2017-03-06 Qubes OS Release X Signing Key
sig! DDFA1A3E36879494 2017-03-08 Qubes Master Signing Key
gpg: 2 good signatures
This is just an example, so the output you receive will not look exactly the same.
What matters is that the last line shows that this key is signed by the Qubes Master Signing Key, which verifies the authenticity of the Release Signing Key.
What matters is the line that shows that this key is signed by the Qubes Master
Signing Key with a `sig!` prefix. This verifies the authenticity of the
Release Signing Key. Note that the `!` flag after the `sig` tag is important
because it means that the key signature is valid. A `sig-` prefix would
indicate a bad signature and `sig%` would mean that gpg encountered an error
while verifying the signature.
It is not necessary to independently verify the authenticity of the Release Signing Key.
@ -433,7 +440,8 @@ The correct ISO is not in your working directory.
Carefully read this page again to be certain that you didn't skip any steps.
In particular, make sure you have the [Qubes Master Signing Key][QMSK], the [Release Signing Key][RSK], *and* the [signature file] and/or [digest file] all for the *correct* Qubes OS version.
If your question is about GPG, please see the [GPG documentation].
If you still have a question, please address it to the [qubes-users mailing list].
Still have question?
Please see [Help, Support, Mailing Lists, and Forum] for places where you can ask!
[website-trust]: /faq/#should-i-trust-this-website
@ -455,6 +463,6 @@ If you still have a question, please address it to the [qubes-users mailing list
[digest file]: #how-to-verify-qubes-iso-digests
[Qubes repositories]: https://github.com/QubesOS
[GPG documentation]: https://www.gnupg.org/documentation/
[qubes-users mailing list]: /support/#qubes-users
[Help, Support, Mailing Lists, and Forum]: /support/
[except dom0]: https://github.com/QubesOS/qubes-issues/issues/2544

13
user/advanced-configuration/config-files.md
View File

@ -31,7 +31,7 @@ The scripts here all run as root.
~~~
# Add entry to /etc/hosts
echo '127.0.0.1 example.com >> /etc/hosts
echo '127.0.0.1 example.com' >> /etc/hosts
~~~
- `/rw/config/qubes-ip-change-hook` - script runs in NetVM after every external IP change and on "hardware" link status change.
@ -85,29 +85,30 @@ Sample config (included in default installation):
~~~
# Sample configuration file for Qubes GUI daemon
# For syntax go http://www.hyperrealm.com/libconfig/libconfig_manual.html
# For syntax go https://www.hyperrealm.com/libconfig/libconfig_manual.html
global: {
# default values
#allow_fullscreen = false;
#override_redirect_protection = true;
#allow_utf8_titles = false;
#secure_copy_sequence = "Ctrl-Shift-c";
#secure_paste_sequence = "Ctrl-Shift-v";
#windows_count_limit = 500;
#audio_low_latency = false;
#audio_low_latency = true;
#log_level = 1;
#trayicon_mode = "border1";
#startup_timeout = 91;
#startup_timeout = 45;
};
# most of setting can be set per-VM basis
VM: {
work: {
#allow_utf8_titles = true;
allow_utf8_titles = true;
};
video-vm: {
#allow_fullscreen = true;
allow_fullscreen = true;
};
};
~~~

6
user/advanced-configuration/disposablevm-customization.md
View File

@ -55,6 +55,8 @@ If you wish to use a [Minimal TemplateVM](/doc/templates/minimal/) as a Disposab
## Customization of DisposableVM
_**Note:** If you are trying to customize Tor Browser in a Whonix DisposableVM, please consult the [Whonix documentation](https://www.whonix.org/wiki/Tor_Browser/Advanced_Users#DVM_Template_Customization)._
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:
@ -64,7 +66,7 @@ This can be done by customizing the DisposableVM Template on which it is based:
2. Change the qube's settings and/or applications, as desired. Some examples of changes you may want to make include:
- Changing Firefox's default startup settings and homepage.
- Changing default editor, image viewer.
- Changing default editor, image viewer. In Debian-based templates this can be done with the `mimeopen` command.
- Changing the DisposableVM's default NetVM. For example, you may wish to set the NetVM to "none." Then, whenever you start a new DisposableVM, you can choose your desired ProxyVM manually (by changing the newly-started DisposableVMs settings). This is useful if you sometimes wish to use a DisposableVM with a Whonix Gateway, for example. It is also useful if you sometimes wish to open untrusted files in a network-disconnected DisposableVM.
4. Shutdown the qube (either by `poweroff` from qube's terminal, or `qvm-shutdown` from dom0 terminal).
@ -80,7 +82,7 @@ The only exception is if you require something like VM to VM communication and h
To create one that has no PCI devices attached, such as for `sys-firewall`:
~~~
qvm-create -C DispVM -l red <sys-VMName>
qvm-create -C DispVM -l green <sys-VMName>
qvm-prefs <sys-VMName> autostart true
qvm-prefs <sys-VMName> netvm <sys-net>
qvm-prefs <sys-VMName> provides_network true

3
user/advanced-configuration/i3.md
View File

@ -25,10 +25,13 @@ That's it. After logging out, you can select i3 in the login manager.
### Customization
**Caution:** The following external resources may not have been reviewed by the Qubes team.
* [xdg_autostart_script](https://gist.github.com/SietsevanderMolen/7b4cc32ce7b4884513b0a639540e454f)
* [i3bar_script](https://gist.github.com/SietsevanderMolen/e7f594f209dfaa3596907e427b657e30)
* [terminal_start_script](https://gist.github.com/SietsevanderMolen/7c6f2b5773dbc0c08e1509e49abd1e96)
* [i3 config with dmenu-i3-window-jumper](https://github.com/anadahz/qubes-i3-config/blob/master/config)
* [dmenu script to open a terminal in a chosen VM](https://gist.github.com/dmoerner/65528941dd20b05c98ee79e92d7e0183)
## Compilation and installation from source

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

@ -33,7 +33,7 @@ In most cases, the GUI tool Qube Settings (available for every qube from the Sta
![vm-settings-disk-image.png](/attachment/wiki/DiskSize/vm-settings-disk-image.png)
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.
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/), 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 the OS-specific follow-up instructions below.

21
user/advanced-configuration/salt.md
View File

@ -464,6 +464,26 @@ Whonix Gateway TemplateVM
Whonix Workstation TemplateVM
#### `update.qubes-dom0`
Updates dom0
#### `update.qubes-vm`
Updates domUs. Example to update all TemplateVMs:
sudo qubesctl --skip-dom0 --templates state.sls update.qubes-vm
Useful options:
- `--max-concurrency` --- Limits how many templates are updated at the same time.
Adjust to your available RAM.
The default is 4, and the GUI updater sets it to 1.
- `--targets=vm1,vm2,...` --- Limit to specific VMs, instead of all of them.
(Use instead of `--templates` or `--standalones`.)
- `--show-output` --- Show an update summary instead of just OK/FAIL.
For other options, see `qubesctl --help`.
## The `qubes` Pillar Module
@ -488,6 +508,7 @@ Template name on which a given VM is based (if any).
VM which provides network to the given VM
## Debugging
The output for each VM is logged in `/var/log/qubes/mgmt-VM_NAME.log`.

2
user/common-tasks/backup-emergency-restore-v2.md
View File

@ -68,7 +68,7 @@ encrypted and compressed.
**Note:** For multi-part files, a loop can be used:
~~~
for f in private.img.*; do
find -name 'private.img.*' | sort -V | while read f; do
openssl enc -d -pass pass:your_passphrase -aes-256-cbc -in $f -out
${f/.img/.img.dec}
done

2
user/common-tasks/backup-emergency-restore-v3.md
View File

@ -93,7 +93,7 @@ any GNU/Linux system with the following procedure.
5. Decrypt the `private.img` file.
[user@restore vm1]$ cat private.img.??? | openssl enc -d -pass pass:your_passphrase -aes-256-cbc -out private.img.dec
[user@restore vm1]$ find -name 'private.img.*[0-9]' | sort -V | xargs cat | openssl enc -d -pass pass:your_passphrase -aes-256-cbc -out private.img.dec
**Note:** If your backup was encrypted with a cipher algorithm other than
`aes-256-cbc`, you must substitute the correct cipher command. This

35
user/common-tasks/backup-emergency-restore-v4.md
View File

@ -145,39 +145,32 @@ Emergency Recovery Instructions
[user@restore ~]$ backup_id=20161020T123455-1234
6. Verify the integrity of and decrypt the `private.img` file that houses your
data.
6. Verify the integrity of your data, decrypt, decompress, and extract `private.img`:
[user@restore ~]$ for f_enc in vm1/private.img.???.enc; do \
[user@restore ~]$ find vm1 -name 'private.img.*.enc' | sort -V | while read f_enc; do \
f_dec=${f_enc%.enc}; \
echo "$backup_id!$f_dec!$backup_pass" | scrypt dec -P $f_enc $f_dec || break; \
done
**Note:** If this command fails, it is likely that the backup is corrupted
or has been tampered with.
7. Decompress and untar the decrypted `private.img` file.
[user@restore ~]$ cat vm1/private.img.??? | gzip -d | tar -xv
echo "$backup_id!$f_dec!$backup_pass" | scrypt dec -P $f_enc || break; \
done | gzip -d | tar -xv
vm1/private.img
If this pipeline fails, it is likely that the backup is corrupted or has
been tampered with.
**Note:** If your backup was compressed with a program other than `gzip`,
you must substitute the correct compression program. This information is
contained in `backup-header` (see step 4). For example, if you used `bzip2`,
then you should do this:
you must substitute the correct compression program in the command above.
This information is contained in `backup-header` (see step 4). For example,
if your backup is compressed with `bzip2`, use `bzip2 -d` instead in the
command above.
[user@restore vm1]$ mv private.img.dec private.img.dec.bz2
[user@restore vm1]$ bunzip2 private.img.dec.bz2
8. Mount `private.img` and access your data.
7. Mount `private.img` and access your data.
[user@restore vm1]$ sudo mkdir /mnt/img
[user@restore vm1]$ sudo mount -o loop vm1/private.img /mnt/img/
[user@restore vm1]$ cat /mnt/img/home/user/your_data.txt
This data has been successfully recovered!
9. Success! If you wish to recover data from more than one VM in your backup,
simply repeat steps 6--8 for each additional VM.
8. Success! If you wish to recover data from more than one VM in your backup,
simply repeat steps 6 and 7 for each additional VM.
**Note:** You may wish to store a copy of these instructions with your
Qubes backups in the event that you fail to recall the above procedure

26
user/common-tasks/backup-restore.md
View File

@ -11,20 +11,25 @@ redirect_from:
Qubes Backup, Restoration, and Migration
========================================
With Qubes, it's easy to back up and restore your whole system, as well as to migrate between two physical machines.
With Qubes, it's easy and secure to back up and restore your whole system, as well as to migrate between two physical machines.
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`.
These functions are integrated into the Qube Manager.
There are also two command-line tools available that perform the same functions: `qvm-backup` and `qvm-backup-restore`.
It's extremely important to make regular backups of all the data you care about.
This is true of all computing, not just the use of Qubes.
Data loss can and does occur in myriad and unexpected ways.
A standard recommendation is to make backups at least weekly: three copies in two different formats, one off-site.
Creating a Backup
-----------------
1. Go to **Applications menu -> System Tools -> Backup Qubes**.
This brings up the **Qubes Backup VMs** window.
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.
VMs in the left-hand **Available** column will not be backed up.
You may choose whether to compress backups by checking or unchecking the **Compress the backup** box.
Normally this should be left on unless you have a specific reason otherwise.
@ -52,11 +57,16 @@ VMs in the left-hand **Available** column will not be backed up.
**Warning: Saving the settings will result in your backup passphrase being saved in plaintext in dom0, so consider your threat model before checking this box.**
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.
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**.
Qubes will proceed to create your backup.
Once the progress bar has completed, you may click **Finish**.
6. Test restore your backup.
Follow the [restore procedure](#restoring-from-a-backup), selecting **Verify backup integrity, do not restore the data**.
This step is optional but strongly recommended.
A backup is useless if you can't restore your data from it, and you can't be sure that your backup is good until you try to restore.
Restoring from a Backup

4
user/common-tasks/disposablevm.md
View File

@ -20,7 +20,9 @@ This means that you can safely work with untrusted files without risk of comprom
DisposableVMs can be launched either directly from dom0's Start Menu or terminal window, or from within AppVMs.
While running, DisposableVMs will appear in Qubes VM Manager with the name `disp####`.
See [this article](https://blog.invisiblethings.org/2010/06/01/disposable-vms.html) for more on why one would want to use a DisposableVM.
[![disposablevm-example.png](/attachment/wiki/DisposableVms/disposablevm-example.png)](/attachment/wiki/DisposableVms/disposablevm-example.png)
This diagram provides a general example of how DisposableVMs can be used to safely open untrusted links and attachments in DisposableVMs. See [this article](https://blog.invisiblethings.org/2010/06/01/disposable-vms.html) for more on why one would want to use a DisposableVM.
## Security ##

4
user/common-tasks/full-screen-mode.md
View File

@ -66,8 +66,8 @@ global: {
Be sure to restart the VM(s) after modifying this file, for the changes to take effect.
**Note:** Regardless of the settings above, you can always put a window into fullscreen mode in Xfce4 using the trusted window manager by right-clicking on a window's title bar and selecting "Fullscreen".
**Note:** Regardless of the settings above, you can always put a window into fullscreen mode in Xfce4 using the trusted window manager by right-clicking on a window's title bar and selecting "Fullscreen" or pressing `alt` + `f11`.
This functionality should still be considered safe, since a VM window still can't voluntarily enter fullscreen mode.
The user must select this option from the trusted window manager in dom0.
To exit fullscreen mode from here, press `alt` + `space` to bring up the title bar menu again, then select "Leave Fullscreen".
To exit fullscreen mode from here, press `alt` + `space` to bring up the title bar menu again, then select "Leave Fullscreen" or simply press `alt` + `f11`.
For StandaloneHVMs, you should set the screen resolution in the qube to that of the host, (or larger), *before* setting fullscreen mode in Xfce4.

261
user/common-tasks/getting-started.md
View File

@ -1,208 +1,209 @@
---
layout: default
title: Get Started
permalink: /getting-started/
permalink: /doc/getting-started/
redirect_from:
- /doc/getting-started/
- /getting-started/
- /en/doc/getting-started/
- /doc/GettingStarted/
- /wiki/GettingStarted/
---
<a name="already-installed"></a>After [installing Qubes](/doc/installation-guide/), let's cover some basic concepts.
You might also like to refer to the [Glossary](/doc/glossary/).
After [downloading] and [installing] Qubes OS, let's cover some basic concepts.
AppVMs (qubes) and TemplateVMs
--------------------------------
Introduction
------------
In Qubes, you run all your programs in lightweight Virtual Machines called **qubes**.
Not every app runs in its own qube.
(That would be a big waste of resources!)
Instead, each qube represents a *security domain* (e.g., "work," "personal," "banking," etc.).
By default all qubes are based on a single, common **TemplateVM** , although you can create more TemplateVMs if you wish.
When you create a new qube, you don't copy the whole root filesystem needed for this qube to work (which would include copying all the programs).
Instead, each qube *shares* the root filesystem with its respective TemplateVM.
A qube has read-only access to the filesystem of the Template on which it's based, so a qube cannot modify a TemplateVM in any way.
This is important, as it means that if a qube is ever compromised, the TemplateVM on which it's based (and any other qubes based on that TemplateVM) will still be safe.
So creating a large number of domains is cheap: each one needs only as much disk space as is necessary to store its private files (e.g., the "home" folder).
In Qubes OS, you run all your programs in lightweight [virtual machines (VMs)] called [qubes].
Not every app runs in its own qube.
(That would be a big waste of resources!)
Instead, each qube represents a [security domain] (e.g., "work," "personal," and "banking").
By default, all qubes are based on a single, common [template], although you can create more templates if you wish.
When you create a new qube, you don't copy the whole system needed for this qube to work (which would include copying all the programs).
Instead, each qube *shares* the system with its respective template.
A qube has read-only access to the system of the template on which it's based, so a qube cannot modify a template in any way.
This is important, as it means that if a qube is ever compromised, the template on which it's based (and any other qubes based on that template) will still be safe.
So, creating a large number of qubes is cheap: each one needs only as much disk space as is necessary to store its private files (e.g., the "home" folder).
If you've installed Qubes using the default options, a few qubes have already been created for you:
If you've installed Qubes OS using the default options, a few qubes have already been created for you:
- work
- personal
- untrusted
- work
- personal
- untrusted
- vault
Each qube, apart from having a distinct name, is also assigned a **label**, which is one of several pre-defined colors.
The trusted window manager uses these colors in order to draw window decorations (color frames) around the windows of applications running in each qube.
It's totally up to you how you'd like to interpret these colors.
You might like to use them to quickly and easily identify the trust level of a given window at a glance.
Personally, I find it natural to associate red with that which is untrusted and dangerous (the “red light” -- stop! danger!), green with that which is safe and trusted, and yellow and orange with things in the middle.
I've also extended this scheme to include blue and black, which I interpret as indicating progressively more trusted domains than green, with black being ultimately trusted.
Alternatively you might use the colors to show that qubes belong to the same domain - for example, you might use 3 or 4 qubes for work activities, and give them all the same distinct color label. It's entirely up to you.
Each qube, apart from having a distinct name, is also assigned a **label**, which is one of several predefined colors.
The trusted window manager uses these colors in order to draw colored borders around the windows of applications running in each qube.
This is designed to allow you to quickly and easily identify the trust level of a given window at a glance.
Most Qubes OS users associate red with what's untrusted and dangerous (like a red light -- stop! danger!), green with what's safe and trusted, and yellow and orange with things in the middle.
This color scheme also extends to include blue and black, which are usually interpreted as indicating progressively more trusted domains than green, with black being ultimately trusted.
However, it's totally up to you how you'd like to interpret these colors.
Qubes OS doesn't assume anything about these colors.
When you make a new qube, the system doesn't do anything special to it depending on whether it's black or red, for example.
The only difference is which color you see and the meaning you assign to that color in your mind.
For example, you could use the colors to show that qubes belong to the same domain.
You might use three or four qubes for work activities and give them all the same distinct color label, for instance.
It's entirely up to you.
![snapshot12.png](/attachment/wiki/GettingStarted/snapshot12.png)
![snapshot_40.png](/attachment/wiki/GettingStarted/snapshot_40.png)
In addition to qubes and TemplateVMs, there's one special domain called "dom0," which is where the Desktop Manager runs.
This is where you log in to the system.
Dom0 is more trusted than any other domain (including TemplateVMs and black-labeled qubes).
If dom0 were ever compromised, it would be Game Over<sup>TM</sup>.
(The entire system would effectively be compromised.)
Due to its overarching importance, dom0 has no network connectivity and is used only for running the Window and Desktop Managers.
Dom0 shouldn't be used for anything else.
In particular, [you should never run user applications in dom0](/doc/security-guidelines/#dom0-precautions).
In addition to qubes and templates, there's one special domain called [dom0], where many system tools and the desktop manager run.
This is where you log in to the system.
Dom0 is more trusted than any other domain (including templates and black-labeled qubes).
If dom0 were ever compromised, it would be "game over."
(The entire system would effectively be compromised.)
Due to its overarching importance, dom0 has no network connectivity and is used only for running the window and desktop managers.
Dom0 shouldn't be used for anything else.
In particular, [you should never run user applications in dom0][dom0-precautions].
(That's what your qubes are for!)
Qubes VM Manager and Command Line Tools
---------------------------------------
All aspects of the Qubes system can be controlled using command line tools run under a dom0 console.
Opening a console window in dom0 can be done in several ways:
GUI and command-line tools
--------------------------
* Go to the Start Menu and click Terminal Emulator
* Press Alt-F3, type `xfce terminal` and press Enter twice
* Right-click on the desktop and select Open Terminal Here
* In previous versions of Qubes with KDE:
* Start → System Tools → Konsole
* Press Alt-F2 and type `konsole`.
All aspects of Qubes OS can be controlled using command-line tools run in a dom0 terminal.
Opening a terminal in dom0 can be done in several ways:
Various command line tools are described as part of this guide, and the whole reference can be found [here](/doc/tools/).
- Go to the Application Launcher and click **Terminal Emulator**.
- Press `Alt+F3`, type `xfce terminal` and press Enter twice.
- Right-click on the desktop and select **Open Terminal Here**.
![r2b1-dom0-konsole.png](/attachment/wiki/GettingStarted/r2b1-dom0-konsole.png)
Various command-line tools are described as part of this guide, and the whole reference can be found [here][tools].
Alternatively, you can use a rather intuitive GUI tool called **Qubes VM Manager**.
It supports most of the functionality that command line tools provide.
The Qubes VM Manager starts and opens automatically when Qubes starts up, but you can also start it by going to Start → System Tools → Qubes Manager.
Once the Qubes VM Manager is running, you can open the window at any time by clicking on the Qubes tray icon, which typically resides in the bottom-right corner of the screen.
Alternatively, you can use a suite of GUI tools, most of which are available through desktop widgets:
![r2b1-qubes-manager-2.png](/attachment/wiki/GettingStarted/r2b1-qubes-manager-2.png)
- The **Domains Widget** allows you to manage running qubes, turn them on and off, and monitor memory usage.
- The **Devices Widget** allows you to attach and detach devices -- such as USB drives and cameras -- to qubes.
- The **Disk Space Widget** will notify you if you're ever running out of disk space.
- The **Updates Widget** will inform you when template updates are available.
Starting Apps in qubes
------------------------
![q40_widgets.png](/attachment/wiki/GettingStarted/q40_widgets.png)
Apps can be started either by using the shortcuts in the Desktop Manager's menu or by using the command line (i.e., a console running in dom0).
For an overview of the entire system, you can use the **Qube Manager** (go to the Application Launcher → System Tools → Qube Manager), which displays the states of all the qubes in your system.
You can start apps directly from the Start Menu or the Application Finder (Alt-F3).
Each qube has its own menu directory under the scheme **Domain: \<name\>**.
Starting apps
-------------
Apps can be started either by using the shortcuts in the Application Launcher menu or by using the command line (i.e., a terminal running in dom0).
You can start apps directly from the Application Launcher or the Application Finder (`Alt+F3`).
Each qube has its own menu directory under the scheme `Domain: <name>`.
After navigating into one of these directories, simply click on the application you'd like to start:
![r2b1-appsmenu-1.png](/attachment/wiki/GettingStarted/r2b1-appsmenu-1.png) ![r2b1-appsmenu-3.png](/attachment/wiki/GettingStarted/r2b1-appsmenu-3.png)
![menu1.png](/attachment/wiki/GettingStarted/menu1.png)
![menu2.png](/attachment/wiki/GettingStarted/menu2.png)
By default, each qube's menu contains only a few shortcuts.
If you'd like to add more, simply click **Add more shortcuts...**, select the desired applications, and click **OK**.
You can also add shortcuts manually.
(This is sometimes necessary if the desired application doesn't show up in the Qubes VM Manager window.)
To do this in KDE, right-click on the **Start** button and click **Menu Editor**.
Click the qube directory in which you'd like the menu to appear, click **New Item**, enter its name as **\<qube name\>: \<app name\>**, and provide the command for starting the app (see below).
Then click **Save** and wait approximately 15 seconds for the changes to propagate to the KDE menu.
If you'd like to add more, enter the qube's **Qube Settings** and add them on the Applications tab.
To start apps from the console in dom0, type:
To start apps from the terminal in dom0, type:
qvm-run -a <qube> "<app name> [arguments]"
$ qvm-run <qube_name> <app_command> [arguments]
e.g.:
qvm-run -a untrusted firefox
$ qvm-run untrusted firefox
The -a parameter will start the qube if it is not already running.
This command will start the qube if it is not already running.
Adding, Removing, and Listing qubes
-------------------------------------
A qube can easily be added and removed by clicking on the **Add** and **Remove** buttons in the Qubes VM Manager.
Adding, removing, and listing qubes
-----------------------------------
A qube can also be added, removed, and qubes may be listed from the command line (i.e., a console running in dom0) using the following tools:
You can easily create a new qube with the **Create Qubes VM** option in the Application Launcher.
If you need to add or remove qubes, simply use the Qube Manager's **Add** and **Remove** buttons.
- `qvm-create`
- `qvm-remove`
- `qvm-ls`
You can also add, remove, and list qubes from the command line using the following tools:
How Many Qubes Do I Need?
---------------------------
- `qvm-create`
- `qvm-remove`
- `qvm-ls`
How many qubes do I need?
-------------------------
That's a great question, but there's no one-size-fits-all answer.
It depends on the structure of your digital life, and this is at least a little different for everyone.
If you plan on using your system for work, then it also depends on what kind of job you do.
It's a good idea to start out with the three qubes created automatically by the installer: work, personal, and untrusted.
Then, if and when you start to feel that some activity just doesn't fit into any of your existing qubes, or you want to partition some part of your life, you can easily create a new qube for it.
You'll also be able to easily copy any files you need to the newly created qube, as explained [here](/doc/copying-files/).
If and when you start to feel that some activity just doesn't fit into any of your existing qubes, or you want to partition some part of your life, you can easily create a new qube for it.
You'll also be able to easily [copy][copy-files] any files you need to the newly created qube.
More paranoid people might find it worthwhile to read [this article](https://blog.invisiblethings.org/2011/03/13/partitioning-my-digital-life-into.html), which describes how one of the Qubes authors partitions her digital life into security domains.
Still not sure?
You might find it helpful to read [this article][partitioning], which describes how one of the Qubes OS architects partitions her digital life into security domains.
Common Tasks
------------
Here are the documentation pages for some of the main actions you'll want to perform.
A full list is available in the [Common Tasks](/doc/#common-tasks) section of the documentation.
Important tasks
---------------
* [Copying and Pasting Text Between Domains](/doc/copy-paste/)
* [Copying and Moving Files Between Domains](/doc/copying-files/)
* [Copying from (and to) dom0](/doc/copy-from-dom0/)
* [Updating Software in dom0](/doc/software-update-dom0/)
* [Updating and Installing Software in VMs](/doc/software-update-vm/)
* [Backup, Restoration, and Migration](/doc/backup-restore/)
* [Using DisposableVMs](/doc/disposablevm/)
* [Using and Managing USB Devices](/doc/usb/)
It's very important to [keep Qubes updated][update] to ensure you have the latest security updates.
Frequently updating is one of the best ways to remain secure against new threats.
Running an application Full Screen
----------------------------------
It's also very important to make regular backups so that you don't lose your data unexpectedly.
The [Qubes backup system] allows you to do this securely and easily.
By default, Qubes doesn't allow any application window to occupy the entire screen such that its window name (which includes the name of the qube to which it belongs) and colored window border are no longer visible.
This is a security precaution designed to prevent a situation in which an application which has been allowed to enter full screen mode begins to emulate the entire Qubes system.
The user should always be able to identify which qube is displaying any given window.
Otherwise, a compromised qube which is able to occupy the entire screen could trick the user into thinking that she is interacting with a variety of different qubes (including dom0), when in fact she is interacting with only a single, compromised qube pretending to be the whole system.
Here are some other tasks you're likely to want to perform.
(A full list is available in the [Common Tasks] section of the documentation.)
**Note:** A similar attack is possible even *without* fullscreen mode.
Since a compromised qube can draw pixels within its own windows however it likes, it could draw a fake password prompt, for example, which appears to have a different colored border so that it looks like it belongs to a different qube.
This is why you should always drag such prompts away from other windows (or use some other means of manipulating the windows) to ensure that they belong to the qube to which they appear to belong.
* [Copying and Pasting Text Between Domains][copy-paste]
* [Copying and Moving Files Between Domains][copy-files]
* [Copying from (and to) dom0]
* [Fullscreen Mode]
* [DisposableVMs]
* [Device Handling] (block, USB, and PCI devices)
To allow a qube to enter full screen mode, one should edit the `/etc/qubes/guid.conf` file in dom0.
If you encounter any problems, please visit the [Help, Support, and Mailing Lists] page.
To allow all qubes to enter full screen mode, set `allow_fullscreen` flag to `true` in the `global` section:
global: {
# default values
allow_fullscreen = false;
#allow_utf8_titles = false;
#secure_copy_sequence = "Ctrl-Shift-c";
#secure_paste_sequence = "Ctrl-Shift-v";
#windows_count_limit = 500;
};
[getting-started-32]: /getting-started-32/
[downloading]: /downloads/
[installing]: /doc/installation-guide/
[virtual machines (VMs)]: /doc/glossary/#vm
[qubes]: /doc/glossary/#qube
[security domain]: /doc/glossary/#domain
[template]: /doc/glossary/#templatevm
[dom0]: /doc/glossary/#dom0
[dom0-precautions]: /doc/security-guidelines/#dom0-precautions
[tools]: /doc/tools/
[partitioning]: https://blog.invisiblethings.org/2011/03/13/partitioning-my-digital-life-into.html
[update]: /doc/updating-qubes-os/
[Qubes backup system]: /doc/backup-restore/
[Common Tasks]: /doc/#common-tasks
[copy-files]: /doc/copying-files/
[copy-paste]: /doc/copy-paste/
[Copying from (and to) dom0]: /doc/copy-from-dom0/
[Fullscreen Mode]: /doc/full-screen-mode/
[DisposableVMs]: /doc/disposablevm/
[Device Handling]: /doc/device-handling/
[Help, Support, and Mailing Lists]: /support/
To allow only select qubes to enter full screen mode, create a per-VM section, and set `allow_fullscreen` flag there to `true`:
VM: {
work: {
allow_fullscreen = true;
};
};
In order for the changes to take effect, restart the qube(s).
More details can be found [here](/doc/full-screen-mode/).
<hr class="more-top more-bottom">
<div class="row">
<div class="col-lg-4 col-md-4">
<div class="col-lg-4 col-md-4 more-bottom">
<h2>Compatible Hardware</h2>
<p>Ready to install Qubes? Make sure your hardware is compatible, as Qubes cannot run on every type of computer. Also, check out <a href="/doc/certified-laptops/">Qubes-certified Laptops</a>.</p>
<p>Make sure your hardware is compatible, as Qubes OS cannot run on every type of computer. Also, check out <a href="/doc/certified-laptops/">Qubes-certified Laptops</a>.</p>
<a href="/hcl/" class="btn btn-primary">
<i class="fa fa-laptop"></i> Hardware Compatibility List
</a>
</div>
<div class="col-lg-4 col-md-4">
<div class="col-lg-4 col-md-4 more-bottom">
<h2>Downloads</h2>
<p>Download an ISO, learn how to verify its authenticity and integrity, and follow our guides to install Qubes. Looking for the source code? You'll find it on <a href="https://github.com/QubesOS">GitHub</a>.</p>
<p>Download an ISO, learn how to verify its authenticity and integrity, and follow our guides to install Qubes OS. Looking for the source code? You'll find it on <a href="https://github.com/QubesOS">GitHub</a>.</p>
<a href="/downloads/" class="btn btn-primary">
<i class="fa fa-download"></i> Downloads
</a>
</div>
<div class="col-lg-4 col-md-4">
<h2>Documentation</h2>
<p>Peruse our extensive library of documentation for users and developers of Qubes. You can even help us <a href="/doc/doc-guidelines/">improve</a> it!</p>
<p>Peruse our extensive library of documentation for users and developers of Qubes OS. You can even help us <a href="/doc/doc-guidelines/">improve</a> it!</p>
<a href="/doc/" class="btn btn-primary">
<i class="fa fa-book"></i> Documentation
</a>
</div>
</div>
<hr class="more-top more-bottom">

19
user/common-tasks/software-update-domu.md
View File

@ -91,15 +91,18 @@ The following sections cover advanced topics pertaining to installing and updati
### RPMFusion for Fedora TemplateVMs
If you would like to enable the [RPM Fusion] repository, open a Terminal of the TemplateVM and type the following commands:
If you would like to enable the [RPM Fusion] repositories, open a Terminal of the TemplateVM and type the following commands, depending on which RPM Fusion repositories you wish to enable (see [RPM Fusion] for details):
~~~
sudo dnf config-manager --set-enabled rpmfusion-free rpmfusion-nonfree
sudo dnf config-manager --set-enabled rpmfusion-free
sudo dnf config-manager --set-enabled rpmfusion-free-updates
sudo dnf config-manager --set-enabled rpmfusion-nonfree
sudo dnf config-manager --set-enabled rpmfusion-nonfree-updates
sudo dnf upgrade --refresh
~~~
## Reverting changes to a TemplateVM
### Reverting changes to a TemplateVM
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.
@ -117,7 +120,7 @@ If you want to undo changes to a TemplateVM, there are three basic methods:
However, it is a bit more complex.
### Root revert
#### Root revert
**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.
@ -132,12 +135,12 @@ Just make sure to **back up** all of your data and changes first!
qvm-volume revert <template>:root
### Reinstall the template
#### Reinstall the template
Please see [How to Reinstall a TemplateVM].
### Full revert
#### Full revert
This is like the simple revert, except:
@ -198,7 +201,7 @@ Example policy file in R4.0 (with Whonix installed, but not set as default Updat
@anyvm @anyvm deny
```
# Installing Snap Packages
### Installing Snap Packages
Snap packages do not use the normal update channels for Debian and Fedora (apt and dnf) and are often installed as the user rather than as root. To support these in an AppVM you need to take the following steps:
@ -268,7 +271,7 @@ Then go to the Applications tab and click "Refresh Applications"
The refresh will take a few minutes; after it's complete the Snap app will appear in the AppVM's list of available applications. At this point the snap will be persistent within the AppVM and will receive updates when the AppVM is running.
# Autostarting Installed Applications
### Autostarting Installed Applications
If you want a desktop app to start automatically every time a qube starts you can create a link to it in the `~/.config/autostart` directory of the **AppVM**. This might be useful for Qubes that you set to automatically start on boot or for Qubes that have a set of apps you typically use all day, such as a chat app.

91
user/downloading-installing-upgrading/install-security.md
View File

@ -1,6 +1,6 @@
---
layout: doc
title: Installation Security
title: Installation security
permalink: /doc/install-security/
redirect_from:
- /en/doc/install-security/
@ -8,81 +8,84 @@ redirect_from:
- /wiki/InstallSecurity/
---
# Installation Security Considerations #
# Installation security
There are several security matters to consider before and during the Qubes installation process.
## Verifying the Qubes ISO ##
## Trusting your hardware
You should [verify] the PGP signature on your Qubes ISO before you install
from it. However, if the machine on which you attempt the verification process
is already compromised, it could falsely claim that a malicious ISO has a good
signature. Therefore, in order to be certain that your Qubes ISO is trustworthy,
you require a trustworthy machine. But how can you be certain *that* machine is
trustworthy? Only by using another trusted machine, and so forth. This is a
[classic problem]. While various [solutions] have been proposed, the point is
that each user must ultimately make a choice about whether to trust that a file
is non-malicious.
No operating system, not even Qubes, can help you if you're installing it on hardware that is already compromised.
This includes CPUs, GPUs, SSDs, HDDs, the motherboard, BIOS/EFI/UEFI, and all relevant firmware.
Unfortunately, in today's world of undetectable supply chain attacks, there are no easy solutions.
(Tools like [Anti Evil Maid (AEM)][AEM] can help with *maintaining* the trustworthiness of your hardware, but not with establishing it in the first place.)
Some users have chosen to use tools like [Coreboot], [Heads], and [Skulls].
## Verifying the Qubes ISO
## Choosing an Installation Medium ##
You should [verify] the PGP signature on your Qubes ISO before you install from it.
However, if the machine on which you attempt the verification process is already compromised, it could falsely claim that a malicious ISO has a good signature.
Therefore, in order to be certain that your Qubes ISO is trustworthy, you require a trustworthy machine.
But how can you be certain *that* machine is trustworthy?
Only by using another trusted machine, and so forth.
This is a [classic problem].
While various [solutions] have been proposed, the point is that each user must ultimately make a choice about whether to trust that a file is non-malicious.
So, after taking some measures to verify its integrity and authenticity, you've
decided to trust your Qubes ISO. Great! Now you must decide what sort of medium
on which to write it so that you can install from it. From a Qubes-specific
security perspective, each has certain pros and cons.
## Choosing an installation medium
So, after taking some measures to verify its integrity and authenticity, you've decided to trust your Qubes ISO.
Great!
Now you must decide what sort of medium on which to write it so that you can install from it.
From a Qubes-specific security perspective, each has certain pros and cons.
### USB Drives ###
### USB drives
Pros:
* Works via USB, including with a [USB qube].
* Non-fixed capacity. (Easy to find one on which the ISO can fit.)
* Non-fixed capacity.
(Easy to find one on which the ISO can fit.)
Cons:
* Rewritable. (If the drive is mounted to a compromised machine, the ISO could
be maliciously altered after it has been written to the drive.)
* Untrustworthy firmware. (Firmware can be malicious even if the drive is new.
Plugging a drive with rewritable firmware into a compromised machine can
also [compromise the drive][BadUSB]. Installing from a compromised drive
could compromise even a brand new Qubes installation.)
* Rewritable.
(If the drive is mounted to a compromised machine, the ISO could be maliciously altered after it has been written to the drive.)
* Untrustworthy firmware.
(Firmware can be malicious even if the drive is new.
Plugging a drive with rewritable firmware into a compromised machine can also [compromise the drive][BadUSB].
Installing from a compromised drive could compromise even a brand new Qubes installation.)
### Optical Discs ###
### Optical discs
Pros:
* Read-only available. (If you use read-only media, you don't have to worry
about the ISO being maliciously altered after it has been written to the
disc. You then have the option of verifying the signature on multiple
different machines.)
* Read-only available.
(If you use read-only media, you don't have to worry about the ISO being maliciously altered after it has been written to the disc.
You then have the option of verifying the signature on multiple different machines.)
Cons:
* Fixed capacity. (If the size of the ISO is larger than your disc, it will be
inconvenient.)
* Passthrough recording (a.k.a., "burning") is not supported by Xen. (This
mainly applies if you're upgrading from a previous version of Qubes.)
Currently, the only options for recording optical discs (e.g., CDs, DVDs,
BRDs) in Qubes are:
* Fixed capacity.
(If the size of the ISO is larger than your disc, it will be inconvenient.)
* Passthrough recording (a.k.a., "burning") is not supported by Xen.
(This mainly applies if you're upgrading from a previous version of Qubes.)
Currently, the only options for recording optical discs (e.g., CDs, DVDs, BRDs) in Qubes are:
1. Use a USB optical drive.
2. Attach a SATA optical drive to a secondary SATA controller, then assign
this secondary SATA controller to an AppVM.
2. Attach a SATA optical drive to a secondary SATA controller, then assign this secondary SATA controller to an AppVM.
3. Use a SATA optical drive attached to dom0.
(Option 3 violates the Qubes security model since it entails transferring an
untrusted ISO to dom0 in order to burn it to disc, which leaves only the
other two options.)
(Option 3 violates the Qubes security model since it entails transferring an untrusted ISO to dom0 in order to burn it to disc, which leaves only the other two options.)
Considering the pros and cons of each, perhaps a USB drive with non-rewritable
(or at least cryptographically-signed) firmware and a physical write-protect
switch might be the option.
Considering the pros and cons of each, perhaps a USB drive with non-rewritable (or at least cryptographically-signed) firmware and a physical write-protect switch might be the best option.
[AEM]: /doc/anti-evil-maid/
[verify]: /security/verifying-signatures/
[classic problem]: https://www.ece.cmu.edu/~ganger/712.fall02/papers/p761-thompson.pdf
[solutions]: https://www.dwheeler.com/trusting-trust/
[USB qube]: /doc/usb-qubes/#creating-and-using-a-usb-qube
[BadUSB]: https://srlabs.de/badusb/
[Coreboot]: https://www.coreboot.org/
[Heads]: http://osresearch.net/
[Skulls]: https://github.com/merge/skulls

408
user/downloading-installing-upgrading/installation-guide.md
View File

@ -1,6 +1,6 @@
---
layout: doc
title: Installation Guide
title: Installation guide
permalink: /doc/installation-guide/
redirect_from:
- /en/doc/installation-guide/
@ -14,171 +14,177 @@ redirect_from:
- /doc/InstallationGuideR2rc2/
- /doc/InstallationGuideR3.0rc1/
- /doc/InstallationGuideR3.0rc2/
- /doc/live-usb/
---
Installation Guide
==================
# Installation guide
Welcome to the Qubes OS installation guide!
This guide will walk you through the process of installing Qubes.
Please read it carefully and thoroughly, as it contains important information for ensuring that your Qubes OS installation is functional and secure.
Pre-installation
----------------
## Pre-installation
### Hardware Requirements ###
### Hardware requirements
<div class="alert alert-danger" role="alert">
<i class="fa fa-exclamation-triangle"></i>
<b>Warning:</b> Qubes has no control over what happens on your computer before you install it.
No software can provide security if it is installed on compromised hardware.
Do not install Qubes on a computer you don't trust.
See <a href="/doc/install-security/">installation security</a> for more information.
</div>
Qubes OS has very specific [system requirements].
To ensure compatibility, we strongly recommend using [Qubes-certified hardware].
Other hardware may require you to perform significant troubleshooting.
You may also find it helpful to consult the [Hardware Compatibility List].
Even on supported hardware, you must ensure that [IOMMU-based virtualization](https://en.wikipedia.org/wiki/Input%E2%80%93output_memory_management_unit#Virtualization) is activated in the BIOS.
Even on supported hardware, you must ensure that [IOMMU-based virtualization] is activated in the BIOS.
Without it, Qubes OS won't be able to enforce isolation.
For Intel-based boards, this setting is called Intel Virtualization for Directed I/O (**Intel VT-d**) and for AMD-based boards, it is called AMD I/O Virtualization Technology (or simply **AMD-Vi**).
This parameter should be activated in your computer's BIOS, alongside the standard Virtualization (**Intel VT-x**) and AMD Virtualization (**AMD-V**) extensions.
This [external guide](https://www.intel.in/content/www/in/en/support/articles/000007139/server-products.html) made for Intel-based boards can help you figure out how to enter your BIOS to locate and activate those settings.
This [external guide][intel-guide] made for Intel-based boards can help you figure out how to enter your BIOS to locate and activate those settings.
If those settings are not nested under the Advanced tab, you might find them under the Security tab.
<div class="alert alert-info" role="alert">
<i class="fa fa-question-circle"></i>
<b>Note : </b> As Qubes OS has no control over what is happening before it takes control over the hardware, the motherboard firmware, which is responsible for bootstrapping the hardware and checking it, must be trusted, alongside the hardware itself.
<div class="alert alert-warning" role="alert">
<i class="fa fa-exclamation-circle"></i>
<b>Note:</b> Qubes OS is not meant to be installed inside a virtual machine as a guest hypervisor.
In other words, <b>nested virtualization</b> is not supported.
In order for a strict compartmentalization to be enforced, Qubes OS needs to be able to manage the hardware directly.
</div>
<div class="alert alert-success" role="alert">
<i class="fa fa-info-circle"></i>
<b>Tip : </b> It is up to the user to pick a combination of firmware and hardware that is trustworthy enough.
One can think of <a href="https://www.coreboot.org/">Coreboot</a> and its security-oriented implementation <a href="http://osresearch.net/">Heads</a>, or <a href="https://github.com/merge/skulls">Skulls</a>, which strives to be easy to use.
At present, they are only compatible with the Lenovo Thinkpad X230. See <a href="/doc/certified-hardware">Qubes-certified hardware</a> for other ideas.
### Copying the ISO onto the installation medium
Start by [downloading][downloads] a Qubes ISO.
<div class="alert alert-danger" role="alert">
<i class="fa fa-exclamation-triangle"></i>
<b>Warning:</b> Any file you download from the internet could be malicious, even if it appears to come from a trustworthy source.
Our philosophy is to <a href="/faq/#what-does-it-mean-to-distrust-the-infrastructure">distrust the infrastructure</a>.
Regardless of how you acquire your Qubes ISO, <a href="/security/verifying-signatures/">verify its authenticity</a> before continuing.
</div>
<div class="alert alert-info" role="alert">
<i class="fa fa-question-circle"></i>
<b>Note : </b> Qubes OS is not meant to be installed inside a virtual machine as a guest hypervisor.
In other terms, <b>nested virtualization</b> is not supported.
In order for a strict compartmentalization to be enforced, Qubes OS needs to be able to manage the hardware directly.
Once the ISO has been verified as authentic, you should copy it onto the installation medium of your choice, such as a dual-layer DVD, a Blu-ray disc, or a USB drive.
The size of each Qubes ISO is available on the [downloads] page by hovering over the download button.
<div class="alert alert-warning" role="alert">
<i class="fa fa-exclamation-circle"></i>
<b>Note:</b> There are important <a href="/doc/install-security/">security considerations</a> to keep in mind when choosing an installation medium.
</div>
### Downloading the ISO ###
See the [downloads] page for ISO downloads. Remember, Qubes OS' team have absolutely no control over those servers, so you should consider that they might be compromised, or just be serving compromised ISOs because their operators decided so, for whatever reason.
Always verify the digital signature on the downloaded ISO. Read our guide on [verifying signatures] for more information about how to download and verify our PGP keys and verify the downloaded ISO.
### Copying the ISO onto the installation medium ###
Once the ISO has been verified as authentic, you should copy it onto the installation medium of your choice, such as a dual-layer DVD, a Blu-ray disc, or a USB key.
(The size of each Qubes ISO is listed on the [downloads] page.)
(Note that there are important [security considerations] to keep in mind when choosing an installation medium.)
<div class="alert alert-danger" role="alert">
<i class="fa fa-exclamation-triangle"></i>
<b>Warning:</b> Be careful to choose the correct device when copying the ISO, or you may lose data.
We strongly recommended making a full backup before modifying any devices.
</div>
If you choose to use a USB drive, copy the ISO onto the USB device, e.g. using `dd`:
$ sudo dd if=Qubes-R3-x86_64.iso of=/dev/sdX status=progress bs=1048576 && sync
Change `Qubes-R3-x86_64.iso` to the filename of the version you're installing, and change `/dev/sdX` to the correct target device e.g., `/dev/sdc`).
$ sudo dd if=Qubes-RX-x86_64.iso of=/dev/sdY status=progress bs=1048576 && sync
Change `Qubes-RX-x86_64.iso` to the filename of the version you're installing, and change `/dev/sdY` to the correct target device e.g., `/dev/sdc`).
Make sure to write to the entire device (e.g., `/dev/sdc`) rather than just a single partition (e.g., `/dev/sdc1`).
<div class="alert alert-danger" role="alert">
<i class="fa fa-exclamation-circle"></i>
<b>Attention : </b> Choosing the wrong device could result in data loss.
</div>
On Windows, you can use the [Rufus] tool to write the ISO to a USB key.
MediaTest is not recommended.
Be sure to select "DD image" mode (you need to do that **after** selecting the Qubes ISO):
Be sure to select "DD image" mode (*after* selecting the Qubes ISO):
<div class="alert alert-danger" role="alert">
<i class="fa fa-exclamation-circle"></i>
<b>Attention : </b> If you do that on Windows 10, you can only install Qubes without MediaTest, which isn’t recommended.
<div class="alert alert-warning" role="alert">
<i class="fa fa-exclamation-circle"></i>
<b>Note:</b> If you do this on Windows 10, you can only install Qubes without MediaTest, which is not recommended.
</div>
![Rufus menu](/attachment/wiki/InstallationGuide/rufus-menu.png)
![Rufus DD image mode](/attachment/wiki/InstallationGuide/rufus-dd-image-mode.png)
If you are an advanced user and you would like to customize your installation, please see [Custom Installation]. Otherwise, follow the instructions below.
If you are an advanced user, and you would like to customize your installation, please see [custom installation].
Otherwise, follow the instructions below.
<div class="alert alert-info" role="alert">
<i class="fa fa-question-circle"></i>
<b>Note : </b> This guide will demonstrate a simple installation using mostly default settings.
</div>
## Installation
Installation
------------
This section will demonstrate a simple installation using mostly default settings.
### Getting to the boot screen ###
### Getting to the boot screen
Just after you power on your machine, make the Qubes OS medium available to the computer by inserting the DVD or USB key you have previously copied the Qubes OS image to.
Just after you power on your machine, make the Qubes OS medium available to the computer by inserting your DVD or USB drive.
Shortly after the Power-on self-test (POST) is completed, you should be greeted with the Qubes OS boot screen.
![Boot screen](/attachment/wiki/InstallationGuide/boot-screen.png)
<div class="alert alert-info" role="alert">
<i class="fa fa-info-circle"></i>
<b>Note : </b> On UEFI install, there is no boot menu on Qubes OS 4.0 by design.
It goes straight to the installer.
The boot menu will be back in Qubes OS 4.1.
<i class="fa fa-info-circle"></i>
<b>Note:</b> When installing Qubes OS 4.0 on UEFI, there is intentionally no boot menu.
It goes straight to the installer.
The boot menu will be back in Qubes OS 4.1.
</div>
From there, you can navigate the boot screen using the arrow keys on your keyboard. Pressing the "Tab" key will reveal options.
You can choose one of three options : install Qubes OS ; test this media and install Qubes OS ; troubleshooting. Select the option to test this media and install Qubes OS.
From here, you can navigate the boot screen using the arrow keys on your keyboard.
Pressing the "Tab" key will reveal options.
You can choose one of three options:
* Install Qubes OS
* Test this media and install Qubes OS
* Troubleshooting
Select the option to test this media and install Qubes OS.
If the boot screen does not appear, there are several options to troubleshoot.
First, try rebooting your computer.
If it still loads your currently installed operating system or does not pick up your installation medium, make sure the boot order is set up appropriately.
If it still loads your currently installed operating system or does not detect your installation medium, make sure the boot order is set up appropriately.
The process to change the boot order varies depending on the currently installed system and the motherboard manufacturer.
If **Windows 10** is installed on your machine, you may need to follow specific instructions to change the boot order. This may require an [advanced reboot](https://support.microsoft.com/en-us/help/4026206/windows-10-find-safe-mode-and-other-startup-settings).
Ideally, you would temporarily select the USB device or DVD drive as a boot up option, so that the next time you boot, your internal storage device will be selected first.
If **Windows 10** is installed on your machine, you may need to follow specific instructions to change the boot order.
This may require an [advanced reboot].
<div class="alert alert-success" role="alert">
<i class="fa fa-info-circle"></i>
<b>Tip : </b> After the POST, you may have a chance to temporally pick a booting device.
</div>
After the POST, you may have a chance to choose a boot device.
You may wish to select the USB drive or DVD drive as a temporary boot option so that the next time you boot, your internal storage device will be selected first.
![Boot order](/attachment/wiki/InstallationGuide/boot-order.png)
### The installer home screen ###
### The installer home screen
On the first screen, you are asked to pick the language that will be used during the installation process.
When you are done, select "Continue".
On the first screen, you are asked to select the language that will be used during the installation process.
When you are done, select **Continue**.
<img src="/attachment/wiki/InstallationGuide/welcome-to-qubes-os-installation-screen.png">
![welcome](/attachment/wiki/InstallationGuide/welcome-to-qubes-os-installation-screen.png)
Prior to the next screen, a compatibility test runs to check whether IOMMU-virtualization is active or not.
If the test fails, a window will pop up.
![Unsupported hardware detected](/attachment/wiki/InstallationGuide/unsupported-hardware-detected.png)
Do not panic : it may simply indicate that IOMMU-virtualization hasn't been activated in the BIOS.
Return to the [Hardware Requirements](/doc/installation-guide/#hardware-requirements) section to learn how to activate it.
If the setting is not configured correctly, it means that your hardware won't be able to leverage some of Qubes OS security features such as a strict isolation of the network and USB adapter.
Do not panic.
It may simply indicate that IOMMU-virtualization hasn't been activated in the BIOS.
Return to the [hardware requirements] section to learn how to activate it.
If the setting is not configured correctly, it means that your hardware won't be able to leverage some Qubes security features, such as a strict isolation of the networking and USB hardware.
If the test passes, you will reach the Installation summary screen.
If the test passes, you will reach the installation summary screen.
The installer loads Xen right at the beginning.
If you can see the installer's graphical screen, and you pass the compatibility check that runs immediately afterward, Qubes OS is likely to work on your system!
<div class="alert alert-info" role="alert">
<i class="fa fa-info-circle"></i>
<b>Note : </b> The installer loads Xen right at the beginning, so if you can see the installer's graphical screen and you pass the compatibility check that runs immediately after that, Qubes OS is likely to work on your system !
Like Fedora, Qubes OS uses the Anaconda installer.
Those that are familiar with RPM-based distributions should feel at home.
### Installation summary
<div class="alert alert-success" role="alert">
<i class="fa fa-check-circle"></i>
<b>Did you know?</b> The Qubes OS installer is completely offline.
It doesn't even load any networking drivers, so there is no possibility of internet-based data leaks or attacks during the installation process.
</div>
<div class="alert alert-info" role="alert">
<i class="fa fa-question-circle"></i>
<b>Note : </b> Like Fedora, Qubes OS uses the Anaconda installer.
Those that are familiar with RPM-based distributions should feel at home.
</div>
### Installation summary ###
The Installation summary screen allows you to change how the end-system will be installed and configured, including localization settings.
At minimum, you are required to pick a storage device on which Qubes OS will be installed.
The Installation summary screen allows you to change how the system will be installed and configured, including localization settings.
At minimum, you are required to select the storage device on which Qubes OS will be installed.
![Installation summary not ready](/attachment/wiki/InstallationGuide/installation-summary-not-ready.png)
### Localization ###
### Localization
Let's assume you wish to add a German keyboard layout.
Go to Keyboard Layout, press the "Plus" symbol, search for "German" as indicated in the screenshot and press "Add".
If you want it be your default language, select the "German" entry in the list and press the arrow button.
Click on "Done" in the upper left corner and you are ready to go !
Let's assume you wish to add a German keyboard layout.
Go to Keyboard Layout, press the "Plus" symbol, search for "German" as indicated in the screenshot and press "Add".
If you want it be your default language, select the "German" entry in the list and press the arrow button.
Click on "Done" in the upper left corner, and you're ready to go!
![Keyboard layout selection](/attachment/wiki/InstallationGuide/keyboard-layout-selection.png)
@ -187,151 +193,185 @@ Follow the same process in the "Language Support" entry.
![Language support selection](/attachment/wiki/InstallationGuide/language-support-selection.png)
<div class="alert alert-info" role="alert">
<i class="fa fa-question-circle"></i>
<b>Note : </b> You can have as many keyboard layout and languages as you want.
Post-install, you will be able to switch between them and install others.
</div>
You can have as many keyboard layout and languages as you want.
Post-install, you will be able to switch between them and install others.
Don't forget to select your time and date by clicking on the Time & Date entry.
![Time and date](/attachment/wiki/InstallationGuide/time-and-date.png)
### Software ###
Under the Software section, you can change the installation source.
As we are demonstrating a simple installation, it is assumed that you are installing Qubes OS using a local medium such as a DVD, so this option won't be illustrated.
### Software
![Add-ons](/attachment/wiki/InstallationGuide/add-ons.png)
Go instead to the Software selection tab, where you can choose which software to install alongside Qubes OS.
Two Add-Ons are available :
On the software selection tab, you can choose which software to install in Qubes OS.
Two options are available:
* **Debian template** : Install these templates if you wish to base some of your Qubes virtual machines on Debian instead of Fedora.
* **Whonix** : Install Whonix templates if you wish for some of your qubes to be based on Whonix.
Whonix lets you route all of your network traffic through Tor if you see fit.
For more information about Whonix, have a look at their [website](https://www.whonix.org/).
* **Debian:** Select this option if you would like to use [Debian] qubes in addition to the default Fedora qubes.
* **Whonix:** Select this option if you would like to use [Whonix] qubes.
Whonix allows you to use [Tor] securely within Qubes.
Whonix lets you route some or all of your network traffic through Tor for greater privacy.
Depending on your threat model, you may need to install Whonix templates right away.
Note that you will also be able to install Add-Ons after the installation is completed.
If you wish for your system to be more lightweight, do not hesitate to un-check those options.
Regardless of your choices on this screen, you will always be able to install these and other [TemplateVMs] later.
If you're short on disk space, you may wish to deselect these options.
<div class="alert alert-info" role="alert">
<i class="fa fa-question-circle"></i>
<b> Note : </b> By default, Qubes OS comes preinstalled with the lightweight Xfce desktop environment for dom0, the main domain.
Other desktop environments will be available to you after the installation is completed, although they may not be officially supported.
By default, Qubes OS comes preinstalled with the lightweight Xfce4 desktop environment.
Other desktop environments will be available to you after the installation is completed, though they may not be officially supported (see [advanced configuration]).
Press **Done** to go back to the installation summary screen.
### Installation destination
Under the System section, you must choose the installation destination.
Select the storage device on which you would like to install Qubes OS.
<div class="alert alert-danger" role="alert">
<i class="fa fa-exclamation-triangle"></i>
<b>Warning:</b> Be careful to choose the correct installation target, or you may lose data.
We strongly recommended making a full backup before proceeding.
</div>
Click on "Done" as soon as you have made your choice to go back to Installation summary screen.
### Installation destination ###
Your installation destination can be an internal or external storage drive, such as an SSD, HDD, or USB drive.
The installation destination must have a least 32 GiB of free space available.
Under the System section, you need to pick the installation destination.
For this step to be completed, you need to select which storage device you would like your system to be installed on. Under the Device Selection section, make sure that you select the correct installation destination.
Ensure that your your target destination has a least 32 GiB of free space available.
<div class="alert alert-warning" role="alert">
<i class="fa fa-exclamation-circle"></i>
<b>Note:</b> The installation destination cannot be the same as the installation medium. For example, if you're installing Qubes OS <em>from</em> a USB drive <em>onto</em> a USB drive, they must be two distinct USB drives, and they must both be plugged into your computer at the same time. (Note: This may not apply to advanced users who partition their devices appropriately.)
</div>
For this setup, options will be left unchanged.
By default, Qubes OS will partition the system itself with LVM on top of LUKS encryption, and will claim the entire storage device.
Installing an operating system onto a USB drive can be a convenient way to try Qubes.
However, USB drives are typically much slower than internal SSDs.
We recommend a very fast USB 3.0 drive for decent performance.
Please note that a minimum storage of 32 GiB is required.
If you want to install Qubes OS onto a USB drive, just select the USB device as the target installation device.
Bear in mind that the installation process is likely to take longer than it would on an internal storage device.
![Select storage device](/attachment/wiki/InstallationGuide/select-storage-device.png)
<div class="alert alert-danger" role="alert">
<i class="fa fa-exclamation-circle"></i>
<b>Attention : </b> Any data on the target storage device will eventually be deleted during the installation process, so make your selection carefully (a separate confirmation dialog will appear if there are available partitions on the disk).
<div class="alert alert-success" role="alert">
<i class="fa fa-check-circle"></i>
<b>Did you know?</b> Qubes OS uses full-disk AES encryption (FDE) via LUKS by default.
</div>
As soon as you leave the current window by pressing "Done", Qubes OS will ask you to pick a passphrase to unlock encrypted partition.
The passphrase should be complex. Keep it in a safe place.
Make sure that your keyboard layout reflects what keyboard you are actually using and click on "Done" to start the installation process!
As soon as you press **Done**, the installer will ask you to enter a passphrase for disk encryption.
The passphrase should be complex.
Make sure that your keyboard layout reflects what keyboard you are actually using.
When you're finished, press **Done**.
<div class="alert alert-danger" role="alert">
<i class="fa fa-exclamation-triangle"></i>
<b>Warning:</b> If you forget your encryption passphrase, there is no way to recover it.
</div>
![Select storage passhprase](/attachment/wiki/InstallationGuide/select-storage-passphrase.png)
Installing an operating system onto a USB drive can be a convenient and secure method of ensuring that your data is protected and remains portable.
If you want to install Qubes OS onto a USB drive, just select the USB device as the storage location for the OS.
Be advised that a minimum storage of 32 GB is required and that a *fast* USB 3.0 compatible drive is mandatory to achieve decent performance.
Also, bear in mind that the installation process is likely to take longer than an installation on a internal storage disk.
<div class="alert alert-info" role="alert">
<i class="fa fa-question-circle"></i>
<b>Note : </b> See <a href="/doc/custom-install/">the Custom Installation</a> for more options.
</div>
You are now ready to go. Press the "Begin Installation" button.
When you're ready, press **Begin Installation**.
![Installation summary ready](/attachment/wiki/InstallationGuide/installation-summary-ready.png)
### Pick your user name ###
### Create your user account
While the installation is ongoing, a new user needs to be created. Click on "User Creation" to define a new user with administrator privileges and a password.
Just as for the disk encryption, this password should be complex. The root account is deactivated and should remain as such.
While the installation process is running, you can create your user account.
This is what you'll use to log in after disk decryption and when unlocking the screen locker.
This is a purely local, offline account in dom0.
By design, Qubes OS is a single-user operating system, so this is just for you.
Select **User Creation** to define a new user with administrator privileges and a password.
Just as for the disk encryption, this password should be complex.
The root account is deactivated and should remain as such.
![Account name and password](/attachment/wiki/InstallationGuide/account-name-and-password.png)
When the installation is complete, click on the "Reboot" button.
Don't forget to remove the installation media, otherwise you may end up seeing the Qubes OS boot screen again.
When the installation is complete, press **Reboot**.
Don't forget to remove the installation medium, or else you may end up seeing the installer boot screen again.
<div class="alert alert-info" role="alert">
<i class="fa fa-question-circle"></i>
<b>Note : </b> By design, Qubes OS is a single user operating system.
</div>
## Post-installation
Post-installation
-----------------
### First boot
### First boot ###
If Qubes OS has been successfully installed, you should see the GRUB menu during the booting process.
If the installation was successful, you should now see the GRUB menu during the boot process.
![Grub boot menu](/attachment/wiki/InstallationGuide/grub-boot-menu.png)
Just after this screen, you will be asked to unlock your storage device.
Just after this screen, you will be asked to enter your encryption passphrase.
![Unlock storage device screen](/attachment/wiki/InstallationGuide/unlock-storage-device-screen.png)
### Initial Setup ###
### Initial Setup
You're almost done. Before you can start using Qubes OS, some configuration is needed.
By default, Qubes OS will create a number of qubes, based on Fedora templates or Whonix templates, so that you can have a more ready-to-use environnement from the get-go.
You're almost done.
Before you can start using Qubes OS, some configuration is needed.
![Initial setup menu](/attachment/wiki/InstallationGuide/initial-setup-menu.png)
* **Create default system qubes** : it is recommended to use system qubes as they offer some of the core functionalities brought by Qubes OS, including network isolation and disposable qubes
* **Create default application qubes** : application qubes are pre-configured qubes meant to be used for specific purposes, such as work or personal.
* **Create Whonix Gateway and Workstation qubes** : in order to be able to use Tor for dedicated qubes, you need this option to be activated.
* **Enabling system and template updates over the Tor anonymity network using Whonix** : this option allows the use of Tor system-wide rather than only for specific qubes.
* **Create USB qube holding all USB controllers** : just like the network qube for the network stack, the USB qube allows to capture the USB controller and to manage USB devices through it.
* **Use sys-net qube for both networking and USB devices** : it saves some memory as only sys-net will be running, instead of sys-net and sys-usb, but also allows easy use of USB networking devices (like 3G/LTE modems) directly in sys-net.
* **Do not configure anything** : This is only for advanced users, as you won't have network access out of the box.
By default, the installer will create a number of qubes (depending on the options you selected during the installation process).
These are designed to give you a more ready-to-use environment from the get-go.
![Initial setup menu configuration](/attachment/wiki/InstallationGuide/initial-setup-menu-configuration.png)
When you are satisfied with you choices, click on "Done".
Pre-selected qubes will be installed and configured, which can take up to 15 minutes.
Let's briefly go over the options:
After the configuration is done, you will be greeted by a login screen. Enter your password and log in.
* **Create default system qubes:**
These are the core components of the system, required for things like internet access.
* **Create default application qubes:**
These are how you compartmentalize your digital life.
There's nothing special about the ones the installer creates.
They're just suggestions that apply to most people.
If you decide you don't want them, you can always delete them later, and you can always create your own.
* **Create Whonix Gateway and Workstation qubes:**
If you want to use Whonix, you should select this option.
* **Enabling system and template updates over the Tor anonymity network using Whonix:**
If you select this option, then whenever you install or update software in dom0 or a TemplateVM, the internet traffic will go through Tor.
* **Create USB qube holding all USB controllers:**
Just like the network qube for the network stack, the USB qube isolates the USB controllers.
* **Use sys-net qube for both networking and USB devices:**
You should select this option if you rely on a USB device for network access, such as a USB modem or a USB Wi-Fi adapter.
* **Do not configure anything:**
This is for very advanced users only.
If you select this option, you'll have to set everything up manually afterward.
When you're satisfied with you choices, press **Done**.
This configuration process may take a while, depending on the speed and compatibility of your system.
After the configuration is done, you will be greeted by the login screen.
Enter your password and log in.
![Login screen](/attachment/wiki/InstallationGuide/login-screen.png)
Congratulations, you are now ready to use Qubes OS !
Congratulations, you are now ready to use Qubes OS!
![Desktop menu](/attachment/wiki/InstallationGuide/desktop-menu.png)
Upgrading Qubes OS
------------------
## Next steps
For instructions on upgrading an existing installation, see [Upgrade Guides].
### Updating
Getting Help
------------
Next, [update] your installation to ensure you have the latest security updates.
Frequently updating is one of the best ways to remain secure against new threats.
### Backups
It is extremely important to make regular backups so that you don't lose your data unexpectedly.
The [Qubes backup system] allows you to do this securely and easily.
### Get Started
[Get Started] with Qubes, and read more about [Common Tasks] and [Managing Operating Systems within Qubes].
## Getting help
* We work very hard to make the [documentation] accurate, comprehensive useful and user friendly.
We urge you to read it! It may very well contain the answers to your questions.
(Since the documentation is a community effort, we'd also greatly appreciate your help in [improving] it!)
We urge you to read it! It may very well contain the answers to your questions.
(Since the documentation is a community effort, we'd also greatly appreciate your help in [improving] it!)
* 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].
* If you don't find your answer in the documentation, please see [Help, Support, Mailing Lists, and Forum] for places to ask.
* Please do **not** email individual members of the Qubes team with questions about installation or other problems.
Instead, please see [Help, Support, Mailing Lists, and Forum] for appropriate places to ask questions.
* 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.
[QSB #46]: /news/2019/01/23/qsb-46/
[system requirements]: /doc/system-requirements/
@ -346,6 +386,20 @@ Getting Help
[Rufus]: https://rufus.akeo.ie/
[documentation]: /doc/
[improving]: /doc/doc-guidelines/
[mailing lists]: /support/
[help]: /help/
[Help, Support, Mailing Lists, and Forum]: /support/
[update]: /doc/updating-qubes-os/
[Qubes backup system]: /doc/backup-restore/
[Common Tasks]: /doc/#common-tasks
[Managing Operating Systems within Qubes]: /doc/#managing-operating-systems-within-qubes
[installation security]: /doc/install-security/
[IOMMU-based virtualization]: https://en.wikipedia.org/wiki/Input%E2%80%93output_memory_management_unit#Virtualization
[intel-guide]: https://web.archive.org/web/20200112220913/https://www.intel.in/content/www/in/en/support/articles/000007139/server-products.html
[advanced reboot]: https://support.microsoft.com/en-us/help/4026206/windows-10-find-safe-mode-and-other-startup-settings
[hardware requirements]: #hardware-requirements
[Debian]: /doc/templates/debian/
[Whonix]: /doc/whonix/
[Tor]: https://www.torproject.org/
[TemplateVMs]: /doc/templates/
[advanced configuration]: /doc/#advanced-configuration
[Get Started]: /getting-started/

125
user/downloading-installing-upgrading/live-usb.md
View File

@ -1,125 +0,0 @@
---
layout: doc
title: Live USB
permalink: /doc/live-usb/
---
Qubes Live USB (alpha)
======================
NOTE: This content applies to Qubes versions earlier than R3.2. See the
[Installation Guide](/doc/installation-guide/) for instructions and warnings
on creating a USB boot drive for testing purposes with Qubes R3.2, R4.0, and
higher.
Qubes Live USB allows you to run and try Qubes OS without having to install it
anywhere. Qubes Live USB is currently in alpha. If you use it, please consider
running the [HCL reporting tool](/hcl/) and sending us the results so that we
can continue to improve it. If would like to contribute to the Qubes OS
Project by improving Qubes Live USB and integrating it with the installer,
please consider applying for a [Google Summer of Code][gsoc-page] scholarship
(if you are eligible) and choosing the QubesOS Project as a mentor
organization. You can find our list of project ideas [here][project-page].
Introduction
------------
When making this Live USB edition of Qubes OS, we faced several challenges which
traditional Linux distros don't have to bother with:
1. We needed to ensure Xen is properly started when booting the stick. In fact
we still don't support UEFI boot for the stick for this reason, even though
the Fedora liveusb creator we used does support it. Only legacy boot for this
version, sorry.
2. We discovered that the Fedora liveusb-create does *not* verify signatures on
downloaded packages. We have temporarily fixed that by creating a local repo,
verifying the signatures manually (ok, with a script ;) ) and then building
from there. Sigh.
3. We had to solve the problem of Qubes too easily triggering an Out Of Memory
condition in Dom0 when running as Live OS.
This last problem has been a result of Qubes using the copy-on-write backing for
the VMs' root filesystems, which is used to implement our cool
[Template-based scheme](/doc/software-update-vm/). Normally these are backed by
regular files on disk. Even though these files are discardable upon VM reboots,
they must be preserved during the VM's life span, and they can easily grow to a
few tens of MBs per VM, sometimes even more. Also, each VM's private
image, which essentially holds just the user home directory, typically starts
with a few tens of MBs for an "empty VM". Now, while these represent rather
insignificant numbers on a disk-basked system, in the case of a live USB all
these files must be stored in RAM, which is a scarce resource on any OS, but
especially on Qubes.
We have implemented some quick optimizations in order to minimize the above
problem, but this is still far from a proper solution. We're planning to work
more on this next.
There are three directions in which we want to do further work on this Qubes
Live USB variant:
1. Introduce an easy, clickable "install to disk" option, merging this with the
Qubes installation ISO. So, e.g. make it possible to first see if the given
hardware is compatible with Qubes (by running the HCL reporting tool) and
only then install on the main disk. Also, ensure UEFI boot works well.
2. Introduce options for persistence while still running this out of a USB
stick. This would be achieved by allowing (select) VMs' private images to be
stored on the r/w partition (or on another stick).
A nice variant of this persistence option, especially for frequent
travelers, would be to augment our backup tools so that it was
possible to create a LiveUSB-hosted backups of select VMs. One could then
pick a few of their VMs, necessary for a specific trip, back them up to a
LiveUSB stick, and take this stick when traveling to a hostile country (not
risking taking other, more sensitive ones for the travel). This should make
life a bit simpler
[for some](https://twitter.com/rootkovska/status/541980196849872896).
3. Introduce more useful preconfigured VMs setup, especially including
Whonix/Tor VMs.
Current limitations
-------------------
(Remember that Qubes Live USB is currently in alpha, so please meter your
expectations accordingly.)
1. Currently just the 3 example VMs (untrusted, personal, work), plus the
default net and firewall VMs are created automatically.
2. The user has an option to manually (i.e. via command line) create an
additional partition, e.g. for storing GPG keyring, and then mounting it to
select VMs. This is to add poor-man's persistence. We will be working on
improving/automating that, of course.
3. Currently there is no "install to disk" option. We will be adding this
in the future.
4. The amount of "disk" space is limited by the amount of RAM the laptop
has. This has a side effect of e.g. not being able to restore (even a few) VMs
from a large Qubes backup blob.
5. It's easy to generate Out Of Memory (OOM) in Dom0 by creating lots of VMs
which are writing a lot into the VMs filesystem.
6. There is no DispVM savefile, so if you start a DispVM the savefile must be
regenerated, which takes about 1-2 minutes.
7. UEFI boot doesn't work, and if you try booting Qubes Live USB via UEFI, Xen
will not be started, rendering the whole experiment unusable.
Downloading and burning
-----------------------
1. Download the ISO (and its signature for verification) from the
[downloads page](/downloads/#qubes-live-usb-alpha).
2. "Burn" (copy) the ISO onto a USB drive (replace `/dev/sdX` with your USB
drive device):
$ sudo dd if=Qubes-R3.0-rc2-x86_64-LIVE.iso of=/dev/sdX
Note that you should specify the whole device, (e.g. `/dev/sdc`, not a single
partition, e.g. `/dev/sdc1`).
**Caution:** It is very easy to misuse the `dd` command. If you mix up `if`
and `of` or specify an incorrect device, you could accidentally overwrite
your primary system drive. Please be careful!
[project-page]: /gsoc/
[gsoc-page]: https://summerofcode.withgoogle.com/organizations/6239659689508864/

9
user/downloading-installing-upgrading/supported-versions.md
View File

@ -47,7 +47,7 @@ The table below shows the OS used for dom0 in each Qubes OS release.
| Release 3.1 | Fedora 20 |
| Release 3.2 | Fedora 23 |
| Release 4.0 | Fedora 25 |
| Release 4.1 | Fedora 31 |
| Release 4.1 | Fedora 32 |
### Note on dom0 and EOL
@ -68,8 +68,8 @@ The following table shows the [TemplateVM] versions **available** for each Qubes
| Release 3.0 | 21, 22\*, 23 | 7 ("wheezy")\*, 8 ("jessie") | None |
| Release 3.1 | 21, 22\*, 23 | 7 ("wheezy")\*, 8 ("jessie"), 9 ("stretch")\* | None |
| Release 3.2 | 23\*, 24\*, 25\*, 26, 27, 28 | 8 ("jessie"), 9 ("stretch") | 13, 14 |
| Release 4.0 | 26, 27, 28, 29, 30, 31 | 8 ("jessie"), 9 ("stretch"), 10 ("buster") | 13, 14, 15 |
| Release 4.1 | 26, 27, 28, 29, 30, 31 | 8 ("jessie"), 9 ("stretch"), 10 ("buster") | 13, 14, 15 |
| Release 4.0 | 26, 27, 28, 29, 30, 31, 32 | 8 ("jessie"), 9 ("stretch"), 10 ("buster") | 13, 14, 15 |
| Release 4.1 | 32 | 10 ("buster") | 15 |
\* Denotes versions for which we have published the packages but have not done
extensive testing.
@ -96,8 +96,9 @@ Qubes support for each [Fedora] TemplateVM ends when that Fedora release reaches
| Fedora 27 | Unsupported |
| Fedora 28 | Unsupported |
| Fedora 29 | Unsupported |
| Fedora 30 | Supported |
| Fedora 30 | Unsupported |
| Fedora 31 | Supported |
| Fedora 32 | Supported |
### Debian

7
user/downloading-installing-upgrading/upgrade/upgrade-to-r4.0.md
View File

@ -44,7 +44,7 @@ Backup R3.2
7. If your backup verifies successfully, proceed to the next section.
If it does not, **stop**.
Go back and repeat the backup steps, review the documentation or search the qubes-users mailing list, or ask for assistance on the [qubes-users mailing list](/support/#qubes-users) or IRC.
Go back and repeat the backup steps, review the documentation, and ask for [help].
Install R4.0
@ -62,7 +62,7 @@ For further details, please see the [installation guide](/doc/installation-guide
If you did not successfully verify your backup in the previous section, cancel the installation, and go back to do that now.
3. Complete the R4.0 installation.
Ask for assistance on the [qubes-users mailing list](/support/#qubes-users) if you run into trouble.
Ask for [help] if you run into trouble.
4. If you are unable to successfully install R4.0 on your system, all is not lost.
Use the R3.2 installer to reinstall R3.2, then restore from your backup.
@ -119,3 +119,6 @@ Please see [Supported Versions](/doc/supported-versions/) for information on sup
* [Upgrading Debian TemplateVMs](/doc/templates/debian/#upgrading)
* [Updating Whonix TemplateVMs](https://www.whonix.org/wiki/Qubes/Update)
[help]: /support/

14
user/downloading-installing-upgrading/version-scheme.md
View File

@ -39,11 +39,11 @@ production. You may ask for support on mailing lists (specifically
When enough development has been made, we announce the first stable version,
like e.g. `3.0.0` (i.e. without `-rc`). This version is considered stable and
we support it for some period. Core components are branched at this moment and
bugfixes are backported from master branch. Questions about stable release
should be directed to the **qubes-users** mailing list. No major features and
interface incompatibilities are to be included in this release. We release
bugfixes as `3.0.1`, `3.0.2` and so on, while new features come into the next
release e.g. `3.1-rcX`.
bugfixes are backported from master branch. Please see [Help, Support, Mailing
Lists, and Forum] for places to ask questions about stable releases. No major
features and interface incompatibilities are to be included in this release. We
release bugfixes as `3.0.1`, `3.0.2` and so on, while new features come into the
next release e.g. `3.1-rcX`.
Tickets in the tracker are sorted out by release major.minor, such as `3.0`,
`3.1` (trac calls this “milestone”).
@ -155,3 +155,7 @@ Check installed version
If you want to know which version you are running, for example to report
an issue, you can either check in the Qubes Manager menu under About / Qubes OS or in the file /etc/qubes-release in dom0. For the latter you can use a command like `cat /etc/qubes-release` in a dom0 terminal.
[Help, Support, Mailing Lists, and Forum]: /support/

21
user/hardware/certified-hardware.md
View File

@ -21,15 +21,15 @@ See [Hardware Testing] for details.
## Qubes-certified Laptops
Qubes-certified laptops are regularly tested by the Qubes developers to ensure compatibility with all of Qubes' features.
The developers test all new major versions and updates to ensure that no regressions are introduced.
Qubes-certified laptops are certified for a [major version][version-scheme] and regularly tested by the Qubes developers to ensure compatibility with all of Qubes' features within that major version.
The developers test all new updates within that major version to ensure that no regressions are introduced.
### Insurgo PrivacyBeast X230
[![insurgo-privacybeast-x230.png](/attachment/site/insurgo-privacybeast-x230.png)][Insurgo PrivacyBeast X230]
The [Insurgo PrivacyBeast X230] meets and exceeds our hardware certification requirements.
The [Insurgo PrivacyBeast X230] meets and exceeds our hardware certification requirements for Qubes 4.
Read our [announcement][privacybeast announcement] of the certification for further details!
@ -37,7 +37,7 @@ Read our [announcement][privacybeast announcement] of the certification for furt
[![nitropad-x230.jpg](/attachment/site/nitropad-x230.jpg)][NitroPad X230]
The [NitroPad X230] satisfies all hardware certification requirements, offering users extensive hardware security options.
The [NitroPad X230] satisfies all hardware certification requirements for Qubes 4, offering users extensive hardware security options.
## Become Hardware Certified
@ -45,15 +45,17 @@ The [NitroPad X230] satisfies all hardware certification requirements, offering
If you are a hardware vendor, you can have your hardware certified as compatible with Qubes OS.
The benefits of hardware certification include:
* Your customers can purchase with confidence, knowing that they can take full advantage of Qubes OS on your hardware.
* Your hardware will continue to be compatible with Qubes OS as it further develops.
* Your customers can purchase with confidence, knowing that they can take full advantage of Qubes OS on your hardware for a specific major version.
* We will continue testing your hardware to ensure compatibility with the supported major version.
In the course of this testing, we will also test your hardware against upcoming versions, which can help with future planning.
* Your hardware will continue to be compatible with Qubes OS as it further develops within that major version, and we will work with you toward preserving compatibility and certification in future releases.
* You can support the development of Qubes OS.
## Hardware Certification Requirements
(Please note that these are the requirements for hardware *certification*, *not* the requirements for *running* Qubes 4.x.
For the latter, please see the [system requirements for Qubes 4.x].)
(Please note that these are the requirements for hardware *certification*, *not* the requirements for *running* Qubes 4.
For the latter, please see the [system requirements for Qubes 4].)
One of the most important security improvements introduced with the release of Qubes 4.0 was to replace paravirtualization (PV) technology with **hardware-enforced memory virtualization**, which recent processors have made possible thanks to so-called Second Level Address Translation ([SLAT]), also known as [EPT][EPT-enabled CPUs] in Intel parlance.
SLAT (EPT) is an extension to Intel VT-x virtualization, which originally was capable of only CPU virtualization but not memory virtualization and hence required a complex Shadow Page Tables approach.
@ -97,12 +99,13 @@ While we are willing to troubleshoot simple issues, we will need to charge a con
If you are interested in having your hardware certified, please [contact us].
[version-scheme]: /doc/version-scheme/
[Hardware Testing]: /doc/hardware-testing/
[stateless laptop]: https://blog.invisiblethings.org/2015/12/23/state_harmful.html
[System Requirements]: /doc/system-requirements/
[Hardware Compatibility List]: /hcl/
[Hardware Certification]: #hardware-certification
[system requirements for Qubes 4.x]: /doc/system-requirements/#qubes-release-4x
[system requirements for Qubes 4]: /doc/system-requirements/#qubes-release-4x
[contact us]: mailto:business@qubes-os.org
[SLAT]: https://en.wikipedia.org/wiki/Second_Level_Address_Translation
[EPT-enabled CPUs]: https://ark.intel.com/Search/FeatureFilter?productType=processors&ExtendedPageTables=true&MarketSegment=Mobile

5
user/managing-os/debian/debian-upgrade.md
View File

@ -1,6 +1,6 @@
---
layout: doc
title: Upgrading Debian TemplateVMs
title: In-place upgrade of Debian TemplateVMs
permalink: /doc/template/debian/upgrade/
redirect_from:
- /doc/template/debian/upgrade-8-to-9/
@ -13,7 +13,7 @@ redirect_from:
# Upgrading Debian TemplateVMs
This page provides instructions for performing an in-place upgrade of an installed [Debian TemplateVM].
If you wish to install a new, unmodified Debian TemplateVM instead of upgrading a template that is already installed in your system, please see the [Debian TemplateVM] page instead.
If you wish to install a new, unmodified Debian TemplateVM instead of upgrading a template that is already installed in your system, please see the [Debian TemplateVM] page instead. ([Learn more about the two options.][Debian TemplateVM Upgrade])
In general, upgrading a Debian TemplateVM follows the same process as [upgrading a native Debian system][upgrade].
@ -152,6 +152,7 @@ We strongly recommend against using any Debian release that has reached [end-of-
[Debian TemplateVM]: /doc/templates/debian/
[Debian TemplateVM Upgrade]: /doc/templates/debian/#upgrading
[upgrade]: https://wiki.debian.org/DebianUpgrade
[switch]: /doc/templates/#switching
[jessie]: https://www.debian.org/releases/jessie/amd64/release-notes/ch-upgrading.en.html

8
user/managing-os/debian/debian.md
View File

@ -41,12 +41,16 @@ After installing a fresh Debian TemplateVM, we recommend performing the followin
## Updating
Please see [Updating software in TemplateVMs].
For routine daily TemplateVM updates within a given Debian release, see [Updating software in TemplateVMs].
## Upgrading
Please see [Upgrading Debian TemplateVMs].
There are two ways to upgrade your TemplateVM to a new Debian release:
- [Install a fresh template to replace the existing one.](#installing) This option may be simpler for less experienced users. After you install the new template, redo all desired template modifications and [switch everything that was set to the old template to the new template][switch]. You may want to write down the modifications you make to your templates so that you remember what to redo on each fresh install. In the old Debian template, see `/var/log/dpkg.log` and `/var/log/apt/history.log` for logs of package manager actions.
- [Perform an in-place upgrade of an existing Debian template.][Upgrading Debian TemplateVMs] This option will preserve any modifications you've made to the template, but it may be more complicated for less experienced users.
## Release-specific notes

11
user/managing-os/fedora/fedora-upgrade.md
View File

@ -1,6 +1,6 @@
---
layout: doc
title: Upgrading Fedora TemplateVMs
title: In-place upgrade of Fedora TemplateVMs
permalink: /doc/template/fedora/upgrade/
redirect_from:
- /doc/template/fedora/upgrade-26-to-27/
@ -24,7 +24,7 @@ redirect_from:
# Upgrading Fedora TemplateVMs
This page provides instructions for performing an in-place upgrade of an installed [Fedora TemplateVM].
If you wish to install a new, unmodified Fedora TemplateVM instead of upgrading a template that is already installed in your system, please see the [Fedora TemplateVM] page instead.
If you wish to install a new, unmodified Fedora TemplateVM instead of upgrading a template that is already installed in your system, please see the [Fedora TemplateVM] page instead. ([Learn more about the two options.][Fedora TemplateVM Upgrade])
## Summary instructions for standard Fedora TemplateVMs
@ -194,14 +194,11 @@ In this case, you have several options:
However, you may end up having to increase the disk image size anyway (see previous option).
3. Do the upgrade in parts, e.g., by using package groups.
(First upgrade `@core` packages, then the rest.)
4. Do not perform an in-place upgrade.
Instead, simply download and install a new template package, then redo all desired template modifications.
Here are some useful messages from the mailing list that also apply to TemplateVM management and migration in general from
[Marek](https://groups.google.com/d/msg/qubes-users/mCXkxlACILQ/dS1jbLRP9n8J) and
[Jason M](https://groups.google.com/d/msg/qubes-users/mCXkxlACILQ/5PxDfI-RKAsJ).
4. Do not perform an in-place upgrade, see [Upgrading Fedora TemplateVMs].
[Fedora TemplateVM]: /doc/templates/fedora/
[Fedora TemplateVM Upgrade]: /doc/templates/fedora/#upgrading
[resize-disk-image]: /doc/resize-disk-image/
[Additional Information]: #additional-information
[switch]: /doc/templates/#switching

32
user/managing-os/fedora/fedora-xfce.md
View File

@ -1,32 +0,0 @@
---
layout: doc
title: The Fedora Xfce TemplateVM
permalink: /doc/templates/fedora-xfce/
---
The Fedora Xfce TemplateVM
=====================
If you would like to use Fedora Xfce (more lightweight compared to GNOME desktop environment) Linux distribution in your qubes, you can install one of the available Fedora Xfce templates.
Installing
----------
To install a specific Fedora Xfce TemplateVM that is not currently installed in your system, use the following command in dom0:
$ sudo qubes-dom0-update --enablerepo=qubes-templates-itl qubes-template-fedora-XX-xfce
(Replace `XX` with the Fedora Xfce version number of the template you wish to install.)
To reinstall a Fedora Xfce TemplateVM that is already installed in your system, see [How to Reinstall a TemplateVM].
Upgrading
---------
To upgrade your Fedora TemplateVM, please see [Upgrading Fedora TemplateVMs].
[Upgrading Fedora TemplateVMs]: /doc/template/fedora/upgrade/
[How to Reinstall a TemplateVM]: /doc/reinstall-template/

16
user/managing-os/fedora/fedora.md
View File

@ -6,7 +6,7 @@ permalink: /doc/templates/fedora/
# The Fedora TemplateVM
The Fedora [TemplateVM] is the default TemplateVM in Qubes OS. This page is about the standard (or "full") Fedora TemplateVM. For the minimal and Xfce versions, please see the [Minimal TemplateVMs] and [Fedora Xfce] pages.
The Fedora [TemplateVM] is the default TemplateVM in Qubes OS. This page is about the standard (or "full") Fedora TemplateVM. For the minimal and Xfce versions, please see the [Minimal TemplateVMs] and [Xfce TemplateVMs] pages.
## Installing
@ -33,24 +33,21 @@ After installing a fresh Fedora TemplateVM, we recommend performing the followin
## Updating
Please see [Updating software in TemplateVMs].
For routine daily updates within a given release, see [Updating software in TemplateVMs].
## Upgrading
Please see [Upgrading Fedora TemplateVMs].
There are two ways to upgrade your TemplateVM to a new Fedora release:
- [Install a fresh template to replace the existing one.](#installing) This option may be simpler for less experienced users. After you install the new template, redo all desired template modifications and [switch everything that was set to the old template to the new template][switch]. You may want to write down the modifications you make to your templates so that you remember what to redo on each fresh install. To see a log of package manager actions, open a terminal in the old Fedora template and use the `dnf history` command.
## Release-specific notes
This section contains notes about specific Fedora releases.
(There is currently no release-specific information documented.)
- [Perform an in-place upgrade of an existing Fedora template.][Upgrading Fedora TemplateVMs] This option will preserve any modifications you've made to the template, but it may be more complicated for less experienced users.
[TemplateVM]: /doc/templates/
[Fedora Xfce]: /doc/templates/fedora-xfce/
[Minimal TemplateVMs]: /doc/templates/minimal/
[Xfce TemplateVMs]: /doc/templates/xfce/
[end-of-life]: https://fedoraproject.org/wiki/Fedora_Release_Life_Cycle#Maintenance_Schedule
[supported]: /doc/supported-versions/#templatevms
[How to Reinstall a TemplateVM]: /doc/reinstall-template/
@ -60,3 +57,4 @@ This section contains notes about specific Fedora releases.
[Updating software in TemplateVMs]: /doc/software-update-domu/#updating-software-in-templatevms
[Upgrading Fedora TemplateVMs]: /doc/template/fedora/upgrade/
[install]: /doc/templates/#installing

18
user/managing-os/minimal-templates.md
View File

@ -16,7 +16,7 @@ redirect_from:
The Minimal [TemplateVMs] are lightweight versions of their standard TemplateVM counterparts.
They have 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.
There are currently three Minimal TemplateVMs corresponding to the standard [Fedora], [Debian] and [CentOS] TemplateVMs.
There are currently three Minimal TemplateVMs corresponding to the standard [Fedora], [Debian], [CentOS] and [Gentoo] TemplateVMs.
## Important
@ -25,7 +25,9 @@ There are currently three Minimal TemplateVMs corresponding to the standard [Fed
If you encounter problems with the Minimal TemplateVMs, we recommend that you use their standard TemplateVM counterparts instead.
2. If something works with a standard TemplateVM but not the minimal version, 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].
In such cases, please do *not* file a bug report.
Instead, please see [Help, Support, Mailing Lists, and Forum] for the appropriate place to ask for help.
Once you have learned how to solve your problem, please [contribute what you learned to the documentation][doc-guidelines].
3. The Minimal TemplateVMs are intentionally *minimal*.
[Do not ask for your favorite package to be added to the minimal template by default.][pref-default]
@ -92,7 +94,8 @@ As usual, the required packages are to be installed in the running template with
- NetVM, such as the template for `sys-net`: `qubes-core-agent-networking` `qubes-core-agent-network-manager` `NetworkManager-wifi` `network-manager-applet` `wireless-tools` `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-usb-proxy` to provide USB devices to other Qubes and `qubes-input-proxy-sender` to provide keyboard or mouse input to dom0.
- [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.
- `default-mgmt-dvm`: requires `qubes-core-agent-passwordless-root` and `qubes-mgmt-salt-vm-connector`.
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:
@ -113,7 +116,7 @@ Also, there are packages to provide additional services:
- `qubes-pdf-converter`: For implementing safe conversion of PDFs.
- `qubes-img-converter`: For implementing safe conversion of images.
- `qubes-snapd-helper`: If you want to use snaps in qubes.
- `qubes-thunderbird`: Additional tools for use in thunderbird.
- `thunderbird-qubes`: Additional tools for use in thunderbird.
- `qubes-app-shutdown-idle`: If you want qubes to automatically shutdown when idle.
- `qubes-mgmt-salt-vm-connector`: If you want to use salt management on the template and qubes.
@ -143,7 +146,8 @@ As usual, the required packages are to be installed in the running template with
- NetVM, such as the template for `sys-net`: `qubes-core-agent-networking` `qubes-core-agent-network-manager`. If your network devices need extra packages for a network VM, use the `lspci` command to identify the devices, then find the package that provides necessary firmware and install it. If you need utilities for debugging and analyzing network connections, install the following packages: `tcpdump` `telnet` `nmap` `nmap-ncat`.
- [USB qube](/doc/usb-qubes/), such as the template for `sys-usb`: `qubes-usb-proxy` to provide USB devices to other Qubes and `qubes-input-proxy-sender` to provide keyboard or mouse input to dom0.
- [VPN qube](/doc/vpn/): You may need to install network-manager VPN packages, depending on the VPN technology you'll be using. After creating 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.
- `default-mgmt-dvm`: requires `qubes-core-agent-passwordless-root` and `qubes-mgmt-salt-vm-connector`.
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:
@ -184,6 +188,7 @@ As usual, the required packages are to be installed in the running template with
- NetVM, such as the template for `sys-net`: `qubes-core-agent-networking` `qubes-core-agent-network-manager` `NetworkManager-wifi` `network-manager-applet` `wireless-tools` `notification-daemon` `gnome-keyring`. If your network devices need extra packages for a network VM, use the `lspci` command to identify the devices, then find the package that provides necessary firnware and install it. If you need utilities for debugging and analyzing network connections, install the following packages: `tcpdump` `telnet` `nmap` `nmap-ncat`
- [USB qube](/doc/usb-qubes/), such as the template for `sys-usb`: `qubes-usb-proxy` to provide USB devices to other Qubes and `qubes-input-proxy-sender` to provide keyboard or mouse input to dom0.
- [VPN qube](/doc/vpn/): You may need to install network-manager VPN packages, depending on the VPN technology you'll be using. After creating 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.
- `default-mgmt-dvm`: requires `qubes-core-agent-passwordless-root` and `qubes-mgmt-salt-vm-connector`.
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:
@ -211,7 +216,8 @@ You could, of course, use `qubes-vm-recommended` to automatically install many o
[Fedora]: /doc/templates/fedora/
[Debian]: /doc/templates/debian/
[CentOS]: /doc/templates/centos/
[qubes-users]: /support/#qubes-users
[Gentoo]: /doc/templates/gentoo/
[Help, Support, Mailing Lists, and Forum]: /support/
[doc-guidelines]: /doc/doc-guidelines/
[pref-default]: /faq/#could-you-please-make-my-preference-the-default
[testing]: /doc/testing/

20
user/managing-os/templates.md
View File

@ -62,6 +62,8 @@ In addition, these templates may be somewhat less stable, since the Qubes develo
* [Arch Linux]
* [CentOS]
* [CentOS Minimal]
* [Gentoo]
* [Gentoo Minimal]
## Installing
@ -78,8 +80,13 @@ Usually, the installation method is to execute the following type of command in
$ sudo qubes-dom0-update qubes-template-<name>
(where `qubes-template-<name>` is the name of your TemplateVM package)
where `qubes-template-<name>` is the name of your TemplateVM package.
If you wish to install a community template, you must enable the community template repo:
$ sudo qubes-dom0-update --enablerepo=qubes-templates-community qubes-template-<name>
If you receive the message that no match is found for `qubes-template-<name>`, see [here][no-match].
## After Installing
@ -112,6 +119,10 @@ If the Applications Menu entry doesn't go away after you uninstall a TemplateVM,
$ rm ~/.local/share/applications/<template-vm-name>
Applications Menu entries for backups of removed VMs can also be found in `/usr/local/share/applications/` of dom0.
$ rm /usr/local/share/applications/<template-vm-name>
## Reinstalling
@ -252,7 +263,7 @@ Note the word "clean" means in this context: the same as their template filesyst
[TemplateBasedVMs]: /doc/glossary/#templatebasedvm
[Fedora]: /doc/templates/fedora/
[Fedora Minimal]: /doc/templates/minimal/
[Fedora Xfce]: /doc/templates/fedora-xfce
[Fedora Xfce]: /doc/templates/xfce
[Debian]: /doc/templates/debian/
[Debian Minimal]: /doc/templates/minimal/
[Whonix]: /doc/templates/whonix/
@ -260,6 +271,10 @@ Note the word "clean" means in this context: the same as their template filesyst
[Arch Linux]: /doc/building-archlinux-template/
[CentOS]: /doc/templates/centos/
[CentOS Minimal]: /doc/templates/minimal/
[CentOS Xfce]: /doc/templates/xfce
[Gentoo]: /doc/templates/gentoo/
[Gentoo Minimal]: /doc/templates/minimal/
[Gentoo Xfce]: /doc/templates/xfce
[Qubes Builder]: /doc/qubes-builder/
[TemplateVM Implementation]: /doc/template-implementation/
[How to Remove VMs Manually]: /doc/remove-vm-manually/
@ -274,3 +289,4 @@ Note the word "clean" means in this context: the same as their template filesyst
[uninstall the old TemplateVM]: #uninstalling
[Updating software in TemplateVMs]: /doc/software-update-domu/#updating-software-in-templatevms
[How to Reinstall a TemplateVM]: /doc/reinstall-template/
[no-match]: /faq/#when-i-try-to-install-a-templatevm-it-says-no-match-is-found

50
user/managing-os/xfce-templates.md Normal file
View File

@ -0,0 +1,50 @@
---
layout: doc
title: Xfce TemplateVMs
permalink: /doc/templates/xfce/
redirect_from:
- /doc/templates/xfce/
- /doc/xfce/
- /en/doc/templates/xfce/
- /doc/Templates/Xfce/
- /wiki/Templates/Xfce/
---
# Xfce TemplateVMs
If you would like to use Xfce (more lightweight compared to GNOME desktop environment) Linux distribution in your qubes,
you can install one of the available Xfce templates for [Fedora], [CentOS] or [Gentoo].
## Installation
The Fedora Xfce TemplateVMs can be installed with the following command (where `X` is your desired distro and version number):
[user@dom0 ~]$ sudo qubes-dom0-update qubes-template-X-xfce
If your desired version is not found, it may still be in [testing].
You may wish to try again with the testing repository enabled:
[user@dom0 ~]$ sudo qubes-dom0-update --enablerepo=qubes-templates-itl-testing qubes-template-X-xfce
If you would like to install a community distribution, like CentOS or Gentoo, try the install command by enabling the community repository:
[user@dom0 ~]$ sudo qubes-dom0-update --enablerepo=qubes-templates-community qubes-template-X-xfce
If your desired version is not found, it may still be in [testing].
You may wish to try again with the testing repository enabled:
[user@dom0 ~]$ sudo qubes-dom0-update --enablerepo=qubes-templates-community-testing qubes-template-X-xfce
The download may take a while depending on your connection speed.
To reinstall a Xfce TemplateVM that is already installed in your system, see [How to Reinstall a TemplateVM].
[How to Reinstall a TemplateVM]: /doc/reinstall-template/
[TemplateVMs]: /doc/templates/
[Fedora]: /doc/templates/fedora/
[Debian]: /doc/templates/debian/
[CentOS]: /doc/templates/centos/
[Gentoo]: /doc/templates/gentoo/
[testing]: /doc/testing/

50
user/reference/glossary.md
View File

@ -36,28 +36,30 @@ A user-friendly term for a [VM](#vm) in Qubes OS.
Domain
------
An area or set of activities in one's digital life that has certain security requirements and therefore involves the use of certain [qubes](#qube).
For example, suppose your "email" domain encompasses the activity of sending PGP-encrypted email.
This domain may include your email qube and your [Split GPG](/doc/split-gpg) qube.
**In Qubes OS:** An area or set of activities in one's digital life that has certain security requirements and therefore involves the use of certain [qubes](#qube).
For example, suppose your "email" domain encompasses the activity of sending PGP-encrypted email.
This domain may include your email qube and your [Split GPG](/doc/split-gpg) qube.
Note that domains and qubes are not the same thing.
In this example, your "email" domain includes the use of two qubes.
Furthermore, a qube can fall under multiple domains simultaneously.
In this example, your "email" domain includes the use of two qubes.
Furthermore, a qube can fall under multiple domains simultaneously.
For example, your Split GPG qube may also be part of your "software development" domain if you PGP-sign your Git commits.
Dom0
**In Xen:** A synonym for [VM](#vm). See [Domain on the Xen Wiki](https://wiki.xenproject.org/wiki/Domain).
dom0
----
Domain Zero.
Also known as the **host** domain, dom0 is the initial VM started by the Xen hypervisor on boot.
Dom0 runs the Xen management toolstack and has special privileges relative to other domains, such as direct access to most hardware.
(Note that the use of "domain" for a synonym for "VM" is specific to Xen. Qubes diverges from this practice. See: [domain](#domain).)
(Note that the use of [domain](#domain) for a synonym for [VM](#vm) is specific to Xen. Qubes diverges from this practice. See: [domain](#domain).)
DomU
domU
----
Unprivileged Domain.
Also known as **guest** domains, domUs are the counterparts to dom0.
All VMs except dom0 are domUs.
By default, most domUs lack direct hardware access.
(Note that the use of "domain" for a synonym for "VM" is specific to Xen. Qubes diverges from this practice. See: [domain](#domain).)
(Note that the use of [domain](#domain) for a synonym for [VM](#vm) is specific to Xen. Qubes diverges from this practice. See: [domain](#domain).)
TemplateVM
----------
@ -85,14 +87,16 @@ Unlike TemplateVMs, however, StandaloneVMs do not supply their root filesystems
AppVM
-----
Application Virtual Machine.
A [VM](#vm) that is intended for running software applications.
Typically a TemplateBasedVM, but may be a StandaloneVM.
Never a TemplateVM.
Application Virtual Machine.
A [VM](#vm) class.
Synonymous with [TemplateBasedVM](#templatebasedvm).
NetVM
-----
Network Virtual Machine.
*This is an old definition from before Qubes 4.0.
NetVMs, as defined here, no longer exist in Qubes 4.0 or later (see [here][pr-748] for technical details).*
Network Virtual Machine.
A type of [VM](#vm) that connects directly to a network.
Other VMs gain access to a network by connecting to a NetVM (usually indirectly, via a [FirewallVM](#firewallvm)).
A NetVM called `sys-net` is created by default in most Qubes installations.
@ -102,12 +106,18 @@ For example, if `untrusted` is directly connected to `sys-firewall` for network
ProxyVM
-------
*This is an old definition from before Qubes 4.0.
ProxyVMs, as defined here, no longer exist in Qubes 4.0 or later (see [here][pr-748] for technical details).*
Proxy Virtual Machine.
A type of [VM](#vm) that proxies network access for other VMs.
Typically, a ProxyVM sits between a NetVM and another VM (such as an AppVM or a TemplateVM) that requires network access.
FirewallVM
----------
*This is an old definition from before Qubes 4.0.
FirewallVMs, as defined here, no longer exist in Qubes 4.0 or later (see [here][pr-748] for technical details).*
Firewall Virtual Machine.
A type of [ProxyVM](#proxyvm) that is used to enforce network-level policies (a.k.a. "firewall rules").
A FirewallVM called `sys-firewall` is created by default in most Qubes installations.
@ -132,14 +142,6 @@ A type of [TemplateBasedVM](#templatebasedvm) on which [DisposableVMs](#disposab
By default, a DisposableVM Template named `fedora-XX-dvm` is created on most Qubes installations (where `XX` is the Fedora version of the default TemplateVM).
DisposableVM Templates are not [TemplateVMs](#templatevm), since (being TemplateBasedVMs) they do not have root filesystems of their own to provide to other VMs.
Rather, DisposableVM Templates are complementary to TemplateVMs insofar as DisposableVM Templates provide their own user filesystems to the DisposableVMs based on them.
There are two main kinds of DisposableVM Templates:
* **Dedicated** DisposableVM Templates are intended neither for installing nor running software.
Rather, they are intended for *customizing* or *configuring* software that has already been installed on the TemplateVM on which the DisposableVM Template is based (see [DisposableVM Customization](/doc/disposablevm-customization/).
This software is then intended to be run (in its customized state) in DisposableVMs that are based on the DisposableVM Template.
* **Non-dedicated** DisposableVM Templates are typically [AppVMs](#appvm) on which DisposableVMs are based.
For example, an AppVM could be used to generate and store trusted data.
Then, a DisposableVM could be created based on the AppVM (thereby making the AppVM a DisposableVM Template) so that the data can be analyzed by an untrusted program without jeopardizing the integrity of the original data.
PV
--
@ -195,3 +197,7 @@ QWT
----
An abbreviation of Qubes [Windows Tools](#windows-tools).
[pr-748]: https://github.com/QubesOS/qubes-doc/pull/748

140
user/security-in-qubes/split-gpg.md
View File

@ -16,18 +16,16 @@ redirect_from:
# Qubes Split GPG #
## What is Split GPG and why should I use it instead of the standard GPG? ##
Split GPG implements a concept similar to having a smart card with your private GPG keys, except that the role of the "smart card" plays another Qubes AppVM.
This way one, not-so-trusted domain, e.g. the one where Thunderbird is running, can delegate all crypto operations, such as encryption/decryption and signing to another, more trusted, network-isolated, domain.
This way the compromise of your domain where Thunderbird or another client app is running -- arguably a not-so-unthinkable scenario -- does not allow the attacker to automatically also steal all your keys.
(We should make a rather obvious comment here that the so-often-used passphrases on private keys are pretty meaningless because the attacker can easily set up a simple backdoor which would wait until the user enters the passphrase and steal the key then.)
The diagram below presents the big picture of Split GPG architecture.
[![split-gpg-diagram.png](/attachment/wiki/SplitGpg/split-gpg-diagram.png)](/attachment/wiki/SplitGpg/split-gpg-diagram.png)
![split-gpg-diagram.png](/attachment/wiki/SplitGpg/split-gpg-diagram.png)
This diagram presents an overview of the Split GPG architecture.
### Advantages of Split GPG vs. traditional GPG with a smart card ###
## Advantages of Split GPG vs. traditional GPG with a smart card ##
It is often thought that the use of smart cards for private key storage guarantees ultimate safety.
While this might be true (unless the attacker can find a usually-very-expensive-and-requiring-physical-presence way to extract the key from the smart card) but only with regards to the safety of the private key itself.
@ -39,25 +37,8 @@ Unfortunately this problem of signing reliability is not solvable by Split GPG)
With Qubes Split GPG this problem is drastically minimized, because each time the key is to be used the user is asked for consent (with a definable time out, 5 minutes by default), plus is always notified each time the key is used via a tray notification from the domain where GPG backend is running.
This way it would be easy to spot unexpected requests to decrypt documents.
![r2-split-gpg-1.png](/attachment/wiki/SplitGpg/r2-split-gpg-1.png)
![r2-split-gpg-3.png](/attachment/wiki/SplitGpg/r2-split-gpg-3.png)
### Current limitations ###
- Current implementation requires importing of public keys to the vault domain.
This opens up an avenue to attack the gpg running in the backend domain via a hypothetical bug in public key importing code.
See ticket [#474] for more details and plans how to get around this problem, as well as the section on [using Split GPG with subkeys] below.
- It doesn't solve the problem of allowing the user to know what is to be signed before the operation gets approved.
Perhaps the GPG backend domain could start a DisposableVM and have the to-be-signed document displayed there? To Be Determined.
- The Split GPG client will fail to sign or encrypt if the private key in the GnuPG backend is protected by a passphrase.
It will give an `Inappropriate ioctl for device` error.
Do not set passphrases for the private keys in the GPG backend domain.
Doing so won't provide any extra security anyway, as explained [above][intro] and [below][using Split GPG with subkeys].
If you are generating a new key pair, or if you have a private key that already has a passphrase, you can use `gpg2 --edit-key <key_id>` then `passwd` to set an empty passphrase.
Note that `pinentry` might show an error when you try to set an empty passphrase, but it will still make the change.
(See [this StackExchange answer][se-pinentry] for more information.)
[![r2-split-gpg-1.png](/attachment/wiki/SplitGpg/r2-split-gpg-1.png)](/attachment/wiki/SplitGpg/r2-split-gpg-1.png)
[![r2-split-gpg-3.png](/attachment/wiki/SplitGpg/r2-split-gpg-3.png)](/attachment/wiki/SplitGpg/r2-split-gpg-3.png)
## Configuring Split GPG ##
@ -69,11 +50,11 @@ Make sure you have the `qubes-gpg-split` package installed in the template you w
For Debian or Whonix:
[user@debian-8 ~]$ sudo apt install qubes-gpg-split
[user@debian-10 ~]$ sudo apt install qubes-gpg-split
For Fedora:
[user@fedora-25 ~]$ sudo dnf install qubes-gpg-split
[user@fedora-32 ~]$ sudo dnf install qubes-gpg-split
### Setting up the GPG backend domain ###
@ -111,9 +92,9 @@ Please be aware of the caveat regarding passphrase-protected keys in the [Curren
Normally it should be enough to set the `QUBES_GPG_DOMAIN` to the GPG backend domain name and use `qubes-gpg-client` in place of `gpg`, e.g.:
[user@work ~]$ export QUBES_GPG_DOMAIN=work-gpg
[user@work ~]$ gpg -K
[user@work ~]$ qubes-gpg-client -K
[user@work-email ~]$ export QUBES_GPG_DOMAIN=work-gpg
[user@work-email ~]$ gpg -K
[user@work-email ~]$ qubes-gpg-client -K
/home/user/.gnupg/secring.gpg
-----------------------------
sec 4096R/3F48CB21 2012-11-15
@ -121,7 +102,7 @@ Normally it should be enough to set the `QUBES_GPG_DOMAIN` to the GPG backend do
ssb 4096R/30498E2A 2012-11-15
(...)
[user@work ~]$ qubes-gpg-client secret_message.txt.asc
[user@work-email ~]$ qubes-gpg-client secret_message.txt.asc
(...)
Note that running normal `gpg -K` in the demo above shows no private keys stored in this AppVM.
@ -135,8 +116,8 @@ If you encounter trouble while trying to set up Split GPG, make sure you're usin
The `qubes-gpg-client-wrapper` script sets the `QUBES_GPG_DOMAIN` variable automatically based on the content of the file `/rw/config/gpg-split-domain`, which should be set to the name of the GPG backend VM. This file survives the AppVM reboot, of course.
[user@work ~]$ sudo bash
[root@work ~]$ echo "work-gpg" > /rw/config/gpg-split-domain
[user@work-email ~]$ sudo bash
[root@work-email ~]$ echo "work-gpg" > /rw/config/gpg-split-domain
Split GPG's default qrexec policy requires the user to enter the name of the AppVM containing GPG keys on each invocation. To improve usability for applications like Thunderbird with Enigmail, in `dom0` place the following line at the top of the file `/etc/qubes-rpc/policy/qubes.Gpg`:
@ -150,17 +131,69 @@ You may also edit the qrexec policy file for Split GPG in order to tell Qubes yo
Note that, because this makes it easier to accept Split GPG's qrexec authorization prompts, it may decrease security if the user is not careful in reviewing presented prompts. This may also be inadvisable if there are multiple AppVMs with Split GPG set up.
### Using Thunderbird + Enigmail with Split GPG ###
## Using Thunderbird ##
### Thunderbird 78 and higher
Starting with version 78, Thunderbird has a built-in PGP feature and no longer requires the Enigmail extension. For users coming from the Enigmail extension, the built-in functionality is more limited currently, including that **public keys must live in your `work-email` qube with Thunderbird rather than your offline `work-gpg` qube**.
In `work-email`, use the Thunderbird config editor (found at the bottom of preferences/options), and search for `mail.openpgp.allow_external_gnupg`. Switch the value to true. Still in config editor, search for `mail.openpgp.alternative_gpg_path`. Set its value to `/usr/bin/qubes-gpg-client-wrapper`. Restart Thunderbird after this change.
[![tb78-1.png](/attachment/wiki/SplitGpg/tb78-1.png)](/attachment/wiki/SplitGpg/tb78-1.png)
[![tb78-2.png](/attachment/wiki/SplitGpg/tb78-2.png)](/attachment/wiki/SplitGpg/tb78-2.png)
[![tb78-3.png](/attachment/wiki/SplitGpg/tb78-3.png)](/attachment/wiki/SplitGpg/tb78-3.png)
You need to obtain your key ID which should be **exactly 16 characters**. Enter the command `qubes-gpg-client-wrapper -K --keyid-format long`:
```
[user@work-email ~]$ qubes-gpg-client-wrapper -K --keyid-format long
/home/user/.gnupg/pubring.kbx
-----------------------------
sec rsa2048/777402E6D301615C 2020-09-05 [SC] [expires: 2022-09-05]
F7D2D4E922DFB7B2589AF3E9777402E6D301615C
uid [ultimate] Qubes test <user@localhost>
ssb rsa2048/370CE932085BA13B 2020-09-05 [E] [expires: 2022-09-05]
```
```
[user@work-email ~]$ qubes-gpg-client-wrapper --armor --export 777402E6D301615C > 777402E6D301615C.asc
```
Open the Account Settings and open the *End-to-End Encryption* tab of the respective email account. Click the *Add Key* button. You'll be offered the choice *Use your external key through GnuPG*. Select it and click Continue.
[![tb78-4.png](/attachment/wiki/SplitGpg/tb78-4.png)](/attachment/wiki/SplitGpg/tb78-4.png)
[![tb78-5.png](/attachment/wiki/SplitGpg/tb78-5.png)](/attachment/wiki/SplitGpg/tb78-5.png)
The key ID reference you would need here is `777402E6D301615C`. Now paste or type the ID of the secret key that you would like to use. Be careful to enter it correctly, because your input isn't verified. Confirm to save this key ID. Now you can select the key ID to use.
[![tb78-6.png](/attachment/wiki/SplitGpg/tb78-6.png)](/attachment/wiki/SplitGpg/tb78-6.png)
[![tb78-7.png](/attachment/wiki/SplitGpg/tb78-7.png)](/attachment/wiki/SplitGpg/tb78-7.png)
This key ID will be used to digitally sign or send an encrypted message with your account. For this to work, Thunderbird needs a copy of your public key. At this time, Thunderbird doesn't fetch the public key from `/usr/bin/qubes-gpg-client-wrapper`, you must manually import it. Export the key as follow (assuming the key ID would be `777402E6D301615C`):
[![tb78-8.png](/attachment/wiki/SplitGpg/tb78-8.png)](/attachment/wiki/SplitGpg/tb78-8.png)
[![tb78-9.png](/attachment/wiki/SplitGpg/tb78-9.png)](/attachment/wiki/SplitGpg/tb78-9.png)
Use Thunderbird's Tools menu to open *OpenPGP Key Management*. In that window, use the File menu to access the *Import Public Key(s) From File* command. Open the file with your public key. After the import was successful, right click on the imported key in the list and select *Key Properties*. You must mark your own key as *Yes, I've verified in person this key has the correct fingerprint*.
Once this is done, you should be able to send an encrypted and signed email by selecting *Require Encryption* or *Digitally Sign This Message* in the compose menu *Options* or *Security* toolbar button. You can try it by sending an email to yourself.
[![tb78-10.png](/attachment/wiki/SplitGpg/tb78-10.png)](/attachment/wiki/SplitGpg/tb78-10.png)
For more details about using smart cards/Split GPG with Thunderbird PGP feature, please see [Thunderbird:OpenPGP:Smartcards] from which the above documentation is inspired.
### Older Thunderbird versions
For Thunderbird versions below 78, the traditional Enigmail + Split GPG setup is required.
It is recommended to set up and use `/usr/bin/qubes-gpg-client-wrapper`, as discussed above, in Thunderbird through the Enigmail addon.
**Warning:** Before adding any account, configuring Enigmail with `/usr/bin/qubes-gpg-client-wrapper` is **required**. By default, Enigmail will generate a default GPG key in `work` associated with the newly created Thunderbird account. Generally, it corresponds to the email used in `work-gpg` associated to your private key. In consequence, a new, separate private key will be stored in `work` but it _does not_ correspond to your private key in `work-gpg`. Comparing the `fingerprint` or `expiration date` will show that they are not the same private key. In order to prevent Enigmail using this default generated local key in `work`, you can safely remove it.
**Warning:** Before adding any account, configuring Enigmail with `/usr/bin/qubes-gpg-client-wrapper` is **required**. By default, Enigmail will generate a default GPG key in `work-email` associated with the newly created Thunderbird account. Generally, it corresponds to the email used in `work-gpg` associated to your private key. In consequence, a new, separate private key will be stored in `work-email` but it _does not_ correspond to your private key in `work-gpg`. Comparing the `fingerprint` or `expiration date` will show that they are not the same private key. In order to prevent Enigmail using this default generated local key in `work-email`, you can safely remove it.
On a fresh Enigmail install, your need to change the default `Enigmail Junior Mode`. Go to Thunderbird preferences and then privacy tab. Select `Force using S/MIME and Enigmail`. Then, in the preferences of Enigmail, make it point to `/usr/bin/qubes-gpg-client-wrapper` instead of the standard GnuPG binary:
![tb-enigmail-split-gpg-settings-2.png](/attachment/wiki/SplitGpg/tb-enigmail-split-gpg-settings-2.png)
[![tb-enigmail-split-gpg-settings-2.png](/attachment/wiki/SplitGpg/tb-enigmail-split-gpg-settings-2.png)](/attachment/wiki/SplitGpg/tb-enigmail-split-gpg-settings-2.png)
### Using Keybase with Split GPG ###
## Using Keybase with Split GPG ##
Keybase, a security focused messaging and file-sharing app with GPG integration, can be configured to use Split GPG.
@ -190,7 +223,7 @@ The most basic `~/.gitconfig` file to with working Split GPG looks something lik
Your key id is the public id of your signing key, which can be found by running `qubes-gpg-client -k`.
In this instance, the key id is DD160C74.
[user@work ~]$ qubes-gpg-client -k
[user@work-email ~]$ qubes-gpg-client -k
/home/user/.gnupg/pubring.kbx
-----------------------------
pub rsa4096/DD160C74 2016-04-26
@ -214,15 +247,15 @@ Now you can use `git stag` to add a signed tag to a commit and `git vtag` to ver
## Importing public keys ###
Use `qubes-gpg-import-key` in the client AppVM to import the key into the GPG backend VM.
Of course a (safe, unspoofable) user consent dialog box is displayed to accept this.
[user@work ~]$ export QUBES_GPG_DOMAIN=work-gpg
[user@work ~]$ qubes-gpg-import-key ~/Downloads/marmarek.asc
[user@work-email ~]$ export QUBES_GPG_DOMAIN=work-gpg
[user@work-email ~]$ qubes-gpg-import-key ~/Downloads/marmarek.asc
![r2-split-gpg-5.png](/attachment/wiki/SplitGpg/r2-split-gpg-5.png)
A safe, unspoofable user consent dialog box is displayed.
<br />
[![r2-split-gpg-5.png](/attachment/wiki/SplitGpg/r2-split-gpg-5.png)](/attachment/wiki/SplitGpg/r2-split-gpg-5.png)
Selecting "Yes to All" will add a line in the corresponding [RPC Policy] file.
## Advanced: Using Split GPG with Subkeys ##
@ -240,8 +273,6 @@ In this example, the following keys are stored in the following locations (see b
| `ssb` | `work-gpg` |
| `pub` | `work-email` |
<br />
* `sec` (master secret key)
Depending on your needs, you may wish to create this as a **certify-only (C)** key, i.e., a key which is capable only of signing (a.k.a., "certifying") other keys.
@ -323,6 +354,24 @@ As always, exercise caution and use your good judgment.)
- [​"GPG Offline Master Key w/ smartcard" maintained by Abel Luck][luck]
- [​"Using GnuPG with QubesOS" by Alex][apapadop]
## Current limitations ##
- Current implementation requires importing of public keys to the vault domain.
This opens up an avenue to attack the gpg running in the backend domain via a hypothetical bug in public key importing code.
See ticket [#474] for more details and plans how to get around this problem, as well as the section on [using Split GPG with subkeys].
- It doesn't solve the problem of allowing the user to know what is to be signed before the operation gets approved.
Perhaps the GPG backend domain could start a DisposableVM and have the to-be-signed document displayed there? To Be Determined.
- The Split GPG client will fail to sign or encrypt if the private key in the GnuPG backend is protected by a passphrase.
It will give an `Inappropriate ioctl for device` error.
Do not set passphrases for the private keys in the GPG backend domain.
Doing so won't provide any extra security anyway, as explained in the introduction and in [using Split GPG with subkeys].
If you are generating a new key pair, or if you have a private key that already has a passphrase, you can use `gpg2 --edit-key <key_id>` then `passwd` to set an empty passphrase.
Note that `pinentry` might show an error when you try to set an empty passphrase, but it will still make the change.
(See [this StackExchange answer][se-pinentry] for more information.)
Note: The error shows only if you **do not** have graphical pinentry installed.
[#474]: https://github.com/QubesOS/qubes-issues/issues/474
[using Split GPG with subkeys]: #advanced-using-split-gpg-with-subkeys
@ -339,3 +388,6 @@ As always, exercise caution and use your good judgment.)
[luck]: https://gist.github.com/abeluck/3383449
[apapadop]: https://apapadop.wordpress.com/2013/08/21/using-gnupg-with-qubesos/
[current-limitations]: #current-limitations
[RPC Policy]: /doc/rpc-policy/
[Thunderbird:OpenPGP:Smartcards]: https://wiki.mozilla.org/Thunderbird:OpenPGP:Smartcards

13
user/security-in-qubes/u2f-proxy.md
View File

@ -75,6 +75,7 @@ In dom0:
$ sudo qubes-dom0-update qubes-u2f-dom0
$ qvm-service --enable work qubes-u2f-proxy
```
The above assumes a `work` qube in which you would like to enable u2f. Repeat the `qvm-service` command for all qubes that should have the proxy enabled. Alternatively, you can add `qubes-u2f-proxy` in VM settings -> Services in the Qube Manager of each qube you would like to enable the service.
In Fedora TemplateVMs:
@ -88,7 +89,6 @@ In Debian TemplateVMs:
$ sudo apt install qubes-u2f
```
Repeat `qvm-service --enable` (or do this in VM settings -> Services in the Qube Manager) for all qubes that should have the proxy enabled.
As usual with software updates, shut down the templates after installation, then restart `sys-usb` and all qubes that use the proxy.
After that, you may use your U2F token (but see [Browser support] below).
@ -112,6 +112,17 @@ Do not delete the file itself.
The default model is to allow a qube to access all and only the keys that were enrolled by that qube.
For example, if your `banking` qube enrolls your banking key, and your `twitter` qube enrolls your Twitter key, then your `banking` qube will have access to your banking key but not your Twitter key, and your `twitter` qube will have access to your Twitter key but not your banking key.
## Non-default USB qube name
If your USB qube is named differently than `sys-usb`, then do the following in the appropriate template(s):
```
systemctl enable qubes-u2fproxy@USB_QUBE.service
systemctl disable qubes-u2fproxy@sys-usb.service
```
Replace `USB_QUBE` with the actual USB qube name.
## TemplateVM and browser support
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.

2
user/security-in-qubes/vm-sudo.md
View File

@ -11,7 +11,7 @@ redirect_from:
Passwordless Root Access in VMs
===============================
Background ([/etc/sudoers.d/qubes](https://github.com/QubesOS/qubes-core-agent-linux/blob/master/misc/qubes.sudoers) in VM):
Background (`/etc/sudoers.d/qubes` in VM):
user ALL=(ALL) NOPASSWD: ALL

29
user/security-in-qubes/yubi-key.md
View File

@ -10,15 +10,15 @@ redirect_from:
Using YubiKey to Qubes authentication
=====================================
You can use YubiKey to enhance Qubes user authentication, for example to mitigate risk of snooping the password.
This can also slightly improve security when you have [USB keyboard](/doc/device-handling-security/#security-warning-on-usb-input-devices).
You can use a YubiKey to enhance Qubes user authentication, for example to mitigate risk of someone snooping the password.
This can also slightly improve security when you have a [USB keyboard](/doc/device-handling-security/#security-warning-on-usb-input-devices).
There (at least) two possible configurations: using OTP mode and using challenge-response mode.
There are (at least) two possible configurations: using OTP mode and using challenge-response mode.
OTP mode
--------
This can be configured using [app-linux-yubikey](https://github.com/adubois/qubes-app-linux-yubikey) package.
This can be configured using the [app-linux-yubikey](https://github.com/adubois/qubes-app-linux-yubikey) package.
This package does not support sharing the same key slot with other applications (it will deny further authentications if you try).
Contrary to instruction there, currently there is no binary package in the Qubes repository and you need to compile it yourself.
@ -27,7 +27,7 @@ This might change in the future.
Challenge-response mode
----------------------
In this mode, your YubiKey will generate a response based on the secret key, and random challenge (instead of counter).
In this mode, your YubiKey will generate a response based on the secret key, and a random challenge (instead of counter).
This means that it isn't possible to generate a response in advance even if someone gets access to your YubiKey.
This makes it reasonably safe to use the same YubiKey for other services (also in challenge-response mode).
@ -46,7 +46,7 @@ To use this mode you need to:
sudo apt-get install yubikey-personalization yubikey-personalization-gui
Shut down your TemplateVM.
Then reboot your USB VM (so changes inside the TemplateVM take effect in your TemplateBased USB VM or install the packages inside your USB VM if you would like to avoid rebooting your USB VM.
Then, either reboot your USB VM (so changes inside the TemplateVM take effect in your USB TemplateBasedVM) or install the packages inside your USB VM if you would like to avoid rebooting it.
2. Configure your YubiKey for challenge-response `HMAC-SHA1` mode, for example [following this tutorial](https://www.yubico.com/products/services-software/personalization-tools/challenge-response/).
@ -57,15 +57,15 @@ To use this mode you need to:
- Note: Different from the above video, use the following settings select
`HMAC-SHA1 mode`: `fixed 64 bit input`.
- We will refer the `Secret Key (20 bytes hex)` as `AESKEY`.
- It is recommended to keep a backup of your `AESKEY` in an offline VM used as vault.
- Consider to keep a backup of your `AESKEY` on paper and store it in a safe place.
- In case you have multiple YubiKeys for backup purposes (in case a yubikey gets lost, stolen or breaks) you can write the same settings into other YubiKeys.
- It is recommended to keep a backup of your `AESKEY` in an offline VM used as a vault.
- Consider keeping a backup of your `AESKEY` on paper and storing it in a safe place.
- If you have multiple YubiKeys for backup purposes (in case a yubikey gets lost, stolen or breaks) you can write the same settings into other YubiKeys.
3. Install [qubes-app-yubikey](https://github.com/QubesOS/qubes-app-yubikey) in dom0.
sudo qubes-dom0-update qubes-yubikey-dom0
4. Adjust USB VM name in case you are using something other than the default
4. Adjust the USB VM name in case you are using something other than the default
`sys-usb` by editing `/etc/qubes/yk-keys/yk-vm` in dom0.
5. Paste your `AESKEY` from step 2 into `/etc/qubes/yk-keys/yk-secret-key.hex` in dom0.
@ -83,18 +83,15 @@ To use this mode you need to:
echo -n "$password" | openssl dgst -sha1
7. Edit `/etc/pam.d/login` in dom0.
Add this line at the beginning:
7. Edit `/etc/pam.d/login` in dom0, adding this line at the beginning:
auth include yubikey
8. Edit `/etc/pam.d/xscreensaver` (or appropriate file if you are using screen locker program) in dom0.
Add this line at the beginning:
8. Edit `/etc/pam.d/xscreensaver` (or appropriate file if you are using another screen locker program) in dom0, adding this line at the beginning:
auth include yubikey
9. Edit `/etc/pam.d/lightdm` (or appropriate file if you are using other display manager) in dom0.
Add this line at the beginning:
9. Edit `/etc/pam.d/lightdm` (or appropriate file if you are using another display manager) in dom0, adding this line at the beginning:
auth include yubikey

0
external/troubleshooting/install-nvidia-driver.md → user/troubleshooting/install-nvidia-driver.md
View File

82
user/troubleshooting/installation-troubleshooting.md Normal file
View File

@ -0,0 +1,82 @@
---
layout: doc
title: Installation Troubleshooting
permalink: /doc/installation-troubleshooting/
---
# Installation Troubleshooting #
## "An unknown error has occurred" error during installation ##
Some people have encountered this error message when trying to install Qubes on drives that already have data on them.
The solution is to exit the installer, wipe all data or delete all partitions, then restart the Qubes installation.
## Trouble installing from USB stick ##
If you are facing issues when booting using UEFI mode, see the [UEFI troubleshooting guide](/doc/uefi-troubleshooting/).
There are a variety of other problems that could arise when using a USB installation medium, and some of the issues can be fixed by doing one or more of the following:
* **Use a different USB drive:**
If possible, try several drives of different sizes and formats.
This determines whether the problem stems from the flash drive or Qubes installer.
Some laptops cannot read from an external boot device larger than 8GB.
If you encounter a black screen when performing an installation from a USB stick, ensure you are using a USB drive less than 8GB, or a partition on that USB less than 8GB and of format FAT32.
Note that the Qubes installation image is over 4GB, so it may not fit on a smaller USB.
If a machine can not boot from a bigger USB, it may be too old to run Qubes.
* **Verify your Qubes ISO:**
Errors will occur if the Qubes installer is corrupted.
Ensure that the installer is correct and complete before writing it to a flash drive by [verifying the ISO](/security/verifying-signatures/#how-to-verify-qubes-iso-signatures).
* **Change the method you used to [write your ISO to a USB key](/doc/installation-guide/#copying-the-iso-onto-the-installation-medium):**
Some people use the ``dd`` command (recommended), others use tools like Rufus and balenaEtcher.
If installation fails after using one tool, try a different one.
For example, if you are facing trouble installing Qubes after writing the ISO using Rufus, then try using other tools like balenaEtcher or the ``dd`` command.
## Boot screen does not appear / system does not detect your installation medium ##
If the boot screen does not appear, there are several options to troubleshoot.
First, try rebooting your computer.
If it still loads your currently installed operating system or does not detect your installation medium, make sure the boot order is set up appropriately.
The process to change the boot order varies depending on the currently installed system and the motherboard manufacturer.
If **Windows 10** is installed on your machine, you may need to follow specific instructions to change the boot order.
This may require an [advanced reboot](https://support.microsoft.com/en-us/help/4026206/windows-10-find-safe-mode-and-other-startup-settings).
## "Not asking for VNC because we don't have a network" / "X startup failed, aborting installation" / "Pane is dead" error during installation ##
The boot mode in use may be causing these error messages.
Try to install after enabling both UEFI and legacy boot modes.
If that doesn't help, then disable one and try the other.
Visit the [UEFI Troubleshooting guide](/doc/uefi-troubleshooting/) if other errors arise during UEFI booting.
These errors may also occur due to an incompatible Nvidia graphics card. If you have one, follow the following instructions:
1. Disable secure/fast boot and use legacy mode
2. Enter GRUB, move the selection to the first choice, and then press the Tab key.
3. Now, you are in edit mode. Move the text cursor with your arrow key and after ``kernel=`` line, add:
nouveau.modeset=0 rd.driver.blacklist=nouveau video=vesa:off
If the above code doesn't fix the problem, replace it with:
noexitboot=1 modprobe.blacklist=nouveau rd.driver.blacklist=nouveau --- intitrd.img
For more information, look at the [Nvidia Troubleshooting guide](/doc/nvidia-troubleshooting/#disabling-nouveau).
## Installation freezes at "Setting up Networking" ##
If you are facing this problem on an Apple computer, check out the [Macbook Troubleshooting guide](/doc/macbook-troubleshooting/).
This issue occurs due to the network card, which may be missing some drivers or is incompatible with Qubes.
First, install all available drivers for the card.
You can install the drivers without internet access by first downloading them on another machine, then transferring them over to the current machine (e.g., with a USB drive).
If installing the available drivers does not help, disable the network card in the BIOS and perform the installation before re-enabling the card.
If this solves the issue, it confirms the PCI card is incompatible with Qubes.
In this case, you may want to consider replacing it with a network card of a different brand.
Broadcom cards are notoriously problematic with Qubes.

0
external/troubleshooting/intel-igfx-troubleshooting.md → user/troubleshooting/intel-igfx-troubleshooting.md
View File

0
external/troubleshooting/macbook-troubleshooting.md → user/troubleshooting/macbook-troubleshooting.md
View File

0
external/troubleshooting/nvidia-troubleshooting.md → user/troubleshooting/nvidia-troubleshooting.md
View File

33
external/troubleshooting/out-of-memory.md → user/troubleshooting/out-of-memory.md
View File

@ -19,29 +19,28 @@ qvm-console-dispvm <VMname>
If this does not work, check the size of /var/lib/qubes/qubes.xml. If it is zero, you'll need to use one of the file backup (stored in /var/lib/qubes/backup), hopefully you have the current data there. Find the most recent one and place in /var/lib/qubes/qubes.xml instead of the empty file.
In any case you'll need some disk space to start the VM. Check `df -h` output if you have some. If not, some hints how to free some disk space:
In any case you'll need some disk space to start the VM. Check `df -h` output if you have some. If not, here are some hints how to free some disk space:
1. Clean yum cache:
1. Clean yum cache.
~~~
sudo yum clean all
~~~
~~~
sudo yum clean all
~~~
1. Delete .img files of a less important VM, that can be found in
2. Delete `.img` files of a less important VM, which can be found in `/var/lib/qubes/appvms/`.
Then, when the system is working again, clean up the rest.
/var/lib/qubes/appvms/. Then, when the system is working again, cleanup the rest with:
~~~
qvm-remove <VMname>
~~~
~~~
qvm-remove <VMname>
~~~
With this method, you lose the data of one VM, but it'll work more reliably.
With this method you lose the data of one VM, but it'll work more reliably.
3. Decrease the filesystem safety margin (5% by default).
1. Decrease filesystem safety margin (5% by default):
~~~
sudo tune2fs -m 4 /dev/mapper/vg_dom0-lv_root
~~~
~~~
sudo tune2fs -m 4 /dev/mapper/vg_dom0-lv_root
~~~
1. Remove some unneeded files in dom0 home (if you have any, most likely not).
4. Remove some unneeded files in dom0 home (if you have any, most likely not).

36
user/troubleshooting/remove-vm-manually.md Normal file
View File

@ -0,0 +1,36 @@
---
layout: doc
title: How to Remove VMs Manually
permalink: /doc/remove-vm-manually/
---
How to Remove VMs Manually
==========================
How to Remove a TemplateVM Manually
-----------------------------------
Try the [normal method] before resorting to this.
All of the following commands should be executed in a dom0 terminal.
When a template is marked as 'installed by package manager', but cannot be uninstalled there, trying to uninstall manually will result in the error "ERROR: VM installed by package manager: template-vm-name". Do as follows to be able to uninstall the template:
1. Check the state of `installed_by_rpm`
$ qvm-prefs template-vm-name
2. If `installed_by_rpm - True]`, mark the template as not installed by package manager
$ qvm-prefs template-vm-name installed_by_rpm false
3. Re-check the state of `installed_by_rpm`
- If `installed_by_rpm - False`, remove the template like you would a regular qube:
$ qvm-remove template-vm-name
- If `installed_by_rpm` remains `True`, reboot your computer to bring qubes.xml in sync with qubesd, and try again to remove the template.
[normal method]: /doc/templates/#uninstalling

134
user/troubleshooting/resume-suspend-troubleshooting.md Normal file
View File

@ -0,0 +1,134 @@
---
layout: doc
title: Suspend/Resume Troubleshooting
permalink: /doc/suspend-resume-troubleshooting/
redirect_from:
- /en/doc/wireless-troubleshooting/
- /doc/wireless-troubleshooting/
---
# Troubleshooting problems relating to suspend/resume #
## Network-Manager says “Device not ready” on suspend/resume ##
These instructions may help with suspend/resume issues for more devices than just wireless cards, that is just the (unfortunately not uncommon) example used here.
If your wireless card works, but after suspending and resuming your computer, the Network-Manager applet just says "Device not ready", then try un-loading and re-loading the driver.
### Determining your wireless card driver ###
First, determine which kernel module corresponds to your wireless card. There are several ways to do this.
The easiest is via the output of `lspci -k` in your sys-net VM:
~~~
[user@sys-net ~]$ lspci -k
00:00.0 Network controller: Intel Corporation Wireless 8260 (rev 3a)
Subsystem: Intel Corporation Device 0130
Kernel driver in use: iwlwifi
Kernel modules: iwlwifi
~~~
Here we see that the machine in question has an Intel wireless card, being used by the `iwlwifi` kernel module.
### Checking logs for relevant messages ###
View the output of `dmesg` in sys-net, and check if you see a bunch of wireless related errors. Depending on your hardware, they may look like the following (or not):
~~~
iwlwifi 0000:00:00.0: loaded firmware version 16.242414.0 op_mode iwlmvm
iwlwifi 0000:00:00.0: Detected Intel(R) Dual Band Wireless AC 8260, REV=0x208
...
IPv6: ADDRCONF(NETDEV_UP): wlp0s0: link is not ready
iwlwifi 0000:00:00.0: L1 Enabled - LTR Enabled
iwlwifi 0000:00:00.0: L1 Enabled - LTR Enabled
iwlwifi 0000:00:00.0: Failed to load firmware chunk!
iwlwifi 0000:00:00.0: Could not load the [0] uCode section
iwlwifi 0000:00:00.0: Failed to start INIT ucode: -110
iwlwifi 0000:00:00.0: Failed to run INIT ucode: -110
...
iwlwifi 0000:00:00.0: Direct firmware load for iwlwifi-8000C-18.ucode failed with error -2
~~~
### Seeing what modules you have loaded ###
You can check which drivers are currently loaded with `lsmod`, and view details about a module with `modinfo <module_name>`.
For example, we list what modules we have loaded:
~~~
[user@sys-net ~]$ lsmod
Module Size Used by
iwlmvm 315392 0
iwlwifi 155648 1 iwlmvm
mac80211 708608 1 iwlmvm
cfg80211 557056 3 iwlwifi,mac80211,iwlmvm
...
~~~
and check one:
~~~
[user@sys-net ~]$ modinfo iwlmvm | grep -E '^(description|author|depends):'
author: Copyright(c) 2003- 2015 Intel Corporation <ilw@linux.intel.com>
description: The new Intel(R) wireless AGN driver for Linux
depends: iwlwifi,mac80211,cfg80211
~~~
Hey, it's our wireless driver!
Now, check if reloading the module makes wireless work again:
~~~
[user@sys-net ~]$ sudo rmmod iwlmvm
[user@sys-net ~]$ sudo modprobe iwlmvm
~~~
and try reconnecting to a network that is known to work.
If that is successful, see below about having Qubes automatically reload the driver for you. If not, try also reloading some dependent modules, in our example we must also reload iwlwifi:
~~~
[user@sys-net ~]$ modinfo iwlwifi | grep -E '^(description|author|depends):'
author: Copyright(c) 2003- 2015 Intel Corporation <ilw@linux.intel.com>
description: Intel(R) Wireless WiFi driver for Linux
depends: cfg80211
~~~
~~~
[user@sys-net ~]$ sudo rmmod iwlmvm
[user@sys-net ~]$ sudo rmmod iwlwifi
[user@sys-net ~]$ sudo modprobe iwlwifi # note the reverse order of loading/unloading
[user@sys-net ~]$ sudo modprobe iwlmvm
~~~
## Drivers do not reload automatically on suspend/resume ##
If reloading the driver (which resets the hardware into a known-state) resolves your issue when done manually, you can have Qubes automatically un/reload them on suspend & resume by listing the relevant modules in `/rw/config/suspend-module-blacklist`.
In the above example, it would look like this:
~~~
[user@sys-net config]$ cat /rw/config/suspend-module-blacklist
# You can list here modules you want to be unloaded before going to sleep. This
# file is used only if the VM has any PCI device assigned. Modules will be
# automatically loaded after resume.
iwlmvm
iwlwifi
~~~
## Power consumption increases on suspend/resume ##
This problem is related to the software method used to disable sibling threads and how it interacts with suspend/resume.
To solve the problem, disable hyper-threading in the BIOS. This [external guide](https://www.pcmag.com/news/how-to-disable-hyperthreading) explains how to disable hyper-threading.
Since Qubes does disable hyperthreading by default (by not using secondary threads), you won't pay any performance cost.
## Attached devices in Windows HVM stop working on suspend/resume ##
After the whole system gets suspended into S3 sleep and subsequently resumed, some attached devices may stop working. To make the devices work, they should be restarted within the VM.
This can be achieved under a Windows HVM by opening the Device Manager, selecting the actual device (such as a USB controller), 'Disabling' the device, and then 'Enabling' the device again.
This is illustrated on the screenshot below:
![r2b1-win7-usb-disable.png](/attachment/wiki/HvmCreate/r2b1-win7-usb-disable.png)

0
external/troubleshooting/sony-vaio-tinkering.md → user/troubleshooting/sony-vaio-tinkering.md
View File

6
external/troubleshooting/thinkpad-troubleshooting.md → user/troubleshooting/thinkpad-troubleshooting.md
View File

@ -16,9 +16,9 @@ redirect_from:
# Lenovo ThinkPad Troubleshooting #
## Instructions to create USB installation medium for newer (UEFI-only) ThinkPads ##
Newer ThinkPads (e.g. T470, T470p, ThinkPad 25) are likely to fail installation attempts made from a USB stick that was created with dd or Rufus, and even from a DVD burned using official ISO images - if the ThinkPad is configured for UEFI boot. If you don't want to use Legacy Mode as a workaround, the following instructions should help you create a Qubes Installation USB stick that works in UEFI-only mode.
Some newer ThinkPads (e.g. T470, T470p, [P51](https://www.svensemmler.org/blog/2017/12/17/qubes-on-thinkpad-p51.html), ThinkPad 25, but not the [P53](https://github.com/QubesOS/qubes-issues/issues/5851)) are likely to fail installation attempts made from a USB stick that was created with dd or Rufus, and even from a DVD burned using official ISO images - if the ThinkPad is configured for UEFI boot. If you don't want to use Legacy Mode as a workaround, the following instructions should help you create a Qubes Installation USB stick that works in UEFI-only mode.
In a nutshell, you need to use the Fedora livecd-tools to make a Qubes Installation USB Stick from the Qubes ISO image, then update the label on the partition of that USB stick to "BOOT", and then update the BOOT/EFI/xen.cfg file on the USB stick so that all labels point to BOOT. In more detail:
In a nutshell, you need to use the Fedora livecd-tools to make a Qubes Installation USB Stick from the Qubes ISO image, then update the label on the partition of that USB stick to "BOOT", and then update the BOOT/EFI/BOOTX64.cfg file on the USB stick so that all labels point to BOOT. In more detail:
1. On your ThinkPad, enter the UEFI setup (press F1 at startup) and make sure to set at least the following options:
- *USB UEFI BIOS Support: Enabled*
@ -37,7 +37,7 @@ In a nutshell, you need to use the Fedora livecd-tools to make a Qubes Installat
``# mount /dev/sdd1 /mnt/qinst/``
10. Use your favorite editor to edit the file */mnt/qinst/EFI/BOOT/xen.cfg*: Replace all instances of ``LABEL=Qubes-R4.0-rc3-x86_64`` with ``LABEL=BOOT``. There is typically no space in front of ``LABEL``, but there is a space at the end of the portion you replace.
10. Use your favorite editor to edit the file */mnt/qinst/EFI/BOOT/BOOTX64.cfg*: Replace all instances of ``LABEL=Qubes-R4.0-rc3-x86_64`` with ``LABEL=BOOT``. There is typically no space in front of ``LABEL``, but there is a space at the end of the portion you replace.
11. Unmount the Qubes Installation USB stick: ``# umount /dev/sdd*`` and disconnect it.
That's it! You can now reboot the machine with the Qubes USB Installation stick attached, and press F12 to select it as the boot device at startup. Proceed to install Qubes OS normally. Enjoy!

65
user/advanced-configuration/uefi-troubleshooting.md → user/troubleshooting/uefi-troubleshooting.md
View File

@ -4,18 +4,20 @@ title: UEFI Troubleshooting
permalink: /doc/uefi-troubleshooting/
---
Troubleshooting UEFI related problems
========================================
# Troubleshooting UEFI related problems #
Change installer kernel parameters in UEFI
---------------------
## Successfully installed in legacy mode, but had to change some kernel parameters ##
If you've installed successfully in legacy mode but had to change some kernel parameters for it to work, you should try installing in UEFI mode with the same parameters.
**Change the xen configuration on a USB media**
01. Attach the usb disk, mount the EFI partition (second partition available on the disk)
02. As `su`, edit your xen config (`EFI/BOOT/BOOTX64.cfg`) changing the `kernel` key to add your kernel parameters on the boot entry of your choice
03. Install using your modified boot entry
02. Open a terminal and enter the command `sudo su -`. Use your preferred text editor (e.g `nano`) to edit your xen config (`EFI/BOOT/BOOTX64.cfg`):
~~~
nano EFI/BOOT/BOOTX64.cfg
~~~
03. Change the `kernel` key to add your kernel parameters on the boot entry of your choice
04. Install using your modified boot entry
**Change xen configuration directly in an iso image**
01. Get EFI partition boundaries `parted Qubes-R4.0-rc4-x86_64.iso unit B print`
@ -25,14 +27,16 @@ If you've installed successfully in legacy mode but had to change some kernel pa
05. Save your changes, unmount and dd to usb device
Installation freezes before displaying installer
-----------------------------------------------------------
## Installation freezes before displaying installer ##
If you have an Nvidia card, see also [Nvidia Troubleshooting](/doc/nvidia-troubleshooting/#disabling-nouveau).
### Removing `noexitboot` and `mapbs` ###
Some systems can freeze with the default UEFI install options.
You can try the following to remove `noexitboot` and `mapbs`.
If you have an Nvidia card, see also [Nvidia Troubleshooting](/doc/nvidia-troubleshooting/#disabling-nouveau).
1. Follow the [steps here](/doc/uefi-troubleshooting/#change-installer-kernel-parameters-in-uefi) to edit the `[qubes-verbose]` section of your installer's `BOOTX64.cfg`.
1. Follow the [steps here](/doc/uefi-troubleshooting/#successfully-installed-in-legacy-mode-but-had-to-change-some-kernel-parameters) to edit the `[qubes-verbose]` section of your installer's `BOOTX64.cfg`.
You want to comment out the `mapbs` and `noexitboot` lines.
The end result should look like this:
@ -59,16 +63,33 @@ This is also a good time to make permanent any other changes needed to get the i
5. Go back to `tty6` (Ctrl-Alt-F6) and click `Reboot`.
6. Continue with setting up default templates and logging in to Qubes.
### Changing `options=console=` parameter to `none` ###
Installation freezes before displaying installer / disable EFI runtime services
------------------------------------------------------------------------------
If removing `noexitboot` and `mapbs` did not help, you can try changing the `options=console=` parameter to `none`. The detailed solution can be found in the comments of [this GitHub issue](https://github.com/QubesOS/qubes-issues/issues/5383)
1. Follow the [steps here](/doc/uefi-troubleshooting/#successfully-installed-in-legacy-mode-but-had-to-change-some-kernel-parameters) to edit the `[qubes-verbose]` section of your installer's `BOOTX64.cfg`.
You want to change `options=console=vga` to `options=console=none`.
The end result should look like this:
~~~
[qubes-verbose]
options=console=none efi=attr=uc
noexitboot=1
mapbs=1
kernel=vmlinuz inst.stage2=hd:LABEL=Qubes-R4.0-x86_64 i915.alpha_support=1
ramdisk=initrd.img
~~~
2. Boot the installer and continue to install as normal
### Disable EFI runtime services ###
On some early, buggy UEFI implementations, you may need to disable EFI under Qubes completely.
This can sometimes be done by switching to legacy mode in your BIOS/UEFI configuration.
If that's not an option there, or legacy mode does not work either, you can try the following to add `efi=no-rs`.
Consider this approach as a last resort, because it will make every Xen update a manual process.
1. Follow the [steps here](/doc/uefi-troubleshooting/#change-installer-kernel-parameters-in-uefi) to edit the `[qubes-verbose]` section of your installer's `xen.cfg`.
1. Follow the [steps here](/doc/uefi-troubleshooting/#successfully-installed-in-legacy-mode-but-had-to-change-some-kernel-parameters) to edit the `[qubes-verbose]` section of your installer's `xen.cfg`.
You want to modify the `efi=attr=uc` setting and comment out the `mapbs` and `noexitboot` lines.
The end result should look like this:
@ -105,9 +126,11 @@ Consider this approach as a last resort, because it will make every Xen update a
Whenever there is a kernel or Xen update for Qubes, you will need to follow [these steps](/doc/uefi-troubleshooting/#boot-device-not-recognized-after-installing) because your system is using the fallback UEFI bootloader in `[...]/EFI/BOOT` instead of directly booting to the Qubes entry under `[...]/EFI/qubes`.
## Installation from USB stick hangs on black screen ##
Installation completes successfully but then boot loops or hangs on black screen
---------------------
Some laptops cannot read from an external boot device larger than 8GB. If you encounter a black screen when performing an installation from a USB stick, ensure you are using a USB drive less than 8GB, or a partition on that USB lesser than 8GB and of format FAT32.
## Installation completes successfully but then boot loops or hangs on black screen ##
There is a [common bug in UEFI implementation](http://xen.markmail.org/message/f6lx2ab4o2fch35r) affecting mostly Lenovo systems, but probably some others too.
While some systems need `mapbs` and/or `noexitboot` disabled to boot, others require them enabled at all times.
@ -148,8 +171,7 @@ Or if you have already rebooted after the first stage install and have encounter
4. Continue with setting up default templates and logging in to Qubes.
Installation completes successfully but then system crash/restarts on next boot
-------------------------------------------
## Installation completes successfully but then system crash/restarts on next boot ##
Some Dell systems and probably others have [another bug in UEFI firmware](http://markmail.org/message/amw5336otwhdxi76).
These systems need `efi=attr=uc` enabled at all times.
@ -176,8 +198,7 @@ Or if you have already rebooted after the first stage install and have encounter
4. Continue with setting up default templates and logging in to Qubes.
Boot device not recognized after installing
------------------------------------------
## Boot device not recognized after installing ##
Some firmware will not recognize the default Qubes EFI configuration.
As such, it will have to be manually edited to be bootable.
@ -198,8 +219,7 @@ This will need to be done after every kernel and Xen update to ensure you use th
cp /boot/efi/EFI/qubes/xen-4.8.3.efi /boot/efi/EFI/BOOT/BOOTX64.efi
Installation finished but "Qubes" boot option is missing and xen.cfg is empty
--------------------------------------------------------------------------------------
## Installation finished but "Qubes" boot option is missing and xen.cfg is empty / Installation fails with "failed to set new efi boot target" ##
In some cases installer fails to finish EFI setup and leave the system without a Qubes-specific EFI configuration.
In such a case you need to finish those parts manually.
@ -233,8 +253,7 @@ You can do that just after installation (switch to `tty2` with Ctrl-Alt-F2), or
efibootmgr -v -c -u -L Qubes -l /EFI/qubes/xen.efi -d /dev/sda -p 1 "placeholder /mapbs /noexitboot"
Accessing installer Rescue mode on UEFI
---------------------------------------
## Accessing installer Rescue mode on UEFI ##
In UEFI mode, the installer does not have a boot menu, but boots directly into the installation wizard.
To get into Rescue mode, you need to switch to tty2 (Ctrl+Alt+F2) and then execute:

0
external/troubleshooting/updating-debian-and-whonix.md → user/troubleshooting/updating-debian-and-whonix.md
View File

0
external/troubleshooting/wireless-troubleshooting.md → user/troubleshooting/wireless-troubleshooting.md
View File