diff --git a/.travis.yml b/.travis.yml index c922b5af..fd574b28 100644 --- a/.travis.yml +++ b/.travis.yml @@ -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 diff --git a/developer/building/qubes-builder.md b/developer/building/qubes-builder.md index 1fa88418..008c00d9 100644 --- a/developer/building/qubes-builder.md +++ b/developer/building/qubes-builder.md @@ -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. diff --git a/developer/building/qubes-iso-building.md b/developer/building/qubes-iso-building.md index e25d1975..f09d7af0 100644 --- a/developer/building/qubes-iso-building.md +++ b/developer/building/qubes-iso-building.md @@ -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: diff --git a/developer/debugging/automated-tests.md b/developer/debugging/automated-tests.md index ca78322c..c222a34c 100644 --- a/developer/debugging/automated-tests.md +++ b/developer/debugging/automated-tests.md @@ -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/ diff --git a/developer/debugging/profiling.md b/developer/debugging/profiling.md index 2fad769c..e20e3208 100644 --- a/developer/debugging/profiling.md +++ b/developer/debugging/profiling.md @@ -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. diff --git a/developer/debugging/vm-interface.md b/developer/debugging/vm-interface.md index 7a79f387..7227c41e 100644 --- a/developer/debugging/vm-interface.md +++ b/developer/debugging/vm-interface.md @@ -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 diff --git a/developer/general/doc-guidelines.md b/developer/general/doc-guidelines.md index bea00fec..79bb1d26 100644 --- a/developer/general/doc-guidelines.md +++ b/developer/general/doc-guidelines.md @@ -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.: diff --git a/developer/general/gsoc.md b/developer/general/gsoc.md index 719f827b..3241fcfb 100644 --- a/developer/general/gsoc.md +++ b/developer/general/gsoc.md @@ -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). diff --git a/developer/general/gsod.md b/developer/general/gsod.md index cc4ab7ef..aa5f1262 100644 --- a/developer/general/gsod.md +++ b/developer/general/gsod.md @@ -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 diff --git a/developer/general/package-contributions.md b/developer/general/package-contributions.md index bc52aae5..1fcbd412 100644 --- a/developer/general/package-contributions.md +++ b/developer/general/package-contributions.md @@ -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 diff --git a/developer/services/admin-api.md b/developer/services/admin-api.md index cdfcc655..6580f062 100644 --- a/developer/services/admin-api.md +++ b/developer/services/admin-api.md @@ -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 | `\n` | - | 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`;
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`
`policy.include.List` | - | - | `\n\n...` | +| `policy.Get`
`policy.include.Get` | name | - | `\n` | +| `policy.Replace`
`policy.include.Replace` | name | `\n` | - | +| `policy.Remove`
`policy.include.Remove` | name | `` | - | + +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 diff --git a/developer/services/qmemman.md b/developer/services/qmemman.md index 356ddbf5..f9581adb 100644 --- a/developer/services/qmemman.md +++ b/developer/services/qmemman.md @@ -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. diff --git a/developer/system/architecture.md b/developer/system/architecture.md index 5d02408e..e66f34fa 100644 --- a/developer/system/architecture.md +++ b/developer/system/architecture.md @@ -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. + diff --git a/doc.md b/doc.md index cfab61f9..88a009b6 100644 --- a/doc.md +++ b/doc.md @@ -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 diff --git a/external/building-guides/building-archlinux-template.md b/external/building-guides/building-archlinux-template.md index 0f996223..9fe8ac80 100644 --- a/external/building-guides/building-archlinux-template.md +++ b/external/building-guides/building-archlinux-template.md @@ -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 diff --git a/external/configuration-guides/fetchmail.md b/external/configuration-guides/fetchmail.md index 25bd4ab6..c3e11ae9 100644 --- a/external/configuration-guides/fetchmail.md +++ b/external/configuration-guides/fetchmail.md @@ -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. diff --git a/external/configuration-guides/mutt.md b/external/configuration-guides/mutt.md index 6118a3d2..c857258d 100644 --- a/external/configuration-guides/mutt.md +++ b/external/configuration-guides/mutt.md @@ -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 diff --git a/external/configuration-guides/vpn.md b/external/configuration-guides/vpn.md index 45227fdb..1f843215 100644 --- a/external/configuration-guides/vpn.md +++ b/external/configuration-guides/vpn.md @@ -12,6 +12,12 @@ redirect_from: How To make a VPN Gateway in Qubes ================================== + + 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) diff --git a/external/customization-guides/language-localization.md b/external/customization-guides/language-localization.md index 79c22558..50ab8cc1 100644 --- a/external/customization-guides/language-localization.md +++ b/external/customization-guides/language-localization.md @@ -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 ----------------------------------- diff --git a/external/os-guides/centos.md b/external/os-guides/centos.md index 3f4ab8e9..61595909 100644 --- a/external/os-guides/centos.md +++ b/external/os-guides/centos.md @@ -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/ diff --git a/external/os-guides/gentoo.md b/external/os-guides/gentoo.md new file mode 100644 index 00000000..219c205b --- /dev/null +++ b/external/os-guides/gentoo.md @@ -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 \ No newline at end of file diff --git a/external/os-guides/windows/windows-tools.md b/external/os-guides/windows/windows-tools.md index 50678ac1..4a5ff7d0 100644 --- a/external/os-guides/windows/windows-tools.md +++ b/external/os-guides/windows/windows-tools.md @@ -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 `` is the name of your Windows 10 VM)* + + qvm-features 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 `` that you use to login to the Windows VM. This can be done via the following command on a `dom0` terminal: *(where `` is the name of your Windows 10 VM)* + + `qvm-prefs default_user ` + + > **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\`. + > 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 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\\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` diff --git a/external/os-guides/windows/windows-vm.md b/external/os-guides/windows/windows-vm.md index 74ea761c..5eeb7f67 100644 --- a/external/os-guides/windows/windows-vm.md +++ b/external/os-guides/windows/windows-vm.md @@ -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\\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= +~~~ + +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 --------------------- diff --git a/external/privacy-guides/signal.md b/external/privacy-guides/signal.md index 5e205c87..b6378855 100644 --- a/external/privacy-guides/signal.md +++ b/external/privacy-guides/signal.md @@ -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. diff --git a/external/security-guides/security-guidelines.md b/external/security-guides/security-guidelines.md index 4a85d552..a9beaf25 100644 --- a/external/security-guides/security-guidelines.md +++ b/external/security-guides/security-guidelines.md @@ -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). diff --git a/introduction/code-of-conduct.md b/introduction/code-of-conduct.md index f4c0d835..99d8c971 100644 --- a/introduction/code-of-conduct.md +++ b/introduction/code-of-conduct.md @@ -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 diff --git a/introduction/faq.md b/introduction/faq.md index 4ca3adde..516491a7 100644 --- a/introduction/faq.md +++ b/introduction/faq.md @@ -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 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-`. +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-`, 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/ diff --git a/introduction/intro.html b/introduction/intro.html new file mode 100644 index 00000000..94469289 --- /dev/null +++ b/introduction/intro.html @@ -0,0 +1,339 @@ +--- +layout: default +title: Introduction +permalink: /intro/ +redirect_from: +- /tour/ +- /en/tour/ +- /tour/#what-is-qubes-os +- /about/ +- /en/about/ +--- + +

