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

Reorganize files to account for new "External" section

Browse source 
QubesOS/qubes-issues#4693
This commit is contained in:
Andrew David Wong 2019-05-26 19:32:45 -05:00
parent 5cc99a23d1
commit d31c786942
No known key found for this signature in database
GPG key ID: 8CE137352A019A17
203 changed files with 0 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

156
user/downloading-installing-upgrading/custom-install.md Normal file
View file

@ -0,0 +1,156 @@
---
layout: doc
title: Custom Installation
permalink: /doc/custom-install/
redirect_from:
- /doc/encryption-config/
---
# Custom Installation
In the present context, "custom installation" refers to things like manual partitioning, setting up LVM and RAID, and manual LUKS encryption configuration.
## Installer Defaults
For reference, these are the typical defaults for a single disk with legacy boot:
~~~
Mount Point: /boot
Desired Capacity: 1024 MiB
Device Type: Standard Partition
File System: ext4
Name: (none)
Mount Point: /
Desired Capacity: (your choice)
Device Type: LVM Thin Provisioning
Volume Group: qubes_dom0
File System: ext4
Name: root
Mount Point: (none)
Desired Capacity: 10 GiB
Device Type: LVM
Volume Group: qubes_dom0
File System: swap
Name: swap
~~~
~~~
SUMMARY OF CHANGES
Order Action Type Device Mount point
1 Destroy Format Unknown Disk (sda)
2 Create Format partition table (MSDOS) Disk (sda)
3 Create Device partition sda1 on Disk
4 Create Format ext4 sda1 on Disk /boot
5 Create Device partition sda2 on Disk
6 Create Format LUKS sda2 on Disk
7 Create Device luks/dm-crypt luks-sda2
8 Create Format physical volume (LVM) luks-sda2
9 Create Device lvmvg qubes_dom0
10 Create Device lvmthinpool qubes_dom0-pool00
11 Create Device lvmthinlv qubes_dom0-root
12 Create Device lvmlv qubes_dom0-swap
13 Create Format swap qubes_dom0-swap
14 Create Format ext4 qubes_dom0-root /
~~~
## Typical Partition Schemes
If you want your partition/LVM scheme to look like the Qubes default but with a few tweaks, follow this example.
With a single disk, the result should look something like this:
~~~
NAME SIZE TYPE MOUNTPOINT
sda disk
├──sda1 1G part /boot
└──sda2 part
└──luks-<UUID> crypt
├──qubes_dom0-pool00_tmeta lvm
├──qubes_dom0-pool00_tdata lvm
└──qubes_dom0-swap lvm [SWAP]
~~~
## Encryption Defaults
By default, `cryptsetup 1.7.5` will create a LUKS/dm-crypt volume as follows:
~~~
Version: 1
Cipher name: aes
Cipher mode: xts-plain64
Hash spec: sha256
~~~
~~~
$ cryptsetup --help
[...]
Default compiled-in device cipher parameters:
loop-AES: aes, Key 256 bits
plain: aes-cbc-essiv:sha256, Key: 256 bits, Password hashing: ripdemd160
LUKS1: aes-xts-plain64, Key: 256 bits, LUKS header hashing: sha256, RNG: /dev/urandom
~~~
This means that, by default, Qubes inherits these upstream defaults:
- AES-128 [[1]][cryptsetup-faq][[2]][dm-crypt][[3]][tomb-238]
- SHA-256
- `/dev/urandom`
- probably an `iter-time` of one second
If, instead, you'd like to use AES-256, SHA-512, `/dev/random`, and a longer `iter-time`, for example, you can configure encryption manually by following the instructions below.
## Example: Custom LUKS Configuration
Boot into the Qubes installer, then press `ctrl`+`alt`+`F2` to get a virtual console.
1. (Optional) Wipe the disk:
# dd if=/dev/zero of=/dev/sda bs=1M status=progress && sync
2. Create partitions:
# fdisk /dev/sda
Follow the steps to create two partitions:
- ~500MiB-1GiB for `/boot`
- The rest for `/` (might want to leave some for overprovisioning if it's an SSD)
4. Create LUKS encrypted volume:
# cryptsetup -v --hash sha512 --cipher aes-xts-plain64 --key-size 512 --use-random --iter-time 10000 --verify-passphrase luksFormat /dev/sda2
5. Open encrypted volume:
# cryptsetup open /dev/sda2 luks
6. Create LVM volumes:
# pvcreate /dev/mapper/luks
# vgcreate qubes_dom0 /dev/mapper/luks
# lvcreate -n swap -L 10G qubes_dom0
# lvcreate -T -l +100%FREE qubes_dom0/pool00
# lvcreate -V1G -T qubes_dom0/pool00 -n root
# lvextend -L <size_of_pool00> /dev/qubes_dom0/root
8. Proceed with the installer.
At the disk selection screen, select:
[x] I will configure partitioning.
[ ] Encrypt my data.
Decrypt your partition, then assign `/`, `/boot`, and `swap`.
Proceed normally from there.
[cryptsetup-faq]: https://gitlab.com/cryptsetup/cryptsetup/wikis/FrequentlyAskedQuestions
[dm-crypt]: https://wiki.archlinux.org/index.php/dm-crypt/Device_encryption
[tomb-238]: https://github.com/dyne/Tomb/issues/238

32
user/downloading-installing-upgrading/download-mirrors.md Normal file
View file

@ -0,0 +1,32 @@
---
layout: sidebar
title: Download Mirrors
permalink: /downloads/mirrors/
---
Qubes Download Mirrors
======================
List of Download Mirrors
------------------------
The full list of known Qubes download mirrors is available [here][mirror-list].
Instructions for Mirror Operators
---------------------------------
If you are interested in offering a mirror for Qubes downloads, thank you!
We greatly appreciate your offer, and we hope these brief instructions are
helpful in streamlining the process.
* We are happy to provide rsync or HTTP master.
* Our preferred frequency is **once every 24 hours**, but anything up to once
every 6-8 hours is fine.
* For technical accommodations, please contact [Wojtek] or [Marek].
* For website updates and fixes, please contact [Andrew].
[mirror-list]: /downloads/#mirrors
[Wojtek]: /team/#wojtek-porczyk
[Marek]: /team/#marek-marczykowski-górecki
[Andrew]: /team/#andrew-david-wong

88
user/downloading-installing-upgrading/install-security.md Normal file
View file

@ -0,0 +1,88 @@
---
layout: doc
title: Installation Security
permalink: /doc/install-security/
redirect_from:
- /en/doc/install-security/
- /doc/InstallSecurity/
- /wiki/InstallSecurity/
---
# Installation Security Considerations #
## Verifying the Qubes ISO ##
You should [verify] the PGP signature on your Qubes ISO before you install
from it. However, if the machine on which you attempt the verification process
is already compromised, it could falsely claim that a malicious ISO has a good
signature. Therefore, in order to be certain that your Qubes ISO is trustworthy,
you require a trustworthy machine. But how can you be certain *that* machine is
trustworthy? Only by using another trusted machine, and so forth. This is a
[classic problem]. While various [solutions] have been proposed, the point is
that each user must ultimately make a choice about whether to trust that a file
is non-malicious.
## Choosing an Installation Medium ##
So, after taking some measures to verify its integrity and authenticity, you've
decided to trust your Qubes ISO. Great! Now you must decide what sort of medium
on which to write it so that you can install from it. From a Qubes-specific
security perspective, each has certain pros and cons.
### USB Drives ###
Pros:
* Works via USB, including with a [USB qube].
* Non-fixed capacity. (Easy to find one on which the ISO can fit.)
Cons:
* Rewritable. (If the drive is mounted to a compromised machine, the ISO could
be maliciously altered after it has been written to the drive.)
* Untrustworthy firmware. (Firmware can be malicious even if the drive is new.
Plugging a drive with rewritable firmware into a compromised machine can
also [compromise the drive][BadUSB]. Installing from a compromised drive
could compromise even a brand new Qubes installation.)
### Optical Discs ###
Pros:
* Read-only available. (If you use read-only media, you don't have to worry
about the ISO being maliciously altered after it has been written to the
disc. You then have the option of verifying the signature on multiple
different machines.)
Cons:
* Fixed capacity. (If the size of the ISO is larger than your disc, it will be
inconvenient.)
* Passthrough recording (a.k.a., "burning") is not supported by Xen. (This
mainly applies if you're upgrading from a previous version of Qubes.)
Currently, the only options for recording optical discs (e.g., CDs, DVDs,
BRDs) in Qubes are:
1. Use a USB optical drive.
2. Attach a SATA optical drive to a secondary SATA controller, then assign
this secondary SATA controller to an AppVM.
3. Use a SATA optical drive attached to dom0.
(Option 3 violates the Qubes security model since it entails transferring an
untrusted ISO to dom0 in order to burn it to disc, which leaves only the
other two options.)
Considering the pros and cons of each, perhaps a USB drive with non-rewritable
(or at least cryptographically-signed) firmware and a physical write-protect
switch might be the option.
[verify]: /security/verifying-signatures/
[classic problem]: https://www.ece.cmu.edu/~ganger/712.fall02/papers/p761-thompson.pdf
[solutions]: https://www.dwheeler.com/trusting-trust/
[USB qube]: /doc/usb-qubes/#creating-and-using-a-usb-qube
[BadUSB]: https://srlabs.de/badusb/

151
user/downloading-installing-upgrading/installation-guide.md Normal file
View file

@ -0,0 +1,151 @@
---
layout: doc
title: Installation Guide
permalink: /doc/installation-guide/
redirect_from:
- /en/doc/installation-guide/
- /doc/InstallationGuide/
- /wiki/InstallationGuide/
- /doc/InstallationGuideR1/
- /doc/InstallationGuideR2B1/
- /doc/InstallationGuideR2B2/
- /doc/InstallationGuideR2B3/
- /doc/InstallationGuideR2rc1/
- /doc/InstallationGuideR2rc2/
- /doc/InstallationGuideR3.0rc1/
- /doc/InstallationGuideR3.0rc2/
---
Installation Guide
==================
Qubes 4.0.1 Warning
-------------------
Immediately after installing Qubes 4.0.1, please upgrade all of your Debian and Whonix TemplateVMs by executing the following commands in a dom0 terminal, as applicable for the templates you chose to install:
$ sudo qubes-dom0-update --action=upgrade qubes-template-debian-9
$ sudo qubes-dom0-update --enablerepo=qubes-templates-community --action=upgrade qubes-template-whonix-gw-14
$ sudo qubes-dom0-update --enablerepo=qubes-templates-community --action=upgrade qubes-template-whonix-ws-14
These upgrades are required in order to be protected from the APT update mechanism vulnerability that was announced and patched in [QSB #46], which was after the release of Qubes 4.0.1.
This method is simpler than the method recommended in [QSB #46], but it is just as safe and effective so long as it is performed immediately after installing Qubes OS.
Hardware Requirements
---------------------
Please see the [system requirements] and [Hardware Compatibility List] pages for
more information on required and recommended hardware.
**Note:** We don't recommend installing Qubes in a virtual machine! It will
likely not work. Please don't send emails asking about it. You can, however,
install it on an external USB hard drive (at least 32 GB) and run from it,
at least for testing. Bear in mind, however, that such disks are typically
*orders* of magnitude slower than even the slowest internal hard drives.
Downloading the ISO
-------------------
See the [downloads] page for ISO downloads. Remember, we have absolutely
no control over those servers, so you should be assuming that they might be
compromised, or just be serving compromised ISOs because their operators decided
so, for whatever reason. Always verify the digital signature on the downloaded
ISO. Make sure to read our guide on [verifying signatures] for more info about
how to download and verify our PGP keys and verify the downloaded ISO.
Copying the ISO onto the installation medium
--------------------------------------------
Once you verify this is an authentic ISO, you should copy it onto the
installation medium of your choice, such as a DVD or a USB drive. (Please note
that there are important [security considerations] to keep in mind when choosing
an installation medium.)
If you prefer to use a USB drive, then you just need to copy the ISO onto the
USB device, e.g. using `dd`:
dd if=Qubes-R3-x86_64.iso of=/dev/sdX bs=1048576 && sync
Change `Qubes-R3-x86_64.iso` to the filename of the version you're installing,
and change `/dev/sdX` to the correct target device (e.g., `/dev/sdc`).
**Warning:** Choosing the wrong device could result in data loss. Make sure to
write to the entire device (e.g., `/dev/sdc`) rather than just a single
partition (e.g., `/dev/sdc1`).
On Windows, you can use the [Rufus] tool. Be sure to select "DD image" mode (you
need to do that **after** selecting the Qubes ISO):
**Warning:** If you do that on Windows 10, you can only install Qubes without
MediaTest, which isn't recommended.
<img src="/attachment/wiki/InstallationGuide/rufus-main-boxed.png" height="350">
Before proceeding with the installation, you are encouraged to first read all
the information on this page. When you're ready, boot your system from the
installation source and follow the on-screen instructions. The installer is very
simple and asks very few questions. (It's actually easier to install Qubes right
now than most other Linux distributions!)
The installer loads Xen right at the beginning, so chances are high that if you
can see the installer's graphical screen and you pass the compatibility check that
runs immediately after that, Qubes will work on your system. :)
If you're an advanced user, and you'd like to customize your installation, please see [Custom Installation].
Installing to a USB drive
-------------------------
Installing an operating system onto a USB drive can be a convenient and secure
method of ensuring that your data is protected. Be advised that a minimum
storage of 32 GB is required on the USB drive. This installation process may
take longer than an installation on a standard hard disk. The installation
process is identical to using a hard disk in conjunction with two exceptions:
* Select the USB as the storage location for the OS.
* Leave the option checked to “Automatically configure my Qubes installation to
the disk(s) I selected and return me to the main menu”.
Upgrading
---------
For instructions in upgrading an existing installation, please see [Upgrade Guides].
Getting Help
------------
* We work very hard on making the [documentation] accurate, comprehensive, and
useful. We urge you to read it! It may very well contain the answers to your
questions. (Since the documentation is a community effort, we'd also greatly
appreciate your help in [improving] it!)
* If you don't find your answer in the documentation, it may be time to consult
the [mailing lists], as well as the many other available sources of [help].
* Please do not email individual developers (Marek, etc.) with
questions about installation or other problems. Please send all such
questions to the appropriate mailing list.
[QSB #46]: /news/2019/01/23/qsb-46/
[system requirements]: /doc/system-requirements/
[Hardware Compatibility List]: /hcl/
[live USB]: /doc/live-usb/
[downloads]: /downloads/
[verifying signatures]: /security/verifying-signatures/
[security considerations]: /doc/install-security/
[Custom Installation]: /doc/custom-install/
[Upgrade Guides]: /doc/upgrade/
[Rufus]: https://rufus.akeo.ie/
[documentation]: /doc/
[improving]: /doc/doc-guidelines/
[mailing lists]: /support/
[help]: /help/

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

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

102
user/downloading-installing-upgrading/supported-versions.md Normal file
View file

@ -0,0 +1,102 @@
---
layout: doc
title: Supported Versions
permalink: /doc/supported-versions/
---
Supported Versions
==================
Qubes OS
--------
Qubes OS releases are supported for **six months** after each subsequent major
or minor release (see [Version Scheme]). The current release and past major
releases are always available on the [Downloads] page, while all ISOs, including
past minor releases, are available from our [download mirrors].
| Qubes OS | Start Date | End Date | Status |
| ------------- | ---------- | ---------- | ----------------------- |
| Release 1 | 2012-09-03 | 2015-03-26 | Old, unsupported |
| Release 2 | 2014-09-26 | 2016-04-01 | Old, unsupported |
| Release 3.0 | 2015-10-01 | 2016-09-09 | Old, unsupported |
| Release 3.1 | 2016-03-09 | 2017-03-29 | Old, unsupported |
| Release 3.2 | 2016-09-29 | 2019-03-28 | Old, unsupported |
| Release 4.0 | 2018-03-28 | TBA | Current, supported |
| Release 4.1 | TBA | TBA | [In development][4.1] |
### Note on point releases ###
Please note that point releases, such as 3.2.1 and 4.0.1, do not designate
separate, new versions of Qubes OS. Rather, they designate their respective
major or minor releases, such as 4.0 and 3.2, inclusive of all package updates
up to a certain point. For example, installing Release 4.0 and fully updating it
results in the same system as installing Release 4.0.1. Therefore, point
releases are not displayed as separate rows on any of the tables on this page.
Dom0
----
The table below shows the OS used for dom0 in each Qubes OS release.
| Qubes OS | Dom0 OS |
| ------------- | --------- |
| Release 1 | Fedora 13 |
| Release 2 | Fedora 18 |
| Release 3.0 | Fedora 20 |
| Release 3.1 | Fedora 20 |
| Release 3.2 | Fedora 23 |
| Release 4.0 | Fedora 25 |
### Note on dom0 and EOL ###
Dom0 is isolated from domUs. DomUs can access only a few interfaces,
such as Xen, device backends (in the dom0 kernel and in other VMs, such as the
NetVM), and Qubes tools (gui-daemon, qrexec-daemon, etc.). These components are
[security-critical], and we provide updates for all of them (when necessary),
regardless of the support status of the base distribution. For this reason, we
consider it safe to continue using a given base distribution in dom0 even after
it has reached EOL (end-of-life).
TemplateVMs
-----------
The table below shows the [TemplateVM] versions supported by each Qubes OS
release. Currently, only Fedora, Debian, and Whonix TemplateVMs are officially supported.
| Qubes OS | Fedora | Debian | Whonix |
| ------------- | ---------------------------- | --------------------------------------------- | ------ |
| Release 1 | 18, 20 | None | None |
| Release 2 | 21 | None | None |
| Release 3.0 | 21, 22\*, 23 | 7 ("wheezy")\*, 8 ("jessie") | None |
| Release 3.1 | 21, 22\*, 23 | 7 ("wheezy")\*, 8 ("jessie"), 9 ("stretch")\* | None |
| Release 3.2 | 23\*, 24\*, 25\*, 26, 27, 28 | 8 ("jessie"), 9 ("stretch") | 13, 14 |
| Release 4.0 | 26, 27, 28, 29 | 8 ("jessie"), 9 ("stretch") | 13, 14 |
\* Denotes versions for which we have published the packages but have not done
extensive testing.
Whonix
------
[Whonix] is an advanced feature in Qubes OS.
Those who wish to use it must stay reasonably close to the cutting edge by upgrading to new stable versions of Qubes OS and Whonix TemplateVMs within a month of their respective releases.
To be precise:
* One month after a new stable version of Qubes OS is released, Whonix TemplateVMs will no longer be supported on any older version of Qubes OS.
This means that users who wish to continue using Whonix TemplateVMs on Qubes must always upgrade to the latest stable Qubes OS version within one month of its release.
* One month after new stable versions of Whonix TemplateVMs are released, older versions of Whonix TemplateVMs will no longer be supported.
This means that users who wish to continue using Whonix TemplateVMs on Qubes must always upgrade to the latest stable Whonix TemplateVM versions within one month of their release.
We aim to announce both types of events one month in advance in order to remind users to upgrade.
[Version Scheme]: /doc/version-scheme/
[Downloads]: /downloads/
[download mirrors]: /downloads/#mirrors
[security-critical]: /doc/security-critical-code/
[TemplateVM]: /doc/templates/
[extended support]: /news/2018/03/28/qubes-40/#the-past-and-the-future
[4.1]: https://github.com/QubesOS/qubes-issues/issues?utf8=%E2%9C%93&q=is%3Aissue+milestone%3A%22Release+4.1%22+
[Whonix]: /doc/whonix/

50
user/downloading-installing-upgrading/testing.md Normal file
View file

@ -0,0 +1,50 @@
---
layout: doc
title: Testing New Releases and Updates
permalink: /doc/testing/
---
Testing New Releases and Updates
================================
Testing new Qubes OS releases and updates is one of the most helpful ways in which you can [contribute] to the Qubes OS Project.
However, you should only attempt to do this if you know what you're doing.
Never rely on code that is in testing for critical work!
Releases
--------
How to test upcoming Qubes OS releases:
* Use [qubes-builder] to build the latest release.
* Test the latest release candidate (RC), if any is currently available.
See [Version Scheme] for details about release versions and schedules.
See [Release Checklist] for details about the RC process.
Updates
-------
How to test updates:
* Enable [dom0 testing repositories].
* Enable [TemplateVM testing repositories].
Providing Feedback
------------------
If you're testing new releases or updates, we would be grateful for your feedback.
We use an [automated build process].
For every package that is uploaded to a testing repository, a GitHub issue is created in the [updates-status] repository for tracking purposes.
We welcome any kind of feedback on any package in any testing repository.
Even a simple <span class="fa fa-thumbs-up" title="Thumbs Up"></span> or <span class="fa fa-thumbs-down" title="Thumbs Down"></span> on the package's associated issue would help us to decide whether the package is ready to be migrated to a stable repository.
If you [report a bug] in a package that is in a testing repository, please reference the appropriate issue in [updates-status].
[contribute]: /doc/contributing/
[qubes-builder]: /doc/qubes-builder/
[Version Scheme]: /doc/version-scheme/
[Release Checklist]: /doc/releases/todo/
[dom0 testing repositories]: /doc/software-update-dom0/#testing-repositories
[TemplateVM testing repositories]: /doc/software-update-vm/#testing-repositories
[automated build process]: https://github.com/QubesOS/qubes-infrastructure/blob/master/README.md
[updates-status]: https://github.com/QubesOS/updates-status/issues
[report a bug]: /doc/reporting-bugs/

64
user/downloading-installing-upgrading/upgrade/upgrade-to-r2.md Normal file
View file

@ -0,0 +1,64 @@
---
layout: doc
title: Upgrading to R2
permalink: /doc/upgrade-to-r2/
redirect_from:
- /en/doc/upgrade-to-r2/
- /doc/UpgradeToR2/
- /doc/UpgradeToR2rc1/
- /wiki/UpgradeToR2rc1/
---
Upgrading Qubes R2 Beta 3 to R2
===================================
Current Qubes R2 Beta 3 (R2B3) systems can be upgraded in-place to the latest R2 (R2) release by following the procedure below.
**Before attempting either an in-place upgrade or a clean installation, we strongly recommend that users back up the system by using the built-in [backup tool](/doc/backup-restore/).**
Upgrade Template and Standalone VM(s)
-------------------------------------
- Qubes R2 comes with new template based on Fedora 20. You can upgrade existing template according to procedure described [here](/doc/templates/fedora/#upgrading).
- **It also possible to download a new Fedora 20-based template from our repositories**. To do this please first upgrade the Dom0 distro as described in the section below.
While technically it is possible to use old Fedora 18 template on R2, it is strongly recommended to upgrade all the Template VMs and Standalone VMs, because Fedora 18 no longer receive security updates.
By default, in Qubes R2, there is only one Template VM, however users are free to create more Template VMs for special purposes, as well as Standalone VMs. If more than one template and/or Standalone VMs are used, then it is recommended to upgrade/replace all of them. More information on using multiple Template VMs, as well as Standalone VMs, can be found [here](/doc/software-update-vm/).
Upgrading dom0
--------------
Note that dom0 in R2 is based on Fedora 20, in contrast to Fedora 18 in previous release, so this operation will upgrade a lot of packages.
1. Open terminal in Dom0. E.g. Start-\>System Settings-\>Konsole.
1. Install all the updates for Dom0:
~~~
sudo qubes-dom0-update
~~~
After this step you should have `qubes-release-2-5` in your Dom0. Important: if you happen to have `qubes-release-2-6*` then you should downgrade to `qubes-release-2-5`! The `qubes-release-2-6*` packages have been uploaded to the testing repos and were kept there for a few hours, until we realized they bring incorrect repo definitions and so we removed them and also have changed the update procedure a bit (simplifying it).
1. Upgrade dom0 to R2:
Note: be sure that the VM used as a update-downloading-vm (by default its the firewallvm based on the default template) has been updated to the latest Qubes packages, specifically `qubes-core-vm-2.1.33` or later. This doesn't imply that the VM must already be upgraded to fc20 -- for Dom0 upgrade we could still use an fc18-based VM (updatevm) it is only important to install the latest Qubes packages there.
~~~
sudo qubes-dom0-update qubes-dom0-dist-upgrade
sudo qubes-dom0-update
~~~
1. If above step completed successfully you should have `qubes-release-2-9` or later. If not, repeat above step with additional `--clean` option.
4a. If you chose not to upgrade your fc18 templates, but instead to download our new fc20-based template you should now be able to do that by simply typing:
~~~
sudo qubes-dom0-update qubes-template-fedora-20-x64
~~~
1. Reboot the system.
Please note that if you use Anti Evil Maid, then it won't be able to unseal the passphrase this time, because the Xen, kernel, and initramfs binaries have changed. Once the system boots up again, you could reseal your Anti Evil Maid's passphrase to the new configuration. Please consult Anti Evil Maid documentation for explanation on how to do that.

77
user/downloading-installing-upgrading/upgrade/upgrade-to-r2b1.md Normal file
View file

@ -0,0 +1,77 @@
---
layout: doc
title: Upgrading to R2B1
permalink: /doc/upgrade-to-r2b1/
redirect_from:
- /en/doc/upgrade-to-r2b1/
- /doc/UpgradeToR2B1/
- /wiki/UpgradeToR2B1/
---
Upgrading Qubes R1 to R2 Beta 1
===============================
**Note: Qubes R2 Beta 1 is no longer supported! Please install or upgrade to a newer Qubes R2.**
**Note: This page is kept for historical reasons only! Do not follow the instructions below'''**
Existing users of Qubes R1 (but not R1 betas!) can upgrade their systems to the latest R2 beta release by following the procedure below. As usual, it is advisable to backup the system before proceeding with the upgrade
Upgrade all Template and Standalone VM(s)
-----------------------------------------
By default, in Qubes R1, there is only one Template VM, however users are free to create more Template VMs for special purposes, as well as Standalone VMs. More information on using multiple Template VMs, as well as Standalone VMs, can be found [SoftwareUpdateVM here]. The steps described in this section should be repeated in *all* user's Template and Standalone VMs.
1. Open terminal in the template VM (or standalone VM). E.g. use the Qubes Manager's right-click menu and choose Run Command in VM and type `gnome-terminal` there.
2. Install `qubes-upgrade-vm` package (this package brings in R2 repo definitions and R2 keys)
~~~
sudo yum install qubes-upgrade-vm
~~~
3. Proceed with normal update in the template (this should bring in also the R2 packages for the VMs):
~~~
sudo yum update
~~~
The installer (yum) will prompt to accept the new Qubes R2 signing key:
~~~
Importing GPG key 0x0A40E458:
Userid : "Qubes OS Release 2 Signing Key"
Fingerprint: 3f01 def4 9719 158e f862 66f8 0c73 b9d4 0a40 e458
Package : qubes-upgrade-vm-1.0-1.fc17.x86_64 (@qubes-vm-current)
From : /etc/pki/rpm-gpg/RPM-GPG-KEY-upgrade-qubes-2-primary
Is this ok [y/N]:
~~~
If you see (as is the case on the "screenshot" above) that the new key was imported from a local filesystem (`/etc/pki/rpm-gpg/...`) you can safely accept the key, without checking its fingerprint. This is because there were only two ways for such a key to make it to your Template VM's filesystem:
- via a legitimate RPM package previously installed (in our case it was the `qubes-upgrade-vm` RPM). Such an RPM must have been signed by one of the keys you decided to trust previously, by default this would be either via the Qubes R1 signing key, or Fedora 17 signing key.
- via system compromise or via some illegal RPM package (e.g. Fedora released package pretending to bring new Firefox). In that case, however, your VM is already compromised, and it careful checking of the new R2 key would not change this situation to any better one. The game is lost for this VM anyway (and all VMs based on this template).
1. Shut down the VM.
Upgrade Dom0
------------
Be sure to do steps described in this section after *all* your template and standalone VMs got updated as described in the section above.
1. Open terminal in Dom0. E.g. Start-\>System Settings-\>Konsole.
2. Upgrade the `qubes-release` package to the latest version which brings in new repo definitions and R2 signing keys:
~~~
sudo qubes-dom0-update qubes-release
~~~
This should install `qubes-release-1-6` in your Dom0.
3. Install R2 packages:
~~~
sudo qubes-dom0-update --releasever=2
~~~
4. Reboot your system. Please note that if you use Anti Evil Maid, then it won't be able to unseal the passphrase this time, because the Xen, kernel, and initramfs binaries have changed. Once the system boots up again, you could reseal your Anti Evil Maid's passphrase to the new configuration. Please consult Anti Evil Maid documentation for explanation on how to do that.

109
user/downloading-installing-upgrading/upgrade/upgrade-to-r2b2.md Normal file
View file

@ -0,0 +1,109 @@
---
layout: doc
title: Upgrading to R2B2
permalink: /doc/upgrade-to-r2b2/
redirect_from:
- /en/doc/upgrade-to-r2b2/
- /doc/UpgradeToR2B2/
- /wiki/UpgradeToR2B2/
---
Upgrading Qubes R1 to R2 (beta2)
================================
Existing users of Qubes R1 (but not R1 betas!) can upgrade their systems to the latest R2 beta release by following the procedure below. As usual, it is advisable to backup the system before proceeding with the upgrade. While it is possible to upgrade the system **it is strongly recommended to reinstall it**. You will preserve all your data and settings thanks to [backup and restore tools](/doc/backup-restore/).
Upgrade all Template and Standalone VM(s)
-----------------------------------------
**If you have already R2 Beta1 installed, follow standard template update procedure (e.g. "Update VM" button in Qubes Manager) and skip the rest of this section**
By default, in Qubes R1, there is only one Template VM, however users are free to create more Template VMs for special purposes, as well as Standalone VMs. More information on using multiple Template VMs, as well as Standalone VMs, can be found [SoftwareUpdateVM here]. The steps described in this section should be repeated in *all* user's Template and Standalone VMs.
1. Open terminal in the template VM (or standalone VM). E.g. use the Qubes Manager's right-click menu and choose Run Command in VM and type `gnome-terminal` there.
2. Install `qubes-upgrade-vm` package (this package brings in R2 repo definitions and R2 keys)
~~~
sudo yum install qubes-upgrade-vm
~~~
3. Proceed with normal update in the template (this should bring in also the R2 packages for the VMs):
~~~
sudo yum update
~~~
The installer (yum) will prompt to accept the new Qubes R2 signing key:
~~~
Importing GPG key 0x0A40E458:
Userid : "Qubes OS Release 2 Signing Key"
Fingerprint: 3f01 def4 9719 158e f862 66f8 0c73 b9d4 0a40 e458
Package : qubes-upgrade-vm-1.0-1.fc17.x86_64 (@qubes-vm-current)
From : /etc/pki/rpm-gpg/RPM-GPG-KEY-upgrade-qubes-2-primary
Is this ok [y/N]:
~~~
If you see (as is the case on the "screenshot" above) that the new key was imported from a local filesystem (`/etc/pki/rpm-gpg/...`) you can safely accept the key, without checking its fingerprint. This is because there were only two ways for such a key to make it to your Template VM's filesystem:
- via a legitimate RPM package previously installed (in our case it was the `qubes-upgrade-vm` RPM). Such an RPM must have been signed by one of the keys you decided to trust previously, by default this would be either via the Qubes R1 signing key, or Fedora 17 signing key.
- via system compromise or via some illegal RPM package (e.g. Fedora released package pretending to bring new Firefox). In that case, however, your VM is already compromised, and it careful checking of the new R2 key would not change this situation to any better one. The game is lost for this VM anyway (and all VMs based on this template).
1. Shut down the VM.
Installing new template
-----------------------
Qubes R2 Beta2 brings new fedora-18-x64 template (based on Fedora 18). You can install it from Qubes installation DVD. Insert installation DVD into your drive and issue following commands:
~~~
$ sudo -s
# mkdir -p /mnt/cdrom
# mount /dev/cdrom /mnt/cdrom # you can also use ISO image instead of /dev/cdrom; then add -o loop option
# yum install /mnt/cdrom/Packages/q/qubes-template-fedora-18-x64*rpm
# umount /mnt/cdrom
~~~
If you already have fedora-17-x64, you can also upgrade it to fedora-18-x64 following [standard Fedora upgrade procedure](https://fedoraproject.org/wiki/Upgrading_Fedora_using_yum) (only "yum" method will work in Qubes VM).
Upgrade Dom0
------------
Be sure to do steps described in this section after *all* your template and standalone VMs got updated as described in the section above.
1. Open terminal in Dom0. E.g. Start-\>System Settings-\>Konsole.
2. Upgrade the `qubes-release` package to the latest version which brings in new repo definitions and R2 signing keys:
~~~
sudo qubes-dom0-update qubes-release
~~~
This should install `qubes-release-1-6` in your Dom0.
3. Install R2 upgrade package:
~~~
sudo qubes-dom0-update --releasever=1 qubes-dist-upgrade
~~~
4. Start upgrade process:
~~~
sudo qubes-dist-upgrade
~~~
5. Follow instructions on screen, first stage of upgrade should end up with reboot request.
6. Reboot your system, ensure that you choose "Qubes Upgrade" boot option.
7. When system starts up, login and start start
~~~
sudo qubes-dist-upgrade
~~~
again. This will start second stage of upgrade, here most packages will be upgraded, so this will take a while.
8. You will be prompted to install new bootloader. If you haven't changed anything in this matter from initial installation, just accept the default.
9. Reboot your system. System shutdown may hung because some running system components no longer match that installed on disk; just wait a few minutes and hard reset the system in such case.
10. This is end of upgrade process, you should now have Qubes R2 system.
Please note that if you use Anti Evil Maid, then it won't be able to unseal the passphrase this time, because the Xen, kernel, and initramfs binaries have changed. Once the system boots up again, you could reseal your Anti Evil Maid's passphrase to the new configuration. Please consult Anti Evil Maid documentation for explanation on how to do that.

77
user/downloading-installing-upgrading/upgrade/upgrade-to-r2b3.md Normal file
View file

@ -0,0 +1,77 @@
---
layout: doc
title: Upgrading to R2B3
permalink: /doc/upgrade-to-r2b3/
redirect_from:
- /en/doc/upgrade-to-r2b3/
- /doc/UpgradeToR2B3/
- /wiki/UpgradeToR2B3/
---
Upgrading Qubes R2 Beta 2 to R2 Beta 3
======================================
Current Qubes R2 Beta 2 (R2B2) systems can be upgraded in-place to the latest R2 Beta 3 (R2B3) release by following the procedure below. However, upgrading in-place is riskier than performing a clean installation, since there are more things which can go wrong. For this reason, **we strongly recommended that users perform a [clean installation](/doc/installation-guide/) of Qubes R2 Beta 3**.
**Before attempting either an in-place upgrade or a clean installation, we strongly recommend that users back up the system by using the built-in [backup tool](/doc/backup-restore/).**
Experienced users may be comfortable accepting the risks of upgrading in-place. Such users may wish to first attempt an in-place upgrade. If nothing goes wrong, then some time and effort will have been saved. If something does go wrong, then the user can simply perform a clean installation, and no significant loss will have occurred (as long as the user [backed up](/doc/backup-restore/) correctly!).
Upgrade all Template and Standalone VM(s)
-----------------------------------------
By default, in Qubes R2, there is only one Template VM, however users are free to create more Template VMs for special purposes, as well as Standalone VMs. More information on using multiple Template VMs, as well as Standalone VMs, can be found [here](/doc/software-update-vm/). The steps described in this section should be repeated in *all* user's Template and Standalone VMs.
It is critical to complete this step **before** proceeding to dom0 upgrade. Otherwise you will most likely ends with unusable system.
1. Open terminal in the template VM (or standalone VM). E.g. use the Qubes Manager's right-click menu and choose Run Command in VM and type `gnome-terminal` there.
2. Proceed with normal update in the template:
~~~
sudo yum update
~~~
3. Ensure that you've got qubes-core-vm package version 2.1.13-3.fc18:
~~~
rpm -q qubes-core-vm
~~~
4. Update the system to R2 beta3 packages:
~~~
sudo yum --enablerepo=qubes-vm-r2b3-current update
~~~
5. **Do not** shutdown the VM.
Upgrading dom0
--------------
Be sure to do steps described in this section after *all* your template and standalone VMs got updated as described in the section above. Also make sure you haven't shutdown any of: netvm, firewallvm, fedora-18-x64 (or to be more precise: template which your netvm and firewallvm is based on).
1. Open terminal in Dom0. E.g. Start-\>System Settings-\>Konsole.
2. Upgrade the `qubes-release` package to the latest version which brings in new repo definitions and R2 signing keys:
~~~
sudo qubes-dom0-update qubes-release
~~~
This should install `qubes-release-2-3.1` in your Dom0.
3. Upgrade dom0 to R2 beta3:
~~~
sudo qubes-dom0-update --enablerepo=qubes-dom0-r2b3-current
~~~
4. If above step completed successfully you should have qubes-core-dom0 at least 2.1.34. If not, repeat above step with additional `--clean` option.
5. Now is the time to shutdown all the VMs:
~~~
qvm-shutdown --all --wait
~~~
6. Reboot the system.
Please note that if you use Anti Evil Maid, then it won't be able to unseal the passphrase this time, because the Xen, kernel, and initramfs binaries have changed. Once the system boots up again, you could reseal your Anti Evil Maid's passphrase to the new configuration. Please consult Anti Evil Maid documentation for explanation on how to do that.

147
user/downloading-installing-upgrading/upgrade/upgrade-to-r3.0.md Normal file
View file

@ -0,0 +1,147 @@
---
layout: doc
title: Upgrading to R3.0
permalink: /doc/upgrade-to-r3.0/
redirect_from:
- /en/doc/upgrade-to-r3.0/
- /doc/UpgradeToR3.0/
- /doc/UpgradeToR3.0rc1/
---
Upgrading Qubes R2 to R3.0
======================================
**This instruction is highly experimental, the official way to upgrade from R2 is to backup the data and reinstall the system. Use at your own risk!**
Current Qubes R3.0 (R3.0) systems can be upgraded in-place to the latest R3.0 by following the procedure below. However, upgrading in-place is riskier than performing a clean installation, since there are more things which can go wrong. For this reason, **we strongly recommended that users perform a [clean installation](/doc/installation-guide/) of Qubes R3.0**.
**Before attempting either an in-place upgrade or a clean installation, we strongly recommend that users back up the system by using the built-in [backup tool](/doc/backup-restore/).**
Experienced users may be comfortable accepting the risks of upgrading in-place. Such users may wish to first attempt an in-place upgrade. If nothing goes wrong, then some time and effort will have been saved. If something does go wrong, then the user can simply perform a clean installation, and no significant loss will have occurred (as long as the user [backed up](/doc/backup-restore/) correctly!).
Upgrade all Template and Standalone VM(s)
-----------------------------------------
By default, in Qubes R2, there is only one Template VM, however users are free to create more Template VMs for special purposes, as well as Standalone VMs. More information on using multiple Template VMs, as well as Standalone VMs, can be found [here](/doc/software-update-vm/). The steps described in this section should be repeated in **all** user's Template and Standalone VMs.
It is critical to complete this step **before** proceeding to dom0 upgrade. Otherwise you will most likely end with unusable system.
### Upgrade Fedora template:
1. Open terminal in the template VM (or standalone VM). E.g. use the Qubes Manager's right-click menu and choose Run Command in VM and type `gnome-terminal` there.
2. Install `qubes-upgrade-vm` package:
sudo yum install qubes-upgrade-vm
3. Proceed with normal update in the template:
sudo yum update
You'll need to accept "Qubes Release 3 Signing Key" - it is delivered by signed qubes-upgrade-vm package (verify that the message is about local file), so you don't need to manually verify it.
4. Shutdown the template VM.
### Upgrade Debian template:
1. Open terminal in the template VM (or standalone VM). E.g. use the Qubes Manager's right-click menu and choose Run Command in VM and type `gnome-terminal` there.
2. Update repository definition:
sudo cp /etc/apt/sources.list.d/qubes-r2.list
/etc/apt/sources.list.d/qubes-r3-upgrade.list
sudo sed -i 's/r2/r3.0/' /etc/apt/sources.list.d/qubes-r3-upgrade.list
3. Proceed with normal update in the template:
sudo apt-get update
sudo apt-get dist-upgrade
There will be some error messages during the process, but our tests does
not revealed any negative consequences.
Update of `qubesdb-vm` package will restart the service, which will fail
(after 3min timeout), but you can ignore this problem for now. After
completing the whole upgrade the service will be properly restarted.
4. Shutdown the template VM.
Upgrading dom0
--------------
Be sure to do steps described in this section after *all* your template and standalone VMs got updated as described in the section above. Also make sure you haven't shutdown any of: netvm, firewallvm - you will not be able to start them again.
1. Open terminal in Dom0. E.g. Start-\>System Settings-\>Konsole.
2. Upgrade the `qubes-release` package to the latest version which brings in new repo definitions and R2 signing keys:
sudo qubes-dom0-update qubes-release
This should install `qubes-release-2-12` in your Dom0.
3. Upgrade dom0 to R3.0:
sudo qubes-dom0-update --releasever=3.0
After this step, until you reboot the system, most of the qvm-* tools will not work.
4. If above step completed successfully you should have `qubes-core-dom0` at least 3.0.8. If not, repeat above step with additional `--clean` option.
5. Enable Xen services:
sudo systemctl enable xenconsoled.service xenstored.service
6. Reboot the system.
It may happen that the system hang during the reboot. Hard reset the system in such case, all the filesystems are unmounted at this stage.
Please note that if you use Anti Evil Maid, then it won't be able to unseal the passphrase this time, because the Xen, kernel, and initramfs binaries have changed. Once the system boots up again, you could reseal your Anti Evil Maid's passphrase to the new configuration. Please consult Anti Evil Maid documentation for explanation on how to do that.
Now, when you have dom0 upgraded, you can install new templates from Qubes R3.0 repositories. Especially Fedora 21 - default Qubes R3.0 template:
sudo qubes-dom0-update qubes-template-fedora-21
Upgrading template on already upgraded dom0
-------------------------------------------
If for some reason you did not upgrade all the templates and standalone VMs before upgrading dom0, you can still do this, but it will be more complicated. This can be the case when you restore backup done on Qubes R2.
When you start R2 template/standalone VM on R3.0, there will be some limitations:
1. qrexec will not connect (you will see an error message during VM startup)
2. GUI will not connect - you will not see any VM window
3. VM will not be configured - especially it will not have network access
Because of above limitations, you will need to configure some of those manually. The instruction assumes the VM name is `custom-template`, but the same instructions can be applied to a standalone VM.
1.Check the VM network parameters, you will need them later:
[user@dom0 ~]$ qvm-ls -n custom-template
-------------------+----+--------+-------+------+-------------+-------+-------------+---------+-------------+
name | on | state | updbl | type | netvm | label | ip | ip back | gateway/DNS |
-------------------+----+--------+-------+------+-------------+-------+-------------+---------+-------------+
[custom-template] | | Halted | Yes | Tpl | *firewallvm | black | 10.137.1.53 | n/a | 10.137.1.1 |
2.Start the VM from command line:
[user@dom0 ~]$ qvm-start custom-template
--> Loading the VM (type = TemplateVM)...
--> Starting Qubes DB...
--> Setting Qubes DB info for the VM...
--> Updating firewall rules...
--> Starting the VM...
--> Starting the qrexec daemon...
Waiting for VM's qrexec agent.............................................................Cannot connect to 'custom-template' qrexec agent for 60 seconds, giving up
ERROR: Cannot execute qrexec-daemon!
You can interrupt with Ctrl-C that qrexec waiting process.
3.Access VM console:
[user@dom0 ~]$ virsh -c xen:/// console custom-template
4.Configure network according to parameters retrieved in first step:
ip addr add 10.137.1.53/32 dev eth0
ip route add 10.137.1.1/32 dev eth0
ip route add via 10.137.1.1
echo nameserver 10.137.1.1 > /etc/resolv.conf
5.Proceed with normal upgrade instruction described on this page.

117
user/downloading-installing-upgrading/upgrade/upgrade-to-r3.1.md Normal file
View file

@ -0,0 +1,117 @@
---
layout: doc
title: Upgrading to R3.1
permalink: /doc/upgrade-to-r3.1/
redirect_from:
- /en/doc/upgrade-to-r3.1/
- /doc/UpgradeToR3.1/
- /doc/UpgradeToR3.1rc1/
---
Upgrading Qubes R3.0 to R3.1
======================================
**Before attempting either an in-place upgrade or a clean installation, we
strongly recommend that users [back up their systems](/doc/backup-restore/).**
Current Qubes R3.0 systems can be upgraded in-place to the latest R3.1
by following the procedure below.
Upgrade all Template and Standalone VM(s)
-----------------------------------------
By default, in Qubes R3.0, there is only one TemplateVM. However, users are
free to create more TemplateVMs for special purposes, as well as StandaloneVMs.
More information on using multiple TemplateVMs, as well as StandaloneVMs, can be
found [here](/doc/software-update-vm/). The steps described in this
section should be repeated in **all** the user's Template and Standalone VMs.
### Upgrade Fedora templates: ###
1. Open a terminal in the TemplateVM (or StandaloneVM). (E.g., use Qubes VM
Manager's right-click menu, choose "Run Command in VM," and type
`gnome-terminal` there.)
2. Install the `qubes-upgrade-vm` package:
sudo yum install qubes-upgrade-vm
3. Proceed with a normal upgrade in the template:
sudo yum upgrade
4. Shut down the template VM.
### Upgrade Debian (and Whonix) templates: ###
1. Open a terminal in the TemplateVM (or StandaloneVM). (E.g., use Qubes VM
Manager's right-click menu, choose "Run Command in VM," and type
`gnome-terminal` there.)
2. Update repository definition:
sudo cp /etc/apt/sources.list.d/qubes-r3.list /etc/apt/sources.list.d/qubes-r3-upgrade.list
sudo sed -i 's/r3.0/r3.1/' /etc/apt/sources.list.d/qubes-r3-upgrade.list
3. Proceed with a normal update in the template:
sudo apt-get update
sudo apt-get dist-upgrade
4. Remove unnecessary now file:
sudo rm -f /etc/apt/sources.list.d/qubes-r3-upgrade.list
5. Shut down the template VM.
Upgrading dom0
--------------
**Important:** Do not perform the steps described in this section until **all**
your Template and Standalone VMs have been upgraded as described in the previous
section. Also, do not shut down `sys-net` or `sys-firewall`, since you will not
be able to start them again until after the entire in-place upgrade procedure is
complete.
1. Open a terminal in Dom0. (E.g., Start -\> System Settings -\> Konsole.)
2. Upgrade dom0 to R3.1:
sudo qubes-dom0-update --releasever=3.1
At this point, most of the `qvm-*` tools will stop working until after you
reboot the system.
3. If the previous step completed successfully, your `qubes-core-dom0` version
should be `3.1.4` or higher. If it's not, repeat the previous step with the
`--clean` option.
4. Reboot dom0.
The system may hang during the reboot. If that happens, do not panic. All
the filesystems will have already been unmounted at this stage, so you can
simply perform a hard reboot (e.g., hold the physical power button down
until the machine shuts off, wait a moment, then press it again to start it
back up).
Please note that if you use [Anti Evil Maid](/doc/anti-evil-maid), it won't be
able to unseal the passphrase the first time the system boots after performing
this in-place upgrade procedure since the Xen, kernel, and initramfs binaries
will have changed. Once the system boots up again, you can reseal your Anti Evil
Maid passphrase to the new configuration. Please consult the Anti Evil Maid
[documentation](/doc/anti-evil-maid) for instructions on how to do that.
If you use USB VM, you may encounter problem with starting it on updated Xen
version (because of strict default settings). Take a look at
[User FAQ](/faq/#i-created-a-usbvm-and-assigned-usb-controllers-to-it-now-the-usbvm-wont-boot)
for details.
Once you have upgraded dom0, you can install new templates from Qubes R3.1
repositories, in particular the new default Fedora 23 template:
sudo qubes-dom0-update qubes-template-fedora-23

167
user/downloading-installing-upgrading/upgrade/upgrade-to-r3.2.md Normal file
View file

@ -0,0 +1,167 @@
---
layout: doc
title: Upgrading to R3.2
permalink: /doc/upgrade-to-r3.2/
redirect_from:
- /en/doc/upgrade-to-r3.2/
- /doc/UpgradeToR3.2/
- /doc/UpgradeToR3.2rc1/
---
Upgrading Qubes R3.1 to R3.2
======================================
**Before attempting either an in-place upgrade or a clean installation, we
strongly recommend that users [back up their systems](/doc/backup-restore/).**
Current Qubes R3.1 systems can be upgraded in-place to the latest R3.2
by following the procedure below.
Upgrading dom0
--------------
1. Close Qubes Manager (right click on its tray icon -\> Exit)
2. Open a terminal in Dom0. (E.g., Start -\> System Settings -\> Konsole.)
3. Install `qubes-release` package carrying R3.2 repository information.
sudo qubes-dom0-update --releasever=3.2 qubes-release
If you made any manual changes to repository definitions, new definitions
will be installed as `/etc/yum.repos.d/qubes-dom0.repo.rpmnew` (you'll see
a message about it during package installation). In such a case, you need
to manually apply the changes to `/etc/yum.repos.d/qubes-dom0.repo` or
simply replace it with .rpmnew file.
If you are using Debian-based VM as UpdateVM (`sys-firewall` by default),
you need to download few more packages manually, but **do not install
them** yet:
sudo qubes-dom0-update systemd-compat-libs perl-libwww-perl perl-Term-ANSIColor perl-Term-Cap gdk-pixbuf2-xlib speexdsp qubes-mgmt-salt-admin-tools lvm2
(...)
Transaction Summary
===============================================================
Install 16 Packages (+ 31 Dependent packages)
Upgrade 4 Packages (+200 Dependent packages)
Total download size: 173 M
Is this ok [y/d/N]: n
Exiting on user command
Your transaction was saved, rerun it with:
yum load-transaction /tmp/yum_save_tx.....
4. Upgrade dom0 to R3.2:
sudo qubes-dom0-update
You may wish to disable the screensaver "Lock screen" feature for this step, as
during the update XScreensaver may encounter an "Authentication failed" issue,
requiring a hard reboot. Alternatively, you may simply move the mouse regularly.
5. If the previous step completed successfully, your `qubes-core-dom0` version
should be `3.2.3` or higher. This can be verified with the command `yum info
qubes-core-dom0`. If it's not, repeat the previous step with the `--clean` option.
6. Update configuration files.
Some of configuration files were saved with `.rpmnew` extension as the
actual files were modified. During upgrade, you'll see information about
such cases, like:
warning: /etc/salt/minion.d/f_defaults.conf created as /etc/salt/minion.d/f_defaults.conf.rpmnew
This will happen for every configuration you have modified manually and for
a few that has been modified by Qubes scripts. If you are not sure what to
do about them, below is a list of commands to deal with few common cases
(either keep the old one, or replace with the new one):
rm -f /etc/group.rpmnew
rm -f /etc/shadow.rpmnew
rm -f /etc/qubes/guid.conf.rpmnew
mv -f /etc/nsswitch.conf{.rpmnew,}
mv -f /etc/pam.d/postlogin{.rpmnew,}
mv -f /etc/salt/minion.d/f_defaults.conf{.rpmnew,}
mv -f /etc/dracut.conf{.rpmnew,}
7. Reboot dom0.
Please note that if you use [Anti Evil Maid](/doc/anti-evil-maid), it won't be
able to unseal the passphrase the first time the system boots after performing
this in-place upgrade procedure since the Xen, kernel, and initramfs binaries
will have changed. Once the system boots up again, you can reseal your Anti Evil
Maid passphrase to the new configuration. Please consult the Anti Evil Maid
[documentation](/doc/anti-evil-maid) for instructions on how to do that.
At first login after upgrade you may got a message like this:
Your saved session type 'kde-plasma' is not valid any more.
Please select a new one, otherwise 'default' will be used.
This is result of upgrade KDE4 (`kde-plasma`) to KDE5 (`plasma`). Simply choose
your favorite desktop environment and continue.
Upgrade all Template and Standalone VM(s)
-----------------------------------------
By default, in Qubes R3.1, there are few TemplateVMs and no StandaloneVMs.
However, users are free to create StandaloneVMs More information on using
multiple TemplateVMs, as well as StandaloneVMs, can be found
[here](/doc/software-update-vm/). The steps described in this section should be
repeated in **all** the user's Template and Standalone VMs.
### Upgrade Fedora templates: ###
**Note:** This will only upgrade your Fedora template from Qubes 3.1 to Qubes
3.2. This will *not* upgrade your Fedora template from Fedora 23 to Fedora 24.
In order to do that, please see the
[Fedora 23 template upgrade instructions](/doc/templates/fedora/#upgrading).
1. Open a terminal in the TemplateVM (or StandaloneVM). (E.g., use Qubes VM
Manager's right-click menu, choose "Run Command in VM," and type
`gnome-terminal` there.)
2. Install the `qubes-upgrade-vm` package:
sudo dnf install --refresh qubes-upgrade-vm
3. Proceed with a normal upgrade in the template:
sudo dnf upgrade --refresh
4. Add new packages (only needed in default template):
sudo dnf install qubes-mgmt-salt-vm-connector
5. Shut down the template VM.
### Upgrade Debian (and Whonix) templates: ###
1. Open a terminal in the TemplateVM (or StandaloneVM). (E.g., use Qubes VM
Manager's right-click menu, choose "Run Command in VM," and type
`gnome-terminal` there.)
2. Update repository definition:
sudo cp /etc/apt/sources.list.d/qubes-r3.list /etc/apt/sources.list.d/qubes-r3-upgrade.list
sudo sed -i 's/r3.1/r3.2/' /etc/apt/sources.list.d/qubes-r3-upgrade.list
3. Proceed with a normal update in the template:
sudo apt-get update
sudo apt-get dist-upgrade
4. Add new packages (only needed in default template):
sudo apt-get install qubes-mgmt-salt-vm-connector
5. Remove unnecessary now file:
sudo rm -f /etc/apt/sources.list.d/qubes-r3-upgrade.list
6. Shut down the template VM.

121
user/downloading-installing-upgrading/upgrade/upgrade-to-r4.0.md Normal file
View file

@ -0,0 +1,121 @@
---
layout: doc
title: Upgrading to R4.0
permalink: /doc/upgrade-to-r4.0/
redirect_from:
- /en/doc/upgrade-to-r4.0/
- /doc/UpgradeToR4.0/
- /doc/UpgradeToR4.0rc1/
---
Upgrading Qubes R3.2 to R4.0
============================
**Before attempting either an in-place upgrade or a clean installation, we strongly recommend that users [back up their systems](/doc/backup-restore/).**
Current Qubes R3.2 systems cannot be upgraded in-place to R4.0.
A full backup, clean 4.0 install, and restore is required.
This can be done by following the procedure below.
Preparation
-----------
1. Go to [downloads](/downloads/) and prepare a USB drive or DVD with the R4.0 installer.
2. If this is your only computer, and you do not have a R3.2 installer, you should also create a separate R3.2 USB drive or DVD installer at this time.
Backup R3.2
-----------
1. Attach the backup drive you will be using.
These steps assume it is a USB drive.
2. Shutdown all non-essential VMs.
Typically, `sys-usb` will be the only VM you need to leave running.
3. Follow the **Creating a Backup** section in the [Backup, Restoration, and Migration](/doc/backup-restore/) guide to back up **all VMs** except sys-usb.
6. Verify the integrity of your backup by following the **Restoring from a Backup** section in the [Backup, Restoration, and Migration](/doc/backup-restore/) guide and:
* If you're using Qubes Manager, check the box under "Restore options" that says, "Verify backup integrity, do not restore the data."
* If you're using `qvm-backup-restore` from the command-line, use the `--verify-only` option.
7. If your backup verifies successfully, proceed to the next section.
If it does not, **stop**.
Go back and repeat the backup steps, review the documentation or search the qubes-users mailing list, or ask for assistance on the [qubes-users mailing list](/support/#qubes-users) or IRC.
Install R4.0
------------
This section provides general guidance on installing R4.0 as part of migrating from R3.2.
For further details, please see the [installation guide](/doc/installation-guide/).
1. Shut down R3.2 and boot the R4.0 installer.
2. Follow the installation prompts until you get to the drive selection screen.
Choose **I want to make additional space available**.
Select the box at the top of the list in order to select all partitions.
**This will erase the entire drive**, so do this only if Qubes is the only OS installed on your computer.
If you did not successfully verify your backup in the previous section, cancel the installation, and go back to do that now.
3. Complete the R4.0 installation.
Ask for assistance on the [qubes-users mailing list](/support/#qubes-users) if you run into trouble.
4. If you are unable to successfully install R4.0 on your system, all is not lost.
Use the R3.2 installer to reinstall R3.2, then restore from your backup.
Restore from your backup
------------------------
1. Welcome to Qubes R4.0!
The first thing you might notice is that **Qubes Manager** is not started by default.
We won't need it for the next step, but we will be starting it later.
2. Since patches may have been released since your installation image was created, update Qubes R4.0 by going to the dom0 command line (**Qubes menu -> Terminal Emulator**) then running:
sudo qubes-dom0-update
3. Reboot dom0.
4. Go to **Qubes menu -> System Tools -> Qubes Manager** to start it.
5. Follow the **Restoring from a Backup** section in the [Backup, Restoration, and Migration](/doc/backup-restore/) guide.
We recommend that you restore only your [TemplateBasedVMs](/doc/glossary/#templatebasedvm) and [StandaloneVMs](/doc/glossary/#standalonevm) from R3.2.
Using [TemplateVMs](/doc/templates/) and [SystemVMs](/doc/glossary/#systemvm) from R3.2 is not fully supported (see [#3514](https://github.com/QubesOS/qubes-issues/issues/3514)).
Instead, we recommend using the TemplateVMs that were created specifically for R4.0, which you can [customize](/doc/software-update-vm/) according to your needs.
For the TemplateVM OS versions supported in R4.0, see [Supported Versions](/doc/supported-versions/#templatevms).
If the restore tool complains about missing templates, you can select the option to restore the AppVMs anyway, then change them afterward to use one of the default R4.0 templates.
Note about additional disp-* qubes created during restore
---------------------------------------------------------
One of differences between R3.2 and R4.0 is the handling of DisposableVMs.
In R3.2, a DisposableVM inherited its network settings (NetVM and firewall rules) from the calling qube.
In R4.0, this is no longer the case.
Instead, in R4.0 it's possible to create multiple DisposableVM Templates and choose which one should be used by each qube.
It's even possible to use different DisposableVM Templates for different operations from the same qube.
This allows much more flexibility, since it allows you to differentiate not only network settings, but all of a qube's properties (including its template, memory settings, etc.).
Restoring a backup from R3.2 preserves the old behavior by creating separate DisposableVM Template for each network-providing qube (and also `disp-no-netvm` for network-isolated qubes).
Then, each restored qube is configured to use the appropriate DisposableVM Template according to its `netvm` or `dispvm_netvm` property from R3.2.
This way, DisposableVMs started on R4.0 by qubes restored from a R3.2 backup have the same NetVM settings as they had on R3.2.
If you find this behavior undesirable and want to configure it differently, you can remove those `disp-*` DisposableVM Templates.
But, to do so, you must first make sure they are not set as the value for the `default_dispvm` property on any other qube.
Both Qubes Manager and the `qvm-remove` tool will show you where a DisposableVM Template is being used, so you can go there and change the setting.
Upgrade all Template and Standalone VM(s)
-----------------------------------------
We strongly recommend that you update **all** TemplateVMs and StandaloneVMs before use so that you have the latest security patches from upstream distributions.
In addition, if the default templates have reached EOL (end-of-life) by the time you install R4.0, we strongly recommend that you upgrade them before use.
Please see [Supported Versions](/doc/supported-versions/) for information on supported OS versions and consult the guides below for specific upgrade instructions:
* [Upgrading Fedora TemplateVMs](/doc/templates/fedora/#upgrading)
* [Upgrading Debian TemplateVMs](/doc/templates/debian/#upgrading)
* [Updating Whonix TemplateVMs](https://www.whonix.org/wiki/Qubes/Update)

18
user/downloading-installing-upgrading/upgrade/upgrade.md Normal file
View file

@ -0,0 +1,18 @@
---
layout: doc
title: Upgrade Guides
permalink: /doc/upgrade/
---
Qubes OS Upgrade Guides
=======================
* [Upgrading from R1 to R2 Beta 1](/doc/upgrade-to-r2b1/)
* [Upgrading from R1 to R2 Beta 2](/doc/upgrade-to-r2b2/)
* [Upgrading from R2 Beta 2 to R2 Beta 3](/doc/upgrade-to-r2b3/)
* [Upgrading from R2 Beta 3 to R2](/doc/upgrade-to-r2/)
* [Upgrading from R2 to R3.0](/doc/upgrade-to-r3.0/)
* [Upgrading from R3.0 to R3.1](/doc/upgrade-to-r3.1/)
* [Upgrading from R3.1 to R3.2](/doc/upgrade-to-r3.2/)
* [Upgrading from R3.2 to R4.0](/doc/upgrade-to-r4.0/)

157
user/downloading-installing-upgrading/version-scheme.md Normal file
View file

@ -0,0 +1,157 @@
---
layout: doc
title: Version Scheme
permalink: /doc/version-scheme/
redirect_from:
- /en/doc/version-scheme/
- /doc/VersionScheme/
- /wiki/VersionScheme/
---
Version Scheme
==============
Beginning with R3 release, we change (and formalise) the versioning scheme.
From now on, it will be as follows.
Qubes distributions and products
--------------------------------
We intend to make it easy to make a remix of Qubes, targeting another
hypervisor or isolation provider. We may also create commercial products
intended for specific circumstances. There is one distinguished distribution
called **Qubes OS**. All source code for it is available for download under GPL
license and is openly developed on the mailing lists. The rest of this document
discusses Qubes OS. Another remix may have its own version series.
Release version
---------------
Qubes OS as a whole is released from time to time. Version scheme for all
releases is modeled after Linux kernel version numbers. When announcing a new
release, we decide on the major.minor version (like `3.0`) and release
`3.0-rc1`. When we feel that enough progress has been made, we put `3.0-rc2`
and so on. All these versions are considered unstable and not ready for
production. You may ask for support on mailing lists (specifically
**qubes-devel**), but it is not guaranteed (you may for example get answer
“update to newer `-rc`”). Public ISO image may or may not be available.
When enough development has been made, we announce the first stable version,
like e.g. `3.0.0` (i.e. without `-rc`). This version is considered stable and
we support it for some period. Core components are branched at this moment and
bugfixes are backported from master branch. Questions about stable release
should be directed to the **qubes-users** mailing list. No major features and
interface incompatibilities are to be included in this release. We release
bugfixes as `3.0.1`, `3.0.2` and so on, while new features come into the next
release e.g. `3.1-rcX`.
Tickets in the tracker are sorted out by release major.minor, such as `3.0`,
`3.1` (trac calls this “milestone”).
Release schedule
----------------
There is no specific schedule for major and minor other that more general
roadmap. When time comes, Supreme Committee declares feature freeze and tags
`-rc1` and releases ISO image. From this time on, no new features are accepted.
Also a strict time schedule kicks in.
Each release candidate period is as follows. For the first two weeks we accept
and assign bugreports to be fixed before next release candidate. For the next
two weeks we generally focus on fixing assigned bugreports, so issues discovered
during this time may be postponed until later RC. Finally after that there is
one week of current-testing freeze, during which time no new packages are
released, in hope that they will be installed by wider user base and tested.
The next RC is released five weeks after the former. All packets are published
in `current` repository and the cycle starts over. There should be no less than
1 and no more than 3 release candidates before final release.
<table>
<thead>
<tr><th>stage</th><th>time</th></tr>
</thead>
<tbody>
<tr><td>initial testing</td><td>2 weeks</td></tr>
<tr><td>bug fixing</td><td>2 weeks</td></tr>
<tr><td>`current-testing` freeze</td><td>1 week</td></tr>
</tbody>
</table>
Starting with second cycle (that is, after `-rc1`) two weeks into the cycle
(after primary bug-reporting period) the Supreme Committee decides whether there
should be another RC. If, based on remaining issues, the Committee decides to
release final, then the Committee agrees upon the release date, which should be
no later than a week after.
!["Release cycle"](/attachment/wiki/VersionScheme/release-cycle.svg)
Bug priorities
--------------
When deciding whether the current release candidate is the final one, the Committee
takes bugs priorities into consideration. The meaning of them is as follows:
* `blocker` - when any such bug is present in the current release candidate, it
can't be considered final release. Bugs with this priority must be fixed before
the next release candidate, even if that means delaying its release (which
should be considered only last resort option).
* `critical` - when any such bug is present in the current release candidate, it
can't be considered final release. But such bugs are not qualified to delay
next release candidate release.
* `major` - existence of such bugs do not strictly prevent the current release
candidate be considered final (but of course we should try hard to not have
them there). Fixing bugs of this priority can be delayed and qualified as
updates to the final stable release.
* `minor` - existence of such bugs do not prevent the current release candidate
be considered final. Fixing such bugs can be delayed to the next Qubes OS
release. Eventually such fixes might be backported as an update to the stable
release(s).
All above is about bugs, no features should be assigned to the current release
after first `-rc`. Supreme Committee is free to adjust priorities appropriately.
Component version
-----------------
Qubes release is defined as specific versions of components, which are
developed more or less separately. Their versions are composed of major and
minor version of target Qubes OS release followed by third component which is
just incremented. There is no apparent indication that given version is stable
or not.
There are some non-essential components like `qubes-apps-*` that are shared
between releases. Their versions indicate oldest qubes-release that is
supported. We try hard to support multiple releases by one branch to ease code
maintenance.
Different Qubes releases remixes may comprise of different components and
version are not guaranteed to be monotonic between releases. We may decide that
for newer release some component should be downgraded. There is no guarantee
that arbitrary combination of different versions of random components will
yield usable (or even install-able) compilation.
Git tags and branches
---------------------
We mark each component version in the repository by tag containing
`v<version>`. Likewise, each Qubes OS release is marked by `R<release>` tag.
At the release of some release we create branches named like `release2`. Only
bugfixes and compatible improvements are backported to these branches. These
branches should compile. All new development is done in `master` branch. This
branch is totally unsupported and may not even compile depending on maintainer
of repository.
All version and release tags should be made and signed by someone from ITL
staff. Public keys are included in `qubes-builder` and available at
[https://keys.qubes-os.org/keys/](https://keys.qubes-os.org/keys/).
Check installed version
-----------------
If you want to know which version you are running, for example to report
an issue, you can either check in the Qubes Manager menu under About / Qubes OS or in the file /etc/qubes-release in dom0. For the latter you can use a command like `cat /etc/qubes-release` in a dom0 terminal.