What is Qubes OS?

+ +
+
+

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

+
+
+ +
+
+

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

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

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

Features

+ +
+
+

Strong isolation

+

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

+
+
+

Template system

+

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

+
+
+

Multiple operating systems

+

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

+
+
+ +
+ +
+
+

DisposableVMs

+

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

+
+
+

Whonix integration

+

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

+
+
+

Device isolation

+

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

+
+
+ +
+ +
+
+

Split GPG

+

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

+
+
+

U2F proxy

+

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

+
+
+

Open-source

+

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

+
+
+ + + + +

Why Qubes OS?

+ +

Physical isolation is a given safeguard that the digital world lacks

+ +
+
+

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

+

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

+

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

+
+
+ + Qube Manager + +
+
+ +

Qubes allows you to compartmentalize your digital life

+ +
+
+ + Compartmentalization example + +
+
+

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

+

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

+

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

+
+
+ +

Made to support vulnerable users and power users alike

+ +
+
+

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

+

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

+

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

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

Video Tours

+

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

+ + Video Tours + +
+
+

Screenshots

+

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

+ + Screenshots + +
+
+

Getting Started

+

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

+ + Getting Started + +
+
+ +

More information

+ +

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

+

+ diff --git a/introduction/intro.md b/introduction/intro.md deleted file mode 100644 index 22d16816..00000000 --- a/introduction/intro.md +++ /dev/null @@ -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? ------------------ - -
-
-

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

-

Qubes OS leverages xen-based virtualization to allow for the creation and management of isolated virtual machines called qubes. - Qubes, which are also referred to as domains or compartments, have specific :

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

Qubes OS Overview Example

- -
-
- - - -

Features

- -
-
-

Strong isolation

-

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

-
-
-

Template system

-

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

-
-
-

Multiple operating systems

-

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

-
-
- -
-
-
-

Disposable VMs

-

Create disposable VMs which are spawned quickly and destroyed when closed

-
-
-

Whonix integration

-

Run Tor securely system-wide using Whonix with Qubes

-
-
-

Controller isolation

-

Secure device handling through isolation of network cards and USB controllers

-
-
- -
-
-
-

Split GPG

-

Utilize Split GPG to store private GPG keys in an AppVM

-
-
-

U2F proxy

-

Operate Qubes U2F proxy to use two-factor authentication

-
-
-

Open-source

-

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

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

Physical isolation is a given safeguard that the digital world lacks

- -
-
-

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

-

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

-

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

-
-
- -
-
- -

Qubes OS compartmentalizes one's digital life

- -
-
- -
-
-

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

-

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

-

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

-
-
- -

Made to support vulnerable users

- -
-
-

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

-

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

-

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

-

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

-
-
- -

snapshot12.png

- -
-
-
-

Video Tours

-

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

- - Video Tours - -
-
-

Screenshots

-

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

- - Screenshots - -
-
-

Getting Started

-

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

- - Getting Started - -
-
- - -More information ----------------- - -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/ diff --git a/introduction/reporting-bugs.md b/introduction/reporting-bugs.md index 7f9a57a4..52d0530e 100644 --- a/introduction/reporting-bugs.md +++ b/introduction/reporting-bugs.md @@ -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/ diff --git a/introduction/statistics.md b/introduction/statistics.md index e46e155d..85f90911 100644 --- a/introduction/statistics.md +++ b/introduction/statistics.md @@ -6,8 +6,10 @@ redirect_from: - /counter/ --- -
- Estimated Qubes OS userbase graph +
+ + Estimated Qubes OS userbase graph +
FAQ diff --git a/introduction/support.md b/introduction/support.md index fe3000f8..ef5cb3a6 100644 --- a/introduction/support.md +++ b/introduction/support.md @@ -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: + + + +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: + * Matrix, strictly Qubes: + * `#qubes` channel on freenode.net via traditional IRC clients or: + +[mailing lists]: #mailing-lists +[wiki-ml]: https://en.wikipedia.org/wiki/Electronic_mailing_list [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/ diff --git a/project-security/verifying-signatures.md b/project-security/verifying-signatures.md index 48640259..e5c9078d 100644 --- a/project-security/verifying-signatures.md +++ b/project-security/verifying-signatures.md @@ -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 diff --git a/user/advanced-configuration/config-files.md b/user/advanced-configuration/config-files.md index 501618aa..f4cd6f69 100644 --- a/user/advanced-configuration/config-files.md +++ b/user/advanced-configuration/config-files.md @@ -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; }; }; ~~~ diff --git a/user/advanced-configuration/disposablevm-customization.md b/user/advanced-configuration/disposablevm-customization.md index 317c9cfb..716a1ede 100644 --- a/user/advanced-configuration/disposablevm-customization.md +++ b/user/advanced-configuration/disposablevm-customization.md @@ -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 +qvm-create -C DispVM -l green qvm-prefs autostart true qvm-prefs netvm qvm-prefs provides_network true diff --git a/user/advanced-configuration/i3.md b/user/advanced-configuration/i3.md index f170a04a..4730e990 100644 --- a/user/advanced-configuration/i3.md +++ b/user/advanced-configuration/i3.md @@ -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 diff --git a/user/advanced-configuration/resize-disk-image.md b/user/advanced-configuration/resize-disk-image.md index 7a74132e..a2e438be 100644 --- a/user/advanced-configuration/resize-disk-image.md +++ b/user/advanced-configuration/resize-disk-image.md @@ -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. diff --git a/user/advanced-configuration/salt.md b/user/advanced-configuration/salt.md index dfb890af..e8427443 100644 --- a/user/advanced-configuration/salt.md +++ b/user/advanced-configuration/salt.md @@ -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`. diff --git a/user/common-tasks/backup-emergency-restore-v2.md b/user/common-tasks/backup-emergency-restore-v2.md index 159607f7..6c03bd3e 100644 --- a/user/common-tasks/backup-emergency-restore-v2.md +++ b/user/common-tasks/backup-emergency-restore-v2.md @@ -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 diff --git a/user/common-tasks/backup-emergency-restore-v3.md b/user/common-tasks/backup-emergency-restore-v3.md index c2774ee9..2718b5d4 100644 --- a/user/common-tasks/backup-emergency-restore-v3.md +++ b/user/common-tasks/backup-emergency-restore-v3.md @@ -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 diff --git a/user/common-tasks/backup-emergency-restore-v4.md b/user/common-tasks/backup-emergency-restore-v4.md index ec9731d4..fa607e78 100644 --- a/user/common-tasks/backup-emergency-restore-v4.md +++ b/user/common-tasks/backup-emergency-restore-v4.md @@ -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 diff --git a/user/common-tasks/backup-restore.md b/user/common-tasks/backup-restore.md index 94a5575f..99a9c2f2 100644 --- a/user/common-tasks/backup-restore.md +++ b/user/common-tasks/backup-restore.md @@ -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 diff --git a/user/common-tasks/disposablevm.md b/user/common-tasks/disposablevm.md index f59be63f..3e7c452a 100644 --- a/user/common-tasks/disposablevm.md +++ b/user/common-tasks/disposablevm.md @@ -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 ## diff --git a/user/common-tasks/full-screen-mode.md b/user/common-tasks/full-screen-mode.md index 1ec7f8fa..62344d33 100644 --- a/user/common-tasks/full-screen-mode.md +++ b/user/common-tasks/full-screen-mode.md @@ -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. diff --git a/user/common-tasks/getting-started.md b/user/common-tasks/getting-started.md index db10e49b..18729c39 100644 --- a/user/common-tasks/getting-started.md +++ b/user/common-tasks/getting-started.md @@ -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/ --- -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 OverTM. -(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: \**. + +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: `. 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 **\: \**, 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 " [arguments]" + $ qvm-run [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/). +
-
+

Compatible Hardware

-

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

+

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

Hardware Compatibility List
-
+

Downloads

-

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

+

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

Downloads

Documentation

-

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

+

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

Documentation
-
+ diff --git a/user/common-tasks/software-update-domu.md b/user/common-tasks/software-update-domu.md index 6be06e59..f5bfa68e 100644 --- a/user/common-tasks/software-update-domu.md +++ b/user/common-tasks/software-update-domu.md @@ -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