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

resolved merge conflicts

Browse Source
This commit is contained in:
GammaSQ 2019-01-05 13:36:34 +01:00
commit 8f7fb84a1f
No known key found for this signature in database
GPG Key ID: D552FD2F98647C64
105 changed files with 4814 additions and 2016 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
_dev/index.rst
View File

@ -1,7 +1,9 @@
Welcome to Qubes OS developer's documentation!
==============================================
Please choose specific repostitory:
This is documentation for the source code. Please choose specific repostitory:
* `core-admin </projects/core-admin>`_
* `core-admin-client </projects/core-admin-client>`_
Or see `the main Qubes OS documentation <https://www.qubes-os.org/doc/>`_.

25
about/code-of-conduct.md
View File

@ -4,6 +4,14 @@ title: Code of Conduct
permalink: /code-of-conduct/
---
## Introduction
This Code of Conduct is a collaborative, evolving document that attempts to transparently set out a public set of standards regarding appropriate conduct in the Qubes OS Project.
It is *not* intended to be a statement or endorsement, whether implicit or explicit, of any particular political or philosophical attitude, belief, or way of living.
Rather, it is an attempt to find a reasonable middle ground among the inevitable disagreements regarding free expression that arise in a large, diverse community of people from around the world.
It is intended to be a practical means of serving the best interests of our users, contributors, and the project itself.
We welcome you to view the [history of changes] to this document and the [discussion] leading to its creation.
## Our Pledge
The Qubes OS project creates a reasonably secure OS. In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to make participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, sexual identity and orientation, or other characteristic.
@ -23,11 +31,11 @@ Examples of unacceptable behavior by participants include:
- The use of sexualized language or imagery and unwelcome sexual attention or advances
- Trolling, insulting/derogatory comments, and personal or political attacks
- Reinforcing stereotypical models for illustration of non-technical users (e.g. our mothers/grandmothers, etc.)
- Public or private harassment, as defined by the [Citizen Code of Conduct](http://citizencodeofconduct.org/)
- Public or private harassment, as defined by the [Citizen Code of Conduct]
- 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](/support/#discussion-list-guidelines).)
(Please also see our [mailing list discussion guidelines].)
## Our Responsibilities
@ -43,7 +51,7 @@ Instances of abusive, harassing, or otherwise unacceptable behavior may be repor
Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership.
## A note on trust
## A Note on Trust
Expect all contributions to be reviewed with some amount of healthy adversarial skepticism, regardless of your perceived standing in the community.
This is a security project, and allowing ourselves to get complacent while reviewing code simply because it comes from a well-known party would not be in the best interest of the project.
@ -51,4 +59,13 @@ Please try not to get offended if you perceive your contributions as being met w
## Attribution
This Code of Conduct is adapted from the [Contributor Covenant, version 1.4](http://contributor-covenant.org/version/1/4) and the [Rust Code of Conduct](https://www.rust-lang.org/en-US/conduct.html).
The initial published version of this Code of Conduct was adapted from the [Contributor Covenant, version 1.4] and the [Rust Code of Conduct].
[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
[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

44
about/faq.md
View File

@ -115,6 +115,12 @@ At the same time, due to the smart use of Xen shared memory, our GUI implementat
Please refer to [this page](/doc/vm-sudo/).
### Why is dom0 so old?
Please see:
- [Why would one want to update software in dom0?](/doc/software-update-dom0/#why-would-one-want-to-install-or-update-software-in-dom0)
- [Note on dom0 and EOL](/doc/supported-versions/#note-on-dom0-and-eol)
### Do you recommend coreboot as an alternative to vendor BIOS?
Yes, where it is possible to use it an open source boot firmware ought to be more trustable than a closed source implementation. [coreboot](https://www.coreboot.org/) is as a result a requirement for [Qubes Certified Hardware](https://www.qubes-os.org/news/2016/07/21/new-hw-certification-for-q4/). The number of machines coreboot currently supports is limited and the use of some vendor supplied blobs is generally still required. Where coreboot does support your machine and is not already installed, you will generally need additional hardware to flash it. Please see the coreboot website / their IRC channel for further information.
@ -129,11 +135,11 @@ Not currently, for the same reasons that [Debian is not certified](https://www.g
### Should I trust this website?
This website is hosted via GitHub Pages behind Cloudflare ([why?](#why-does-this-website-use-cloudflare)).
This website is hosted on [GitHub Pages](https://pages.github.com/) ([why?](#why-do-you-use-github)).
Therefore, it is largely outside of our control.
We don't consider this a problem, however, since we explicitly [distrust the infrastructure](#what-does-it-mean-to-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](https://github.com/QubesOS/qubesos.github.io), [verify the PGP signatures on the commits and/or tags](/security/verifying-signatures/#verifying-qubes-code) (signed by the [doc-signing keys](https://github.com/QubesOS/qubes-secpack/tree/master/keys/doc-signing)), then either [render the site on your local machine](https://github.com/QubesOS/qubesos.github.io/blob/master/README.md#instructions) 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](/doc/doc-guidelines/#markdown-conventions).
Instead, if you want to obtain your own, trustworthy copy of this website in a secure way, you should clone our [website repo](https://github.com/QubesOS/qubesos.github.io), [verify the PGP signatures on the commits and/or tags](/security/verifying-signatures/#how-to-verify-qubes-repos) (signed by the [doc-signing keys](https://github.com/QubesOS/qubes-secpack/tree/master/keys/doc-signing)), then either [render the site on your local machine](https://github.com/QubesOS/qubesos.github.io/blob/master/README.md#instructions) 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](/doc/doc-guidelines/#markdown-conventions).
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"?
@ -149,11 +155,11 @@ Since we don't want to encourage or endorse this, we make our distrust of the in
Also see: [Should I trust this website?](#should-i-trust-this-website)
### Why does this website use Cloudflare?
### Why do you use GitHub?
Three main reasons:
1. We [distrust the infrastructure](#what-does-it-mean-to-distrust-the-infrastructure), including Cloudflare.
1. We [distrust the infrastructure](#what-does-it-mean-to-distrust-the-infrastructure), including GitHub (though there are aspects we're still [working on](https://github.com/QubesOS/qubes-issues/issues/3958)).
2. It's free (as in beer). We'd have to spend either time or money to implement a solution ourselves or pay someone to do so, and we can't spare either one right now.
3. It has low admin/overhead requirements, which is very important, given how little time we have to spare.
@ -161,10 +167,10 @@ Also see: [Should I trust this website?](#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](#what-does-it-mean-to-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 (e.g., HTTPS via Cloudflare page rules).
Although we caution users against [placing undue trust in this website](#should-i-trust-this-website) because we [distrust the infrastructure](#what-does-it-mean-to-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:
1. Our GitHub Pages + Cloudflare platform doesn't support it.
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!)
@ -226,7 +232,7 @@ It is possible to install Qubes on a system with 2 GB of RAM, but the system wou
### Can I install Qubes 4.x on a system without VT-x or VT-d?
Qubes 4.x requires Intel VT-x with EPT / AMD-V with RVI (SLAT) and Intel VT-d / AMD-Vi (aka AMD IOMMU) for proper functionality (see the [4.x System Requirements](/doc/system-requirements/#qubes-release-4x)). You may be able to install it without the required CPU features for testing purposes only, but VMs may not function correctly and there will be no security isolation. For more information, see our post on [updated requirements for Qubes-certified hardware](/news/2016/07/21/new-hw-certification-for-q4/).
Qubes 4.x requires Intel VT-x with EPT / AMD-V with RVI (SLAT) and Intel VT-d / AMD-Vi (aka AMD IOMMU) for proper functionality (see the [4.x System Requirements](/doc/system-requirements/#qubes-release-4x)). If you are receiving an error message on install saying your "hardware lacks the features required to proceed", check to make sure the virtualization options are enabled in your BIOS/UEFI configuration. You may be able to install without the required CPU features for testing purposes only, but VMs may not function correctly and there will be no security isolation. For more information, see our post on [updated requirements for Qubes-certified hardware](/news/2016/07/21/new-hw-certification-for-q4/).
### Can I install Qubes 3.2 on a system without VT-x?
@ -267,6 +273,14 @@ Yes, and see [this message](http://groups.google.com/group/qubes-devel/msg/64121
Some users have been able to do this, but it is neither recommended nor supported. Qubes should be installed bare-metal. (After all, it uses its own bare-metal hypervisor!)
### What is a terminal?
A [terminal emulator](https://en.wikipedia.org/wiki/Terminal_emulator), nowadays often referred to as just a *terminal*, is a program which provides a text window.
Inside that window, a [shell](https://en.wikipedia.org/wiki/Shell_(computing)) is typically running in it.
A shell provides a [command-line interface](https://en.wikipedia.org/wiki/Command-line_interface) where the user can enter and run [commands](https://en.wikipedia.org/wiki/Command_(computing)).
See introductions on Wikibooks: [here](https://en.wikibooks.org/wiki/Fedora_And_Red_Hat_System_Administration/Shell_Basics), [here](https://en.wikibooks.org/wiki/A_Quick_Introduction_to_Unix) and [here](https://en.wikibooks.org/wiki/Bash_Shell_Scripting).
### Why does my network adapter not work?
You may have an adapter (wired, wireless), that is not compatible with open-source drivers shipped by Qubes. There may be a binary blob, which provides drivers in the linux-firmware package.
@ -488,6 +502,16 @@ Here are some examples of non-Qubes reports about this problem:
More examples can be found by searching for "Failed to synchronize cache for repo" (with quotation marks) on your preferred search engine.
### Could you please make my preference the default?
Wouldn't it be great if Qubes were configured just the way you like it by default with all of your favorite programs and settings?
Then you could just install Qubes without having to install any programs in it or adjust any settings!
You might even think that if a particular program or setting works so well for *you*, it would work well for *everyone*, so you'd actually be doing everyone a favor!
The problem is that Qubes has [tens of thousands of different users](/statistics/) with radically different needs and purposes.
There is no particular configuration that will be ideal for everyone (despite how much you might feel that your preference would be better for everyone), so the best we can do is to put power in the hands of users to configure their Qubes installations the way they like (subject to security constraints, of course).
Please don't ask for your favorite program to be installed by default or for some setting that obviously varies by user preference to be changed so that it matches *your* preference.
This is an incredibly selfish attitude that demonstrates a complete lack of consideration for the thousands of other Qubes users who don't happen to share your preferences.
----------
@ -553,4 +577,8 @@ For more details about how we improved on Xen's native stub domain use, see [her
### Is Secure Boot supported?
Secure Boot is not supported out of the box as UEFI support in Xen is very basic. Arguably secure boot reliance on UEFI integrity is not the best design. The relevant binaries (shim.efi, xen.efi, kernel / initramfs) are not signed by the Qubes Team and secure boot has not been tested. Intel TXT (used in [Anti Evil Maid](/doc/anti-evil-maid/)) at least tries to avoid or limit trust in BIOS.
UEFI Secure Boot is not supported out of the box as UEFI support in Xen is very basic.
Arguably secure boot reliance on UEFI integrity is not the best design.
The relevant binaries (shim.efi, xen.efi, kernel / initramfs) are not signed by the Qubes Team and secure boot has not been tested.
Intel TXT (used in [Anti Evil Maid](/doc/anti-evil-maid/)) at least tries to avoid or limit trust in BIOS.
See the Heads project [[1]](https://trmm.net/Heads) [[2]](http://osresearch.net/) for a better-designed non-UEFI-based secure boot scheme with very good support for Qubes.

114
about/join.md
View File

@ -4,114 +4,10 @@ title: Join
permalink: /join/
---
Join the Qubes OS Team!
=======================
The Qubes OS Project is seeking individuals for the positions listed
below. If you're interested in any of these positions, please send an email to
[Marek Marczykowski-Górecki](mailto:marmarek@invisiblethingslab.com).
Besides the positions below, there are many different ways you can [contribute to the Qubes OS project](/doc/contributing/).
Stable release manager
----------------------
### General tasks ###
* Deciding what will be fixed in each stable release and what will be fixed
only in new major releases
* Backporting fixes to stable releases (and requesting core dev input when it
isn't trivial)
* Releasing packages for stable release (deciding when the package should be
released to the `current-testing` repository and when it should be moved to
the `current` repository)
As this position involves great trust and may have major impact on project
security, we'd like for the candidate to be already known and active in Qubes
OS community.
Core developer
--------------
### General tasks ###
* Actual debugging of issues
* Writing new features
* Writing tests
* Writing developer documentation (API, etc)
* Providing input for community contributors when requested
### Required and optional skills ###
* Python
* Shell scripting
* System configuration (basic services, startup scripts etc)
* Git, make
* (Optional) networking, firewalling
* (Optional) X11 protocol (raw)
* (Optional) GUI frameworks (Gtk, Qt)
* (Optional) kernel and/or hypervisor debugging skills
* (Optional) low level stuff (UEFI, PCI communication,
including IOMMU, networking down to ethernet layer, Xen
backend/frontend interfaces)
* (Optional) libvirt internals
* (Optional) salt stack
* (Optional) advanced desktop environment configuration, including
writing plugins (KDE, Gnome)
The more "optional" the better :)
### Example features for implementation ###
#### Smaller ####
* [#1499](https://github.com/QubesOS/qubes-issues/issues/1499)
* [#1454](https://github.com/QubesOS/qubes-issues/issues/1454)
* [#1363](https://github.com/QubesOS/qubes-issues/issues/1363)
* [#1329](https://github.com/QubesOS/qubes-issues/issues/1329)
* [#979](https://github.com/QubesOS/qubes-issues/issues/979)
#### Larger ####
* [#1455](https://github.com/QubesOS/qubes-issues/issues/1455)
* [#1426](https://github.com/QubesOS/qubes-issues/issues/1426)
* [#971](https://github.com/QubesOS/qubes-issues/issues/971)
* [#889](https://github.com/QubesOS/qubes-issues/issues/889)
* [#866](https://github.com/QubesOS/qubes-issues/issues/866)
* [#830](https://github.com/QubesOS/qubes-issues/issues/830)
Qubes Live USB Maintainer
-------------------------
### Required Skills ###
* Shell
* Python
* Bootloaders (`grub2`, `isolinux`)
* `initrd` creation (`dracut`)
* Kickstart (automated installation -- basics are enough)
* A general understanding of Qubes OS ;)
GNOME Desktop Environment developer
-------------------------------------
### Tasks ###
* Custom window decorations (colored frames)
* Configuration for Qubes OS dom0
* Disable uneeded things (e.g., file manager)
* Configure menu to ease navigation through multiple VMs (similar to [what is
configured in KDE](https://github.com/QubesOS/qubes-issues/issues/1784#issuecomment-216868265))
* [Implementation of new, GTK based Qubes Manager](https://github.com/QubesOS/qubes-issues/issues/1870)
### Example Tasks ###
Listed here: [#1806](https://github.com/QubesOS/qubes-issues/issues/1806)
### Required Skills ###
* GNOME
* GTK
* Whatever is needed to customize GNOME
Joining the Qubes OS Team
=========================
The Qubes OS Project does not currently have any open positions.
This page will be updated when open positions become available.
In the meantime, there are many different ways you can [contribute to the Qubes OS project](/doc/contributing/).

2
about/screenshots.md
View File

@ -85,7 +85,7 @@ Qubes also supports secure file copying between AppVMs.
[![r2b2-open-in-dispvm-1.png](/attachment/wiki/QubesScreenshots/r2b2-open-in-dispvm-1.png)](/attachment/wiki/QubesScreenshots/r2b2-open-in-dispvm-1.png) [![r2b2-open-in-dispvm-3.png](/attachment/wiki/QubesScreenshots/r2b2-open-in-dispvm-3.png)](/attachment/wiki/QubesScreenshots/r2b2-open-in-dispvm-3.png)
Qubes' unique Disposable VMs (DispVMs) allow the user to open any file in a disposable VM in a matter of seconds! A file can be edited in a disposable VM, and any changes are projected back onto the original file. Currently, there is no way to mark files to be automatically opened in a disposable VM (one needs to right-click on the file and choose the "Open in Disposable VM" option), but this is planned for the R2 Beta 3 release.
Qubes' unique DisposableVMs (DispVMs) allow the user to open any file in a disposable VM in a matter of seconds! A file can be edited in a disposable VM, and any changes are projected back onto the original file. Currently, there is no way to mark files to be automatically opened in a disposable VM (one needs to right-click on the file and choose the "Open in DisposableVM" option), but this is planned for the R2 Beta 3 release.
* * * * *

63
about/statistics.md
View File

@ -10,10 +10,61 @@ redirect_from:
<img src="https://tools.qubes-os.org/counter/stats.png" alt="Estimated Qubes OS userbase graph"/>
</div>
The graph is updated daily.
FAQ
---
### How often is this graph updated?
Daily.
### Why is the bar for the current month so low?
Since the graph is updated daily, the bar for the current month will be very low at the start of the month and rise gradually until the end of the month.
### How is the userbase estimated?
We simply count the number of unique IPv4 addresses that connect to the Qubes update servers each month (except for Tor connections; see [below][tor-methodology]).
### How has the methodology for counting Tor users changed?
Before, we simply counted the number of unique Tor exit node IPv4 addresses that connected to the Qubes update servers each month.
However, this underestimated the actual number of Tor users, since many Tor users can use the same exit node.
The new methodology is to estimate the number of Tor users as a proportion of the total number of *requests* from Tor exit nodes on the assumption that the proportion of users to requests is roughly the same for both clearnet and Tor users.
To be precise, the formula is:
```
tor_users = tor_requests * (plain_users / plain_requests)
```
Where:
- `tor_users` is the estimated number of Qubes users who download updates via Tor each month.
- `tor_requests` is the total number of requests the Qubes update servers receive from Tor exit nodes each month.
- `plain_users` is the number of unique clearnet IPv4 addresses that connect to the Qubes update servers each month.
- `plain_requests` is the total number of requests the Qubes update servers receive from clearnet IPv4 addresses each month.
We cross-reference the list of connecting IP addresses with [TorDNSEL's exit lists] in order to distinguish Tor and clearnet IPs and requests.
For this purpose, we count an IP address as belonging to a Tor exit node if there was a Tor exit node active for that address within the 24-hour periods before or after it connected to the Qubes update servers.
### What kinds of data do you collect about Qubes users?
We collect:
- The IPv4 addresses that connect to the Qubes update servers
- The number of requests from each IPv4 address
- Standard server access and error logs
We do not collect any other kinds of data about Qubes users.
### Where can I find the raw data and source code?
The raw data is available [here][raw-data].
(This does not include any personally-identifying user data.)
Please note that the format of this data is not documented and may change any time if the developers feel the need to include something else.
The source code is available [here][source-code].
[tor-methodology]: #how-has-the-methodology-for-counting-tor-users-changed
[TorDNSEL's exit lists]: https://metrics.torproject.org/collector.html#type-tordnsel
[raw-data]: https://tools.qubes-os.org/counter/stats.json
[source-code]: https://github.com/woju/qubes-stats
Raw data is available at
[https://tools.qubes-os.org/counter/stats.json](https://tools.qubes-os.org/counter/stats.json).
Format is not documented and may change any time should the developers feel the
need to include something else. Source code is available at
[https://github.com/woju/qubes-stats](https://github.com/woju/qubes-stats).

481
about/support.md
View File

@ -13,16 +13,14 @@ redirect_from:
- /wiki/QubesLists/
---
Help, Support, and Mailing Lists
================================
# Help, Support, and Mailing Lists #
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.
Staying safe
------------
## Staying safe ##
The Qubes mailing lists are open to the public. The contents of the list are
crawled by search engines and archived by third-party services outside of our
@ -58,8 +56,7 @@ cryptographically signed, anyone would be in a position to [verify] that these
came from the same keyholder.
Discussion list guidelines
--------------------------
## Discussion list 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
@ -79,120 +76,185 @@ and knowledgeable people who enjoy corresponding on these lists. The vast
majority of them will be happy to help you if you follow these simple
guidelines.
* **Be polite and respectful.** 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
likely to be ignored.
### Be polite and respectful ###
* **Be concise.** Include only essential information. Most of your readers lead
busy lives and have precious little time. We *want* to spend some of that
time helping you, if we can. But if you ramble, it will be easier to skip
over you and help someone else who gets right to the point.
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
likely to be ignored.
* **Help us help you.** Tell us what you've already tried, and which
documentation pages you've already read. Put yourself in your readers' shoes.
What essential information would they require in order to be able to help
you? Make sure to include that information in your message. [Ask
questions the smart way.][smart-questions]
### Be concise ###
* **Be patient.** Do not "bump" a thread more than once every three days *at
most*. If it seems like your messages to the mailing lists are consistently
being ignored, make sure you're following the guidelines explained on this
page. If you're already doing so but still not getting any replies, then it's
likely that no one who knows the answer has had time to reply yet. Remember
that the devs are very busy working on Qubes. They usually only have a chance
to answer questions on the mailing lists once every several days.
Include only essential information. Most of your readers lead
busy lives and have precious little time. We *want* to spend some of that
time helping you, if we can. But if you ramble, it will be easier to skip
over you and help someone else who gets right to the point.
### Help us help you ###
Tell us what you've already tried, and which
documentation pages you've already read. Put yourself in your readers' shoes.
What essential information would they require in order to be able to help
you? Make sure to include that information in your message. [Ask
questions the smart way.][smart-questions]
### Be patient ###
Do not "bump" a thread more than once every three days *at
most*. If it seems like your messages to the mailing lists are consistently
being ignored, make sure you're following the guidelines explained on this
page. If you're already doing so but still not getting any replies, then it's
likely that no one who knows the answer has had time to reply yet. Remember
that the devs are very busy working on Qubes. They usually only have a chance
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.
### 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.
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].
* **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.
### Specific rules and notes ###
* While the mailing lists are implemented as Google Group web forums, many
discussants treat them as conventional [mailing lists] rather than web
forums. The Qubes OS Project does not maintain a web forum apart from the
mailing lists.
* Send your message to the correct list. Read the sections below to determine
which list is correct for your message.
* Do not [top-post].
* Include a precise and informative subject line. This will allow others to
easily find your thread in the future and use it as a reference. (Bad: "Help!
Qubes problems!" Good: "R2B2 Installation problem: Apple keyboard not working
in installer.")
* If your message is not successfully sent to the list, it probably got caught
in the spam filter. We check the spam filter regularly, so please be patient,
and your message should be approved (and your email address added to the
whitelist) within a few days.
* Keep the mailing list CCed throughout the conversation unless there's a
special need for privacy (in which case, use PGP encryption). This increases
the likelihood that a greater quantity of useful information will be
available to everyone in the future.
* Quote appropriately. If you're replying to a thread (whether your own or
someone else's), you should make sure to quote enough from previous messages
in the thread so that people reading your message can understand the context
without having to find and read earlier messages from that thread. Each reply
should continue the conversation and, ideally, be readable as a conversation
in itself. Do not quote advertisements in signatures or inline PGP signature
blocks. (Quoting the latter interferes with the ability of programs like
Enigmail to properly quote replies thereafter).
* If you do not speak English, you should feel free to post in your own
language. However, bear in mind that most members of the list can only read
English. You may wish to include an automated translation in your message out
of consideration for those readers. If you choose to write in English, please
do not apologize for doing so poorly, as it is unnecessary. We understand and
will ask for clarification if needed.
* While we're generally open to hearing suggestions for new features, please
note that we already have a pretty well defined [roadmap], and it's rather
unlikely that we will change our schedule in order to accommodate your
request. If there's a particular feature you'd like to see in Qubes, a much
more effective way to make it happen is to contribute a patch that implements
it. We happily accept such contributions, provided they meet our standards.
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.
#### Use the correct list ####
Send your message to the correct list. Read the sections below to determine
which list is correct for your message.
#### Do not top-post ####
[Top-posting] is placing your reply above the quoted message to which you're
replying. Please refrain from doing this. Instead, either [interleave] your
reply by placing parts of your message immediately below each quoted portion
to which it is replying, or [bottom-post] by placing your entire reply below
the quoted message to which you're replying.
#### Use proper subject lines ####
Include a precise and informative subject line. This will allow others to
easily find your thread in the future and use it as a reference. (Bad: "Help!
Qubes problems!" Good: "R2B2 Installation problem: Apple keyboard not working
in installer.")
#### Do not send duplicates ####
If your message is not successfully sent to the list, it probably got caught
in the spam filter. We check the spam filter regularly, so please be patient,
and your message should be approved (and your email address added to the
whitelist) within a few days.
#### Keep the list CCed ####
Keep the mailing list CCed throughout the conversation unless there's a
special need for privacy (in which case, use PGP encryption). This increases
the likelihood that a greater quantity of useful information will be
available to everyone in the future.
#### Quote appropriately ####
If you're replying to a thread (whether your own or
someone else's), you should make sure to quote enough from previous messages
in the thread so that people reading your message can understand the context
without having to find and read earlier messages from that thread. Each reply
should continue the conversation and, ideally, be readable as a conversation
in itself. Do not quote advertisements in signatures or inline PGP signature
blocks. (Quoting the latter interferes with the ability of programs like
Enigmail to properly quote replies thereafter).
#### English not required ####
If you do not speak English, you should feel free to post in your own
language. However, bear in mind that most members of the list can only read
English. You may wish to include an automated translation in your message out
of consideration for those readers. If you choose to write in English, please
do not apologize for doing so poorly, as it is unnecessary. We understand and
will ask for clarification if needed.
#### Suggestions ####
While we're generally open to hearing suggestions for new features, please
note that we already have a pretty well defined [roadmap], and it's rather
unlikely that we will change our schedule in order to accommodate your
request. If there's a particular feature you'd like to see in Qubes, a much
more effective way to make it happen is to contribute a patch that implements
it. We happily accept such contributions, provided they meet our standards.
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 ####
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
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. However, there is an [unofficial
forum](https://qubes-os.info) that is synced with the mailing lists.)
#### Gmane ####
Qubes mailing lists are also available via Gmane, a service that provides mailing lists in the form of newsgroups.
This makes it possible for you to subscribe and read all mails sent to the list without having them all sent to your normal mail account.
To use Gmane, you need a newsreader such as [Thunderbird].
To add Gmane's server to Thunderbird, follow the instructions in [Mozilla Thunderbird's documentation for how to add newsgroups][thunderbird-newsgroup].
In the fourth step replace `news.mozilla.org` with `news.gmane.org`.
To subscribe to a list, click **Subscribe...** and search for the newsgroup `gmane.os.qubes.<list>`, for example, [`gmane.os.qubes.user`].
Check the box beside the name and click **OK**.
You can now send and reply to mails the same way you would normally.
To unsubscribe from the list, click **Subscribe...** and search for the newsgroup `gmane.os.qubes.<list>`, for example, [`gmane.os.qubes.user`].
Uncheck the box beside the name and click **OK**.
Thunderbird will automatically remove the newsgroup.
qubes-announce
--------------
## 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, and only
[Qubes Security Bulletins (QSBs)][qsb] and new Qubes OS releases are announced
here.
[Qubes Security Bulletins (QSBs)][qsb] and new stable Qubes OS releases are
announced here.
### How to subscribe
#### Google Groups
* To subscribe to the list, send a blank email to
`qubes-announce+subscribe@googlegroups.com`.
* Note: A Gmail account is *not* required. Any email address will work.
* To unsubscribe, send a blank email to
`qubes-announce+unsubscribe@googlegroups.com`.
* This list can also be browsed via an optional [Google Groups web
interface][qubes-announce-web].
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
-----------
### How to use this list
## 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:
@ -202,8 +264,6 @@ Examples of topics or questions suitable for this list include:
* Hardware compatibility problems
* Questions of the form: "How do I...?"
### Read these first
Please try searching both the Qubes website and the archives of the mailing
lists before sending a question. In addition, please make sure that you have
read and understood the following basic documentation prior to posting to the
@ -214,55 +274,17 @@ list:
* The [User FAQ]
* The [documentation] (for questions about how to use Qubes OS)
### How to subscribe and post
#### Google Groups
You don't have to subscribe in order to post to this list. However, subscribing
might nonetheless be desirable, as it ensures that your messages will not be
eaten by the Google Groups spam filter and allows you to receive messages which
were sent directly to the list.
* To subscribe to the list, send a blank email to
`qubes-users+subscribe@googlegroups.com`.
* Note: A Gmail account is *not* required. Any email address will work.
* To post a message to the list, address your email to
`qubes-users@googlegroups.com`.
* Note: You don't have to be subscribed in order to post.
* To unsubscribe, send a blank email to
`qubes-users+unsubscribe@googlegroups.com`.
* This list also has a [Google Groups web interface][qubes-users-web].
* Some users prefer to interact with the mailing list through the web
interface. 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 this interface.
* You can also search the [traditional mail archive][qubes-users-archive]
#### Gmane
The mailing list is also available via Gmane, a service that provides mailing
lists in the form of newsgroups. This makes it possible for you to subscribe
and read all mails sent to the list without having them all sent to your normal
mail account. To use Gmane, you need a newsreader such as Mozilla Thunderbird.
To add Gmane's server to Thunderbird, follow the instructions in
[Mozilla Thunderbird's documentation for how to add
newsgroups][thunderbird-newsgroup].
In the fourth step replace `news.mozilla.org` with `news.gmane.org`.
* To subscribe to the list, click on **Subscribe...** and search for the
newsgroup [`gmane.os.qubes.user`]. Click on the checkbox besides the name
and **OK**.
* You send and reply to mails the same way you would normally.
* To unsubscribe from the list, click on **Subscribe...**
search for the newsgroup [`gmane.os.qubes.user`], uncheck the checkbox, and
click on **OK**. Thunderbird will automatically remove the newsgroup.
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
-----------
### How to use this list
## 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
@ -276,112 +298,38 @@ 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.
### How to subscribe and post
#### Google Groups
You must be subscribed in order to post to this list.
* To subscribe to the list, send a blank email to
`qubes-devel+subscribe@googlegroups.com`.
* Note: A Gmail account is *not* required. Any email address will work.
* To post a message to the list, address your email to
`qubes-devel@googlegroups.com`.
* Note: You must be subscribed in order to post. If your post does not
appear, please allow time for moderation to occur.
* To unsubscribe, send a blank email to
`qubes-devel+unsubscribe@googlegroups.com`.
* This list has a [Google Groups web interface][qubes-devel-web].
* Some users prefer to interact with the mailing list through the web
interface. 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 this interface.
* You can also search the [traditional mail archive][qubes-devel-archive]
#### Gmane
The mailing list is also available via Gmane, a service that provides mailing
lists in the form of newsgroups. This makes it possible for you to subscribe
and read all mails sent to the list without having them all sent to your normal
mail account. To use Gmane, you need a newsreader such as Mozilla Thunderbird.
To add Gmane's server to Thunderbird, follow the instructions in
[Mozilla Thunderbird's documentation for how to add
newsgroups][thunderbird-newsgroup].
In the fourth step replace `news.mozilla.org` with `news.gmane.org`.
* To subscribe to the list, click on **Subscribe...** and search for the
newsgroup [`gmane.os.qubes.devel`]. Click on the checkbox besides the name
and **OK**.
* You send and reply to mails the same way you would normally.
* To unsubscribe from the list, click on **Subscribe...**
search for the newsgroup [`gmane.os.qubes.devel`], uncheck the checkbox, and
click on **OK**. Thunderbird will automatically remove the newsgroup.
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
-------------
### How to use this list
## qubes-project ##
This list is for non-technical discussion and coordination around the
Qubes OS project.
Examples of topics or question suitable for this list include:
* Participation (talks, workshops, etc.) at upcoming events
* Project funding applications and strategies
* FOSS governance discussions
* Most Github issues tagged "[business]"
* Participation (talks, workshops, etc.) at upcoming events
* Project funding applications and strategies
* FOSS governance discussions
* Most Github issues tagged "[business]"
### How to subscribe and post
#### Google Groups
You don't have to subscribe in order to post to this list. However, subscribing
might nonetheless be desirable, as it ensures that your messages will not be
eaten by the Google Groups spam filter and allows you to receive messages which
were sent directly to the list.
* To subscribe to the list, send a blank email to
`qubes-project+subscribe@googlegroups.com`.
* Note: A Gmail account is *not* required. Any email address will work.
* To post a message to the list, address your email to
`qubes-project@googlegroups.com`.
* Note: You don't have to be subscribed in order to post.
* To unsubscribe, send a blank email to
`qubes-project+unsubscribe@googlegroups.com`.
* This list also has a [Google Groups web interface][qubes-project-web].
* Some users prefer to interact with the mailing list through the web
interface. 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 this interface.
#### Gmane
The mailing list is also available via Gmane, a service that provides mailing
lists in the form of newsgroups. This makes it possible for you to subscribe
and read all mails sent to the list without having them all sent to your normal
mail account. To use Gmane, you need a newsreader such as Mozilla Thunderbird.
To add Gmane's server to Thunderbird, follow the instructions in
[Mozilla Thunderbird's documentation for how to add
newsgroups][thunderbird-newsgroup].
In the fourth step replace `news.mozilla.org` with `news.gmane.org`.
* To subscribe to the list, click on **Subscribe...** and search for the
newsgroup [`gmane.os.qubes.project`]. Click on the checkbox besides the name
and **OK**.
* You send and reply to mails the same way you would normally.
* To unsubscribe from the list, click on **Subscribe...**
search for the newsgroup [`gmane.os.qubes.project`], uncheck the checkbox, and
click on **OK**. Thunderbird will automatically remove the newsgroup.
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
-----------------
### How to use this list
## qubes-translation ##
This list is for discussion around the localization and translation of Qubes OS,
its documentation, and the website.
@ -392,25 +340,14 @@ Examples of topics or question suitable for this list include:
* Who is managing localization for a given language
* Most Github issues tagged "[localization]"
### How to subscribe and post
#### Google Groups
You must be subscribed in order to post to this list.
* To subscribe to the list, send a blank email to
`qubes-translation+subscribe@googlegroups.com`.
* Note: A Gmail account is *not* required. Any email address will work.
* To post a message to the list, address your email to
`qubes-translation@googlegroups.com`.
* Note: You don't have to be subscribed in order to post.
* To unsubscribe, send a blank email to
`qubes-translation+unsubscribe@googlegroups.com`.
* This list also has a [Google Groups web interface][qubes-translation-web].
* Some users prefer to interact with the mailing list through the web
interface. 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 this interface.
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
@ -422,7 +359,9 @@ You must be subscribed in order to post to this list.
[verify]: /security/verifying-signatures/
[qsb]: /security/bulletins/
[qubes-announce-web]: https://groups.google.com/group/qubes-announce
[top-post]: https://en.wikipedia.org/wiki/Posting_style
[Top-posting]: https://en.wikipedia.org/wiki/Posting_style#Top-posting
[interleave]: https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
[bottom-post]: https://en.wikipedia.org/wiki/Posting_style#Bottom-posting
[roadmap]: https://github.com/QubesOS/qubes-issues/milestones
[smart-questions]: http://www.catb.org/esr/faqs/smart-questions.html
[Whonix]: /doc/whonix/
@ -431,6 +370,11 @@ You must be subscribed in order to post to this list.
[System Requirements]: /doc/system-requirements/
[User FAQ]: /faq/#users
[documentation]: /doc/
[MUAs]: https://en.wikipedia.org/wiki/Email_client
[Thunderbird]: https://www.thunderbird.net/
[Mutt]: http://www.mutt.org/
[distrust the infrastructure]: /faq/#what-does-it-mean-to-distrust-the-infrastructure
[Split GPG]: /doc/split-gpg/
[thunderbird-newsgroup]: https://support.mozilla.org/en-US/kb/creating-newsgroup-account
[qubes-users-archive]: https://www.mail-archive.com/qubes-users@googlegroups.com/
[qubes-devel-archive]: https://www.mail-archive.com/qubes-devel@googlegroups.com/
@ -445,4 +389,5 @@ You must be subscribed in order to post to this list.
[localization]: https://github.com/QubesOS/qubes-issues/issues?utf8=%E2%9C%93&q=is%3Aissue%20is%3Aopen%20label%3Alocalization
[coc]: /code-of-conduct/
[Transifex]: https://www.transifex.com/otf/qubes/
[issue tracker]: /doc/reporting-bugs/

56
about/video-tours.html
View File

@ -5,6 +5,38 @@ permalink: /video-tours/
---
<div id="tour">
<div class="row">
<div class="col-lg-12 col-md-12 col-xs-12">
<h2 class="add-bottom">Micah Lee presents "Qubes OS: The Operating System That Can Protect You Even If You Get Hacked"</h2>
<p><a href="https://micahflee.com/">Micah Lee</a>, a long-time Qubes <a href="/experts/">advocate</a>, presented <a href="https://www.hope.net/schedule.html#-qubes-os-the-operating-system-that-can-protect-you-even-if-you-get-hacked-">Qubes OS: The Operating System That Can Protect You Even If You Get Hacked</a> at the <a href="https://www.hope.net/index.html">Circle of HOPE</a> conference, which took place July 20-22, 2018 in New York City.</p>
<iframe id="ls_embed_1533360087" src="https://livestream.com/accounts/9197973/events/8286152/videos/178431606/player?width=960&height=540&enableInfo=true&defaultDrawer=feed&autoPlay=false&mute=false" width="960" height="540" frameborder="0" scrolling="no" allowfullscreen> </iframe>
</div>
</div>
<hr class="more-top more-bottom">
<div class="row">
<div class="col-lg-4 col-md-4 col-xs-12">
<h2>Introduction</h2>
<p>Learn the basics in this introduction to Qubes OS.</p><br>
<a href="/intro/" class="btn btn-primary">
<i class="fa fa-flag"></i> What is Qubes OS?
</a>
</div>
<div class="col-lg-4 col-md-4 col-xs-12">
<h2>Screenshots</h2>
<p>See what using Qubes actually looks like with these screenshots of various applications running in Qubes.</p>
<a href="/screenshots/" class="btn btn-primary">
<i class="fa fa-picture-o"></i> See Screenshots
</a>
</div>
<div class="col-lg-4 col-md-4 col-xs-12">
<h2>Getting Started</h2>
<p>Ready to get started with Qubes? Here's what you need to know after installing.</p>
<a href="/getting-started/" class="btn btn-primary">
<i class="fa fa-cubes"></i> Getting Started
</a>
</div>
</div>
<hr class="more-top more-bottom">
<div class="row">
<div class="col-lg-8 col-md-12 col-xs-12">
<h2 class="add-bottom">A Video Tour of Qubes 3.1 by Matthew Wilson</h2>
@ -36,24 +68,24 @@ permalink: /video-tours/
<hr class="more-top more-bottom">
<div class="row">
<div class="col-lg-4 col-md-4 col-xs-12">
<h2>Introduction</h2>
<p>Learn the basics in this introduction to Qubes OS.</p><br>
<a href="/intro/" class="btn btn-primary">
<i class="fa fa-flag"></i> What is Qubes OS?
<h2>Docs</h2>
<p>Dive into the Qubes documentation with guides, tips, and troubleshooting help.</p>
<a href="/doc/" class="btn btn-primary">
<i class="fa fa-book"></i> Documentation
</a>
</div>
<div class="col-lg-4 col-md-4 col-xs-12">
<h2>Screenshots</h2>
<p>See what using Qubes actually looks like with these screenshots of various applications running in Qubes.</p>
<a href="/screenshots/" class="btn btn-primary">
<i class="fa fa-picture-o"></i> See Screenshots
<h2>Downloads</h2>
<p>Download an ISO, verify your download, and install Qubes.</p>
<a href="/downloads/" class="btn btn-primary">
<i class="fa fa-download"></i> Downloads
</a>
</div>
<div class="col-lg-4 col-md-4 col-xs-12">
<h2>Getting Started</h2>
<p>Ready to get started with Qubes? Here's what you need to know after installing.</p>
<a href="/getting-started/" class="btn btn-primary">
<i class="fa fa-cubes"></i> Getting Started
<h2>Security</h2>
<p>Get PGP keys, security bulletins, and canaries. Learn more about our security practices.</p>
<a href="/security/" class="btn btn-primary">
<i class="fa fa-lock"></i> Security Center
</a>
</div>
</div>

85
basics_dev/code-signing.md
View File

@ -78,6 +78,15 @@ uid Bilbo Baggins <bilbo@shire.org>
sub 4096R/69B0EA85 2013-03-13
~~~
Upload the Key
--------------
For others to find the public key, please upload it to a server.
```
$ gpg --send-keys --keyserver pool.sks-keyservers.net 69B0EA85
gpg: sending key 488BA441 to hkp server pool.sks-keyservers.net
```
Using PGP with Git
------------------
@ -103,16 +112,26 @@ your Git commits.
commit -S
~~~
3. (Optional) Create signed tags:
3. (Optional) Create signed tags.
Signed commits are totally sufficient to contribute to Qubes OS.
However, if you have commits which are not signed and you do not want to change them,
you can create a signed tag for the commit and push it before the check.
This is useful for example, if you have a commit back in the git history which
you like to sign now without rewriting the history.
~~~
git tag -s <tag_name> -m "<tag_message>"
~~~
You can also create an alias to make this easier:
You can also create an alias to make this easier.
Edit your `~/.gitconfig` file.
In the `[alias]` section, add `stag` to create signed tags and `spush` to create signed tags and push them.
~~~
stag = "!id=`git rev-parse --verify HEAD`; git tag -s tag_for_${id:0:8} -m \"Tag for commit $id\""
[alias]
stag = "!bash -c 'id=\"`git rev-parse --verify HEAD`\"; tag_name="signed_tag_for_${id:0:8}"; git tag -s "$tag_name" -m \"Tag for commit $id\"; echo \"$tag_name\"'"
spush = "!bash -c 'git push origin `git stag`'"
~~~
You may also find it convenient to have an alias for verifying the tag on the
@ -122,6 +141,63 @@ your Git commits.
vtag = !git tag -v `git describe`
~~~
GitHub Signature Verification (optional)
----------------------------------------
GitHub shows a green `Verified` label indicating that the GPG signature could be
verified using any of the contributor’s GPG keys uploaded to GitHub. You can
upload your public key on GitHub by adding your public GPG key on the [New GPG
key][GitHub New GPG key] under the [SSH GPG keys page][GitHub SSH GPG keys
page].
Code Signature Checks
---------------------
The [signature-checker] checks if code contributions are signed.
Although GitHub adds a little green `Verified` button next to the commit, the [signature-checker] uses this algorithm to check if a commit is correctly signed:
1. Is the commit signed?
If the commit is not signed, you can see the message
> policy/qubesos/code-signing — No signature found
2. If the commit is signed, the key is downloaded from a GPG key server.
If you can see the following error message, please check if you have uploaded the key to a key server.
> policy/qubesos/code-signing — Unable to verify (no valid key found)
### No Signature Found
> policy/qubesos/code-signing — No signature found
In this case, you have several options to sign the commit:
1. Amend the commit and replace it with a signed commit.
You can use this command to create a new signed commit:
```
git commit --amend -S
```
This also rewrites the commit so you need to push it forcefully:
```
git push -f
```
2. Create a signed tag for the unsigned commit.
If the commit is back in history and you do not want to change it,
you can create a signed tag for this commit and push the signature.
You can use the alias from above:
```
git checkout <commit>
git spush
```
Now, the signature checker needs to re-check the signature.
Please comment on the pull request that you would like to have the signatures checked again.
### Unable To Verify
> policy/qubesos/code-signing — Unable to verify (no valid key found)
This means that the [signature-checker] has found a signature for the commit
but is not able to verify it using the any key available.
This might be that you forgot to upload the key to a key server.
Please upload it.
Using PGP with Email
--------------------
@ -135,4 +211,7 @@ Enigmail is a security addon for the Mozilla Thunderbird email client that allow
[source code]: /doc/source-code/
[developer mailing list]: /support/#qubes-devel
[Enigmail]: https://www.enigmail.net/
[signature-checker]: https://github.com/marmarek/signature-checker
[GitHub New GPG key]: https://github.com/settings/gpg/new
[GitHub SSH GPG keys page]: https://github.com/settings/keys

4
basics_dev/gsoc.md
View File

@ -116,7 +116,7 @@ would override all the user changes there). More details:
- ability to deploy the template into various storage mechanisms (sparse
files, LVM thin volumes etc).
- template metadata, templates repository - enable the user to browse
available templates (probably should be done in dedicated VM, or Disposable VM)
available templates (probably should be done in dedicated VM, or DisposableVM)
- Implement the above mechanism:
- tool to download named template - should perform download operation in
some VM (as dom0 have no network access), then transfer the data to dom0,
@ -285,7 +285,7 @@ details: [#1552](https://github.com/QubesOS/qubes-issues/issues/1552),
**Expected results**:
- Extend existing Thunderbird extension to decide on action (where to open/save attachments) based on message sender - recognized as email address, or signing key
- Add Firefox extension to open links in Disposable VM / selected VM (right-click option and a default action for not-whitelisted URLs/domains)
- Add Firefox extension to open links in DisposableVM / selected VM (right-click option and a default action for not-whitelisted URLs/domains)
- The same for Chrome
- Add tests for above enhancements
- Update user documentation

2
basics_dev/usability-ux.md
View File

@ -227,6 +227,6 @@ Learning to make well designing intuitive interfaces and software is specialized
- [Learn Design Principles](http://learndesignprinciples.com) by Melissa Mandelbaum
- [Usability in Free Software](http://jancborchardt.net/usability-in-free-software) by Jan C. Borchardt
- [Superheroes & Villains in Design](https://vimeo.com/70030549) by Aral Balkan
- [First Rule of Usability? Don’t Listen to Users](http://www.nngroup.com/articles/first-rule-of-usability-dont-listen-to-users/) by by Jakob Nielsen
- [First Rule of Usability? Don’t Listen to Users](http://www.nngroup.com/articles/first-rule-of-usability-dont-listen-to-users/) by Jakob Nielsen
- [10 Usability Heuristics for User Interface Design](https://www.nngroup.com/articles/ten-usability-heuristics/) by Jakob Nielsen
- [Hack Design](https://hackdesign.org/) - online learning program

71
basics_user/doc-guidelines.md
View File

@ -22,14 +22,13 @@ documentation or some way it can be improved, please [report] it! Better
yet, you can [edit the documentation][contribute] yourself, both to add or improve existing content.
How to Report Issues
--------------------
Questions, problems, and improvements
-------------------------------------
To report an issue, please create one in [qubes-issues], but before you do,
please make sure it does **not** already exist. Documentation-related
issues will be assigned the `doc` label. Issues which have been created in
[qubes-issues] are significantly more likely to be addressed than those sent in
emails to the mailing lists or to individuals.
If you have a question about something you read in the documentation, please send it to the appropriate [mailing list][support].
If you see that something in the documentation should be fixed or improved, please [contribute] the change yourself.
To report an issue with the documentation, please follow our standard [issue reporting guidelines][report].
(If you report an issue with the documentation, you will likely be asked to address it, unless there is a clear indication in your report that you are not willing or able to do so.)
How to Contribute
@ -74,7 +73,9 @@ contribution.
![fork](/attachment/wiki/doc-edit/05-fork.png)
Now you can make your modifications. You can also preview the changes to see how
they'll be formatted by clicking the "Preview changes" tab.
they'll be formatted by clicking the "Preview changes" tab. **Important:** If
you're making any formatting changes, please [render the site locally] to verify
that everything looks correct before submitting any changes.
![edit](/attachment/wiki/doc-edit/06-edit.png)
@ -224,26 +225,6 @@ Good general content that was submitted only to one branch would effectively dis
For further discussion about version-specific documentation in Qubes, see [here][version-thread].
Contribution Suggestions
------------------------
* If you find any inaccuracies in the documentation, please correct them!
* If you find an inaccuracy but don't know how to correct it, you can still help
by documenting the inaccuracy. For example, if you have *thoroughly* tested
a set of steps in the documentation and know *for certain* that they no
longer work on a certain version of Qubes (maybe because the steps are
out-of-date), then please add a note to the documentation indicating this.
You may also wish to provide a link to a relevant thread on the [mailing
lists].
* Where appropriate, specify the version of the software to which your
contribution applies. For example, if you're contributing a set of
instructions for doing something in dom0, specify the version(s) of Qubes OS
with which you know these instructions to work. This allows future readers to
more easily estimate the accuracy and applicability of information.
Style Guidelines
----------------
@ -261,7 +242,7 @@ When making contributions, please try to observe the following style conventions
* In order to enable offline browsing, use relative paths (e.g., `/doc/doc-guidelines/` instead of `https://www.qubes-os.org/doc/doc-guidelines/`, except when the source text will be reproduced outside of the Qubes website repo.
Examples of exceptions:
* [QSBs] (intended to be read as plain text)
* [News] posts (plain text is reproduced on the [mailing lists])
* [News] posts (plain text is reproduced on the [mailing lists][support])
* URLs that appear inside code blocks (e.g., in comments and document templates)
* Files like `README.md` and `CONTRIBUTING.md`
* Insert a newline at, and only at, the end of each sentence, except when the text will be reproduced outside of the Qubes website repo (see previous item for examples).
@ -273,6 +254,33 @@ When making contributions, please try to observe the following style conventions
where appropriate.
* Use underline headings (`=====` and `-----`) if possible.
If this is not possible, use Atx-style headings on both the left and right sides (`### H3 ###`).
* When writing code blocks, use [syntax highlighting](https://github.github.com/gfm/#info-string) where [possible](https://github.com/jneen/rouge/wiki/List-of-supported-languages-and-lexers) and use `[...]` for anything omitted.
* When providing command line examples:
* Tell the reader where to open a terminal (dom0 or a specific domU), and show the command along with its output (if any) in a code block, e.g.:
~~~markdown
Open a terminal in dom0 and run:
```shell_session
$ cd test
$ echo Hello
Hello
```
~~~
* Precede each command with the appropriate command prompt:
At a minimum, the prompt should contain a trailing `#` (for the user `root`) or `$` (for other users) on Linux systems and `>` on Windows systems, respectively.
* Don't try to add comments inside the code block.
For example, *don't* do this:
~~~markdown
Open a terminal in dom0 and run:
```shell_session
# Navigate to the new directory
$ cd test
# Generate a greeting
$ echo Hello
Hello
```
~~~
The `#` symbol preceding each comment is ambiguous with a root command prompt.
Instead, put your comments *outside* of the code block in normal prose.
* Use `[reference-style][ref]` links.
`[ref]: https://daringfireball.net/projects/markdown/syntax#link`
@ -289,17 +297,18 @@ Please try to write good commit messages, according to the
[qubes-doc]: https://github.com/QubesOS/qubes-doc
[glossary]: /doc/glossary/
[report]: #how-to-report-issues
[report]: /doc/reporting-bugs/
[contribute]: #how-to-contribute
[qubes-issues]: https://github.com/QubesOS/qubes-issues/issues
[gh-fork]: https://guides.github.com/activities/forking/
[gh-pull]: https://help.github.com/articles/using-pull-requests/
[GitHub]: https://github.com/
[mailing lists]: /support/
[support]: /support/
[version-example]: /doc/template/fedora/upgrade-25-to-26/
[version-thread]: https://groups.google.com/d/topic/qubes-users/H9BZX4K9Ptk/discussion
[QSBs]: /security/bulletins/
[News]: /news/
[md]: https://daringfireball.net/projects/markdown/
[git-commit]: /doc/coding-style/#commit-message-guidelines
[render the site locally]: https://github.com/QubesOS/qubesos.github.io#instructions

28
basics_user/getting-started.md
View File

@ -56,7 +56,14 @@ 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.
To open a console window in dom0, either go to Start-\>System Tools-\>Konsole or press Alt-F2 and type `konsole`.
Opening a console window in dom0 can be done in several ways:
* 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`.
Various command line tools are described as part of this guide, and the whole reference can be found [here](/doc/tools/).
@ -64,7 +71,7 @@ Various command line tools are described as part of this guide, and the whole re
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.
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.
![r2b1-qubes-manager-2.png](/attachment/wiki/GettingStarted/r2b1-qubes-manager-2.png)
@ -74,7 +81,7 @@ Starting Apps in qubes
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).
You can start apps directly from the start menu.
You can start apps directly from the Start Menu or the Application Finder (Alt-F3).
Each qube has its own menu directory under the scheme **Domain: \<name\>**.
After navigating into one of these directories, simply click on the application you'd like to start:
@ -122,6 +129,21 @@ You'll also be able to easily copy 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.
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.
* [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/)
Running an application Full Screen
----------------------------------

2
basics_user/intro.md
View File

@ -213,7 +213,7 @@ technical details have been omitted here for the sake of presentation.
* Ready to give Qubes a try? Head on over to the [downloads] page.
[disposable qube]: /doc/dispvm/
[disposable qube]: /doc/disposablevm/
[networking]: /doc/networking/
[firewalls]: /doc/firewall/
[USB]: /doc/usb/

114
basics_user/reporting-bugs.md
View File

@ -1,6 +1,6 @@
---
layout: doc
title: Reporting Bugs
title: Reporting bugs and other issues
permalink: /doc/reporting-bugs/
redirect_from:
- /en/doc/reporting-bugs/
@ -13,94 +13,98 @@ redirect_from:
- /bug-reports/
---
Reporting Bugs
==============
# Reporting bugs and other issues #
One of the most important ways in which you can [contribute to the Qubes OS Project] is by reporting any bugs you have found.
All issues pertaining to the Qubes OS Project (including auxiliary infrastructure such as the [website]) are tracked in [qubes-issues], our GitHub issue tracker.
Important
---------
## Important ##
- **To disclose a security issue confidentially, please see the [Security] page.**
- **In all other cases, please do not email individual developers about bugs.**
- **In all other cases, please do not email individual developers about issues.**
- **Please note that many issues can be resolved by reading the [documentation].**
- **If you see something that should be changed in the documentation, [submit a change][Documentation Guidelines].**
## Issue tracker guidelines ##
Where to submit your report
---------------------------
### Do not submit questions ###
All issues pertaining to the Qubes OS Project (including auxiliary infrastructure such as the [website]) are tracked in [qubes-issues], our GitHub issues tracker.
However, [qubes-issues] is not intended for personal, localized troubleshooting questions, such as problems that affect only a specific laptop model.
Those questions should instead be asked in [qubes-users], where they are more likely to be answered.
Instead, [qubes-issues] is meant for tracking more general bugs and enhancements that affect a broad range of Qubes users.
Please see the sections [How to submit a report on GitHub] and [How to submit a report on the mailing lists] below for more information.
[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].
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 ###
How to submit a report on GitHub
--------------------------------
If your issue is not actionable, please send it to the appropriate [mailing list][Help, Support, and Mailing Lists] instead.
If your issue would be about more than one thing, file them as separate issues instead.
**Before you submit an issue in [qubes-issues], please check to see whether it has already been reported.**
Search through the existing issues by typing your key words in the **Filters** box.
Make sure to check both currently open issues, as well as issues that are already closed.
### New issues should not be duplicates of existing issues ###
Before you submit an issue, check to see whether it has already been reported.
Search through the existing issues -- both open and closed -- by typing your key words in the **Filters** box.
If you find an issue that seems to be similar to yours, read through it.
If this issue is the same as yours, you can comment with additional information to help the maintainer debug it.
If you find an issue that is the same as or subsumes yours, leave a comment on the existing issue rather than filing a new one, even if the existing issue is closed.
If an issue affects more than one Qubes version, we usually keep only one issue for all versions.
The Qubes team will see your comment and reopen the issue, if appropriate.
For example, you can leave a comment with additional information to help the maintainer debug it.
Adding a comment will subscribe you to email notifications, which can be helpful in getting important updates regarding the issue.
If you don't have anything to add but still want to receive email updates, you can click the "watch" button at the bottom of the comments.
When you file a new issue, you should be sure to include the version of Qubes you're using, as well as versions of related software packages.
### Every issue must be of a single type ###
Every issue must be exactly one of the following types: a bug report (`bug`), a feature request (`enhancement`), or a task (`task`).
Do not file multi-typed issues.
Instead, file multiple issues of distinct types.
The Qubes team will classify your issue according to its type.
### New issues should include all relevant information ###
When you file a new issue, you should be sure to include the version of Qubes you're using, as well as versions of related software packages ([how to copy information out of dom0]).
If your issue is related to hardware, provide as many details as possible about the hardware, which could include using command-line tools such as `lspci`.
If you're reporting a bug in a package that is in a [testing] repository, please reference the appropriate issue in the [updates-status] repository.
Project maintainers really appreciate thorough explanations.
It usually helps them address the problem more quickly, so everyone wins!
Once your issue is addressed, your GitHub issue may be closed.
### There are no guarantees that your issue will be addressed ###
Keep in mind that `qubes-issues` is an issue tracker, not a support system.
Creating a new issue is simply a way for you to submit an item for the Qubes team's consideration.
It is up to the Qubes team to decide whether or how to address your issue, which may include closing the issue without taking any action on it.
Even if your issue is kept open, however, you should not expect it to be addressed within any particular time frame, or at all.
At the time of this writing, there are well over one thousand open issues in `qubes-issues`.
The Qubes team has its own roadmap and priorities, which will govern the manner and order in which open issues are addressed.
## Following up afterward ##
If your issue is addressed, your GitHub issue may be closed.
After that, the package containing the fix will move to the appropriate [testing] repository, then to the appropriate stable repository.
If you so choose, you can test the fix while it's in the [testing] repository, or you can wait for it to land in the stable repository.
If, after testing the fix, you find that it does not really fix your bug, please leave a comment on your issue explaining the situation.
When you do, we will receive a notification and respond on your issue or reopen it (or both).
Please **do not** create a duplicate issue or attempt to contact the developers individually about your problem.
## See also ##
How to submit a report on the mailing lists
-------------------------------------------
Before submitting a report on the mailing lists, please check to see whether your issue has already been reported by searching through the archives.
You can do this by visiting the Google Groups web interfaces for both [qubes-users] and [qubes-devel].
Please see the [Mailing Lists] page for further information.
- [Help, Support, and Mailing Lists]
- [Testing New Releases and Updates][testing]
- [How to Contribute]
- [Contributing Code]
- [Package Contributions]
- [Documentation Guidelines]
How to copy information out of dom0
-----------------------------------
Copying information out of dom0 can be useful when reporting bugs.
See [Copying from (and to) dom0] for more information.
Testing new releases and updates
--------------------------------
Please see [Testing New Releases and Updates][testing].
Improving the code
------------------
Please see our guidelines on [how to contribute code].
[contribute to the Qubes OS Project]: /doc/contributing/
[Security]: /security/
[documentation]: /doc/
[website]: /
[qubes-issues]: https://github.com/QubesOS/qubes-issues/issues
[Mailing List]: /support/
[Help, Support, and Mailing Lists]: /support/
[qubes-users]: /support/#qubes-users
[qubes-devel]: /support/#qubes-devel
[How to submit a report on GitHub]: #how-to-submit-a-report-on-github
[How to submit a report on the mailing lists]: #how-to-submit-a-report-on-the-mailing-lists
[testing]: /doc/testing/
[updates-status]: https://github.com/QubesOS/updates-status/issues
[Copying from (and to) dom0]: /doc/copy-from-dom0/
[how to contribute code]: /doc/contributing/#contributing-code
[how to copy information out of dom0]: /doc/copy-from-dom0/
[testing]: /doc/testing/
[How to Contribute]: /doc/contributing/
[Contributing Code]: /doc/contributing/#contributing-code
[Package Contributions]: /doc/package-contributions/
[Documentation Guidelines]: /doc/doc-guidelines/

6
building/building-archlinux-template.md
View File

@ -59,7 +59,7 @@ redirect_from:
* rpmdevtools
* python-sh
* python2-sh
* dialog
@ -70,7 +70,7 @@ redirect_from:
* The tools can usually be installed all together with the following terminal command string:
* **$ sudo dnf install git createrepo rpm-build make wget rpmdevtools python-sh dialog rpm-sign gnupg**
* **$ sudo dnf install git createrepo rpm-build make wget rpmdevtools python2-sh dialog rpm-sign gnupg**
<br>
<br>
![arch-template-04](/attachment/wiki/ArchlinuxTemplate/arch-template-04.png)
@ -117,7 +117,7 @@ redirect_from:
* Edit the '**qubes-os-r3.2.conf**' which is found in **/home/user/qubes-builder/example-configs** Use the text editor of your choice.
* **$ cd /home/user/qubes-builder/example-config/**
* **$ cd /home/user/qubes-builder/example-configs/**
* **$ nano -W qubes-os-r3.2.conf** or **$ gedit qubes-os-r3.2.conf** or etc….
<br>

60
building/building-non-fedora-template.md
View File

@ -8,10 +8,10 @@ redirect_from:
- /wiki/BuildingNonFedoraTemplate/
---
Building a TemplateVM for ArchLinux (or another non fedora OS)
Building a TemplateVM for ArchLinux (or another non Fedora OS)
==============================================================
If you don't like using Fedora because of specific administration or package management / building needs, you could build a VM Template for your Distribution of choice.
If you don't like using Fedora because of specific administration, package management or other building needs, you could build a TemplateVM for your distribution of choice.
This article shows how to build a template for a different OS, taking ArchLinux as an example.
@ -23,9 +23,9 @@ You can start creating Qubes builder scripts for your new OS. Just note that it
chroot initialization
---------------------
You need to install your OS inside a chroot that will be used to build all the required qubes agents of tools.
You need to customize some scripts that will be used to build all the Qubes tools.
The scripts you will be interested in will be inside the qubes-src/linux-template-builder project:
The scripts you will be interested in will be inside the `qubes-src/linux-template-builder` folder:
~~~
scripts_fedora
@ -35,15 +35,15 @@ scripts_yourOSname
### 00\_prepare.sh
The goal of the first script 00\_prepare.sh is to download and verify the signature of the installation cd and tools. You can use the \$CACHEDIR directory variable to store files that could be reused (such as downloaded scripts or iso files)
The goal of the first script `00_prepare.sh` is to download and verify the signature of the installation CD and tools. You can use the `$CACHEDIR` directory variable to store files that could be reused (such as downloaded scripts or iso files).
### 01\_install\_core.sh
The goal of this script is to install a base environment of your target OS inside the \$INSTALLDIR directory variable. Generally you need to bootstrap/install your package manager inside the \$INSTALLDIR directory and install the base packages.
The goal of this script is to install a base environment of your target OS inside the `$INSTALLDIR` directory variable. Generally you need to bootstrap/install your package manager inside the `$INSTALLDIR` directory and install the base packages.
### Testing the installation process
Edit the builder.conf file to change the variable DISTS\_VM to your OS name (DISTS\_VM=your\_os\_name). The try to make the template to check that at least these to first scripts are working correctly:
Edit the file `builder.conf` to change the variable `$DISTS_VM` to your OS name (`DISTS_VM=your_os_name`). The try to create (make) the template to check that at least these first two scripts are working correctly:
~~~
make linux-template-builder
@ -52,7 +52,7 @@ make linux-template-builder
Qubes builder Makefiles
-----------------------
Now you need to create Makefiles specific to your OS. You will find the required scripts directly inside qubes-builder:
Now you need to create Makefiles specific to your OS. You will find the required scripts directly inside the `qubes-builder` folder:
~~~
prepare-chroot-yourOSname
@ -61,30 +61,30 @@ Makefile.yourOSname
### prepare-chroot-yourOSname
The goal of this file is to prepare a development environment of your target OS inside a chroot. You will reuse there the 00\_prepare.sh and 01\_install\_core.sh scripts. Additionally, the following things will be necessary to use to chroot environment:
The goal of this file is to prepare a development environment of your target OS inside a chroot. You will reuse the `00_prepare.sh` and `01_install_core.sh` scripts. Additionally, the following things will be necessary to put in this Makefile:
- the \$1 variable will contain the installation directory (INSTALLDIR should contain the same value than \$1 when you run 00\_prepare or 01\_install\_core)
- the `$1` variable will contain the installation directory (`$INSTALLDIR` should contain the same value as `$1` when you run `00_prepare.sh` or `01_install_core.sh`)
- after your base system is installed, you should install development tools and libraries (gcc, make, ...)
- create a user called 'user' inside your chroot, and give him enough rights to run the command sudo without any password
- register all the repository that could be necessary and synchronize the package database
- register all the repositories that are be necessary and synchronize the package database
- register a custom repository that will be used to store Qubes packages
### Makefile.yourOSname
This file will be used to define the action required when installing a package. The most important one are:
This file will be used to define the action required when installing a custom package. The most important one are:
- dist-prepare-chroot: that's where you will call prepare-chroot-yourOSname if the chroot has not been initialized
- dist-package: that's where you will chroot the development environment and run the command used to build a package.
- dist-build-dep: that's where you will create the custom repository for your target OS based on already compiled packages.
- `dist-prepare-chroot`: that's where you will call `prepare-chroot-yourOSname` if the chroot has not been initialized.
- `dist-package`: that's where you will chroot the development environment and run the command used to build a package.
- `dist-build-dep`: that's where you will create the custom repository for your target OS based on already compiled packages.
These additional target need to exist once you created your first packages:
- dist-copy-out: that's where you will retrieve the package you just built and put it with all the other package you prepared.
- update-repo: that's where you will retrieve the package that have been built and that need to be installed inside the template
- `dist-copy-out`: that's where you will retrieve the package you just built and put it with all the other packages you prepared.
- `update-repo`: that's where you will retrieve the package that have been built and add it to the custom repository.
### Testing the development chroot
You will be able to test these script when making the first Qubes packages. Don't forget that the first things that run when running 'make somcomponent-vm' will be these two scripts, and that you will need to debug it at this point.
You will be able to test these scripts when making the first Qubes packages. Don't forget that the first things that run when running `make somcomponent-vm` will be these two scripts, and that you will need to debug it at this point.
Qubes packages
--------------
@ -99,7 +99,7 @@ Qubes packages
Additional Installation scripts
-------------------------------
Again you need to work on scripts inside the qubes-src/linux-template-builder project:
Again you need to work on scripts inside the `qubes-src/linux-template-builder` folder:
~~~
scripts_fedora
@ -109,7 +109,7 @@ scripts_yourOSname
### 02\_install\_groups.sh
The goal of this script is to install all the package that you want to use in your template (eg: firefox, thunderbird, a file manager, Xorg...)
The goal of this script is to install all the packages that you want to use in your template (eg: firefox, thunderbird, a file manager, Xorg...).
### 04\_install\_qubes.sh
@ -128,28 +128,24 @@ If no Qubes packages are available for your selected OS. You could start to inst
- to create required Qubes packages
- to identify potential issue making all Qubes agents and scripts working correctly.
As soon as you manage to make qrexec and qubes-gui-agent working, it should be sufficient to start preparing a template VM.
As soon as you manage to make `qrexec` and `qubes-gui-agent` working, it should be sufficient to start preparing a template VM.
### Xen libraries
Several XEN libraries are required for Qubes to work correctly. In fact, you need to make xenstore commands working before anything else. For this, Qubes git can be used as several patches have been selected by Qubes developers that could impact the activity inside a VM. Start be retrieving a recent git and identify how you can build a package from it: `git clone https://github.com/QubesOS/qubes-vmm-xen.git`
Several Xen libraries are required for Qubes to work correctly. In fact, you need to make `xenstore` commands working before anything else. For this, Qubes git can be used as several patches have been selected by Qubes developers that could impact the activity inside a VM. Start be retrieving a recent git and identify how you can build a package from it: `git clone https://github.com/QubesOS/qubes-vmm-xen.git`.
Find the .spec file in the git repository (this is the file being used to build rpm packages), and try to adapt it to your OS in order to build a package similar to the target 'vmm-xen'. For example, a PKGBUILD has been created for [ArchLinux](/doc/templates/archlinux/) and can be found in the vmm-xen repository.
Don't be afraid with the complexity of the PKGBUILD, most of the code is almost a copy/paste of required sources and patches found in the .spec file provided in the git repository.
Note once the package has been successfully compiled and installed, you need to setup XEN filesystem. Add the following line to your fstab (you can create this line in your package install script): `xen /proc/xen xenfs defaults 0 0`
Note once the package has been successfully compiled and installed, you need to setup XEN filesystem. Add the following line to your fstab (you can create this line in your package install script): `xen /proc/xen xenfs defaults 0 0`.
Now install the package you built and mount /proc/xen. Verify that xenstore-read works by running: `xenstore-read name` That should give you the current name.
Now install the package you built and mount `/proc/xen`. Verify that xenstore-read works by running: `xenstore-read name`. That should give you the current name.
### Qubes-OS core agents (qrexec...)
### ArchLinux example PKGBUILDs
[https://aur.archlinux.org/packages/qu/qubes-vm-core/PKGBUILD](https://aur.archlinux.org/packages/qu/qubes-vm-core/PKGBUILD)
Qubes OS core agent (qrexec...) - [https://aur.archlinux.org/packages/qu/qubes-vm-core/PKGBUILD](https://aur.archlinux.org/packages/qu/qubes-vm-core/PKGBUILD)
### Qubes-OS kernel modules
Qubes OS kernel modules - [https://aur.archlinux.org/packages/qu/qubes-vm-kernel-modules/PKGBUILD](https://aur.archlinux.org/packages/qu/qubes-vm-kernel-modules/PKGBUILD)
[https://aur.archlinux.org/packages/qu/qubes-vm-kernel-modules/PKGBUILD](https://aur.archlinux.org/packages/qu/qubes-vm-kernel-modules/PKGBUILD)
### Qubes-OS gui agents
[https://aur.archlinux.org/packages/qu/qubes-vm-gui/PKGBUILD](https://aur.archlinux.org/packages/qu/qubes-vm-gui/PKGBUILD)
Qubes OS GUI agent - [https://aur.archlinux.org/packages/qu/qubes-vm-gui/PKGBUILD](https://aur.archlinux.org/packages/qu/qubes-vm-gui/PKGBUILD)

2
building/building-whonix-template.md
View File

@ -8,7 +8,7 @@ redirect_from:
## Building Whonix Templates
The Whonix templates are easily downloaded and installed by following the [procedure here](/doc/whonix/install/).
The Whonix templates are easily downloaded and installed by following the [procedure here](https://www.whonix.org/wiki/Qubes/Install).
However, they are integrated into `qubes-builder` so they are straight-forward to build yourself if you prefer.
Many other Qubes templates can also be built by following this procedure.

9
building/qubes-builder.md
View File

@ -20,23 +20,26 @@ installation ISO.
In order to use it, one should use an rpm-based distro, like Fedora :), and should ensure the following packages are installed:
- sudo
- gpg
- gnupg
- git
- createrepo
- rpm-build
- make
- wget
- rpmdevtools
- python-sh
- python2-sh
- dialog
- rpm-sign
- dpkg-dev
- debootstrap
- PyYAML
- devscripts
- perl-Digest-MD5
- perl-Digest-SHA
Usually one can install those packages by just issuing:
sudo dnf install gpg git createrepo rpm-build make wget rpmdevtools python-sh dialog rpm-sign dpkg-dev debootstrap PyYAML
sudo dnf install gnupg git createrepo rpm-build make wget rpmdevtools python2-sh dialog rpm-sign dpkg-dev debootstrap 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. The full build requires some 25GB of free space, so keep that in mind when deciding where to place this directory.

4
building/qubes-r3-building.md
View File

@ -34,7 +34,7 @@ Last, you may want to disable memory balancing on `dev26` but keep in mind the i
Once you've built `dev26`, open a Terminal window to it and install the necessary dependencies (see [QubesBuilder](/doc/qubes-builder/) for more info):
~~~
$ sudo dnf install git createrepo rpm-build make wget rpmdevtools dialog rpm-sign gnupg dpkg-dev debootstrap python2-sh
$ sudo dnf install gnupg git createrepo rpm-build make wget rpmdevtools python2-sh dialog rpm-sign dpkg-dev debootstrap PyYAML devscripts 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):
@ -52,7 +52,7 @@ gpg --import qubes-developers-keys.asc
~~~
**Note** In the above process, we do *not* rely on the security of our server (keys.qubes-os.org) nor the connection (ssl, cert) -- we only rely on you getting the Qubes Master Signing Key fingerprint *somehow* and ensuring they match!
See [Verifying Signatures](/security/verifying-signatures/#importing-qubes-signing-keys) for verification sources.
See [Verifying Signatures](/security/verifying-signatures/#1-get-the-qubes-master-signing-key-and-verify-its-authenticity) for verification sources.
Now let's bootstrap the builder. Unfortunately, the builder cannot verify itself (the classic Chicken and Egg problem), so we need to verify the signature manually:

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

@ -1,20 +1,25 @@
---
layout: doc
title: Emergency Backup Recovery - format version 2
title: Emergency Backup Recovery (v2)
permalink: /doc/backup-emergency-restore-v2/
redirect_from:
- /en/doc/backup-emergency-restore-v2/
- /doc/BackupEmergencyRestoreV2/
---
Emergency Backup Recovery without Qubes - format version 2
==========================================================
Emergency Backup Recovery without Qubes (v2)
============================================
This page describes how to perform emergency restore of backup created on Qubes R2 Beta3 or earlier (which uses backup format 2).
This page describes how to perform emergency restore of backup created on Qubes
R2 Beta3 or earlier (which uses backup format 2).
The Qubes backup system has been designed with emergency disaster recovery in mind. No special Qubes-specific tools are required to access data backed up by Qubes. In the event a Qubes system is unavailable, you can access your data on any GNU/Linux system with the following procedure.
The Qubes backup system has been designed with emergency disaster recovery in
mind. No special Qubes-specific tools are required to access data backed up by
Qubes. In the event a Qubes system is unavailable, you can access your data on
any GNU/Linux system with the following procedure.
**Note:** In the following example, the backup file is assumed to be both encrypted and compressed.
**Note:** In the following example, the backup file is assumed to be both
encrypted and compressed.
1. Untar the main backup file.
@ -36,7 +41,7 @@ The Qubes backup system has been designed with emergency disaster recovery in mi
dom0-home/dom0user.000.hmac
~~~
1. Verify the integrity of the `private.img` file which houses your data.
2. Verify the integrity of the `private.img` file which houses your data.
~~~
[user@restore ~]$ cd vm1/
@ -46,11 +51,15 @@ The Qubes backup system has been designed with emergency disaster recovery in mi
(stdin)= cf83e1357eefb8bdf1542850d66d8007d620e4050b5715dc83f4a921d36ce9ce47d0d13c5d85f2b0ff8318d2877eec2f63b931bd47417a81a538327af927da3e
~~~
**Note:** The hash values should match. If they do not match, then the backup file may have been tampered with, or there may have been a storage error.
**Note:** The hash values should match. If they do not match, then the backup
file may have been tampered with, or there may have been a storage error.
**Note:** If your backup was hashed with a message digest algorithm other than `sha512`, you must substitute the correct message digest command. A complete list of supported message digest algorithms can be found with `openssl list-message-digest-algorithms`.
**Note:** If your backup was hashed with a message digest algorithm other
than `sha512`, you must substitute the correct message digest command. A
complete list of supported message digest algorithms can be found with
`openssl list-message-digest-algorithms`.
1. Decrypt the `private.img` file.
3. Decrypt the `private.img` file.
~~~
[user@restore vm1]$ openssl enc -d -pass pass:your_passphrase -aes-256-cbc -in private.img.000 -out private.img.dec.000
@ -65,18 +74,22 @@ The Qubes backup system has been designed with emergency disaster recovery in mi
done
~~~
**Note:** If your backup was encrypted with a cipher algorithm other than `aes-256-cbc`, you must substitute the correct cipher command. A complete list of supported cipher algorithms can be found with `openssl list-cipher-algorithms`.
**Note:** If your backup was encrypted with a cipher algorithm other than
`aes-256-cbc`, you must substitute the correct cipher command. A complete
list of supported cipher algorithms can be found with `openssl
list-cipher-algorithms`.
1. Decompress the decrypted `private.img` file.
4. Decompress the decrypted `private.img` file.
~~~
[user@restore vm1]$ zforce private.img.dec.*
[user@restore vm1]$ gunzip private.img.dec.000.gz
~~~
**Note:** If your backup was compressed with a program other than `gzip`, you must substitute the correct compression program.
**Note:** If your backup was compressed with a program other than `gzip`, you
must substitute the correct compression program.
1. Untar the decrypted and decompressed `private.img` file.
5. Untar the decrypted and decompressed `private.img` file.
~~~
[user@restore vm1]$ tar -M -xvf private.img.dec.000
@ -95,9 +108,10 @@ The Qubes backup system has been designed with emergency disaster recovery in mi
~~~
2. `chmod +x new-volume-script`.
3. `tar --new-volume-script=./new-volume-script -xvf private.img.dec.000`. (The `--new-volume-script` option enables multi-volume untaring.)
3. `tar --new-volume-script=./new-volume-script -xvf private.img.dec.000`.
(The `--new-volume-script` option enables multi-volume untaring.)
1. Mount the private.img file and access your data.
6. Mount the private.img file and access your data.
~~~
[user@restore vm1]$ sudo mkdir /mnt/img
@ -106,6 +120,9 @@ The Qubes backup system has been designed with emergency disaster recovery in mi
This data has been successfully recovered!
~~~
**Note:** You may wish to store a plain text copy of these instructions with your Qubes backups in the event that you fail to recall the above procedure while this web page is inaccessible. You may obtain a plaintext version of this file in Git repository housing all the documentation at:
**Note:** You may wish to store a plain text copy of these instructions with
your Qubes backups in the event that you fail to recall the above procedure
while this web page is inaccessible. You may obtain a plaintext version of
this file in Git repository housing all the documentation at:
https://github.com/QubesOS/qubes-doc.git

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

@ -1,20 +1,25 @@
---
layout: doc
title: Emergency Backup Recovery - format version 3
title: Emergency Backup Recovery (v3)
permalink: /doc/backup-emergency-restore-v3/
redirect_from:
- /en/doc/backup-emergency-restore-v3/
- /doc/BackupEmergencyRestoreV3/
---
Emergency Backup Recovery without Qubes - format version 3
==========================================================
Emergency Backup Recovery without Qubes (v3)
============================================
This page describes how to perform an emergency restore of a backup created on Qubes R2 or later (which uses backup format version 3).
This page describes how to perform an emergency restore of a backup created on
Qubes R2 or later (which uses backup format version 3).
The Qubes backup system has been designed with emergency disaster recovery in mind. No special Qubes-specific tools are required to access data backed up by Qubes. In the event a Qubes system is unavailable, you can access your data on any GNU/Linux system with the following procedure.
The Qubes backup system has been designed with emergency disaster recovery in
mind. No special Qubes-specific tools are required to access data backed up by
Qubes. In the event a Qubes system is unavailable, you can access your data on
any GNU/Linux system with the following procedure.
**Note:** In the following example, the backup file is both *encrypted* and *compressed*.
**Note:** In the following example, the backup file is both *encrypted* and
*compressed*.
1. Untar the main backup file.
@ -34,18 +39,28 @@ The Qubes backup system has been designed with emergency disaster recovery in mi
dom0-home/dom0user.000
dom0-home/dom0user.000.hmac
2. Verify the integrity of the `backup-header` file, which contains basic information about your backup.
2. Verify the integrity of the `backup-header` file, which contains basic
information about your backup.
[user@restore ~]$ openssl dgst -sha512 -hmac "your_passphrase" backup-header
HMAC-SHA512(backup-header)= 5b266783e116fe3b2601a54c249ca5f5f96d421dfe6828eeaeb2dcd014e9e945c27b3d7b0f952f5d55c927318906d9c360f387b0e1f069bb8195e96543e2969c
[user@restore ~]$ cat backup-header.hmac
(stdin)= 5b266783e116fe3b2601a54c249ca5f5f96d421dfe6828eeaeb2dcd014e9e945c27b3d7b0f952f5d55c927318906d9c360f387b0e1f069bb8195e96543e2969c
**Note:** The hash values should match. If they do not match, then the backup file may have been tampered with, or there may have been a storage error.
**Note:** The hash values should match. If they do not match, then the
backup file may have been tampered with, or there may have been a storage
error.
**Note:** If your backup was hashed with a message digest algorithm other than `sha512`, you must substitute the correct message digest command. This information is contained in the `backup-header` file (see step 3), however it is not recommended to open this file until its integrity and authenticity has been verified (the current step). A complete list of supported message digest algorithms can be found with `openssl list-message-digest-algorithms`.
**Note:** If your backup was hashed with a message digest algorithm other
than `sha512`, you must substitute the correct message digest command. This
information is contained in the `backup-header` file (see step 3), however
it is not recommended to open this file until its integrity and
authenticity has been verified (the current step). A complete list of
supported message digest algorithms can be found with `openssl
list-message-digest-algorithms`.
3. Read the `backup-header`. You'll need some of this information later. The file will look similar to this:
3. Read the `backup-header`. You'll need some of this information later. The
file will look similar to this:
[user@restore ~]$ cat backup-header
version=3
@ -55,7 +70,8 @@ The Qubes backup system has been designed with emergency disaster recovery in mi
compressed=True
compression-filter=gzip
**Note:** If you see `version=2` here, go to [Emergency Backup Recovery - format version 2](/doc/backup-emergency-restore-v2/) instead.
**Note:** If you see `version=2` here, go to [Emergency Backup Recovery -
format version 2](/doc/backup-emergency-restore-v2/) instead.
4. Verify the integrity of the `private.img` file which houses your data.
@ -65,15 +81,25 @@ The Qubes backup system has been designed with emergency disaster recovery in mi
[user@restore vm1]$ cat private.img.000.hmac
(stdin)= cf83e1357eefb8bdf1542850d66d8007d620e4050b5715dc83f4a921d36ce9ce47d0d13c5d85f2b0ff8318d2877eec2f63b931bd47417a81a538327af927da3e
**Note:** The hash values should match. If they do not match, then the backup file may have been tampered with, or there may have been a storage error.
**Note:** The hash values should match. If they do not match, then the
backup file may have been tampered with, or there may have been a storage
error.
**Note:** If your backup was hashed with a message digest algorithm other than `sha512`, you must substitute the correct message digest command. This information is contained in the `backup-header` file (see step 3). A complete list of supported message digest algorithms can be found with `openssl list-message-digest-algorithms`.
**Note:** If your backup was hashed with a message digest algorithm other
than `sha512`, you must substitute the correct message digest command. This
information is contained in the `backup-header` file (see step 3). A
complete list of supported message digest algorithms can be found with
`openssl list-message-digest-algorithms`.
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
**Note:** If your backup was encrypted with a cipher algorithm other than `aes-256-cbc`, you must substitute the correct cipher command. This information is contained in the `backup-header` file (see step 3). A complete list of supported cipher algorithms can be found with `openssl list-cipher-algorithms`.
**Note:** If your backup was encrypted with a cipher algorithm other than
`aes-256-cbc`, you must substitute the correct cipher command. This
information is contained in the `backup-header` file (see step 3). A
complete list of supported cipher algorithms can be found with `openssl
list-cipher-algorithms`.
6. Decompress the decrypted `private.img` file.
@ -81,7 +107,13 @@ The Qubes backup system has been designed with emergency disaster recovery in mi
private.img.dec -- replaced with private.img.dec.gz
[user@restore vm1]$ gunzip private.img.dec.gz
**Note:** If your backup was compressed with a program other than `gzip`, you must substitute the correct compression program. This information is contained in the `backup-header` file (see step 3).
**Note:** If your backup was compressed with a program other than `gzip`,
you must substitute the correct compression program. This information is
contained in the `backup-header` file (see step 3). For example, if you
used `bzip2`, then you should do this:
[user@restore vm1]$ mv private.img.dec private.img.dec.bz2
[user@restore vm1]$ bunzip2 private.img.dec.bz2
7. Untar the decrypted and decompressed `private.img` file.
@ -95,9 +127,14 @@ The Qubes backup system has been designed with emergency disaster recovery in mi
[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 4--8 for each additional VM.
9. Success! If you wish to recover data from more than one VM in your backup,
simply repeat steps 4--8 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 while this web page is inaccessible. All Qubes documentation, including this page, is available in plain text format in the following Git repository:
**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
while this web page is inaccessible. All Qubes documentation, including
this page, is available in plain text format in the following Git
repository:
https://github.com/QubesOS/qubes-doc.git

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

@ -1,31 +1,84 @@
---
layout: doc
title: Emergency Backup Recovery - format version 4
title: Emergency Backup Recovery (v4)
permalink: /doc/backup-emergency-restore-v4/
redirect_from:
- /en/doc/backup-emergency-restore-v4/
- /doc/BackupEmergencyRestoreV4/
---
Emergency Backup Recovery without Qubes - format version 4
==========================================================
Emergency Backup Recovery without Qubes (v4)
============================================
This page describes how to perform an emergency restore of a backup created on Qubes R4.0 or later (which uses backup format version 4).
This page describes how to perform an emergency restore of a backup created on
Qubes R4.X (which uses backup format version 4).
The Qubes backup system has been designed with emergency disaster recovery in mind. No special Qubes-specific tools are required to access data backed up by Qubes. In the event a Qubes system is unavailable, you can access your data on any GNU/Linux system with the following procedure.
The Qubes backup system has been designed with emergency disaster recovery in
mind. No special Qubes-specific tools are required to access data backed up by
Qubes. In the event a Qubes system is unavailable, you can access your data on
any GNU/Linux system with the following procedure.
**Note:** In the following example, the backup file is both *encrypted* and *compressed*.
1. Backup content is encrypted and integrity protected using [scrypt
utility](https://www.tarsnap.com/scrypt.html). You need to obtain it to
restore your data. If your distribution have it packaged (like on Debian),
install the package standard way, otherwise you need to compile it yourself
(verify its signature first!).
Versions up to 1.2.0 (inclusive) do not support `-P` option for easier
scripting - which means you'll need to enter the passphrase for each file
separately, instead of using `echo ... | scrypt`.
Required `scrypt` Utility
-------------------------
2. Untar the main backup file.
In Qubes 4.X, backups are encrypted and integrity-protected with [scrypt]. You
will need a copy of this utility in order to access your data. Since `scrypt`
is not pre-installed on every GNU/Linux system, it is strongly recommended that
you store a copy of it with your backups. If your distribution has `scrypt`
packaged (e.g., Debian), you can install the package in the standard way using
your distribution's package manager. Otherwise, you'll need to obtain a
compiled binary (instructions below) or compile the program from source
yourself. (Don't forget to [verify signatures] first!) Note that versions of
`scrypt` up to 1.2.0 (inclusive) do not support the `-P` option for easier
scripting, which means you'll need to enter the passphrase for each file
separately, instead of using `echo ... | scrypt`.
Here are instructions for obtaining a compiled `scrypt` binary. This example
uses an RPM-based system (Fedora), but the same general procedure should work on
any GNU/Linux system.
1. If you're not on Qubes 4.X, [get and verify the Release 4 Signing Key].
2. If you're not on Qubes 4.X, import the Release 4 Signing Key:
[user@restore ~]$ sudo rpm --import qubes-release-4-signing-key.asc
3. Download the `scrypt` RPM:
[user@restore ~]$ dnf download scrypt
or, if that doesn't work:
[user@restore ~]$ curl -O https://yum.qubes-os.org/r4.0/current/vm/fc28/rpm/scrypt-1.2.1-1.fc28.x86_64.rpm
4. Verify the signature on the `scrypt` RPM:
[user@restore ~]$ rpm -K scrypt-*.rpm
scrypt-*.rpm: digests signatures OK
The message `digests signatures OK` means that both the digest (i.e., the
output of a hash function) and PGP signature verification were successful.
5. Install `rpmdevtools`:
[user@restore ~]$ sudo dnf install rpmdevtools
6. Extract the `scrypt` binary from the RPM:
[user@restore ~]$ rpmdev-extract scrypt-*.rpm
7. (Optional) Create an alias for the new binary:
[user@restore ~]$ alias scrypt="scrypt-*/usr/bin/scrypt"
Emergency Recovery Instructions
-------------------------------
**Note:** In the following example, the backup file is both *encrypted* and
*compressed*.
1. Untar the main backup file.
[user@restore ~]$ tar -i -xvf qubes-backup-2015-06-05T123456
backup-header
@ -39,25 +92,35 @@ The Qubes backup system has been designed with emergency disaster recovery in mi
vm1/whitelisted-appmenus.list.000.enc
dom0-home/dom0user.000.enc
3. Set backup passhprase environment variable. While this isn't strictly required, it will be handy later and will avoid saving the passphrase into shell history.
**Note:** Each VM in the backup file has its path listed in
`qubes.xml.000.enc` (search for the `backup-path` property). You can
extract only the files necessary for your VM (`vmX`) with `tar -i -xvf
qubes-backup-2015-06-05T123456 backup-header backup-header.hmac vmX/`.
read backup_pass
2. Set the backup passhprase environment variable. While this isn't strictly
required, it will be handy later and will avoid saving the passphrase in
the shell's history.
4. Verify integrity of `backup-header`. For compatibility reasons `backup-header.hmac` is in fact is an encrypted *and integrity protected* version of `backup-header`.
[user@restore ~]$ read backup_pass
3. Verify the integrity of `backup-header`. For compatibility reasons,
`backup-header.hmac` is an encrypted *and integrity protected*
version of `backup-header`.
[user@restore ~]$ set +H
[user@restore ~]$ echo "backup-header!$backup_pass" |\
scrypt -P dec backup-header.hmac backup-header.verified && \
scrypt dec -P backup-header.hmac backup-header.verified && \
diff -qs backup-header backup-header.verified
Files backup-header and backup-header.verified are identical
**Note:** If the above fail, it may be either mean that backup was tampered
with, or it is in different format (see point 3 above). In that case, look into
`backup-header`, at `version` field. If it contains anything else than
`version=4`, go to other version of instruction: [Emergency Backup Recovery -
format version 2](/doc/backup-emergency-restore-v2/), [Emergency Backup
Recovery - format version 3](/doc/backup-emergency-restore-v3/)
**Note:** If this command fails, it may be that the backup was tampered
with or is in a different format. In the latter case, look inside
`backup-header` at the `version` field. If it contains a value other than
`version=4`, go to the instructions for that format version:
- [Emergency Backup Recovery without Qubes (v2)]
- [Emergency Backup Recovery without Qubes (v3)]
5. Read the `backup-header`. You'll need some of this information later. The file will look similar to this:
4. Read `backup-header`:
[user@restore ~]$ cat backup-header
version=4
@ -66,33 +129,55 @@ Recovery - format version 3](/doc/backup-emergency-restore-v3/)
compression-filter=gzip
backup_id=20161020T123455-1234
6. Verify the integrity and decrypt the `private.img` file which houses your data.
5. Set `backup_id` to the value in the last line of `backup-header`:
[user@restore ~]$ backup_id=20161020T123455-1234
6. Verify the integrity of and decrypt the `private.img` file that houses your
data.
[user@restore ~]$ backup_id=20161020T123455-1234 # see backup-header above
[user@restore ~]$ for f_enc in vm1/private.img.???.enc; do \
f_dec=${f_enc%.enc}; \
echo "$backup_id!$f_dec!$backup_pass" | scrypt -P dec $f_enc $f_dec || break; \
echo "$backup_id!$f_dec!$backup_pass" | scrypt dec -P $f_enc $f_dec || break; \
done
**Note:** If the above fail, most likely your backup is corrupted, or been tampered with.
**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
vm1/private.img
**Note:** If your backup was compressed with a program other than `gzip`, you must substitute the correct compression program. This information is contained in the `backup-header` file (see step 3).
**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:
8. Mount the private.img file and access your data.
[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.
[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 5--8 for each additional VM.
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.
**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 while this web page is inaccessible. All Qubes documentation, including this page, is available in plain text format in the following Git repository:
**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
while this web page is inaccessible. All Qubes documentation, including
this page, is available in plain text format in the following Git
repository:
https://github.com/QubesOS/qubes-doc.git
[scrypt]: https://www.tarsnap.com/scrypt.html
[verify signatures]: https://www.qubes-os.org/security/verifying-signatures)
[get and verify the Release 4 Signing Key]: https://www.qubes-os.org/security/verifying-signatures/#2-get-the-release-signing-key
[Emergency Backup Recovery without Qubes (v2)]: https://www.qubes-os.org/doc/backup-emergency-restore-v2/
[Emergency Backup Recovery without Qubes (v3)]: https://www.qubes-os.org/doc/backup-emergency-restore-v3/

175
common-tasks/disposablevm.md Normal file
View File

@ -0,0 +1,175 @@
---
layout: doc
title: DisposableVMs
permalink: /doc/disposablevm/
redirect_from:
- /doc/dispvm/
- /en/doc/dispvm/
- /doc/DisposableVms/
- /wiki/DisposableVMs/
---
DisposableVMs
=============
A DisposableVM (previously known as a "DispVM") is a lightweight VM that can be created quickly and will disappear when closed.
DisposableVMs are usually created in order to host a single application, like a viewer, editor, or web browser.
From inside an AppVM, choosing the `Open in DisposableVM` option on a file will launch a DisposableVM for just that file.
Changes made to a file opened in a DisposableVM are passed back to the originating VM.
This means that you can safely work with untrusted files without risk of compromising your other VMs.
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.
Security
--------
If a [DVM Template] becomes compromised, then any DisposableVM based on that DVM Template could be compromised.
In particular, the *default* DVM Template is important because it is used by the "Open in DisposableVM" feature.
This means that it will have access to everything that you open with this feature.
For this reason, it is strongly recommended that you base the default DVM Template on a trusted TemplateVM.
### DisposableVMs and Local Forensics ###
At this time, DisposableVMs should not be relied upon to circumvent local forensics, as they do not run entirely in RAM.
For details, see [this thread](https://groups.google.com/d/topic/qubes-devel/QwL5PjqPs-4/discussion).
When it is essential to avoid leaving any trace, consider using [Tails](https://tails.boum.org/).
DisposableVMs and Networking (R4.0 and later)
-----------------------------
Similarly to how AppVMs are based on their underlying [TemplateVM](https://www.qubes-os.org/doc/glossary/#templatevm), DisposableVMs are based on their underlying [DVM Template](https://www.qubes-os.org/doc/glossary/#dvm-template).
R4.0 introduces the concept of multiple DVM Templates, whereas R3.2 was limited to only one.
On a fresh installation of Qubes, the default DVM Template is called `fedora-XX-dvm` (where `XX` is the Fedora version of the default TemplateVM).
If you have included the Whonix option in your install, there will also be a `whonix-ws-dvm` DVM Template available for your use.
You can set any AppVM to have the ability to act as a DVM Template with:
qvm-prefs <vmname> template_for_dispvms True
The default system wide DVM Template can be changed with `qubes-prefs default_dispvm`.
By combining the two, choosing `Open in DisposableVM` from inside an AppVM will open the document in a DisposableVM based on the default DVM Template you specified.
You can change this behaviour for individual VMs: in the Application Menu, open Qube Settings for the VM in question and go to the "Advanced" tab.
Here you can edit the "Default DisposableVM" setting to specify which DVM Template will be used to launch DisposableVMs from that VM.
This can also be changed from the command line with:
qvm-prefs <vmname> default_dispvm <dvmtemplatename>
For example, `anon-whonix` has been set to use `whonix-ws-dvm` as its `default_dispvm`, instead of the system default.
You can even set an AppVM that has also been configured as a DVM Template to use itself, so DisposableVMs launched from within the AppVM/DVM Template would inherit the same settings.
NetVM and firewall rules for DVM Templates can be set as they can for a normal VM.
By default a DisposableVM will inherit the NetVM and firewall settings of the DVM Template on which it is based.
This is a change in behaviour from R3.2, where DisposableVMs would inherit the settings of the AppVM from which they were launched.
Therefore, launching a DisposableVM from an AppVM will result in it using the network/firewall settings of the DVM Template on which it is based.
For example, if an AppVM uses sys-net as its NetVM, but the default system DisposableVM uses sys-whonix, any DisposableVM launched from this AppVM will have sys-whonix as its NetVM.
**Warning:** The opposite is also true. This means if you have changed anon-whonix's `default_dispvm` to use the system default, and the system default DisposableVM uses sys-net, launching a DisposableVM from inside anon-whonix will result in the DisposableVM using sys-net.
A DisposableVM launched from the Start Menu inherits the NetVM and firewall settings of the DVM Template on which it is based.
Note that changing the "NetVM" setting for the system default DVM Template *does* affect the NetVM of DisposableVMs launched from the Start Menu.
Different DVM Templates with individual NetVM settings can be added to the Start Menu.
**Important Notes:**
Some DVM Templates will automatically create a menu item to launch a DVM, if you do not see an entry and want to add one please use the command:
qvm-features deb-dvm appmenus-dispvm 1
To launch a DVM from the command line, in dom0 please type the following:
qvm-run --dispvm=NameOfDVM --service qubes.StartApp+NameOfApp
DisposableVMs and Networking (R3.2 and earlier)
-----------------------------
NetVM and firewall rules for DisposableVMs can be set as they can for a normal VM.
By default a DisposableVM will inherit the NetVM and firewall settings of the VM from which it is launched.
Thus if an AppVM uses sys-net as its NetVM, any DisposableVM launched from this AppVM will also have sys-net as its NetVM.
You can change this behaviour for individual VMs: in Qubes VM Manager open VM Settings for the VM in question and go to the "Advanced" tab.
Here you can edit the "NetVM for DisposableVM" setting to change the NetVM of any DisposableVM launched from that VM.
A DisposableVM launched from the Start Menu inherits the NetVM of the [DVM Template](/doc/glossary/#dvm-template).
By default the DVM template is called `fedora-XX-dvm` (where `XX` is the Fedora version of the default TemplateVM).
As an "internal" VM it is hidden in Qubes VM Manager, but can be shown by selecting "Show/Hide internal VMs".
Note that changing the "NetVM for DisposableVM" setting for the DVM Template does *not* affect the NetVM of DisposableVMs launched from the Start Menu; only changing the DVM Template's own NetVM does.
Opening a file in a DisposableVM via GUI
-----------------------------------------
In an AppVM's file manager, right click on the file you wish to open in a DisposableVM, then choose "Open in DisposableVM".
Wait a few seconds and the default application for this file type should appear displaying the file content.
This app is running in its own dedicated VM -- a DisposableVM created for the purpose of viewing or editing this very file.
Once you close the viewing application the whole DisposableVM will be destroyed.
If you have edited the file and saved the changes, the changed file will be saved back to the original AppVM, overwriting the original.
![r1-open-in-dispvm-1.png](/attachment/wiki/DisposableVms/r1-open-in-dispvm-1.png) ![r1-open-in-dispvm-2.png](/attachment/wiki/DisposableVms/r1-open-in-dispvm-2.png)
Opening a fresh web browser instance in a new DisposableVM
-----------------------------------------------------------
Sometimes it is desirable to open an instance of Firefox within a new fresh DisposableVM.
This can be done easily using the Start Menu: just go to **Application Menu -\> DisposableVM -\> DisposableVM:Firefox web browser**.
Wait a few seconds until a web browser starts.
Once you close the viewing application the whole DisposableVM will be destroyed.
![r1-open-in-dispvm-3.png](/attachment/wiki/DisposableVms/r1-open-in-dispvm-3.png)
Opening a file in a DisposableVM via command line (from AppVM)
---------------------------------------------------------------
Use the `qvm-open-in-dvm` command from a terminal in your AppVM:
~~~
[user@work-pub ~]$ qvm-open-in-dvm Downloads/apple-sandbox.pdf
~~~
Note that the `qvm-open-in-dvm` process will not exit until you close the application in the DisposableVM.
Starting an arbitrary program in a DisposableVM from an AppVM
--------------------------------------------------------------
Sometimes it can be useful to start an arbitrary program in a DisposableVM. This can be done from an AppVM by running
~~~
[user@vault ~]$ qvm-run '$dispvm' xterm
~~~
The created DisposableVM can be accessed via other tools (such as `qvm-copy-to-vm`) using its `disp####` name as shown in the Qubes Manager or `qvm-ls`.
Starting an arbitrary application in a DisposableVM via command line (from Dom0)
---------------------------------------------------------------------------------
The Start Menu has shortcuts for opening a terminal and a web browser in dedicated DisposableVMs, since these are very common tasks.
However, it is possible to start an arbitrary application in a DisposableVM directly from Dom0 by running
R4.0 (border colour will be inherited from that set in the `dispvm-template`)
~~~
[joanna@dom0 ~]$ qvm-run --dispvm=dispvm-template --service qubes.StartApp+xterm
~~~
R3.2 (border colour can be specified in the command)
~~~
[joanna@dom0 ~]$ echo xterm | /usr/lib/qubes/qfile-daemon-dvm qubes.VMShell dom0 DEFAULT red
~~~
(The DisposableVM appmenu used for starting Firefox runs a very similar command to the one above.)
Customizing DisposableVMs
--------------------------
You can change the template used to generate the DisposableVMs, and change settings used in the DisposableVM savefile.
These changes will be reflected in every new DisposableVM based on that template.
Full instructions can be found [here](/doc/disposablevm-customization/).
[DVM Template]: /doc/glossary/#dvm-template

151
common-tasks/dispvm.md
View File

@ -1,151 +0,0 @@
---
layout: doc
title: Disposable VMs
permalink: /doc/dispvm/
redirect_from:
- /en/doc/dispvm/
- /doc/DisposableVms/
- /wiki/DisposableVMs/
---
Disposable VMs (DispVMs)
========================
A Disposable VM (DispVM) is a lightweight VM that can be created quickly and will disappear when closed.
Disposable VMs are usually created in order to host a single application, like a viewer, editor, or web browser.
From inside an AppVM, choosing the `Open in Disposable VM` option on a file will launch a DispVM for just that file.
Changes made to a file opened in a DispVM are passed back to the originating VM.
This means that you can safely work with untrusted files without risk of compromising your other VMs.
DispVMs can be launched either directly from Dom0's Start Menu or terminal window, or from within AppVMs.
While running, DispVMs 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 Disposable VM.
Disposable VMs and Networking (R4.0 and later)
-----------------------------
Similarly to how AppVMs are based on their underlying [TemplateVM](https://www.qubes-os.org/doc/glossary/#templatevm), DispVMs are based on their underlying [DVM Template](https://www.qubes-os.org/doc/glossary/#dvm-template).
R4.0 introduces the concept of multiple DVM Templates, whereas R3.2 was limited to only one.
On a fresh installation of Qubes, the default DVM Template is called `fedora-XX-dvm` (where `XX` is the Fedora version of the default TemplateVM).
If you have included the Whonix option in your install, there will also be a `whonix-ws-dvm` DVM Template available for your use.
You can set any AppVM to have the ability to act as a DVM Template with:
qvm-prefs <vmname> template_for_dispvms true
The default system wide DVM Template can be changed with `qubes-prefs default_dispvm`.
By combining the two, choosing `Open in Disposable VM` from inside an AppVM will open the document in a DispVM based on the default DVM Template you specified.
You can change this behaviour for individual VMs: in the Application Menu, open Qube Settings for the VM in question and go to the "Advanced" tab.
Here you can edit the "Default DispVM" setting to specify which DVM Template will be used to launch DispVMs from that VM.
This can also be changed from the command line with:
qvm-prefs <vmname> default_dispvm <dvmtemplatename>
For example, `anon-whonix` has been set to use `whonix-ws-dvm` as its `default_dispvm`, instead of the system default.
You can even set an AppVM that has also been configured as a DVM Template to use itself, so DispVMs launched from within the AppVM/DVM Template would inherit the same settings.
NetVM and firewall rules for DVM Templates can be set as they can for a normal VM.
By default a DispVM will inherit the NetVM and firewall settings of the DVM Template on which it is based.
This is a change in behaviour from R3.2, where DispVMs would inherit the settings of the AppVM from which they were launched.
Therefore, launching a DispVM from an AppVM will result in it using the network/firewall settings of the DVM Template on which it is based.
For example, if an AppVM uses sys-net as its NetVM, but the default system DispVM uses sys-whonix, any DispVM launched from this AppVM will have sys-whonix as its NetVM.
**Warning:** The opposite is also true. This means if you have changed anon-whonix's `default_dispvm` to use the system default, and the system default DispVM uses sys-net, launching a DispVM from inside anon-whonix will result in the DispVM using sys-net.
A Disposable VM launched from the Start Menu inherits the NetVM and firewall settings of the DVM Template on which it is based.
Note that changing the "NetVM" setting for the system default DVM Template *does* affect the NetVM of DispVMs launched from the Start Menu.
Different DVM Templates with individual NetVM settings can be added to the Start Menu.
Disposable VMs and Networking (R3.2 and earlier)
-----------------------------
NetVM and firewall rules for Disposable VMs can be set as they can for a normal VM.
By default a DispVM will inherit the NetVM and firewall settings of the VM from which it is launched.
Thus if an AppVM uses sys-net as its NetVM, any DispVM launched from this AppVM will also have sys-net as its NetVM.
You can change this behaviour for individual VMs: in Qubes VM Manager open VM Settings for the VM in question and go to the "Advanced" tab.
Here you can edit the "NetVM for DispVM" setting to change the NetVM of any DispVM launched from that VM.
A Disposable VM launched from the Start Menu inherits the NetVM of the [DVM Template](/doc/glossary/#dvm-template).
By default the DVM template is called `fedora-XX-dvm` (where `XX` is the Fedora version of the default TemplateVM).
As an "internal" VM it is hidden in Qubes VM Manager, but can be shown by selecting "Show/Hide internal VMs".
Note that changing the "NetVM for DispVM" setting for the DVM Template does *not* affect the NetVM of DispVMs launched from the Start Menu; only changing the DVM Template's own NetVM does.
Opening a file in a Disposable VM via GUI
-----------------------------------------
In an AppVM's file manager, right click on the file you wish to open in a Disposable VM, then choose "Open in Disposable VM".
Wait a few seconds and the default application for this file type should appear displaying the file content.
This app is running in its own dedicated VM -- a Disposable VM created for the purpose of viewing or editing this very file.
Once you close the viewing application the whole Disposable VM will be destroyed.
If you have edited the file and saved the changes, the changed file will be saved back to the original AppVM, overwriting the original.
![r1-open-in-dispvm-1.png](/attachment/wiki/DisposableVms/r1-open-in-dispvm-1.png) ![r1-open-in-dispvm-2.png](/attachment/wiki/DisposableVms/r1-open-in-dispvm-2.png)
Opening a fresh web browser instance in a new Disposable VM
-----------------------------------------------------------
Sometimes it is desirable to open an instance of Firefox within a new fresh Disposable VM.
This can be done easily using the Start Menu: just go to **Application Menu -\> DisposableVM -\> DispVM:Firefox web browser**.
Wait a few seconds until a web browser starts.
Once you close the viewing application the whole Disposable VM will be destroyed.
![r1-open-in-dispvm-3.png](/attachment/wiki/DisposableVms/r1-open-in-dispvm-3.png)
Opening a file in a Disposable VM via command line (from AppVM)
---------------------------------------------------------------
Use the `qvm-open-in-dvm` command from a terminal in your AppVM:
~~~
[user@work-pub ~]$ qvm-open-in-dvm Downloads/apple-sandbox.pdf
~~~
Note that the `qvm-open-in-dvm` process will not exit until you close the application in the Disposable VM.
Starting an arbitrary program in a Disposable VM from an AppVM
--------------------------------------------------------------
Sometimes it can be useful to start an arbitrary program in a DispVM. This can be done from an AppVM by running
~~~
[user@vault ~]$ qvm-run '$dispvm' xterm
~~~
The created Disposable VM can be accessed via other tools (such as `qvm-copy-to-vm`) using its `disp####` name as shown in the Qubes Manager or `qvm-ls`.
Starting an arbitrary application in a Disposable VM via command line (from Dom0)
---------------------------------------------------------------------------------
The Start Menu has shortcuts for opening a terminal and a web browser in dedicated DispVMs, since these are very common tasks.
However, it is possible to start an arbitrary application in a DispVM directly from Dom0 by running
R4.0 (border colour will be inherited from that set in the `dispvm-template`)
~~~
[joanna@dom0 ~]$ qvm-run --dispvm=dispvm-template --service qubes.StartApp+xterm
~~~
R3.2 (border colour can be specified in the command)
~~~
[joanna@dom0 ~]$ echo xterm | /usr/lib/qubes/qfile-daemon-dvm qubes.VMShell dom0 DEFAULT red
~~~
(The Disposable VM appmenu used for starting Firefox runs a very similar command to the one above.)
Customizing Disposable VMs
--------------------------
You can change the template used to generate the Disposable VMs, and change settings used in the Disposable VM savefile.
These changes will be reflected in every new Disposable VM based on that template.
Full instructions can be found [here](/doc/dispvm-customization/).
Disposable VMs and Local Forensics
----------------------------------
At this time, DispVMs should not be relied upon to circumvent local forensics, as they do not run entirely in RAM.
For details, see [this thread](https://groups.google.com/d/topic/qubes-devel/QwL5PjqPs-4/discussion).
When it is essential to avoid leaving any trace, consider using [Tails](https://tails.boum.org/).

22
common-tasks/full-screen-mode.md
View File

@ -32,16 +32,6 @@ Enabling full screen mode for select VMs
If you want to enable full screen mode for select VMs, you can do that by creating the following entry in the `/etc/qubes/guid.conf` file in Dom0:
**Note:** Regardless of the settings below, you can always put a window into
fullscreen mode in Xfce4 using the trusted window manager by right-clicking on
a window's title bar and selecting "Fullscreen". This functionality should still
be considered safe, since a VM window still can't voluntarily enter fullscreen
mode. The user must select this option from the trusted window manager in dom0.
To exit fullscreen mode from here, press `alt` + `space` to bring up the title
bar menu again, then select "Leave Fullscreen".
**Note:** There should be only one `VM: {}` block in the file (or you will [get into problems](https://groups.google.com/d/msg/qubes-users/-Yf9yNvTsVI/xXsEm8y2lrYJ))
~~~
VM: {
personal: {
@ -52,6 +42,8 @@ VM: {
The string 'personal' above is an example only and should be replaced by the actual name of the VM for which you want to enable this functionality.
**Note:** There should be only one `VM: {}` block in the file (or you will [get into problems](https://groups.google.com/d/msg/qubes-users/-Yf9yNvTsVI/xXsEm8y2lrYJ))
One can also enable this functionality for all the VMs globally in the same file, by modifying the 'global' section:
~~~
@ -66,3 +58,13 @@ 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". 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".
For StandaloneHVMs, you should set the screen resolution in the qube to that of the host, (or larger), *before* setting fullscreen mode in Xfce4.

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

@ -76,7 +76,7 @@ If you only want to create a shortcut for a single AppVM, you can create a custo
What about applications in DispVMs?
-----------------------------------
[See here](/doc/dispvm-customization/#adding-arbitrary-programs-to-disposable-vm-application-menu).
[See here](/doc/disposablevm-customization/#adding-arbitrary-programs-to-disposablevm-application-menu).
Behind the scenes
-----------------

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

@ -1,6 +1,6 @@
---
layout: doc
title: Updating software in dom0
title: Installing and updating software in dom0
permalink: /doc/software-update-dom0/
redirect_from:
- /en/doc/software-update-dom0/
@ -8,47 +8,48 @@ redirect_from:
- /wiki/SoftwareUpdateDom0/
---
Updating software in dom0
=========================
Installing and updating software in dom0
========================================
Why would one want to update software in dom0?
----------------------------------------------
Why would one want to install or update software in dom0?
---------------------------------------------------------
Normally, there should be few reasons for updating software in dom0. This is because there is no networking in dom0, which means that even if some bugs are discovered e.g. in the dom0 Desktop Manager, this really is not a problem for Qubes, because none of the third-party software running in dom0 is accessible from VMs or the network in any way. Some exceptions to this include: Qubes GUI daemon, Xen store daemon, and disk back-ends. (We plan move the disk backends to an untrusted domain in a future Qubes release.) Of course, we believe this software is reasonably secure, and we hope it will not need patching.
Normally, there should be few reasons for installing or updating software in dom0. This is because there is no networking in dom0, which means that even if some bugs are discovered e.g. in the dom0 Desktop Manager, this really is not a problem for Qubes, because none of the third-party software running in dom0 is accessible from VMs or the network in any way. Some exceptions to this include: Qubes GUI daemon, Xen store daemon, and disk back-ends. (We plan move the disk backends to an untrusted domain in a future Qubes release.) Of course, we believe this software is reasonably secure, and we hope it will not need patching.
However, we anticipate some other situations in which updating dom0 software might be necessary or desirable:
However, we anticipate some other situations in which installing or updating dom0 software might be necessary or desirable:
- Updating drivers/libs for new hardware support
- Correcting non-security related bugs (e.g. new buttons for qubes manager)
- Adding new features (e.g. GUI backup tool)
How is software updated securely in dom0?
-----------------------------------------
How is software installed and updated securely in dom0?
-------------------------------------------------------
The update process is split into two phases: "resolve and download" and "verify and install." The "resolve and download" phase is handled by the "UpdateVM." (The role of UpdateVM can be assigned to any VM in the Qubes VM Manager, and there are no significant security implications in this choice. By default, this role is assigned to the firewallvm.) After the UpdateVM has successfully downloaded new packages, they are sent to dom0, where they are verified and installed. This separation of duties significantly reduces the attack surface, since all of the network and metadata processing code is removed from the TCB.
The install/update process is split into two phases: "resolve and download" and "verify and install." The "resolve and download" phase is handled by the "UpdateVM." (The role of UpdateVM can be assigned to any VM in the Qubes VM Manager, and there are no significant security implications in this choice. By default, this role is assigned to the firewallvm.) After the UpdateVM has successfully downloaded new packages, they are sent to dom0, where they are verified and installed. This separation of duties significantly reduces the attack surface, since all of the network and metadata processing code is removed from the TCB.
Although this update scheme is far more secure than directly downloading updates in dom0, it is not invulnerable. For example, there is nothing that the Qubes project can feasibly do to prevent a malicious RPM from exploiting a hypothetical bug in GPG's `--verify` operation. At best, we could switch to a different distro or package manager, but any of them could be vulnerable to the same (or a similar) attack. While we could, in theory, write a custom solution, it would only be effective if Qubes repos included all of the regular TemplateVM distro's updates, and this would be far too costly for us to maintain.
How to update software in dom0
------------------------------
How to install and update software in dom0
------------------------------------------
As of Qubes R2 Beta 3, the main update functions have been integrated into the Qubes VM Manager GUI: Simply select dom0 in the VM list, then click the **Update VM system** button (the blue, downward-pointing arrow). In addition, updating dom0 has been made more convenient: You will be prompted on the desktop whenever new dom0 updates are available and given the choice to run the update with a single click.
### How to update dom0
Of course, command line tools are still available for accomplishing various update-related tasks (some of which are not available via Qubes VM Manager). In order to update dom0 from the command line, start a console in dom0 and then run one of the following commands:
In the Qubes VM Manager, simply select dom0 in the VM list, then click the **Update VM system** button (the blue, downward-pointing arrow). In addition, updating dom0 has been made more convenient: You will be prompted on the desktop whenever new dom0 updates are available and given the choice to run the update with a single click.
1. To check and install updates for dom0 software:
Alternatively, command-line tools are available for accomplishing various update-related tasks (some of which are not available via Qubes VM Manager). In order to update dom0 from the command line, start a console in dom0 and then run one of the following commands:
To check and install updates for dom0 software:
~~~
$ sudo qubes-dom0-update
~~~
1. To install additional packages in dom0 (usually not recommended):
### How to install a specific package
To install additional packages in dom0 (usually not recommended):
~~~
$ sudo qubes-dom0-update anti-evil-maid
~~~
You may also pass the `--enablerepo=` option in order to enable optional repositories (see yum configuration in dom0). However, this is only for advanced users who really understand what they are doing.
You may also pass the `--enablerepo=` option in order to enable optional repositories (see yum configuration in dom0). However, this is only for advanced users who really understand what they are doing.
You can also pass commands to `dnf` using `--action=...`.
### How to downgrade a specific package
@ -122,7 +123,7 @@ sudo qubes-dom0-update --enablerepo=qubes-dom0-security-testing
sudo qubes-dom0-update --enablerepo=qubes-dom0-unstable
~~~
To enable or disable any of these repos permanently, change the corresponding boolean in
To enable or disable any of these repos permanently, change the corresponding `enabled` value to `1` in
`/etc/yum.repos.d/qubes-dom0.repo`.
### Kernel Upgrade ###
@ -138,9 +139,9 @@ If the update process does not automatically do it (you should see it mentioned
from the update command), you may need to manually rebuild the EFI or grub config depending on which
your system uses.
EFI
EFI: Replace the example version numbers with the one you are upgrading to.
~~~
sudo dracut -f /boot/efi/EFI/qubes/initramfs-$(uname -r).img $(uname -r)
sudo dracut -f /boot/efi/EFI/qubes/initramfs-4.14.35-1.pvops.qubes.x86_64.img 4.14.35-1.pvops.qubes.x86_64
~~~
Grub2

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

@ -68,7 +68,7 @@ sudo dnf upgrade --enablerepo=qubes-vm-*-security-testing
sudo dnf upgrade --enablerepo=qubes-vm-*-unstable
~~~
To enable or disable any of these repos permanently, change the corresponding boolean in `/etc/yum.repos.d/qubes-*.repo`.
To enable or disable any of these repos permanently, change the corresponding `enabled` value to `1` in `/etc/yum.repos.d/qubes-*.repo`.
### Debian ###
@ -168,7 +168,33 @@ However, a compromise of a template affects only a subset of all your AppVMs (in
Also, if your AppVMs are network disconnected, even though their filesystems might get compromised due to the corresponding template compromise, it still would be difficult for the attacker to actually leak out the data stolen in an AppVM.
Not impossible (due to existence of cover channels between VMs on x86 architecture), but difficult and slow.
Standalone VMs
Standalone VMs (R4.0 and later)
--------------
Standalone VMs have their own copy of the whole filesystem, and thus can be updated and managed on their own.
But this means that they take a few GBs on disk, and also that centralized updates do not apply to them.
Sometimes it might be convenient to have a VM that has its own filesystem, where you can directly introduce changes, without the need to start/stop the template VM.
Such situations include e.g.:
- VMs used for development (devel environments require a lot of \*-devel packages and specific devel tools)
- VMs used for installing untrusted packages.
Normally you install digitally signed software from Red Hat/Fedora repositories, and it's reasonable that such software has non malicious *installation* scripts (rpm pre/post scripts).
However, when you would like to install some packages from less trusted sources, or unsigned, then using a dedicated (untrusted) standalone VM might be a better way.
In order to create a standalone VM you can use a command line like this (from console in Dom0):
```
qvm-create --class StandaloneVM --label <label> --property virt_mode=hvm <vmname>
```
... or click appropriate options in the Qubes Manager's Create VM window.
(Note: Technically, `virt_mode=hvm` is not necessary for every StandaloneVM. However, it makes sense if you want to use a kernel from within the VM.)
Standalone VMs (R3.2 and earlier)
--------------
Standalone VMs have their own copy of the whole filesystem, and thus can be updated and managed on their own.
@ -191,6 +217,7 @@ qvm-create <vmname> --standalone --label <label>
... or click appropriate options in the Qubes Manager's Create VM window.
Using more than one template
----------------------------
@ -240,7 +267,7 @@ And in both cases defaults listed above are applied if the service is not explic
### Technical details (R4.0)
Instead of using a network connection like in R3.2, R4.0 uses RPC/qrexec.
The proxy is configured in qrexec policy: `/etc/qubes-rpc/policy/qubes.UpdatesProxy`.
The proxy is configured in qrexec policy on dom0: `/etc/qubes-rpc/policy/qubes.UpdatesProxy`.
By default this is set to sys-net and/or sys-whonix, depending on firstboot choices.
This new design allows for templates to be updated even when they are not connected to any netvm.
@ -300,7 +327,7 @@ But, of course, the problem of finding malware hooks in general is hard, so this
Also note that the user filesystem's metadata might got maliciously modified by malware in order to exploit a hypothetical bug in the AppVM kernel whenever it mounts the malformed filesystem.
However, these exploits will automatically stop working (and so the infection might be cleared automatically) after the hypothetical bug got patched and the update applied (via template update), which is an exceptional feature of Qubes OS.
Also note that Disposable VMs do not have persistent user filesystem, and so they start up completely "clean" every time.
Also note that DisposableVMs do not have persistent user filesystem, and so they start up completely "clean" every time.
Note the word "clean" means in this context: the same as their template filesystem, of course.
RPMFusion for a Fedora TemplateVM

13
common-tasks/usb.md
View File

@ -144,10 +144,14 @@ If possible, use a method specific for particular device type (for example, bloc
### Installation of qubes-usb-proxy ###
[installation]: #installation-of-qubes-usb-proxy
To use this feature, you need to install [`qubes-usb-proxy`][qubes-usb-proxy] package in the templates used for the USB qube and qubes you want to connect USB devices to.
Note you cannot pass through devices from dom0 (in other words: USB VM is required).
`qubes-usb-proxy` should be installed by default in the template VM.
However, if you receive this error: `ERROR: qubes-usb-proxy not installed in the VM`, you can install the `qubes-usb-proxy` with the package manager in the VM you want to attach the USB device to.
Note, you cannot pass through devices from dom0 (in other words: a USB VM is required).
To use this feature, you need to have the [`qubes-usb-proxy`][qubes-usb-proxy] package installed in the template used for the USB qube and in the qube to which you want to connect USB devices. ( If the qube is TemplateBased then it should be installed in the relevant template as usual. )
If you do not have the package installed you will see this error: `ERROR: qubes-usb-proxy not installed in the VM`.
`qubes-usb-proxy` should be installed by default in the standard Fedora and Debian templates.
You install the `qubes-usb-proxy` package using the package manager as usual.
- Fedora: `sudo dnf install qubes-usb-proxy`
- Debian/Ubuntu: `sudo apt-get install qubes-usb-proxy`
@ -196,3 +200,4 @@ Additional Reading:
[YubiKey]: /doc/YubiKey/
[Creating a USB qube]: /doc/usb-qube-how-to/
[Using a USB keyboard]: /doc/usb-qube-how-to/#enable-a-usb-keyboard-for-login
[qubes-usb-proxy]: https://github.com/QubesOS/qubes-app-linux-usb-proxy

36
configuration/change-time-zone.md Normal file
View File

@ -0,0 +1,36 @@
---
layout: doc
title: Changing your Time Zone
permalink: /doc/change-time-zone/
---
# Changing your Time Zone #
## Qubes 4.0 ##
### Command line ###
If you use the i3 window manager or would prefer to change the system's time
zone in terminal you can issue the `timedatectl` command with the option
`set-timezone`.
For example, to set the system's time zone to Berlin, Germany type in a dom0
terminal:
$ sudo timedatectl set-timezone 'Europe/Berlin'
You can list the available time zones with the option `list-timezones` and show
the current settings of the system clock and time zone with option `status`.
Example output status of `timedatectl` on a system with time zone set to
Europe/Berlin:
[user@dom0 ~]$ timedatectl status
Local time: Sun 2018-10-14 06:20:00 CEST
Universal time: Sun 2018-10-14 04:20:00 UTC
RTC time: Sun 2018-10-14 04:20:00
Time zone: Europe/Berlin (CEST, +0200)
Network time on: no
NTP synchronized: no
RTC in local TZ: no

15
configuration/config-files.md
View File

@ -9,8 +9,11 @@ redirect_from:
- "/wiki/UserDoc/ConfigFiles/"
---
Qubes specific VM config files
==============================
Configuration Files
===================
Qubes-specific VM config files
------------------------------
These files are placed in /rw, which survives a VM restart.
That way, they can be used to customize a single VM instead of all VMs based on the same template.
@ -28,7 +31,7 @@ The scripts here all run as root.
- `/rw/config/qubes-ip-change-hook` - script runs in NetVM after every external IP change and on "hardware" link status change.
- (R4.0 only) in ProxyVMs/AppVMs with `qvm-features <vmname> qubes-firewall true`, scripts placed in the following directories will be executed in the listed order followed by `qubes-firewall-user-script` after each firewall update.
- (R4.0 only) in ProxyVMs (or AppVMs with `qubes-firewall` service enabled), scripts placed in the following directories will be executed in the listed order followed by `qubes-firewall-user-script` after each firewall update.
Good place to write own custom firewall rules.
~~~
@ -37,7 +40,7 @@ The scripts here all run as root.
/rw/config/qubes-firewall-user-script
~~~
- (R3.2 only) `/rw/config/qubes-firewall-user-script` - script runs in ProxyVM/AppVM with `qvm-features <vmname> qubes-firewall true` after each firewall update.
- (R3.2 only) `/rw/config/qubes-firewall-user-script` - script runs in ProxyVM (or AppVM with `qubes-firewall` service enabled) after each firewall update.
Good place to write own custom firewall rules.
- `/rw/config/suspend-module-blacklist` - list of modules (one per line) to be unloaded before system goes to sleep.
@ -48,8 +51,9 @@ Note that scripts need to be executable (chmod +x) to be used.
Also, take a look at [bind-dirs](/doc/bind-dirs) for instructions on how to easily modify arbitrary system files in an AppVM and have those changes persist.
GUI and audio configuration in dom0
===================================
-----------------------------------
The GUI configuration file `/etc/qubes/guid.conf` in one of a few not managed by qubes-prefs or the Qubes Manager tool.
Sample config (included in default installation):
@ -97,3 +101,4 @@ Currently supported settings:
- `audio_low_latency` - force low-latency audio mode (about 40ms compared to 200-500ms by default).
Note that this will cause much higher CPU usage in dom0.

16
configuration/disk-trim.md
View File

@ -26,6 +26,8 @@ If you run `fstrim --all` inside a TemplateVM, in a worst case the `discard` can
If discards are not supported at any one of those layers, it will not make it to the underlying physical device.
There are some security implications to permitting TRIM (read for example [this article](https://asalor.blogspot.com/2011/08/trim-dm-crypt-problems.html)), but in most cases not exploitable.
Conversely, TRIM can improve security against local forensics when using SSDs, because with TRIM enabled deleting data (usually) results in the actual data being erased quickly, rather than remaining in unallocated space indefinitely.
However deletion is not guaranteed, and can fail to happen without warning for a variety of reasons.
Configuration
@ -94,3 +96,17 @@ To enable TRIM support in dom0 with LUKS you need to:
5. To verify if discards are enabled you may use `dmsetup table` (confirm the line for your device mentions "discards") or just run `fstrim -av` (you should see a `/` followed by the number of bytes trimmed).
Swap Space
----------
By default TRIM is not enabled for swap.
To enable it add the `discard` flag to the options for the swap entry in `/etc/fstab`.
This may or may not actually improve performance.
If you only want the security against local forensics benefit of TRIM, you can use the `discard=once` option instead to only perform the TRIM operation once during at boot.
To verify that TRIM is enabled, check `dmesg` for what flags were enabled when the swap space was activated.
You should see something like the following:
Adding 32391164k swap on /dev/mapper/qubes_dom0-swap. Priority:-2 extents:1 across:32391164k SSDscFS
The `s` indicates that the entire swap device will be trimmed at boot, and `c` indicates that individual pages are trimmed after they are no longer being used.

37
configuration/gui-configuration.md Normal file
View File

@ -0,0 +1,37 @@
---
layout: doc
title: GUI Configuration and Troubleshooting
permalink: /doc/gui-configuration/
---
GUI Configuration and Troubleshooting
=====================================
Video RAM adjustment for high-resolution displays
-------------------------------------------------
**Problem:** You have a 4K external display, and when you connect it, you can't click on anything but a small area in the upper-right corner.
When a qube starts, a fixed amount of RAM is allocated to the graphics buffer called video RAM.
This buffer needs to be at least as big as the whole desktop, accounting for all displays that are or will be connected to the machine.
By default, it is as much as needed for the current display and an additional full HD (FHD) display (1920×1080 8 bit/channel RGBA).
This logic fails when the machine has primary display in FHD resolution and, after starting some qubes, a 4K display is connected.
The buffer is too small, and internal desktop resize fails.
**Solution:** Increase the minimum size of the video RAM buffer.
```sh
qvm-features dom0 gui-videoram-min $(($WIDTH * $HEIGHT * 4 / 1024))
qvm-features dom0 gui-videoram-overhead 0
```
Where `$WIDTH`×`$HEIGHT` is the maximum desktop size that you anticipate needing.
For example, if you expect to use a 1080p display and a 4k display side-by-side, that is `(1920 + 3840) × 2160 × 4 / 1024 = 48600`, or slightly more than 48 MiB per qube.
After making these adjustments, the qubes need to be restarted.
The amount of memory allocated per qube is the maximum of:
- `gui-videoram-min`
- current display + `gui-videoram-overhead`
Default overhead is about 8 MiB, which is enough for a 1080p display (see above).
So, the `gui-videoram-overhead` zeroing is not strictly necessary; it only avoids allocating memory that will not be used.

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

@ -16,8 +16,7 @@ By default, VMs kernels are provided by dom0. This means that:
3. You can **not** modify any of the above from inside a VM;
4. Installing additional kernel modules is cumbersome.
*Note* In the examples below, although the specific version numbers might be old, the commands have been verified on R3.2 with debian-9 and fedora-26 templates.
At the time of writing, there is a blocking issue for R4.0 [3563](https://github.com/QubesOS/qubes-issues/issues/3563).
*Note* In the examples below, although the specific version numbers might be old, the commands have been verified on R3.2 and R4.0 with debian-9 and fedora-26 templates.
To select which kernel a given VM will use, you can either use Qubes Manager (VM settings, advanced tab), or the `qvm-prefs` tool:
@ -208,7 +207,102 @@ mke2fs 1.42.12 (29-Aug-2014)
--> Done.
~~~
Using kernel installed in the VM
Using kernel installed in the VM (R4.0)
--------------------------------
Both debian-9 and fedora-26 templates already have grub and related tools preinstalled so if you want to use one of the distribution kernels, all you need to do is clone either template to a new one, then:
~~~
qvm-prefs <clonetemplatename> virt_mode hvm
qvm-prefs <clonetemplatename> kernel ''
~~~
If you'd like to use a different kernel than default, continue reading.
### Installing kernel in Fedora VM (R4.0)
Install whatever kernel you want.
You need to also ensure you have the `kernel-devel` package for the same kernel version installed.
If you are using a distribution kernel package (`kernel` package), the initramfs and kernel modules may be handled automatically.
If you are using a manually built kernel, you need to handle this on your own.
Take a look at the `dkms` documentation, especially the `dkms autoinstall` command may be useful.
If you did not see the `kernel` install rebuild your initramfs, or are using a manually built kernel, you will need to rebuild it yourself.
Replace the version numbers in the example below with the ones appropriate to the kernel you are installing:
~~~
sudo dracut -f /boot/initramfs-4.15.14-200.fc26.x86_64.img 4.15.14-200.fc26.x86_64
~~~
Once the kernel is installed, you need to create a GRUB configuration.
You may want to adjust some settings in `/etc/default/grub`; for example, lower `GRUB_TIMEOUT` to speed up VM startup.
Then, you need to generate the actual configuration:
In Fedora it can be done using the `grub2-mkconfig` tool:
~~~
sudo grub2-mkconfig -o /boot/grub2/grub.cfg
~~~
You can safely ignore this error message:
~~~
grub2-probe: error: cannot find a GRUB drive for /dev/mapper/dmroot. Check your device.map
~~~
Then shutdown the VM.
**Note:** You may also use `PV` mode instead of `HVM` but this is not recommended for security purposes.
If you require `PV` mode, install `grub2-xen` in dom0 and change the template's kernel to `pvgrub2`.
Booting to a kernel inside the template is not supported under `PVH`.
### Installing kernel in Debian VM (R4.0)
Install whatever kernel you want, making sure to include the headers.
If you are using a distribution kernel package (`linux-image-amd64` package), the initramfs and kernel modules should be handled automatically.
If not, or you are building the kernel manually, do this using `dkms` and `initramfs-tools`:
sudo dkms autoinstall -k <kernel-version> # replace this <kernel-version> with actual kernel version
sudo update-initramfs -u
The output should look like this:
$ sudo dkms autoinstall -k 3.16.0-4-amd64
u2mfn:
Running module version sanity check.
- Original module
- No original module exists within this kernel
- Installation
- Installing to /lib/modules/3.16.0-4-amd64/updates/dkms/
depmod....
DKMS: install completed.
$ sudo update-initramfs -u
update-initramfs: Generating /boot/initrd.img-3.16.0-4-amd64
When the kernel is installed, you need to create a GRUB configuration.
You may want to adjust some settings in `/etc/default/grub`; for example, lower `GRUB_TIMEOUT` to speed up VM startup.
Then, you need to generate the actual configuration with the `update-grub2` tool:
~~~
sudo mkdir /boot/grub
sudo update-grub2
~~~
You can safely ignore this error message:
~~~
grub2-probe: error: cannot find a GRUB drive for /dev/mapper/dmroot. Check your device.map
~~~
Then shutdown the VM.
**Note:** You may also use `PV` mode instead of `HVM` but this is not recommended for security purposes.
If you require `PV` mode, install `grub2-xen` in dom0 and change the template's kernel to `pvgrub2`.
Booting to a kernel inside the template is not supported under `PVH`.
Using kernel installed in the VM (R3.2)
--------------------------------
**This option is available only in Qubes R3.1 or newer**
@ -226,7 +320,7 @@ To make it happen, at a high level you need to:
**WARNING: When using a kernel from within a VM, the `kernelopts` parameter is ignored.**
### Installing PV GRUB2
### Installing PV GRUB2 (R3.2)
Simply execute:
@ -234,7 +328,7 @@ Simply execute:
sudo qubes-dom0-update grub2-xen
~~~
### Installing kernel in Fedora VM
### Installing kernel in Fedora VM (R3.2)
In a Fedora based VM, you need to install the `qubes-kernel-vm-support` package.
This package includes the additional kernel module and initramfs addition required to start a Qubes VM (for details see [template implementation](/doc/template-implementation/)).
@ -251,10 +345,11 @@ You need to also ensure you have the `kernel-devel` package for the same kernel
If you are using a distribution kernel package (`kernel` package), the initramfs and kernel modules may be handled automatically.
If you are using a manually built kernel, you need to handle this on your own.
Take a look at the `dkms` documentation, especially the `dkms autoinstall` command may be useful.
If you did not see the `kernel` install rebuild your initramfs, or are using a manually built kernel, you will need to rebuild it yourself with the following:
If you did not see the `kernel` install rebuild your initramfs, or are using a manually built kernel, you will need to rebuild it yourself.
Replace the version numbers in the example below with the ones appropriate to the kernel you are installing:
~~~
sudo dracut -f /boot/initramfs-$(uname -r).img $(uname -r)
sudo dracut -f /boot/initramfs-4.15.14-200.fc26.x86_64.img 4.15.14-200.fc26.x86_64
~~~
Once the kernel is installed, you need to create a GRUB configuration.
@ -280,7 +375,7 @@ This can take a while to complete- longer than your `qrexec_timeout` setting, wh
To confirm this is the case, see [Troubleshooting](/doc/managing-vm-kernel/#troubleshooting) below or just wait for five minutes and shutdown the VM.
It should respond normally on future boots.
### Installing kernel in Debian VM
### Installing kernel in Debian VM (R3.2)
In a Debian based VM, you need to install the `qubes-kernel-vm-support` package.
This package includes the additional kernel module and initramfs addition required to start a Qubes VM (for details see [template implementation](/doc/template-implementation/)).

2
configuration/network-printer.md
View File

@ -30,7 +30,7 @@ As a result, installation of such third-party RPMs in a default template VM expo
(Again, it's not buggy or malicious drivers that we fear here, but rather malicious installation scripts for those drivers).
In order to mitigate this risk, one might consider creating a custom template (i.e. clone the original template) and then install the third-party, unverified drivers there.
Such template might then be made a DVM template for [Disposable VM creation](/doc/dispvm/), which should allow one to print any document by right-clicking on it, choosing "Open in Disposable VM" and print from there.
Such template might then be made a DVM template for [DisposableVM creation](/doc/disposablevm/), which should allow one to print any document by right-clicking on it, choosing "Open in DisposableVM" and print from there.
This would allow to print documents from more trusted AppVMs (based on a trusted default template that is not poisoned by third-party printer drivers).
However, one should be aware that most (all?) network printing protocols are insecure, unencrypted protocols.

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

@ -16,6 +16,7 @@ Resize Disk Image
There are several disk images which can be easily extended, but pay attention to the overall consumed space of your sparse/thin disk images.
See also [OS Specific Follow-up Instructions](/doc/resize-disk-image/#os-specific-follow-up-instructions) at the end of this page.
Since a TemplateBasedVM [inherits its system filesystem from the Template on which it is based](/getting-started/#appvms-qubes-and-templatevms), it is not possible to resize the system disk for a TemplateBasedVM.
### Template disk image (R4.0)

124
configuration/salt.md
View File

@ -240,6 +240,24 @@ This way dom0 doesn't directly interact with potentially malicious target VMs;
and in the case of a compromised Salt VM, because they are temporary, the
compromise cannot spread from one VM to another.
In Qubes 3.2, this temporary VM is based on the default template.
Beginning with Qubes 4.0 and after [QSB #45], we implemented two changes:
1. Added the `management_dispvm` VM property, which specifies the DVM
Template that should be used for management, such as Salt
configuration. TemplateBasedVMs inherit this property from their
parent TemplateVMs. If the value is not set explicitly, the default
is taken from the global `management_dispvm` property. The
VM-specific property is set with the `qvm-prefs` command, while the
global property is set with the `qubes-prefs` command.
2. Created the `default-mgmt-dvm` DVM Template, which is hidden from
the menu (to avoid accidental use), has networking disabled, and has
a black label (the same as TemplateVMs). This VM is set as the global
`management_dispvm`. Keep in mind that this DVM template has full control
over the VMs it's used to manage.
## Writing Your Own Configurations
Let's start with a quick example:
@ -353,11 +371,107 @@ Ensures the specified domain is running:
qvm.running:
- name: salt-test4
## Virtual Machine Formulae
You can use these formulae to download, install, and configure VMs in Qubes.
These formulae use pillar data to define default VM names and configuration details.
The default settings can be overridden in the pillar data located in:
```
/srv/pillar/base/qvm/init.sls
```
In dom0, you can apply a single state with `sudo qubesctl state.sls STATE_NAME`.
For example, `sudo qubesctl state.sls qvm.personal` will create a `personal` VM (if it does not already exist) with all its dependencies (TemplateVM, `sys-firewall`, and `sys-net`).
### Available states
#### `qvm.sys-net`
System NetVM
#### `qvm.sys-usb`
System UsbVM
#### `qvm.sys-net-with-usb`
System UsbVM bundled into NetVM. Do not enable together with `qvm.sys-usb`.
#### `qvm.usb-keyboard`
Enable USB keyboard together with USBVM, including for early system boot (for LUKS passhprase).
This state implicitly creates a USBVM (`qvm.sys-usb` state), if not already done.
#### `qvm.sys-firewall`
System firewall ProxyVM
#### `qvm.sys-whonix`
Whonix gateway ProxyVM
#### `qvm.personal`
Personal AppVM
#### `qvm.work`
Work AppVM
#### `qvm.untrusted`
Untrusted AppVM
#### `qvm.vault`
Vault AppVM with no NetVM enabled.
#### `qvm.default-dispvm`
Default DisposableVM template - fedora-26-dvm AppVM
#### `qvm.anon-whonix`
Whonix workstation AppVM.
#### `qvm.whonix-ws-dvm`
Whonix workstation AppVM for Whonix DisposableVMs.
#### `qvm.updates-via-whonix`
Setup UpdatesProxy to route all templates updates through Tor (sys-whonix here).
#### `qvm.template-fedora-21`
Fedora-21 TemplateVM
#### `qvm.template-fedora-21-minimal`
Fedora-21 minimal TemplateVM
#### `qvm.template-debian-7`
Debian 7 (wheezy) TemplateVM
#### `qvm.template-debian-8`
Debian 8 (jessie) TemplateVM
#### `qvm.template-whonix-gw`
Whonix Gateway TemplateVM
#### `qvm.template-whonix-ws`
Whonix Workstation TemplateVM
## The `qubes` Pillar Module
Additional pillar data is available to ease targeting configurations (for
example all templates).
***Note*** List here may be subject to changes in future releases.
Additional pillar data is available to ease targeting configurations (for example all templates).
**Note:** This list is subject to change in future releases.
### `qubes:type`
@ -423,11 +537,10 @@ The solution is to shut down the updateVM between each install:
* [Top files][salt-doc-top]
* [Jinja templates][jinja]
* [Qubes specific modules][salt-qvm-doc]
* [Formulas for default Qubes VMs][salt-virtual-machines-doc] ([and actual states][salt-virtual-machines-states])
* [Formulas for default Qubes VMs][salt-virtual-machines-states]
[salt-doc]: https://docs.saltstack.com/en/latest/
[salt-qvm-doc]: https://github.com/QubesOS/qubes-mgmt-salt-dom0-qvm/blob/master/README.rst
[salt-virtual-machines-doc]: https://github.com/QubesOS/qubes-mgmt-salt-dom0-virtual-machines/blob/master/README.rst
[salt-virtual-machines-states]: https://github.com/QubesOS/qubes-mgmt-salt-dom0-virtual-machines/tree/master/qvm
[salt-doc-states]: https://docs.saltstack.com/en/latest/ref/states/all/
[salt-doc-states-file]: https://docs.saltstack.com/en/latest/ref/states/all/salt.states.file.html
@ -440,3 +553,4 @@ The solution is to shut down the updateVM between each install:
[jinja]: http://jinja.pocoo.org/
[jinja-tmp]: http://jinja.pocoo.org/docs/2.9/templates/
[jinja-call-salt-functions]: https://docs.saltstack.com/en/getstarted/config/jinja.html#get-data-using-salt
[QSB #45]: /news/2018/12/03/qsb-45/

41
configuration/secondary-storage.md
View File

@ -20,7 +20,7 @@ Qubes 4.0 is more flexible than earlier versions about placing different VMs on
For example, you can keep templates on one disk and AppVMs on another, without messy symlinks.
These steps assume you have already created a separate [volume group](https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/6/html/logical_volume_manager_administration/vg_admin#VG_create) and [thin pool](https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/6/html/logical_volume_manager_administration/thinly_provisioned_volume_creation) (not thin volume) for your HDD.
See also [this example](https://www.linux.com/blog/how-full-encrypt-your-linux-system-lvm-luks) if you would like to create an encrypted LVM pool (but note you can use a single logical volume if preferred, and to use the `-T` option on `lvcreate` to specify it is thin).
See also [this example](https://www.linux.com/blog/how-full-encrypt-your-linux-system-lvm-luks) if you would like to create an encrypted LVM pool (but note you can use a single logical volume if preferred, and to use the `-T` option on `lvcreate` to specify it is thin). You can find the commands for this example applied to Qubes at the bottom of this R4.0 section.
First, collect some information in a dom0 terminal:
@ -50,6 +50,45 @@ For example:
In theory, you can still use file-based disk images ("file" pool driver), but it lacks some features such as you won't be able to do backups without shutting down the qube.
#### Example HDD setup ####
Assuming the secondary hard disk is at /dev/sdb (it will be completely erased), you can set it up for encryption by doing in a dom0 terminal (use the same passphrase as the main Qubes disk to avoid a second password prompt at boot):
sudo cryptsetup luksFormat --hash=sha512 --key-size=512 --cipher=aes-xts-plain64 --verify-passphrase /dev/sdb
sudo blkid /dev/sdb
Note the device's UUID (in this example "b209..."), we will use it as its luks name for auto-mounting at boot, by doing:
sudo nano /etc/crypttab
And adding this line (change both "b209..." for your device's UUID from blkid) to crypttab:
luks-b20975aa-8318-433d-8508-6c23982c6cde UUID=b20975aa-8318-433d-8508-6c23982c6cde none
Reboot the computer so the new luks device appears at /dev/mapper/luks-b209... and we can then create its pool, by doing this on a dom0 terminal (substitute the b209... UUIDs with yours):
First create the physical volume
sudo pvcreate /dev/mapper/luks-b20975aa-8318-433d-8508-6c23982c6cde
Then create the LVM volume group, we will use for example "qubes" as the <vg_name>:
sudo vgcreate qubes /dev/mapper/luks-b20975aa-8318-433d-8508-6c23982c6cde
And then use "poolhd0" as the <thin_pool_name> (LVM thin pool name):
sudo lvcreate -T -n poolhd0 -l +100%FREE qubes
Finally we will tell Qubes to add a new pool on the just created thin pool
qvm-pool --add poolhd0_qubes lvm_thin -o volume_group=qubes,thin_pool=poolhd0,revisions_to_keep=2
By default VMs will be created on the main Qubes disk (i.e. a small SSD), to create them on this secondary HDD do the following on a dom0 terminal:
qvm-create -P poolhd0_qubes --label red unstrusted-hdd
### R3.2 ###
In dom0:

38
configuration/vpn.md
View File

@ -50,11 +50,43 @@ Set up a ProxyVM as a VPN gateway using NetworkManager
3. Set up your VPN as described in the NetworkManager documentation linked above.
4. Configure your AppVMs to use the new VM as a NetVM.
4. (Optional) Make your VPN start automatically.
Edit `/rw/config/rc.local` and add these lines:
```bash
# Automatically connect to the VPN once Internet is up
while ! ping -c 1 -W 1 1.1.1.1; do
sleep 1
done
PWDFILE="/rw/config/NM-system-connections/secrets/passwd-file.txt"
nmcli connection up file-vpn-conn passwd-file $PWDFILE
```
You can find the actual "file-vpn-conn" in `/rw/config/NM-system-connections/`.
Create directory `/rw/config/NM-system-connections/secrets/` (You can put your `*.crt` and `*.pem` files here too).
Create a new file `/rw/config/NM-system-connections/secrets/passwd-file.txt`:
```
vpn.secrets.password:XXXXXXXXXXXXXX
```
And substitute "XXXXXXXXXXXXXX" for the actual password.
The contents of `passwd-file.txt` may differ depending on your VPN settings. See the [documentation for `nmcli up`](https://www.mankier.com/1/nmcli#up).
5. (Optional) Make the network fail-close for the AppVMs if the connection to the VPN breaks.
Edit `/rw/config/qubes-firewall-user-script` and add these lines:
```bash
# Block forwarding of connections through upstream network device
# (in case the vpn tunnel breaks)
iptables -I FORWARD -o eth0 -j DROP
iptables -I FORWARD -i eth0 -j DROP
```
6. Configure your AppVMs to use the new VM as a NetVM.
![Settings-NetVM.png](/attachment/wiki/VPN/Settings-NetVM.png)
5. Optionally, you can install some [custom icons](https://github.com/Zrubi/qubes-artwork-proxy-vpn) for your VPN
7. Optionally, you can install some [custom icons](https://github.com/Zrubi/qubes-artwork-proxy-vpn) for your VPN
Set up a ProxyVM as a VPN gateway using iptables and CLI scripts
@ -212,6 +244,8 @@ It has been tested with Fedora 23 and Debian 8 templates.
# (in case the vpn tunnel breaks):
iptables -I FORWARD -o eth0 -j DROP
iptables -I FORWARD -i eth0 -j DROP
ip6tables -I FORWARD -o eth0 -j DROP
ip6tables -I FORWARD -i eth0 -j DROP
# Block all outgoing traffic
iptables -P OUTPUT DROP

4
configuration/zfs.md
View File

@ -18,7 +18,7 @@ Beware: Dragons might eat your precious data!
Install ZFS in Dom0
===================
Install DKMS style packages for Fedora <sup>(defunct\\ in\\ 0.6.2\\ due\\ to\\ spl/issues/284)</sup>
Install DKMS style packages for Fedora <sup>(defunct in 0.6.2 due to spl/issues/284)</sup>
----------------------------------------------------------------------------------------------------
Fetch and install repository for DKMS style packages for your Dom0 Fedora version [http://zfsonlinux.org/fedora.html](http://zfsonlinux.org/fedora.html):
@ -37,7 +37,7 @@ Install DKMS style packages from git-repository
Build and install your DKMS or KMOD packages as described in [http://zfsonlinux.org/generic-rpm.html](http://zfsonlinux.org/generic-rpm.html).
### Prerequisites steps in AppVM <sup>(i.e.\\ disp1)</sup>
### Prerequisites steps in AppVM <sup>(i.e. disp1)</sup>
Checkout repositories for SPL and ZFS:

6
customization/dark-theme.md
View File

@ -157,11 +157,7 @@ The advantage of creating a dark themed Template VM is, that each AppVM which is
6. *(Optional)* Modify Firefox
**Note:** Firefox uses GTK style settings by default. This can create side effects such as unusable forms or search fields. There are two different ways to avoid this. Either by using a add-on or by overwriting the defaults.
- use the theme [GTK+ Dark Theme Global Fixes](https://userstyles.org/styles/111694/gtk-dark-theme-global-fixes) and the [Stylish](https://addons.mozilla.org/en-US/firefox/addon/stylish/) addon
- or add the following line to `/rw/config/rc.local`
**Note:** Firefox uses GTK style settings by default. This can create side effects such as unusable forms or search fields. One way to avoid this is to add the following line to `/rw/config/rc.local`:
sed -i.bak "s/Exec=firefox %u/Exec=bash -c 'GTK_THEME=Adwaita:light firefox %u'/g" /usr/share/applications/firefox.desktop

372
customization/disposablevm-customization.md Normal file
View File

@ -0,0 +1,372 @@
---
layout: doc
title: DisposableVM Customization
permalink: /doc/disposablevm-customization/
redirect_from:
- /doc/dispvm-customization/
- /en/doc/dispvm-customization/
- /doc/DispVMCustomization/
- /doc/UserDoc/DispVMCustomization/
- /wiki/UserDoc/DispVMCustomization/
---
DisposableVM Customization
============================
Security
--------
If a DVM Template becomes compromised, then any DisposableVM based on that DVM Template could be compromised.
Therefore, you should not make any risky customizations (e.g., installing untrusted browser plugins) in important DVM Templates.
In particular, the *default* DVM Template is important becuase it is used by the "Open in DisposableVM" feature.
This means that it will have access to everything that you open with this feature.
For this reason, it is strongly recommended that you base the default DVM Template on a trusted TemplateVM and refrain from making any risky customizations to it.
Qubes 4.0
----------
A DisposableVM (previously known as a "DispVM") in Qubes 4.0 can be based on any TemplateBasedVM. You can also choose to use different AppVMs for different DisposableVMs. To prepare AppVM to be a base for DisposableVM, you need to set `template_for_dispvms` property, for example:
[user@dom0 ~]$ qvm-prefs fedora-26-dvm template_for_dispvms True
Additionally, if you want to have menu entries for starting applications in DisposableVM based on this AppVM (instead of in the AppVM itself), you can achieve it with `appmenus-dispvm` feature:
[user@dom0 ~]$ qvm-features fedora-26-dvm appmenus-dispvm 1
### Creating new DisposableVM base AppVM ###
In Qubes 4.0, you're no longer restricted to a single DVM Template. Instead, you can create as many as you want. Whenever you start a new DisposableVM, you can choose to base it on whichever DVM Template you like.
To create new DVM Template, lets say `custom-dvm`, based on `debian-9` template, use following commands:
[user@dom0 ~]$ qvm-create --template debian-9 --label red custom-dvm
[user@dom0 ~]$ qvm-prefs custom-dvm template_for_dispvms True
[user@dom0 ~]$ qvm-features custom-dvm appmenus-dispvm 1
Additionally you may want to set it as default DVM Template:
[user@dom0 ~]$ qubes-prefs default_dispvm custom-dvm
The above default is used whenever a qube request starting a new DisposableVM and do not specify which one (for example `qvm-open-in-dvm` tool). This can be also set in qube settings and will affect service calls from that qube. See [qrexec documentation](/doc/qrexec3/#extra-keywords-available-in-qubes-40-and-later) for details.
If you wish to use the `fedora-minimal` template as a DVM Template, see the "DVM Template" use case under [fedora-minimal customization](/doc/templates/fedora-minimal/#customization).
### Customization of DisposableVM ###
It is possible to change the settings for each new DisposableVM. This can be done by customizing the base AppVM:
1. Start a terminal in the `fedora-26-dvm` qube (or another base for DisposableVM) by running the following command in a dom0 terminal. (If you enable `appmenus-dispvm` feature (as explained at the top), applications menu for this VM (`fedora-26-dvm`) will be "Disposable: fedora-26-dvm" (instead of "Domain: fedora-26-dvm") and entries there will start new DisposableVM based on that VM (`fedora-26-dvm`). Not in that VM (`fedora-26-dvm`) itself).
[user@dom0 ~]$ qvm-run -a fedora-26-dvm gnome-terminal
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 the DisposableVM's default NetVM. For example, you may wish to set the NetVM to "none." Then, whenever you start a new DisposableVM, you can choose your desired ProxyVM manually (by changing the newly-started DisposableVMs settings). This is useful if you sometimes wish to use a DisposableVM with a Whonix Gateway, for example. It is also useful if you sometimes wish to open untrusted files in a network-disconnected DisposableVM.
4. Shutdown the qube (either by `poweroff` from qube's terminal, or `qvm-shutdown` from dom0 terminal).
### Using static DisposableVMs for sys-* ###
You can use a static DisposableVM for `sys-*` as long as it is stateless.
For example, a `sys-net` using DHCP or `sys-usb` will work.
In most cases `sys-firewall` will also work, even if you have configured AppVM firewall rules.
The only exception is if you require something like VM to VM communication and have manually edited `iptables` or other items directly inside the firewall AppVM.
To create one that has no PCI devices attached, such as for `sys-firewall`:
~~~
qvm-create -C DispVM -l red <sys-VMName>
qvm-prefs <sys-VMName> autostart true
qvm-prefs <sys-VMName> netvm <sys-net>
qvm-prefs <sys-VMName> provides_network true
~~~
Next, set the old `sys-firewall` autostart to false, and update any references to the old one to instead point to the new.
For example, with `qvm-prefs work netvm sys-firewall2`.
To create one with a PCI device attached such as for `sys-net` or `sys-usb`, use the additional commands as follows.
**Note** You can use `qvm-pci` to [determine](/doc/assigning-devices/#r40) the `<BDF>`.
Also, you will often need to include the `-o no-strict-reset=True` [option](/doc/assigning-devices/#r40-1) with USB controllers.
~~~
qvm-create -C DispVM -l red <sys-VMName>
qvm-prefs <sys-VMName> virt_mode hvm
qvm-service <sys-VMName> meminfo-writer off
qvm-pci attach --persistent <sys-VMName> dom0:<BDF>
qvm-prefs <sys-VMName> autostart true
qvm-prefs <sys-VMName> netvm ''
# optional, if this DisposableVM will be providing networking
qvm-prefs <sys-VMName> provides_network true
~~~
Next, set the old `sys-` VM's autostart to false, and update any references to the old one.
For example, `qvm-prefs sys-firewall netvm <sys-VMName>`.
See below for a complete example of a `sys-net` replacement:
~~~
qvm-create -C DispVM -l red sys-net2
qvm-prefs sys-net2 virt_mode hvm
qvm-service sys-net2 meminfo-writer off
qvm-pci attach --persistent sys-net2 dom0:00_1a.0
qvm-prefs sys-net2 autostart true
qvm-prefs sys-net2 netvm ''
qvm-prefs sys-net2 provides_network true
qvm-prefs sys-net autostart false
qvm-prefs sys-firewall netvm sys-net2
qubes-prefs clockvm sys-net2
~~~
Note that these types of DisposableVMs will not show in the Application menu, but you can still get to a terminal if needed with `qvm-run <sys-VMName> gnome-terminal`.
### Adding programs to DisposableVM Application Menu ###
For added convenience, arbitrary programs can be added to the Application Menu of the DisposableVM.
In order to do that, select "Qube settings" entry in selected base AppVM, go to "Applications" tab and select desired applications as for any other qube.
Note that currently only applications whose main process keeps running until you close the application (i.e. do not start a background process instead) will work. One of known examples of incompatible applications is GNOME Terminal (shown on the list as "Terminal"). Choose different terminal emulator (like XTerm) instead.
### Create Custom sys-net sys-firewall and sys-usb DisposableVMs ###
Users have the option of creating customized DisposableVMs for the `sys-net`, `sys-firewall` and `sys-usb` VMs. In this configuration, a fresh VM instance is created each time a DisposableVM is launched. Functionality is near-identical to the default VMs created following a new Qubes’ installation, except the user benefits from a non-persistent filesystem.
Functionality is not limited, users can:
* Set custom firewall rule sets and run Qubes VPN scripts.
* Set DisposableVMs to autostart at system boot.
* Attach PCI devices with the `--persistent` option.
Using DisposableVMs in this manner is ideal for untrusted qubes which require persistent PCI devices, such as USB VMs and NetVMs.
>_**Note:**_ Users who want customized VPN or firewall rule sets must create a separate dvm for use by each DisposableVM. If dvm customization is not needed, then a single dvm is used as a template for all DisposableVMs.
#### Create and configure the dvm from which the DisposableVM will be based on ####
1. Create the dvm
[user@dom0 ~]$ qvm-create --class AppVM --label gray <dvm-name>
2. _(optional)_ In the dvm, add custom firewall rule sets, Qubes VPN scripts etc
Firewall rules sets and Qubes VPN scripts can be added just like any other VM
3. Set the dvm as template for DisposableVMs
[user@dom0 ~]$ qvm-prefs <dvm_name> template_for_dispvms true
#### Create the sys-net DisposableVM ####
1. Create `sys-net` DisposableVM based on the dvm
[user@dom0 ~]$ qvm-create --template <dvm_name> --class DispVM --label red disp-sys-net
2. Set `disp-sys-net` virtualization mode to [hvm](/doc/hvm/)
[user@dom0 ~]$ qvm-prefs disp-sys-net virt_mode hvm
3. Set `disp-sys-net` to provide network for other VMs
[user@dom0 ~]$ qvm-prefs disp-sys-net provides_network true
4. Set `disp-sys-net` NetVM to none
[user@dom0 ~]$ qvm-prefs disp-sys-net netvm ""
5. List all available PCI devices to determine the correct _backend:BDF_ address(es) to assign to `disp-sys-net`
[user@dom0 ~]$ qvm-pci
6. Attach the network PCI device(s) to `disp-sys-net`: Finding and assigning PCI devices can be found [here](/doc/assigning-devices/)
[user@dom0 ~]$ qvm-pci attach --persistent disp-sys-net <backend>:<bdf>
7. _(recommended)_ Set `disp-sys-net` to start automatically when Qubes boots
[user@dom0 ~]$ qvm-prefs disp-sys-net autostart true
8. _(optional)_ Set `disp-sys-net` as the dom0 time source
[user@dom0 ~]$ qubes-prefs clockvm disp-sys-net
#### Create the sys-firewall DisposableVM ####
1. Create `sys-firewall` DisposableVM
[user@dom0 ~]$ qvm-create --template <dvm_name> --class DispVM --label green disp-sys-firewall
2. Set `disp-sys-firewall` to provide network for other VMs
[user@dom0 ~]$ qvm-prefs disp-sys-firewall provides_network true
3. Set `disp-sys-net` as the NetVM for `disp-sys-firewall`
[user@dom0 ~]$ qvm-prefs disp-sys-firewall netvm disp-sys-net
4. Set `disp-sys-firewall` as NetVM for other AppVMs
[user@dom0 ~]$ qvm-prefs <vm_name> netvm disp-sys-firewall
5. _(recommended)_ Set `disp-sys-firewall` to auto-start when Qubes boots
[user@dom0 ~]$ qvm-prefs disp-sys-firewall autostart true
6. _(optional)_ Set `disp-sys-firewall` as the default NetVM
[user@dom0 ~]$ qubes-prefs default_netvm disp-sys-firewall
#### Create the sys-usb DisposableVM ####
1. Create the `disp-sys-usb`
[user@dom0 ~]$ qvm-create --template <dvm-name> --class DispVM --label red disp-sys-usb
2. Set the `disp-sys-usb` virtualization mode to hvm
[user@dom0 ~]$ qvm-prefs disp-sys-usb virt_mode hvm
3. Set `disp-sys-usb` NetVM to none
[user@dom0 ~]$ qvm-prefs usb-disp netvm ""
4. List all available PCI devices
[user@dom0 ~]$ qvm-pci
5. Attach the USB controller to the `disp-sys-usb`
>_**Note:**_ Most of the commonly used USB controllers (all Intel integrated controllers) require the `-o no-strict-reset=True` option to be set. Instructions detailing how this option is set can be found [here](/doc/assigning-devices/#r40-1).
[user@dom0 ~]$ qvm-pci attach --persistent disp-sys-usb <backined>:<bdf>
6. _(optional)_ Set `disp-sys-usb` to auto-start when Qubes boots
[user@dom0 ~]$ qvm-prefs disp-sys-usb autostart true
7. Users should now follow instructions on [How to hide USB controllers from dom0](/doc/usb/#how-to-hide-all-usb-controllers-from-dom0)
#### Starting the DisposableVMs ####
Prior to starting the new VMs, users should ensure that no other VMs such as the old `sys-net` and `sys-usb` VMs are running. This is because no two VMs can share the same PCI device while both running. It is recommended that users detach the PCI devices from the old VMs without deleting them. This will allow users to reattach the PCI devices if the newly created DisposableVMs fail to start.
Detach PCI device from VM
[user@dom0~]$ qvm-pci detach <vm_name> <backend>:<bdf>
#### Troubleshooting ####
The `disp-sys-usb` VM does not start
If the `disp-sys-usb` does not start, it could be due to a PCI passthrough problem. For more details on this issue along with possible solutions, users can look [here](/doc/assigning-devices/#pci-passthrough-issues)
### Deleting DisposableVM ###
Deleting disposable VM is slightly peculiar. While working in a VM or disposable VM, you may want to open a document in another disposable VM. For this reason, the property `default_dispvm` may be set to the name of your disposable VM in a number of VMs:
[user@dom0 ~]$ qvm-prefs workvm | grep default_dispvm
default_dispvm - custom-dvm
This will prevent the deletion of the DVM. In order to fix this you need to unset the `default_dispvm` property:
[user@dom0 ~]$ qvm-prefs workvm default_dispvm ""
You can then delete the DVM:
[user@dom0 ~]$ qvm-remove custom-dvm
This will completely remove the selected VM(s)
custom-dvm
If you still encounter the issue, you may have forgot to clean an entry. Looking at the system logs will help you
[user@dom0 ~]$ journalctl | tail
Qubes 3.2
----------
### Changing the DVM Template ###
You may want to use a non-default template the [DVM Template](/doc/glossary/#dvm-template). One example is to use a less-trusted template with some less trusted, third-party, often unsigned, applications installed, such as e.g. third-party printer drivers.
In order to regenerate the DisposableVM "snapshot" (called 'savefile' on Qubes) one can use the following command in Dom0:
[user@dom0 ~]$ qvm-create-default-dvm <custom-template-name>
This would create a new DisposableVM savefile based on the custom template.
For example `<custom-template-name>` could be the name of the existing `debian-8` vm, which creates the disposable vm `debain-8-dvm`.
Now, whenever one opens a file (from any AppVM) in a DisposableVM, a DisposableVM based on this template will be used.
One can easily verify if the new DisposableVM template is indeed based on a custom template (in the example below the template called "f17-yellow" was used as a basis for the DisposableVM):
[user@dom0 ~]$ ll /var/lib/qubes/dvmdata/
total 0
lrwxrwxrwx 1 user user 45 Mar 11 13:59 default_dvm.conf -> /var/lib/qubes/appvms/f17-yellow-dvm/dvm.conf
lrwxrwxrwx 1 user user 49 Mar 11 13:59 default_savefile -> /var/lib/qubes/appvms/f17-yellow-dvm/dvm-savefile
lrwxrwxrwx 1 user user 47 Mar 11 13:59 savefile_root -> /var/lib/qubes/vm-templates/f17-yellow/root.img
If you wish to use the `fedora-minimal` template as a DVM Template, see the "DVM Template" use case under [fedora-minimal customization](/doc/templates/fedora-minimal/#customization).
### Customization of DisposableVM ###
It is possible to change the settings of each new DisposableVM. This can be done by customizing the DVM Template:
1. Start a terminal in the `fedora-23-dvm` TemplateVM by running the following command in a dom0 terminal. (By default, this TemplateVM is not shown in Qubes VM Manager. However, it can be shown by selecting "Show/Hide internal VMs.")
[user@dom0 ~]$ qvm-run -a fedora-23-dvm gnome-terminal
2. Change the VM's settings and/or applications, as desired. Note that currently Qubes supports exactly one DVM Template, so any changes you make here will affect all DisposableVMs. Some examples of changes you may want to make include:
- Changing Firefox's default startup settings and homepage.
- Changing Nautilus' default file preview settings.
- Changing the DisposableVM's default NetVM. For example, you may wish to set the NetVM to "none." Then, whenever you start a new DisposableVM, you can choose your desired ProxyVM manually (by changing the newly-started DisposableVM's settings). This is useful if you sometimes wish to use a DisposableVM with a Whonix Gateway, for example. It is also useful if you sometimes wish to open untrusted files in a network-disconnected DisposableVM.
3. Create an empty `/home/user/.qubes-dispvm-customized` file in the VM (not in dom0):
[user@fedora-23-dvm ~]$ touch /home/user/.qubes-dispvm-customized
4. Shutdown the VM (either by `poweroff` from VM terminal, or `qvm-shutdown` from dom0 terminal).
5. Regenerate the DVM Template using the default template:
[user@dom0 ~]$ qvm-create-default-dvm --default-template
Or, if you're [using a non-default template](#changing-the-dvm-template), regenerate the DVM Template using your custom template:
[user@dom0 ~]$ qvm-create-default-dvm <custom-template-name>
**Note:** All of the above requires at least qubes-core-vm \>= 2.1.2 installed in template.
### Adding arbitrary programs to DisposableVM Application Menu ###
For added convenience, arbitrary programs can be added to the Application Menu of the DisposableVM. In order to do that create (e.g.) `arbitrary.desktop` file in `/usr/local/share/applications` in Dom0. That file will point to the desired program. Use the following template for the file:
[Desktop Entry]
Version=1.0
Type=Application
Exec=sh -c 'echo arbitrary | /usr/lib/qubes/qfile-daemon-dvm qubes.VMShell dom0 DEFAULT red'
Icon=dispvm-red
Terminal=false
Name=DispVM: Arbitrary Name
GenericName=DispVM: Arbitrary Generic Name
StartupNotify=false
Categories=Network;X-Qubes-VM;
Next, the `/etc/xdg/menus/applications-merged/qubes-dispvm.menu` file has to be modified so that it points to the newly-created .desktop file. (If you use i3 you can skip this step; the shortcut gets added to dmenu automatically.)
Add a `<Filename>arbitrary.desktop</Filename>` line so that your modified file looks like this:
<Include>
<Filename>qubes-dispvm-firefox.desktop</Filename>
<Filename>qubes-dispvm-xterm.desktop</Filename>
<Filename>arbitrary.desktop</Filename>
</Include>
After saving the changes the new shortcut should appear in the DisposableVM Applications menu.

173
customization/dispvm-customization.md
View File

@ -1,173 +0,0 @@
---
layout: doc
title: Disposable VM Customization
permalink: /doc/dispvm-customization/
redirect_from:
- /en/doc/dispvm-customization/
- /doc/DispVMCustomization/
- /doc/UserDoc/DispVMCustomization/
- /wiki/UserDoc/DispVMCustomization/
---
Disposable VM Customization
============================
Qubes 4.0
----------
Disposable VM (DispVM) in Qubes 4.0 can be based on any TemplateBasedVM. You can also choose to use different AppVMs for different Disposable VMs. To prepare AppVM to be a base for Disposable VM, you need to set `template_for_dispvms` property, for example:
[user@dom0 ~]$ qvm-prefs fedora-26-dvm template_for_dispvms True
Additionally, if you want to have menu entries for starting applications in Disposable VM based on this AppVM (instead of in the AppVM itself), you can achieve it with `appmenus-dispvm` feature:
[user@dom0 ~]$ qvm-features fedora-26-dvm appmenus-dispvm 1
### Creating new Disposable VM base AppVM ###
In Qubes 4.0, you're no longer restricted to a single DVM Template. Instead, you can create as many as you want. Whenever you start a new Disposable VM, you can choose to base it on whichever DVM Template you like.
To create new DVM Template, lets say `custom-dvm`, based on `debian-9` template, use following commands:
[user@dom0 ~]$ qvm-create --template debian-9 --label red custom-dvm
[user@dom0 ~]$ qvm-prefs custom-dvm template_for_dispvms True
[user@dom0 ~]$ qvm-features custom-dvm appmenus-dispvm 1
Additionally you may want to set it as default DVM Template:
[user@dom0 ~]$ qubes-prefs default_dispvm custom-dvm
The above default is used whenever a qube request starting a new Disposable VM and do not specify which one (for example `qvm-open-in-dvm` tool). This can be also set in qube settings and will affect service calls from that qube. See [qrexec documentation](/doc/qrexec3/#extra-keywords-available-in-qubes-40-and-later) for details.
If you wish to use the `fedora-minimal` template as a DVM Template, see the "DVM Template" use case under [fedora-minimal customization](/doc/templates/fedora-minimal/#customization).
### Customization of Disposable VM ###
It is possible to change the settings for each new Disposable VM (DispVM). This can be done by customizing the base AppVM:
1. Start a terminal in the `fedora-26-dvm` qube (or another base for DispVM) by running the following command in a dom0 terminal. (If you enable `appmenus-dispvm` feature (as explained at the top), applications menu for this VM (`fedora-26-dvm`) will be "Disposable: fedora-26-dvm" (instead of "Domain: fedora-26-dvm") and entries there will start new DispVM based on that VM (`fedora-26-dvm`). Not in that VM (`fedora-26-dvm`) itself).
[user@dom0 ~]$ qvm-run -a fedora-26-dvm gnome-terminal
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 the DispVM's default NetVM. For example, you may wish to set the NetVM to "none." Then, whenever you start a new DispVM, you can choose your desired ProxyVM manually (by changing the newly-started DispVMs settings). This is useful if you sometimes wish to use a DispVM with a Whonix Gateway, for example. It is also useful if you sometimes wish to open untrusted files in a network-disconnected DispVM.
4. Shutdown the qube (either by `poweroff` from qube's terminal, or `qvm-shutdown` from dom0 terminal).
### Adding programs to Disposable VM Application Menu ###
For added convenience, arbitrary programs can be added to the Application Menu of the Disposable VM.
In order to do that, select "Qube settings" entry in selected base AppVM, go to "Applications" tab and select desired applications as for any other qube.
Note that currently only applications whose main process keeps running until you close the application (i.e. do not start a background process instead) will work. One of known examples of incompatible applications is GNOME Terminal (shown on the list as "Terminal"). Choose different terminal emulator (like XTerm) instead.
### Deleting Disposable VM ###
Deleting disposable VM is slightly peculiar. While working in a VM or disposable VM, you may want to open a document in another disposable VM. For this reason, the property `default_dispvm` may be set to the name of your disposable VM in a number of VMs:
[user@dom0 ~]$ qvm-prefs workvm | grep default_disp
default_dispvm - custom-dvm
This will prevent the deletion of the DVM. In order to fix this you need to unset the `default_disp` property:
[user@dom0 ~]$ qubes-prefs workvm default_disp ""
You can then delete the DVM:
[user@dom0 ~]$ qvm-remove custom-dvm
This will completely remove the selected VM(s)
custom-dvm
If you still encounter the issue, you may have forgot to clean an entry. Looking at the system logs will help you
[user@dom0 ~]$ journalctl | tail
Qubes 3.2
----------
### Changing the DVM Template ###
You may want to use a non-default template the [DVM Template](/doc/glossary/#dvm-template). One example is to use a less-trusted template with some less trusted, third-party, often unsigned, applications installed, such as e.g. third-party printer drivers.
In order to regenerate the Disposable VM "snapshot" (called 'savefile' on Qubes) one can use the following command in Dom0:
[user@dom0 ~]$ qvm-create-default-dvm <custom-template-name>
This would create a new Disposable VM savefile based on the custom template.
For example `<custom-template-name>` could be the name of the existing `debian-8` vm, which creates the disposable vm `debain-8-dvm`.
Now, whenever one opens a file (from any AppVM) in a Disposable VM, a Disposable VM based on this template will be used.
One can easily verify if the new Disposable VM template is indeed based on a custom template (in the example below the template called "f17-yellow" was used as a basis for the Disposable VM):
[user@dom0 ~]$ ll /var/lib/qubes/dvmdata/
total 0
lrwxrwxrwx 1 user user 45 Mar 11 13:59 default_dvm.conf -> /var/lib/qubes/appvms/f17-yellow-dvm/dvm.conf
lrwxrwxrwx 1 user user 49 Mar 11 13:59 default_savefile -> /var/lib/qubes/appvms/f17-yellow-dvm/dvm-savefile
lrwxrwxrwx 1 user user 47 Mar 11 13:59 savefile_root -> /var/lib/qubes/vm-templates/f17-yellow/root.img
If you wish to use the `fedora-minimal` template as a DVM Template, see the "DVM Template" use case under [fedora-minimal customization](/doc/templates/fedora-minimal/#customization).
### Customization of Disposable VM ###
It is possible to change the settings of each new Disposable VM (DispVM). This can be done by customizing the DispVM template:
1. Start a terminal in the `fedora-23-dvm` TemplateVM by running the following command in a dom0 terminal. (By default, this TemplateVM is not shown in Qubes VM Manager. However, it can be shown by selecting "Show/Hide internal VMs.")
[user@dom0 ~]$ qvm-run -a fedora-23-dvm gnome-terminal
2. Change the VM's settings and/or applications, as desired. Note that currently Qubes supports exactly one DispVM template, so any changes you make here will affect all DispVMs. Some examples of changes you may want to make include:
- Changing Firefox's default startup settings and homepage.
- Changing Nautilus' default file preview settings.
- Changing the DispVM's default NetVM. For example, you may wish to set the NetVM to "none." Then, whenever you start a new DispVM, you can choose your desired ProxyVM manually (by changing the newly-started DispVM's settings). This is useful if you sometimes wish to use a DispVM with a Whonix Gateway, for example. It is also useful if you sometimes wish to open untrusted files in a network-disconnected DispVM.
3. Create an empty `/home/user/.qubes-dispvm-customized` file in the VM (not in dom0):
[user@fedora-23-dvm ~]$ touch /home/user/.qubes-dispvm-customized
4. Shutdown the VM (either by `poweroff` from VM terminal, or `qvm-shutdown` from dom0 terminal).
5. Regenerate the DispVM template using the default template:
[user@dom0 ~]$ qvm-create-default-dvm --default-template
Or, if you're [using a non-default template](#changing-the-dvm-template), regenerate the DispVM using your custom template:
[user@dom0 ~]$ qvm-create-default-dvm <custom-template-name>
**Note:** All of the above requires at least qubes-core-vm \>= 2.1.2 installed in template.
### Adding arbitrary programs to Disposable VM Application Menu ###
For added convenience, arbitrary programs can be added to the Application Menu of the Disposable VM. In order to do that create (e.g.) `arbitrary.desktop` file in `/usr/local/share/applications` in Dom0. That file will point to the desired program. Use the following template for the file:
[Desktop Entry]
Version=1.0
Type=Application
Exec=sh -c 'echo arbitrary | /usr/lib/qubes/qfile-daemon-dvm qubes.VMShell dom0 DEFAULT red'
Icon=dispvm-red
Terminal=false
Name=DispVM: Arbitrary Name
GenericName=DispVM: Arbitrary Generic Name
StartupNotify=false
Categories=Network;X-Qubes-VM;
Next, the `/etc/xdg/menus/applications-merged/qubes-dispvm.menu` file has to be modified so that it points to the newly-created .desktop file. (If you use i3 you can skip this step; the shortcut gets added to dmenu automatically.)
Add a `<Filename>arbitrary.desktop</Filename>` line so that your modified file looks like this:
<Include>
<Filename>qubes-dispvm-firefox.desktop</Filename>
<Filename>qubes-dispvm-xterm.desktop</Filename>
<Filename>arbitrary.desktop</Filename>
</Include>
After saving the changes the new shortcut should appear in the Disposable VM Applications menu.

31
customization/i3.md
View File

@ -11,18 +11,25 @@ redirect_from:
# i3 installation in dom0
i3 is part of the testing repository (as of Qubes R3.1) and can be installed from there
using the dom0 update mechanism.
i3 is part of the stable repository (as of Qubes R3.1) and can be installed by
using the [dom0 update mechanism](/doc/software-update-dom0/). To install the i3
window manager and the its Qubes specific configuration:
$ sudo qubes-dom0-update --enablerepo=qubes-dom0-current-testing i3
$ sudo qubes-dom0-update i3 i3-settings-qubes
Qubes-specific configuation is available in a separate package and can be installed
optionally. Otherwise you can write your own configuration (see below).
$ sudo qubes-dom0-update --enablerepo=qubes-dom0-current-testing i3-settings-qubes
The Qubes-specific configuration (package `i3-settings-qubes`) can be installed
optionally in case you would prefer writing your own configuration (see
[customization](#customization) section for scripts and configuration).
That's it. After logging out, you can select i3 in the login manager.
### Customization
* [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)
## Compilation and installation from source
Note that the compilation from source is done in a Fedora based domU (could
@ -33,7 +40,7 @@ installed through the package manager.
Clone the i3-qubes repository here:
$ git clone https://github.com/SietsevanderMolen/i3-qubes.git
$ git clone https://github.com/QubesOS/qubes-desktop-linux-i3
In this case, the most interesting file is probably
`i3/0001-Show-qubes-domain-in-non-optional-colored-borders.patch` It's the patch
@ -47,7 +54,7 @@ it.
### Building
You'll need to install the build dependencies, which are listed in
build-deps.list. You can verify them and then install them with
build-deps.list. You can verify them and then install them with:
$ sudo dnf install -y $(cat build-deps.list)
@ -76,12 +83,8 @@ dependencies that we can easily install with:
rxvt-unicode xcb-util-wm perl-JSON-XS xcb-util-cursor \\
dzen2 dmenu xorg-x11-fonts-misc libev
After that you can just install the generated rpm like any other local package
After that you can just install the generated rpm like any other local package:
$ sudo yum localinstall i3.rpm
Log out, select i3, then log in again.
[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

12
customization/kde.md
View File

@ -40,6 +40,8 @@ You can also change your default login manager (lightdm) to the new KDE default:
* reboot
If you encounter performance issues with KDE, try switching back to LightDM.
Window Management
-----------------
@ -69,6 +71,16 @@ on.)
This can be useful for creating a simple shell script which will set up your
workspace the way you like.
Removal
------------
If you decide to remove KDE do **not** use `dnf remove @kde-desktop-qubes`. You will almost certainly break your system.
The safest way to remove (most of) KDE is:
~~~
sudo dnf remove kdelibs,plasma-workspace
~~~
Mailing List Threads
--------------------

25
customization/language-localization.md
View File

@ -14,28 +14,33 @@ Language Localization
How to set up pinyin input in Qubes
-----------------------------------
1. In the TemplateVM in which the AppVMs you would like to use pinyin input is based, please install `ibus-pinyin` via the package manager or terminal. If the template is Fedora-based, run `sudo dnf install ibus-pinyin`, if the template is Debian-based, run `sudo apt install ibus-pinyin`
The pinyin input method will be installed in a TemplateVM to make it available after restarts and across multiple AppVMs.
2. Close and shut down the TemplateVM.
1. In a TemplateVM, install `ibus-pinyin` via the package manager or terminal.
If the template is Fedora-based, run `sudo dnf install ibus-pinyin`.
If the template is Debian-based, run `sudo apt install ibus-pinyin`
3. Restart an AppVM which is based on the template you installed `ibus-pinyin` in, and open a terminal.
2. Shut down the TemplateVM.
4. Run `ibus-setup`
3. Start or restart an AppVM based on the template in which you installed `ibus-pinyin` and open a terminal.
5. You will likely get the error message telling you to paste the following into your bashrc:
4. Run `ibus-setup`.
5. You will likely get an error message telling you to paste the following into your bashrc:
export GTK_IM_MODULE=ibus
export XMODIFIERS=@im=ibus
export QT_IM_MODULE=ibus
Copy the text into your `~/.bashrc` file with your favorite text editor.
You will need to do this on any AppVM in which you wish to use pinyin input.
You will need to do this for any AppVM in which you wish to use pinyin input.
6. Set up ibus input as you like using the graphical menu (add pinyin or intelligent pinyin to selections). You can bring the menu back by issuing `ibus-setup` from a terminal.
6. Set up ibus input as you like using the graphical menu (add pinyin or intelligent pinyin to selections).
You can bring the menu back by issuing `ibus-setup` from a terminal.
7. Set up your shortcut for switching between inputs, by default it is super-space.
7. Set up your shortcut for switching between inputs.
By default it is super-space.
If ibus-pinyin is not enabled when you restart one of these AppVMs, open a terminal and run `ibus-setup` to activate ibus again.
If `ibus-pinyin` is not enabled when you restart one of these AppVMs, open a terminal and run `ibus-setup` to activate ibus again.
For further discussion, see [this qubes-users thread](https://groups.google.com/forum/#!searchin/qubes-users/languge/qubes-users/VcNPlhdgVQM/iF9PqSzayacJ).

93
customization/removing-templatevm-packages.md Normal file
View File

@ -0,0 +1,93 @@
---
layout: doc
title: Removing TemplateVM Packages
permalink: /doc/removing-templatevm-packages/
---
# Removing TemplateVM Packages
When removing any packages from a default TemplateVM, be sure to check what's being removed by `apt autoremove` or `dnf`.
When removing certain packages, for instance Thunderbird, `apt` and `dnf` will attempt to remove many packages required by qubes for the template to function correctly under qubes.
As an example from a terminal in a TemplateVM:
```shell_session
$ sudo apt remove thunderbird
Reading package lists... Done
Building dependency tree
Reading state information... Done
The following packages were automatically installed and are no longer required:
debugedit libjs-sphinxdoc libjs-underscore librpm3 librpmbuild3 librpmio3
librpmsign3 libsqlite0 linux-headers-4.9.0-6-amd64
linux-headers-4.9.0-6-common linux-image-4.9.0-6-amd64 python-backports-abc
python-cffi-backend python-concurrent.futures python-croniter
python-cryptography python-dateutil python-enum34 python-idna
python-iniparse python-ipaddress python-jinja2 python-libxml2 python-lzma
python-markupsafe python-msgpack python-openssl python-pyasn1 python-pycurl
python-requests python-rpm python-singledispatch python-six python-sqlite
python-sqlitecachec python-tornado python-tz python-urlgrabber
python-urllib3 python-xpyb python-yaml qubes-core-agent-dom0-updates
qubes-core-agent-passwordless-root qubes-gpg-split qubes-img-converter
qubes-input-proxy-sender qubes-mgmt-salt-vm-connector qubes-pdf-converter
qubes-usb-proxy rpm rpm-common rpm2cpio salt-common salt-ssh usbutils yum
yum-utils
Use 'sudo apt autoremove' to remove them.
The following packages will be REMOVED:
icedove lightning qubes-thunderbird qubes-vm-recommended thunderbird
0 upgraded, 0 newly installed, 5 to remove and 0 not upgraded.
After this operation, 151 MB disk space will be freed.
Do you want to continue? [Y/n]
```
Note all of the qubes packages are tracked as dependencies that will no longer be required. `apt remove` will only remove the packages listed, which is ok.
If, however you also run `apt autoremove` the other qubes packages necessary for TemplateVMs will be removed.
If you'd still like to remove one of these applications without breaking your TemplateVM you have a couple different options.
## Removing Only Packages Not Needed for a Qubes TemplateVM
### Debian
1. In your TemplateVM terminal run:
```shell_session $ apt remove package-name```
Note the packages "no longer required"
2. If the list of "no longer required" packages includes anything beginning with `qubes-` or `salt-` make a note to yourself to **never** run `$ sudo apt autoremove` on this TemplateVM
**Recommended but optional:** Use `apt-mark` to make `apt autoremove` safe again.
```shell_session
$ sudo apt mark-manual package-name package-name
```
Replace package-names with actual `qubes-*` and `salt-*` packages you'd like to retain.
For example, still in your TemplateVM terminal:
```shell_session
$ sudo apt-mark manual qubes-core-agent-dom0-updates qubes-core-agent-passwordless-root qubes-gpg-split qubes-img-converter qubes-input-proxy-sender qubes-mgmt-salt-vm-connector qubes-pdf-converter salt-common salt-ssh qubes-usb-proxy
```
`$ apt autoremove` should now be safe to use.
### Fedora
In your TemplateVM terminal, run:
```shell_session
$ dnf remove --noautoremove package-name
```
## Recovering A TemplateVM which you've already removed needed qubes-* packages
If you've already removed packages, run `apt autoremove` and restarted your VM you've lost passwordless sudo access.
You can login as root, open a terminal in dom0 and run:
```shell_session
$ qvm-run -u root vmname xterm
```
This will open an xterm terminal in the TemplateVM named `vmname`
Once you're logged in as root, reinstall these packages & their dependencies:
### Debian
```shell_session
$ sudo apt install qubes-core-agent-dom0-updates qubes-core-agent-passwordless-root qubes-gpg-split qubes-img-converter qubes-input-proxy-sender qubes-mgmt-salt-vm-connector qubes-pdf-converter salt-common salt-ssh
```
### Fedora
Similar to Debian for example (package names may vary):
```shell_session
$ sudo dnf install qubes-core-agent-dom0-updates qubes-core-agent-passwordless-root qubes-gpg-split qubes-img-converter qubes-input-proxy-sender qubes-mgmt-salt-vm-connector qubes-pdf-converter salt-common salt-ssh
```

24
debugging/automated-tests.md
View File

@ -21,7 +21,7 @@ Integration tests are written with the assumption that they will be called on de
**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.
Most of the tests are stored in the [core-admin repository](https://github.com/QubesOS/qubes-core-admin/tree/master/tests) in the `tests` directory.
Most of the tests are stored in the [core-admin repository](https://github.com/QubesOS/qubes-core-admin/tree/master/qubes/tests) in the `tests` directory.
To start them you can use standard python unittest runner:
python -m unittest -v qubes.tests
Or our custom one:
@ -99,6 +99,28 @@ 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:
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].
### Tests configuration
Test run can be altered using environment variables:
- `DEFAULT_LVM_POOL` - LVM thin pool to use for tests, in `VolumeGroup/ThinPool` format
- `QUBES_TEST_PCIDEV` - PCI device to be used in PCI passthrough tests (for example sound card)
- `QUBES_TEST_TEMPLATES` - space separated list of templates to run tests on; if not set, all installed templates are tested
- `QUBES_TEST_LOAD_ALL` - load all tests (including tests for all templates) when relevant test modules are imported; this needs to be set for test runners not supporting [load_tests protocol](https://docs.python.org/3/library/unittest.html#load-tests-protocol)
### Adding a new test to core-admin
After adding a new unit test to [core-admin/tests](https://github.com/QubesOS/qubes-core-admin/tree/master/tests) you'll have to make sure of two things:

9
debugging/vm-interface.md
View File

@ -80,14 +80,13 @@ update, so VM can setup a watch here to trigger rules reload.
retrieving them). The first rule has number `0000`.
Each rule is a single QubesDB entry, consisting of pairs `key=value` separated
by space. Order of those pairs in a single rule is undefined. QubesDB enforces
a limit on a single entry length - 3072 bytes.
by space. QubesDB enforces limit on a single entry length - 3072 bytes.
Possible options for a single rule:
- `action`, values: `accept`, `drop`; this is present in every rule
- `dst4`, value: destination IPv4 address with a mask; for example: `192.168.0.0/24`
- `dst6`, value: destination IPv6 address with a mask; for example: `2000::/3`
- `dstname`, value: DNS hostname of destination host
- `dsthost`, value: DNS hostname of destination host
- `proto`, values: `tcp`, `udp`, `icmp`
- `specialtarget`, value: One of predefined target, currently defined values:
- `dns` - such option should match DNS traffic to default DNS server (but
@ -101,8 +100,8 @@ Possible options for a single rule:
Options must appear in the rule in the order listed above. Duplicated options
are forbidden.
Rule matches only when all predicates matches. Only one of `dst4`, `dst6`,
`dstname`, `specialtarget` can be used in a single rule.
A rule matches only when all predicates match. Only one of `dst4`, `dst6` or
`dsthost` can be used in a single rule.
If tool applying firewall encounters any parse error (unknown option, invalid
value, duplicated option, etc), it should drop all the traffic coming from that `SOURCE_IP`,

21
doc.md
View File

@ -63,10 +63,10 @@ Common 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/)
* [Installing and Updating Software in dom0](/doc/software-update-dom0/)
* [Installing and Updating Software in VMs](/doc/software-update-vm/)
* [Backup, Restoration, and Migration](/doc/backup-restore/)
* [Using Disposable VMs](/doc/dispvm/)
* [Using Disposable VMs](/doc/disposablevm/)
* [Using and Managing USB Devices in R3.2](/doc/usb/)
* [Using Block or Storage Devices in Qubes R4.0](/doc/block-devices/)
* [Using USB Devices in Qubes R4.0](/doc/usb-devices)
@ -92,7 +92,7 @@ Managing Operating Systems within Qubes
* [Creating and Using HVM Domains](/doc/hvm/)
* [Tips for Using Linux in an HVM](/doc/linux-hvm-tips/)
* [Creating a NetBSD VM](/doc/netbsd/)
* [How to Reinstall a TemplateVM](/doc/reinstall-template)
* [How to Reinstall a TemplateVM](/doc/reinstall-template/)
Security Guides
@ -104,6 +104,7 @@ Security Guides
* [Installing Anti Evil Maid](/doc/anti-evil-maid/)
* [Using Multi-factor Authentication with Qubes](/doc/multifactor-authentication/)
* [Using GPG more securely in Qubes: Split GPG](/doc/split-gpg/)
* [The Qubes U2F Proxy](/doc/u2f-proxy/)
* [How to Set Up a Split Bitcoin Wallet in Qubes](/doc/split-bitcoin/)
* [[Unofficial] Split dm-crypt](https://github.com/rustybird/qubes-split-dm-crypt)
* [Configuring YubiKey for user authentication](/doc/yubi-key/)
@ -129,6 +130,8 @@ Configuration Guides
* [Multibooting](/doc/multiboot/)
* [Resize Disk Image](/doc/resize-disk-image/)
* [RPC Policies](/doc/rpc-policy/)
* [Changing your Time Zone](/doc/change-time-zone/)
* [GUI Configuration and Troubleshooting](/doc/gui-configuration/)
* [Installing ZFS in Qubes](/doc/zfs/)
* [Mutt Guide](/doc/mutt/)
* [Postfix Guide](/doc/postfix/)
@ -151,8 +154,8 @@ Configuration Guides
Customization Guides
--------------------
* [DispVM Customization](/doc/dispvm-customization/)
* [Customizing Fedora minimal templates](/doc/fedora-minimal-template-customization)
* [Customizing Windows 7 templates](/doc/windows-template-customization)
* [Customizing Fedora minimal templates](/doc/fedora-minimal-template-customization/)
* [Customizing Windows 7 templates](/doc/windows-template-customization/)
* [Using KDE in dom0](/doc/kde/)
* [Installing XFCE in dom0](/doc/xfce/)
* [Installing i3 in dom0](/doc/i3/)
@ -160,11 +163,13 @@ Customization Guides
* [Language Localization](/doc/language-localization/)
* [Dark Theme in Dom0 and DomU](/doc/dark-theme/)
* [How to make any file in a TemplateBasedVM persistent using bind-dirs](/doc/bind-dirs/)
* [Safely Removing TemplateVM Packages (Example: Thunderbird)](/doc/removing-templatevm-packages/)
Troubleshooting
---------------
* [Home directory is out of disk space error](/doc/out-of-memory/)
* [Newer hardware doesn't work](/doc/newer-hardware-troubleshooting/)
* [Installing on system with new AMD GPU (missing firmware problem)](https://groups.google.com/group/qubes-devel/browse_thread/thread/e27a57b0eda62f76)
* [How to install an Nvidia driver in dom0](/doc/install-nvidia-driver/)
* [Nvidia troubleshooting guide](/doc/nvidia-troubleshooting/)
@ -235,7 +240,7 @@ System
------
* [Qubes OS Architecture Overview](/doc/architecture/)
* [Qubes OS Architecture Spec v0.3 [PDF]](/attachment/wiki/QubesArchitecture/arch-spec-0.3.pdf)
* [Security-critical elements of Qubes OS](/doc/security-critical-code/)
* [Security-critical Code in Qubes OS](/doc/security-critical-code/)
* [Qubes Core Admin](https://dev.qubes-os.org/projects/core-admin/en/latest/)
* [Qubes Core Admin Client](https://dev.qubes-os.org/projects/core-admin-client/en/latest/)
* [Qubes Admin API](/news/2017/06/27/qubes-admin-api/)
@ -251,7 +256,7 @@ Services
* [Inter-domain file copying](/doc/qfilecopy/) (deprecates [`qfileexchgd`](/doc/qfileexchgd/))
* [Dynamic memory management in Qubes](/doc/qmemman/)
* [Implementation of DisposableVMs](/doc/dvm-impl/)
* [Article about disposable VMs](http://theinvisiblethings.blogspot.com/2010/06/disposable-vms.html)
* [Article about DisposableVMs](http://theinvisiblethings.blogspot.com/2010/06/disposable-vms.html)
* [Dom0 secure update mechanism](/doc/dom0-secure-updates/)
Debugging

7
hardware/system-requirements.md
View File

@ -3,6 +3,7 @@ layout: doc
title: System Requirements
permalink: /doc/system-requirements/
redirect_from:
- /system-requirements/
- /en/doc/system-requirements/
- /doc/SystemRequirements/
- /wiki/SystemRequirements/
@ -32,7 +33,8 @@ redirect_from:
* Fast SSD (strongly recommended)
* Intel IGP (strongly preferred)
* Nvidia GPUs may require significant [troubleshooting][nvidia].
* ATI GPUs have not been formally tested (but see the [Hardware Compatibility List]).
* AMD GPUs have not been formally tested, but Radeons (RX580 and earlier) generally work well
* See the [Hardware Compatibility List]
* [Intel VT-x] or [AMD-V] (required for running HVM domains, such as Windows-based AppVMs)
* [Intel VT-d] or [AMD-Vi (aka AMD IOMMU)] (required for effective isolation of network VMs)
* TPM with proper BIOS support (required for [Anti Evil Maid])
@ -52,7 +54,8 @@ redirect_from:
* Fast SSD (strongly recommended)
* Intel IGP (strongly preferred)
* Nvidia GPUs may require significant [troubleshooting][nvidia].
* ATI GPUs have not been formally tested (but see the [Hardware Compatibility List]).
* AMD GPUs have not been formally tested, but Radeons (RX580 and earlier) generally work well
* See the [Hardware Compatibility List]
* TPM with proper BIOS support (required for [Anti Evil Maid])
* A non-USB keyboard or multiple USB controllers
* Also consider the [hardware certification requirements for Qubes 4.x].

44
installing/installation-guide.md
View File

@ -19,16 +19,48 @@ redirect_from:
Installation Guide
==================
Warning
-------
Qubes 3.2 Warning
-----------------
There is a set of known upstream bugs in the Fedora installer that affect Qubes 3.2 ([Bug 1170803], [Bug 1374983], and [Bug 1268700]; tracked in Qubes issue [#2835]).
This issue is fixed in Qubes 4.0.
On Qubes 3.2, because of these bugs, the installer will try to access all existing disk partitions, run fsck on them, and mount them.
Because of these bugs, the installer will try to access all existing disk partitions, run fsck on them, and mount them.
Therefore, we *strongly* recommended that, prior to starting the Qubes installer, you physically disconnect all disks that you do not want to be modified.
Furthermore, if you are installing Qubes on a potentially compromised system, we *strongly* recommended that you wipe your target installation disk before starting the installer.
Qubes 4.0 Warning
-----------------
In new installations of Qubes 4.0, the following steps may need to be applied in dom0 and Fedora 26 TemplateVMs in order to receive updates (see [#3737]).
Steps for dom0 updates:
1. Open the Qubes Menu by clicking on the "Q" icon in the top-left corner of the screen.
2. Select `Terminal Emulator`.
3. In the window that opens, enter this command:
sudo nano /etc/yum.repos.d/qubes-dom0.repo
4. This opens the nano text editor. Change all four instances of `http` to `https`.
5. Press `CTRL+X`, then `Y`, then `ENTER` to save changes and exit.
6. Check for updates normally.
Steps for Fedora 26 TemplateVM updates:
1. Open the Qubes Menu by clicking on the "Q" icon in the top-left corner of the screen.
2. Select `Template: fedora-26`, then `fedora-26: Terminal`.
3. In the window that opens, enter the command for your version:
[Qubes 3.2] sudo gedit /etc/yum.repos.d/qubes-r3.repo
[Qubes 4.0] sudo gedit /etc/yum.repos.d/qubes-r4.repo
4. This opens the gedit text editor in a window. Change all four instances of `http` to `https`.
5. Click the "Save" button in the top-right corner of the window.
6. Close the window.
7. Check for updates normally.
8. Shut down the TemplateVM.
Hardware Requirements
---------------------
@ -54,6 +86,7 @@ how to download and verify our PGP keys and verify the downloaded ISO.
**Note:** The Qubes R4.0 ISO is large, so if you are using R3.2 to download it you may need to [increase the private storage](/doc/resize-disk-image/#expand-disk-image-r32) available to the AppVM.
Copying the ISO onto the installation medium
--------------------------------------------
@ -65,7 +98,7 @@ 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=1M && sync
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`).
@ -135,6 +168,7 @@ Getting Help
[Bug 1374983]: https://bugzilla.redhat.com/show_bug.cgi?id=1374983
[Bug 1268700]: https://bugzilla.redhat.com/show_bug.cgi?id=1268700
[#2835]: https://github.com/QubesOS/qubes-issues/issues/2835
[#3737]: https://github.com/QubesOS/qubes-issues/issues/3737
[system requirements]: /doc/system-requirements/
[Hardware Compatibility List]: /hcl/
[live USB]: /doc/live-usb/

58
installing/supported-versions.md
View File

@ -14,29 +14,36 @@ 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 Version | Start Date | End Date | Status |
| ---------------- | ---------- | ---------- | ----------------------- |
| 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 | TBA | Old, [extended support] |
| Release 3.2.1 | TBA | 2019-03-28 | In development |
| Release 3.2 | 2016-09-29 | 2019-03-28 | Old, [extended support] |
| Release 4.0 | 2018-03-28 | TBA | Current, supported |
| Release 4.1 | TBA | TBA | In development |
### 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 Version | Dom0 OS |
| ---------------- | --------- |
| 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 3.2.1 | Fedora 23 |
| Release 4.0 | Fedora 25 |
### Note on dom0 and EOL ###
@ -49,29 +56,46 @@ 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 and Debian TemplateVMs are officially supported.
release. Currently, only Fedora, Debian, and Whonix TemplateVMs are officially supported.
| Qubes OS Version | Fedora Versions | Debian Versions |
| ---------------- | -------------------- | --------------------------------------------- |
| Release 1 | 18, 20 | None |
| Release 2 | 21 | None |
| Release 3.0 | 21, 22\*, 23 | 7 ("wheezy")\*, 8 ("jessie") |
| Release 3.1 | 21, 22\*, 23 | 7 ("wheezy")\*, 8 ("jessie"), 9 ("stretch")\* |
| Release 3.2 | 23\*, 24\*, 25, 26 | 8 ("jessie"), 9 ("stretch") |
| Release 3.2.1 | 26 | 8 ("jessie"), 9 ("stretch") |
| Release 4.0 | 26 | 8 ("jessie"), 9 ("stretch") |
| 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
[Whonix]: /doc/whonix/

2
installing/upgrade/upgrade-to-r4.0.md
View File

@ -100,5 +100,5 @@ Please see [Supported Versions](/doc/supported-versions/) for information on sup
* [Upgrading Fedora TemplateVMs](/doc/templates/fedora/#upgrading)
* [Upgrading Debian TemplateVMs](/doc/templates/debian/#upgrading)
* [Updating Whonix TemplateVMs](/doc/whonix/update/)
* [Updating Whonix TemplateVMs](https://www.whonix.org/wiki/Qubes/Update)

346
managing-os/hvm.md
View File

@ -10,38 +10,40 @@ redirect_from:
---
Creating and using HVM (fully virtualized) domains
=============================================================
==================================================
What are HVM domains?
---------------------
HVM domains (Hardware VM), in contrast to PV domains (Paravirtualized domains), allow one to create domains based on any OS for which one has an installation ISO. For example, this allows one to have Windows-based VMs in Qubes.
Interested readers might want to check
[this article](https://blog.invisiblethings.org/2012/03/03/windows-support-coming-to-qubes.html)
to learn why it took so long for Qubes OS to support HVM domains
(Qubes 1 only supported Linux based PV domains). As of
Qubes 4, every VM is PVH by default, except those with attached PCI devices which are HVM.
[See here](https://blog.invisiblethings.org/2017/07/31/qubes-40-rc1.html) for a discussion
of the switch to HVM from R3.2's PV, and [here](/news/2018/01/11/qsb-37/)
for changing the default to PVH.
Interested readers might want to check [this article](https://blog.invisiblethings.org/2012/03/03/windows-support-coming-to-qubes.html) to learn why it took so long for Qubes OS to support HVM domains (Qubes 1 only supported Linux based PV domains). As of Qubes 4, every VM is PVH by default, except those with attached PCI devices which are HVM. [See here](https://blog.invisiblethings.org/2017/07/31/qubes-40-rc1.html) for a discussion of the switch to HVM from R3.2's PV, and [here](/news/2018/01/11/qsb-37/) for changing the default to PVH.
Creating an HVM domain
----------------------
First, let's create a new HVM domain. Use the `--hvm` switch to `qvm-create`, or choose HVM type in the Qubes Manager VM creation dialog box:
### R3.2 ###
With a GUI: in Qubes Manager VM creation dialog box choose the "Standalone qube not based on a template" type.
If "install system from device" is selected (which is by default), then `virt_mode` will be set to `hvm` automatically.
Otherwise, open the newly created VM's Qube Settings GUI and in the "Advanced" tab select "HVM" in the virtualization mode drop-down list.
Command line (the VM's name and label color are for illustration purposes):
~~~
qvm-create win7 --hvm --label green
qvm-create my-new-vm --hvm --label green
~~~
The name of the domain ("win7") as well as its label ("green") are just exemplary of course.
### R4.0 ###
**Note:** To create a StandaloneVM in Qubes R4, use the --class option, as VMs are template-based by default
With a GUI: in Qubes Manager VM creation dialog box choose the "Standalone qube not based on a template" type.
If "install system from device" is selected (which is by default), then `virt_mode` will be set to `hvm` automatically.
Otherwise, open the newly created VM's Qube Settings GUI and in the "Advanced" tab select `HVM` in the virtualization mode drop-down list.
Also, make sure "Kernel" is set to `(none)` on the same tab.
Command line (name and label color are for illustration purposes.
VMs are template-based by default so the `--class StandaloneVM` option is needed to create a StandaloneVM):
~~~
qvm-create win7 --class StandaloneVM --property virt_mode=hvm --property kernel="" --property memory=4096 --property maxmem=4096 --property debug=True --label green
qvm-features win7 video-model cirrus
qvm-create my-new-vm --class StandaloneVM --property virt_mode=hvm --property kernel='' --label=green
~~~
If you receive an error like this one, then you must first enable VT-x in your BIOS:
@ -50,45 +52,165 @@ If you receive an error like this one, then you must first enable VT-x in your B
libvirt.libvirtError: invalid argument: could not find capabilities for arch=x86_64
~~~
Now we need to install an OS inside this VM. This can be done by attaching an installation ISO to and starting the VM (this can currently only be done from command line, but in the future we will surely add an option to do this also from the manager):
Installing an OS in an HVM domain
---------------------------------
You will have to boot the VM with the installation media "attached" to it. You may either use the GUI or command line instructions. That can be accomplished in three ways:
1. If you have the physical cdrom media and a disk drive
~~~
qvm-start my-new-vm --cdrom=/dev/cdrom
~~~
2. If you have an ISO image of the installation media located in dom0
~~~
qvm-start my-new-vm --cdrom=dom0:/usr/local/iso/installcd.iso
~~~
3. If you have an ISO image of the installation media located in a VM (obviously the VM where the media is located must be running)
~~~
qvm-start my-new-vm --cdrom=someVM:/home/user/installcd.iso
~~~
For security reasons you should *never* copy untrusted data to dom0. Qubes doesn't provide any easy to use mechanism for copying files between VMs and Dom0 anyway and generally tries to discourage such actions.
Next, the VM will start booting from the attached installation media. Depending on the OS being installed in the VM, one might be required to start the VM several times (as is the case with Windows 7 installations) because whenever the installer wants to "reboot the system" it actually shuts down the VM and Qubes won't automatically start it. Several invocations of `qvm-start` command (as shown above) might be needed.
Setting up networking for HVM domains
-------------------------------------
Just like standard paravirtualized AppVMs, the HVM domains get fixed IP addresses centrally assigned by Qubes. Normally Qubes agent scripts (or services on Windows) running within each AppVM are responsible for setting up networking within the VM according the configuration created by Qubes (through [keys](/doc/vm-interface/#qubesdb) exposed by dom0 to the VM). Such centrally managed networking infrastructure allows for [advanced networking configuration](https://blog.invisiblethings.org/2011/09/28/playing-with-qubes-networking-for-fun.html).
A generic HVM domain such as a standard Windows or Ubuntu installation, however, has no Qubes agent scripts running inside it initially and thus requires manual networking configuration so that it match the values assigned by Qubes for this domain.
Even though we do have a small DHCP server that runs inside HVM untrusted stub domain to make the manual network configuration not necessary for many VMs, this won't work for most modern Linux distributions which contain Xen networking PV drivers (but not Qubes tools) built in which bypass the stub-domain networking (their net frontends connect directly to the net backend in the netvm). In this instance our DHCP server is not useful.
In order to manually configure networking in a VM, one should first find out the IP/netmask/gateway assigned to the particular VM by Qubes. This can be seen e.g. in the Qubes Manager in the VM's properties:
![r2b1-manager-networking-config.png](/attachment/wiki/HvmCreate/r2b1-manager-networking-config.png)
Alternatively, one can use the `qvm-ls -n` command to obtain the same information and configure the networking within the HVM according to those settings (IP/netmask/gateway).
DNS servers: in R3.2 the DNS addresses are the same as the gateway's IP. In R4.0, the DNS ips are `10.139.1.1` and `10.139.1.2`.
Qubes R3.2 only supports IPv4. Qubes R4.0 has [opt-in support](https://www.qubes-os.org/doc/networking/#ipv6) for IPv6 forwarding.
Using Template-based HVM domains
--------------------------------
Please see our dedicated page on [installing and using Windows-based AppVMs](/doc/windows-appvms/).
Cloning HVM domains
-------------------
Just like normal AppVMs, the HVM domains can also be cloned either using a command-line `qvm-clone` command or via manager's 'Clone VM' option in the right-click menu.
The cloned VM will get identical root and private images and will essentially be identical to the original VM except that it will get a different MAC address for the networking interface:
~~~
qvm-start win7 --cdrom=DispVM:/home/user/win7.iso
or
qvm-start win7 --cdrom=dom0:/usr/local/iso/win7_en.iso
[joanna@dom0 ~]$ qvm-prefs my-new-vm
name : my-new-vm
label : green
type : HVM
netvm : firewallvm
updateable? : True
installed by RPM? : False
include in backups: False
dir : /var/lib/qubes/appvms/my-new-vm
config : /var/lib/qubes/appvms/my-new-vm/my-new-vm.conf
pcidevs : []
root img : /var/lib/qubes/appvms/my-new-vm/root.img
private img : /var/lib/qubes/appvms/my-new-vm/private.img
vcpus : 4
memory : 512
maxmem : 512
MAC : 00:16:3E:5E:6C:05 (auto)
debug : off
default user : user
qrexec_installed : False
qrexec timeout : 60
drive : None
timezone : localtime
[joanna@dom0 ~]$ qvm-clone my-new-vm my-new-vm-copy
/.../
[joanna@dom0 ~]$ qvm-prefs my-new-vm-copy
name : my-new-vm-copy
label : green
type : HVM
netvm : firewallvm
updateable? : True
installed by RPM? : False
include in backups: False
dir : /var/lib/qubes/appvms/my-new-vm-copy
config : /var/lib/qubes/appvms/my-new-vm-copy/my-new-vm-copy.conf
pcidevs : []
root img : /var/lib/qubes/appvms/my-new-vm-copy/root.img
private img : /var/lib/qubes/appvms/my-new-vm-copy/private.img
vcpus : 4
memory : 512
maxmem : 512
MAC : 00:16:3E:5E:6C:01 (auto)
debug : off
default user : user
qrexec_installed : False
qrexec timeout : 60
drive : None
timezone : localtime
~~~
The above first command assumes the installation ISO was transferred to a DispVM (copied using `dd` command from an installation CDROM for example). The second is for when the iso is in Dom0, which is not recommended. If one wishes to use the actual physical media without copying it first to a file, then one can just pass `/dev/cdrom` as an argument to `--cdrom`:
Note how the MAC addresses differ between those two otherwise identical VMs. The IP addresses assigned by Qubes will also be different of course to allow networking to function properly:
~~~
qvm-start win7 --cdrom=/dev/cdrom
[joanna@dom0 ~]$ qvm-ls -n
/.../
my-new-vm-copy | | Halted | Yes | | *firewallvm | green | 10.137.2.3 | n/a | 10.137.2.1 |
my-new-vm | | Halted | Yes | | *firewallvm | green | 10.137.2.7 | n/a | 10.137.2.1 |
/.../
~~~
Next, the VM will start booting from the attached CDROM device (which in the example above just happens to be a Windows 7 installation disk). Depending on the OS being installed in the VM, one might be required to start the VM several times (as is the case with Windows 7 installations), because whenever the installer wants to "reboot the system" it actually shuts down the VM and Qubes won't automatically start it. Several invocations of qvm-start command (as shown above) might be needed.
**Note:** If your Windows installation gets stuck at the glowing Windows logo, you might want to read [Issue 2488](https://github.com/QubesOS/qubes-issues/issues/2488) for a solution.
[![r2b1-win7-installing.png](/attachment/wiki/HvmCreate/r2b1-win7-installing.png)](/attachment/wiki/HvmCreate/r2b1-win7-installing.png)
Using Installation ISOs located in other VMs
--------------------------------------------
Sometimes one wants to download the installation ISO from the Web and use it for HVM creation. For security reasons, networking is disabled for Qubes Dom0, which makes it impossible to download an ISO within Dom0. Qubes also does not provide any easy to use mechanisms for copying files between AppVMs and Dom0 and generally tries to discourage such actions. Due to these factors it would be inconvenient to require that the installation ISO for an HVM domain be always located in Dom0. The good news, however, is that this is indeed not required. One can use the following syntax when specifying the location of an installation ISO (such as the Windows 7 installation ISO):
If for any reason one would like to make sure that the two VMs have the same MAC address, one can use qvm-prefs to set a fixed MAC address for the VM:
~~~
--cdrom=[appvm]:[/path/to/iso/within/appvm]
[joanna@dom0 ~]$ qvm-prefs my-new-vm-copy -s mac 00:16:3E:5E:6C:05
[joanna@dom0 ~]$ qvm-prefs my-new-vm-copy
name : my-new-vm-copy
label : green
type : HVM
netvm : firewallvm
updateable? : True
installed by RPM? : False
include in backups: False
dir : /var/lib/qubes/appvms/my-new-vm-copy
config : /var/lib/qubes/appvms/my-new-vm-copy/my-new-vm-copy.conf
pcidevs : []
root img : /var/lib/qubes/appvms/my-new-vm-copy/root.img
private img : /var/lib/qubes/appvms/my-new-vm-copy/private.img
vcpus : 4
memory : 512
maxmem : 512
MAC : 00:16:3E:5E:6C:05
debug : off
default user : user
qrexec_installed : False
qrexec timeout : 60
drive : None
timezone : localtime
~~~
Assuming that an installation ISO named `ubuntu-12.10-desktop-i386.iso` has been downloaded in `work-web` AppVM and is located within the `/home/user/Downloads` directory within this AppVM, one can immediately create a new HVM using this ISO as an installation media with the following command issued in Dom0:
Installing Qubes support tools in Windows 7 VMs
-----------------------------------------------
~~~
qvm-create --hvm ubuntu --label red
qvm-start ubuntu --cdrom=work-web:/home/user/Downloads/ubuntu-12.10-desktop-i386.iso
~~~
Windows specific steps are described on [separate page](/doc/windows-appvms/).
The AppVM where the ISO is kept must be running for this to work as this VM is now serving the ISO and acting as a disk backend.
Assigning PCI devices to HVM domains
------------------------------------
![r2b1-installing-ubuntu-1.png](/attachment/wiki/HvmCreate/r2b1-installing-ubuntu-1.png)
HVM domains (including Windows VMs) can be [assigned PCI devices](/doc/assigning-devices/) just like normal AppVMs. E.g. one can assign one of the USB controllers to the Windows VM and should be able to use various devices that require Windows software, such as phones, electronic devices that are configured via FTDI, etc.
One problem at the moment however, is that after the whole system gets suspended into S3 sleep and subsequently resumed, some attached devices may stop working and should be restarted within the VM. This can be achieved under a Windows HVM by opening the Device Manager, selecting the actual device (such as a USB controller), 'Disabling' the device, and then 'Enabling' the device again. This is illustrated on the screenshot below:
![r2b1-win7-usb-disable.png](/attachment/wiki/HvmCreate/r2b1-win7-usb-disable.png)
Converting VirtualBox VM to HVM
-------------------------------
@ -121,16 +243,16 @@ Convert vmdk to raw:
qemu-img convert -O raw *.vmdk win10.raw
~~~
Create new HVM in Dom0, with amount of RAM in MB you wish:
Copy the root image file to a temporary location in Dom0:
~~~
qvm-create --hvm win10 --label red --mem=4096
qvm-run --pass-io untrusted 'cat "/media/user/externalhd/win10.raw"' > /home/user/win10-root.img
~~~
Copy file to Dom0:
Create a new HVM in Dom0 with the root image we just copied to Dom0 (change the amount of RAM in GB as you wish):
~~~
qvm-run --pass-io untrusted 'cat "/media/user/externalhd/win10.raw"' > /var/lib/qubes/appvms/win10/root.img
qvm-create --hvm win10 --label red --mem=4096 --root-move-from /home/user/win10-root.img
~~~
Start win10 VM:
@ -159,147 +281,11 @@ List filetypes supported by qemu-img:
qemu-img -h | tail -n1
~~~
Setting up networking for HVM domains
-------------------------------------
Just like standard paravirtualized AppVMs, the HVM domains get fixed IP addresses centrally assigned by Qubes. Normally Qubes agent scripts running within each AppVM are responsible for setting up networking within the VM according the configuration created by Qubes. Such centrally managed networking infrastructure allows for [advanced networking configuration](https://blog.invisiblethings.org/2011/09/28/playing-with-qubes-networking-for-fun.html).
A generic HVM domain such as a standard Windows or Ubuntu installation, however, has no Qubes agent scripts running inside it initially and thus requires manual networking configuration so that it match the values assigned by Qubes for this domain.
Even though we do have a small DHCP server that runs inside HVM untrusted stub domain to make the manual network configuration not necessary for many VMs, this won't work for most modern Linux distributions which contain Xen networking PV drivers (but not Qubes tools) built in which bypass the stub-domain networking (their net frontends connect directly to the net backend in the netvm). In this instance our DHCP server is not useful.
In order to manually configure networking in a VM, one should first find out the IP/netmask/gateway assigned to the particular VM by Qubes. This can be seen e.g. in the Qubes Manager in the VM's properties:
![r2b1-manager-networking-config.png](/attachment/wiki/HvmCreate/r2b1-manager-networking-config.png)
Alternatively, one can use `qvm-ls -n` command to obtain the same information. One should configure the networking within the HVM according to those settings (IP/netmask/gateway). One should set DNS addresses to the same IP as gateway.
Only IPv4 networking is currently supported in Qubes.
**Note:** If one plans on installing Qubes Tools for Windows guests (see below) it is 'not' necessary to configure networking manually as described in this section, because the tools will take care of setting the networking automatically for such Windows domains.
Using Template-based HVM domains
--------------------------------
Please see our dedicated page on [installing and using Windows-based AppVMs](/doc/windows-appvms/).
Cloning HVM domains
-------------------
Just like normal AppVMs, the HVM domains can also be cloned either using a command-line `qvm-clone` command or via manager's 'Clone VM' option in the right-click menu.
The cloned VM will get identical root and private images and will essentially be identical to the original VM except that it will get a different MAC address for the networking interface:
~~~
[joanna@dom0 ~]$ qvm-prefs win7
name : win7
label : green
type : HVM
netvm : firewallvm
updateable? : True
installed by RPM? : False
include in backups: False
dir : /var/lib/qubes/appvms/win7
config : /var/lib/qubes/appvms/win7/win7.conf
pcidevs : []
root img : /var/lib/qubes/appvms/win7/root.img
private img : /var/lib/qubes/appvms/win7/private.img
vcpus : 4
memory : 512
maxmem : 512
MAC : 00:16:3E:5E:6C:05 (auto)
debug : off
default user : user
qrexec_installed : False
qrexec timeout : 60
drive : None
timezone : localtime
[joanna@dom0 ~]$ qvm-clone win7 win7-copy
/.../
[joanna@dom0 ~]$ qvm-prefs win7-copy
name : win7-copy
label : green
type : HVM
netvm : firewallvm
updateable? : True
installed by RPM? : False
include in backups: False
dir : /var/lib/qubes/appvms/win7-copy
config : /var/lib/qubes/appvms/win7-copy/win7-copy.conf
pcidevs : []
root img : /var/lib/qubes/appvms/win7-copy/root.img
private img : /var/lib/qubes/appvms/win7-copy/private.img
vcpus : 4
memory : 512
maxmem : 512
MAC : 00:16:3E:5E:6C:01 (auto)
debug : off
default user : user
qrexec_installed : False
qrexec timeout : 60
drive : None
timezone : localtime
~~~
Note how the MAC addresses differ between those two otherwise identical VMs. The IP addresses assigned by Qubes will also be different of course to allow networking to function properly:
~~~
[joanna@dom0 ~]$ qvm-ls -n
/.../
win7-copy | | Halted | Yes | | *firewallvm | green | 10.137.2.3 | n/a | 10.137.2.1 |
win7 | | Halted | Yes | | *firewallvm | green | 10.137.2.7 | n/a | 10.137.2.1 |
/.../
~~~
If for any reason one would like to make sure that the two VMs have the same MAC address, one can use qvm-prefs to set a fixed MAC address for the VM:
~~~
[joanna@dom0 ~]$ qvm-prefs win7-copy -s mac 00:16:3E:5E:6C:05
[joanna@dom0 ~]$ qvm-prefs win7-copy
name : win7-copy
label : green
type : HVM
netvm : firewallvm
updateable? : True
installed by RPM? : False
include in backups: False
dir : /var/lib/qubes/appvms/win7-copy
config : /var/lib/qubes/appvms/win7-copy/win7-copy.conf
pcidevs : []
root img : /var/lib/qubes/appvms/win7-copy/root.img
private img : /var/lib/qubes/appvms/win7-copy/private.img
vcpus : 4
memory : 512
maxmem : 512
MAC : 00:16:3E:5E:6C:05
debug : off
default user : user
qrexec_installed : False
qrexec timeout : 60
drive : None
timezone : localtime
~~~
Installing Qubes support tools in Windows 7 VMs
-----------------------------------------------
Windows specific steps are described on [separate page](/doc/windows-appvms/).
Assigning PCI devices to HVM domains
------------------------------------
HVM domains (including Windows VMs) can be [assigned PCI devices](/doc/assigning-devices/) just like normal AppVMs. E.g. one can assign one of the USB controllers to the Windows VM and should be able to use various devices that require Windows software, such as phones, electronic devices that are configured via FTDI, etc.
One problem at the moment however, is that after the whole system gets suspended into S3 sleep and subsequently resumed, some attached devices may stop working and should be restarted within the VM. This can be achieved under a Windows HVM by opening the Device Manager, selecting the actual device (such as a USB controller), 'Disabling' the device, and then 'Enabling' the device again. This is illustrated on the screenshot below:
[![r2b1-win7-usb-disable.png](/attachment/wiki/HvmCreate/r2b1-win7-usb-disable.png)](/attachment/wiki/HvmCreate/r2b1-win7-usb-disable.png)
Further reading
---------------
Other documents related to HVM:
- [Windows VMs](/doc/windows-vm/)
- [LinuxHVMTips](/doc/linux-hvm-tips/)

473
managing-os/pentesting/kali.md
View File

@ -6,16 +6,22 @@ redirect_from:
- /doc/kali/
---
**General reminder:**
# How to create a Kali Linux VM
## Warnings
- The installation scripts and provided tools may have bugs, be vulnerable to Man in the Middle (MitM) attacks or other vulnerabilities.
- Adding additional repositories or tools for installing software extends your trust to those tool providers.
Please keep in mind that using such a VM or VM's based on the template for security and privacy critical tasks is not recommended.
- Please keep in mind that using such a VM or VM's based on the template for security and privacy critical tasks is not recommended.
How to Create a Kali Linux VM
=============================
- Kali Linux distribution is a rolling distribution based constantly on Debian testing release, so it always will have newer software base than available in Qubes OS debian template. Keep in mind that it may result in problems (especially in regard to package dependency) not covered by this tutorial.
## Qubes 3.2
### How to Create a Kali Linux VM
This guide is being created to give guidance on ways in which you could create a [Kali Linux][kali] penetration testing VM (qube) in Qubes OS.
@ -23,14 +29,12 @@ Kali Linux is the most widely used penetration testing Linux distribution.
There are multiple ways to create a Kali Linux VM:
1. Create a HVM and use the offical ISO to install the system or convert a [Virtual Image][kali-vbox]. Explained [here](#hvm).
2. Clone the Qubes OS Debian image and turn it into a Kali Linux distribution using [katoolin]. Explained [here](#katoolin).
3. Clone the Qubes OS 'jessie' Debian template, upgrade it to 'stretch'
(Debian 9.0) and turn it into a Kali linux template. Explained
[here](#templatevm-from-debian).
1. Create a HVM and use the offical ISO to install the system or convert a [Virtual Image][kali-vbox]. Explained [here](#hvm3_2).
2. Clone the Qubes OS latest Debian template image and turn it into a Kali Linux distribution:
- using [katoolin]. Explained [here](#katoolin3_2).
- manually. Explained [here](#templatevm-from-debian3_2).
Kali Linux HVM <a name="hvm"/>
--------------
### Kali Linux HVM <a name="hvm3_2"/>
1. Download the Kali installation DVD
@ -38,21 +42,26 @@ Kali Linux HVM <a name="hvm"/>
3. Start the HVM with attached CD/DVD
qvm-start <hvm-name> --cdrom <vm-name>:/home/user/Downloads/<iso-name>.iso
[user@dom0 ~]$ qvm-start <hvm-name> --cdrom <vm-name>:/home/user/Downloads/<iso-name>.iso
Debian based Kali Template with Katoolin <a name="katoolin"/>
----------------------------------------
### Debian based Kali Template with Katoolin <a name="katoolin3_2"/>
Katoolin is a script (written in Python) which helps you to install Kali tools.
**Note:** The prompt on each line indicates where each command should be entered (`@dom0`, `@debian-<X>` or `@kali`).
1. (Optional) Install `debian-8` template (if not already installed)
1. (Optional) Check for latest Debian stable template and install it (if not already done)
2. Update your `debian-8` template
[user@dom0 ~]$ sudo qubes-dom0-update --action="search all" qubes-template-debian
[user@dom0 ~]$ sudo qubes-dom0-update <latest Debian template>
sudo apt-get update
sudo apt-get dist-upgrade
2. Start, update and close your latest Debian template
3. Clone `debian-8` template (two options)
[user@dom0 ~]$ qvm-start debian-<X>
[user@dom0 ~]$ qvm-run -a debian-<X> gnome-terminal
[user@debian-<X> ~]$ sudo apt-get update
[user@debian-<X> ~]$ sudo apt-get upgrade
[user@dom0 ~]$ qvm-shutdown debian-<X>
3. Clone `debian-<X>` template (two options)
1. Via Qubes VM Manager
@ -60,31 +69,42 @@ Katoolin is a script (written in Python) which helps you to install Kali tools.
2. Via command line
qvm-clone debian-8 kali
[user@dom0 ~]$ qvm-clone debian-<X> kali
4. Start and upgrade the `kali` Template from Debian 8 to Debian 9
4. Check the name of currently used repository in `/etc/apt/sources.list` and current testing [Debian release][Debian-releases]. Update repository list accordingly
sudo sed -i 's/jessie/stretch/g' /etc/apt/sources.list
sudo sed -i 's/jessie/stretch/g' /etc/apt/sources.list.d/qubes-r3.list
sudo apt-get update
sudo apt-get dist-upgrade
sudo apt-get autoremove
[user@kali ~]$ sudo sed -i 's/<current stable>/<current testing>/g' /etc/apt/sources.list
[user@kali ~]$ sudo sed -i 's/<current stable>/<current testing>/g' /etc/apt/sources.list.d/qubes-r<X>.list
5. Install Katoolin and add Kali Linux repositories
e.g. in this example we update `stretch` stable repository to `buster` testing repository
[user@kali ~]$ sudo sed -i 's/stretch/buster/g' /etc/apt/sources.list
[user@kali ~]$ sudo sed -i 's/stretch/buster/g' /etc/apt/sources.list.d/qubes-r<X>.list
5. Upgrade `kali` template to latest Debian testing release
[user@kali ~]$ sudo apt-get update
[user@kali ~]$ sudo apt-get dist-upgrade
[user@kali ~]$ sudo apt-get autoremove
**Note:** During execution of a `dist-upgrade` command read carefully list of packages to be removed.
If it contains `qubes-*` packages, terminate operation and try to resolve `qubes-*` packages missing dependencies first.
6. Install Katoolin and add Kali Linux repositories
1. Install Katoolin
sudo apt-get install git
git clone https://github.com/LionSec/katoolin.git
sudo cp katoolin/katoolin.py /usr/bin/katoolin
sudo chmod +x /usr/bin/katoolin
rm -rf katoolin
[user@kali ~]$ sudo apt-get install git
[user@kali ~]$ git clone https://github.com/LionSec/katoolin.git
[user@kali ~]$ sudo cp katoolin/katoolin.py /usr/bin/katoolin
[user@kali ~]$ sudo chmod +x /usr/bin/katoolin
[user@kali ~]$ rm -rf katoolin
2. Add Kali Linux repositories
- start katoolin
sudo katoolin
[user@kali ~]$ sudo katoolin
- select 'Add Kali repositories & Update'
@ -123,30 +143,34 @@ Katoolin is a script (written in Python) which helps you to install Kali tools.
What do you want to do ?> ^CShutdown requested...Goodbye...
6. Clean up and update `kali` template
7. Clean up and update `kali` template
sudo apt-get dist-upgrade
sudo apt-get autoremove
[user@kali ~]$ sudo apt-get dist-upgrade
[user@kali ~]$ sudo apt-get autoremove
7. Shutdown and trim `kali` template
8. Shutdown and trim `kali` template
- Shutdown `kali` template
sudo shutdown -h now
[user@kali ~]$ sudo shutdown -h now
- In `dom0` console:
qvm-trim-template kali
[user@dom0 ~]$ qvm-trim-template kali
8. Start image
9. Start image
9. Install tools
[user@dom0 ~]$ qvm-start kali
10. Install tools
**Note** [Resize the template disk image][qubes-resize-disk-image] to at least 20GB if you plan on installing all packages from Kali distribution.
1. View Categories
- start katoolin
sudo katoolin
[user@kali ~]$ sudo katoolin
- select `2) View Categories`
@ -156,29 +180,26 @@ Katoolin is a script (written in Python) which helps you to install Kali tools.
- **Note:** The `all` option does not work for `Information Gathering`, `Web Apps`, `Forensic Tools`, `Reverse Engineering` and `Extra`.
10. Create a AppVMs based on the `kali` template
11. Create a AppVMs based on the `kali` template
- (Optional) Attach necessary devices
Kali Linux TemplateVM from a Debian template <a name="debian-upgrade"/><a name="templatevm-from-debian"/>
--------------------------------------------
### Kali Linux TemplateVM from a Debian template <a name="templatevm-from-debian3_2"/>
This section will explain how to create your own [Kali] Linux TemplateVM based
on a Debian 9.0 (Stretch) TemplateVM. The basic idea is to personalize the
on a current stable Debian TemplateVM. The basic idea is to personalize the
template with all the tools needed, and then spin up isolated AppVMs based on
the template.
This has been tested on Qubes OS 3.2.
The steps can be summarised as:
1. Install Qubes' Debian 8.0 (Jessie) template
2. Upgrade the template to Debian 9.0 (Stretch)
1. Install Qubes stable Debian template
2. Upgrade the template to Debian testing release
3. Install Kali Linux through the ``kali-linux-full`` package
4. Use the template to build AppVM so that you can maintain isolation between
e.g. pentesting jobs
### Get Kali Linux GPG key ###
#### Get Kali Linux GPG key
**CAUTION:** Before proceeding, please carefully read [On Digital Signatures and Key Verification][qubes-verifying-signatures].
This website cannot guarantee that any PGP key you download from the Internet is authentic.
@ -188,11 +209,14 @@ This step is required since by (security) default a TemplateVM do not have a
direct Internet connectivity. Users understanding the risks of enabling such
access can change this configuration in firewall settings for the TemplateVM.
**Note:** The prompt on each line indicates where each command should be entered
(`@dom0`, `@kali-rolling`, `@xxxx-dvm` or `@debian-<X>`).
1. Retrive the Kali Linux GPG key using a DispVM.
[user@xxxx-dvm ~]$ gpg --keyserver hkp://keys.gnupg.net --recv-key 7D8D0BF6
[user@xxxx-dvm ~]$ gpg --list-keys --with-fingerprint 7D8D0BF6
[user@xxxx-dvm ~]$ gpg --export --armor 7D8D0BF6 > kali-key.asc
[user@xxxx-dvm ~]$ gpg --keyserver hkp://keys.gnupg.net --recv-key 44C6513A8E4FB3D30875F758ED444FF07D8D0BF6
[user@xxxx-dvm ~]$ gpg --list-keys --with-fingerprint 44C6513A8E4FB3D30875F758ED444FF07D8D0BF6
[user@xxxx-dvm ~]$ gpg --export --armor 44C6513A8E4FB3D30875F758ED444FF07D8D0BF6 > kali-key.asc
2. **DO NOT TURN OFF** the DispVM, the `kali-key.asc` file will be copied to
the Kali Linux template in a further step.
@ -200,35 +224,58 @@ access can change this configuration in firewall settings for the TemplateVM.
3. Make sure the key is the authentic Kali key.
See the [Kali website] for further advice and instructions on verification.
### Create a Kali Linux (rolling) template ###
#### Create a Kali Linux (rolling) template
These instructions will show you how to upgrade a Debian 9 TemplateVM to Kali Linux.
These instructions will show you how to upgrade a Debian TemplateVM to Kali Linux.
**Note:** The prompt on each line indicates where each command should be entered
(`@dom0`, `@kali-rolling` or `@xxxx-dvm`).
1. (Optional) Check for latest Debian stable template and install it (if not already done)
1. Ensure the base template is not running.
[user@dom0 ~]$ sudo qubes-dom0-update --action="search all" qubes-template-debian
[user@dom0 ~]$ sudo qubes-dom0-update <latest Debian template>
[user@dom0 ~]$ qvm-shutdown debian-9
2. Start, update and close your latest Debian template
2. Clone the base template and start a terminal in the new template.
[user@dom0 ~]$ qvm-start debian-<X>
[user@dom0 ~]$ qvm-run -a debian-<X> gnome-terminal
[user@debian-<X> ~]$ sudo apt-get update
[user@debian-<X> ~]$ sudo apt-get upgrade
[user@dom0 ~]$ qvm-shutdown debian-<X>
[user@dom0 ~]$ qvm-clone debian-9 kali-rolling
[user@dom0 ~]$ qvm-run -a kali-rolling gnome-terminal
3. Clone `debian-X` template
3. Copy the Kali GPG key from the DispVM to the new template:
[user@dom0 ~]$ qvm-clone debian-<X> kali-rolling
4. Check the name of currently used repository in `/etc/apt/sources.list` and current testing [Debian release][Debian-releases]. Update repository list accordingly
[user@kali-rolling ~]$ sudo sed -i 's/<current stable>/<current testing>/g' /etc/apt/sources.list
[user@kali-rolling ~]$ sudo sed -i 's/<current stable>/<current testing>/g' /etc/apt/sources.list.d/qubes-r<X>.list
e.g. in this example we update `stretch` stable repository to `buster` testing repository
[user@kali-rolling ~]$ sudo sed -i 's/stretch/buster/g' /etc/apt/sources.list
[user@kali-rolling ~]$ sudo sed -i 's/stretch/buster/g' /etc/apt/sources.list.d/qubes-r<X>.list
5. Upgrade `kali-rolling` template to latest Debian testing release
[user@kali-rolling ~]$ sudo apt-get update
[user@kali-rolling ~]$ sudo apt-get dist-upgrade
[user@kali-rolling ~]$ sudo apt-get autoremove
**Note:** During execution of a `dist-upgrade` command read carefully list of packages to be removed. If it contains `qubes-*` packages, terminate operation and try to resolve `qubes-*` packages missing dependencies first.
6. Copy the Kali GPG key from the DispVM to the new template:
[user@xxxx-dvm ~]$ qvm-copy-to-vm kali-rolling kali-key.asc
The DispVM can now be turned off.
4. Add the Kali GPG key to the list of keys trusted to authenticate packages:
7. Add the Kali GPG key to the list of keys trusted to authenticate packages:
[user@kali-rolling ~]$ cat /home/user/QubesIncoming/dispXXX/kali-key.asc | sudo apt-key add -
This command should return `OK` on a line by itself.
5. Attempt the upgrade process in the new template.
8. Attempt the upgrade process in the new template.
[user@kali-rolling ~]$ sudo cat <<EOF > /etc/apt/sources.list.d/kali.list
# Kali Linux repository
@ -238,20 +285,20 @@ These instructions will show you how to upgrade a Debian 9 TemplateVM to Kali Li
[user@kali-rolling ~]$ sudo apt-get dist-upgrade
[user@kali-rolling ~]$ sudo apt-get autoremove
6. Shut down and trim the new template.
9. Shut down and trim the new template.
[user@dom0 ~]$ qvm-shutdown kali-rolling
[user@dom0 ~]$ qvm-trim-template kali-rolling
7. Ensure a terminal can be opened in the new template.
10. Ensure a terminal can be opened in the new template.
[user@dom0 ~]$ qvm-run -a kali-rolling gnome-terminal
### Install the Kali tools ###
#### Install the Kali tools
At this point you should have a working template and you can install the tools you need.
1. [resize the template disk image][qubes-resize-disk-image] if you plan on installing the full Kali distribution. For example to install `kali-linux-full` you must **grow** the size of the VM system from 10GB to at least 20GB.
1. [Resize the template disk image][qubes-resize-disk-image] if you plan on installing the full Kali distribution. For example to install `kali-linux-full` you must **grow** the size of the VM system from 10GB to at least 20GB.
2. Install Kali Linux tools:
@ -259,22 +306,293 @@ At this point you should have a working template and you can install the tools y
3. (Optional) Customise the template's home directory (e.g. install your licensed copy of Burp Suite Professional)
### Use the template ###
#### Use the template
The template is ready to be used. You can now spin up AppVMs based on the `kali-rolling` template.
## Qubes 4.0
Alternative Options to Kali Linux
---------------------------------
### How to Create a Kali Linux VM
This guide is being created to give guidance on ways in which you could create a [Kali Linux][kali] penetration testing VM (qube) in Qubes OS.
Kali Linux is the most widely used penetration testing Linux distribution.
There are multiple ways to create a Kali Linux VM:
1. Create a HVM and use the offical ISO to install the system or convert a [Virtual Image][kali-vbox]. Explained [here](#hvm4_0).
2. Clone the Qubes OS latest Debian template image and turn it into a Kali Linux distribution:
- using [katoolin]. Explained [here](#katoolin4_0).
- manually. Explained [here](#templatevm-from-debian4_0).
### Kali Linux HVM <a name="hvm4_0"/>
1. Download the Kali installation DVD
2. Create a new HVM
3. Start the HVM with attached CD/DVD
[user@dom0 ~]$ qvm-start <hvm-name> --cdrom <vm-name>:/home/user/Downloads/<iso-name>.iso
### Debian based Kali Template with Katoolin <a name="katoolin4_0"/>
**Note:** The prompt on each line indicates where each command should be entered (`@dom0`, `@debian-<X>` or `@kali`).
1. (Optional) Check for latest Debian stable template and install it (if not already done)
[user@dom0 ~]$ sudo qubes-dom0-update --action="search all" qubes-template-debian
[user@dom0 ~]$ sudo qubes-dom0-update <latest Debian template>
2. Start, update and close your latest Debian template
[user@dom0 ~]$ qvm-start debian-<X>
[user@dom0 ~]$ qvm-run -a debian-<X> gnome-terminal
[user@debian-<X> ~]$ sudo apt-get update
[user@debian-<X> ~]$ sudo apt-get upgrade
[user@dom0 ~]$ qvm-shutdown debian-<X>
3. Clone `debian-<X>` template (two options)
1. Via Qubes VM Manager
![Clone Debian Template](/attachment/wiki/Kali/clone-kali.png)
2. Via command line
[user@dom0 ~]$ qvm-clone debian-<X> kali
4. Check the name of currently used repository in `/etc/apt/sources.list` and current testing [Debian release][Debian-releases]. Update repository list accordingly.
[user@kali ~]$ sudo sed -i 's/<current stable>/<current testing>/g' /etc/apt/sources.list
[user@kali ~]$ sudo sed -i 's/<current stable>/<current testing>/g' /etc/apt/sources.list.d/qubes-r<X>.list
e.g. in this example we update `stretch` stable repository to `buster` testing repository
[user@kali ~]$ sudo sed -i 's/stretch/buster/g' /etc/apt/sources.list
[user@kali ~]$ sudo sed -i 's/stretch/buster/g' /etc/apt/sources.list.d/qubes-r<X>.list
5. Upgrade `kali` template to latest Debian testing release
[user@kali ~]$ sudo apt-get update
[user@kali ~]$ sudo apt-get dist-upgrade
[user@kali ~]$ sudo apt-get autoremove
**Note:** During execution of a `dist-upgrade` command read carefully list of packages to be removed.
If it contains `qubes-*` packages, terminate operation and try to resolve `qubes-*` packages missing dependencies first.
6. Install Katoolin and add Kali Linux repositories
1. Install Katoolin
[user@kali ~]$ sudo apt-get install git
[user@kali ~]$ git clone https://github.com/LionSec/katoolin.git
[user@kali ~]$ sudo cp katoolin/katoolin.py /usr/bin/katoolin
[user@kali ~]$ sudo chmod +x /usr/bin/katoolin
[user@kali ~]$ rm -rf katoolin
2. Add Kali Linux repositories
- start katoolin
[user@kali ~]$ sudo katoolin
- select 'Add Kali repositories & Update'
1) Add Kali repositories & Update
2) View Categories
3) Install classicmenu indicator
4) Install Kali menu
5) Help
kat > 1
![Add Kali repositories and Update menu](/attachment/wiki/Kali/katoolin-add-update-repo-menu.png)
- select 'Add kali linux repositories'
1) Add kali linux repositories
2) Update
3) Remove all kali linux repositories
4) View the contents of sources.list file
What do you want to do ?> 1
![Add Kali repositories](/attachment/wiki/Kali/katoolin-add-repos-menu.png)
- update Kali repositories
1) Add kali linux repositories
2) Update
3) Remove all kali linux repositories
4) View the contents of sources.list file
What do you want to do ?> 2
- quit katoolin by pressing `CRTL` + `c` keys
What do you want to do ?> ^CShutdown requested...Goodbye...
7. Clean up and update `kali` template
[user@kali ~]$ sudo apt-get dist-upgrade
[user@kali ~]$ sudo apt-get autoremove
8. Install tools
**Note** [Resize the template disk image][qubes-resize-disk-image] to at least 20GB if you plan on installing all packages from Kali distribution.
1. View Categories
- start katoolin
[user@kali ~]$ sudo katoolin
- select `2) View Categories`
2. Select the categories/tools you want to install
- For more information on how to use Katoolin see [How to Auto Install All Kali Linux Tools Using “Katoolin” on Debian/Ubuntu][katoolin-howto].
- **Note:** The `all` option does not work for `Information Gathering`, `Web Apps`, `Forensic Tools`, `Reverse Engineering` and `Extra`.
9. Create a AppVMs based on the `kali` template
- (Optional) Attach necessary devices
### Kali Linux TemplateVM from a Debian template <a name="templatevm-from-debian4_0"/>
This section will explain how to create your own [Kali] Linux TemplateVM based
on a current stable Debian TemplateVM. The basic idea is to personalize the
template with all the tools needed, and then spin up isolated AppVMs based on
the template.
The steps can be summarised as:
1. Install Qubes stable Debian template
2. Upgrade the template to Debian testing release
3. Install Kali Linux through the ``kali-linux-full`` package
4. Use the template to build AppVM so that you can maintain isolation between
e.g. pentesting jobs
#### Get Kali Linux GPG key
**CAUTION:** Before proceeding, please carefully read [On Digital Signatures and Key Verification][qubes-verifying-signatures].
This website cannot guarantee that any PGP key you download from the Internet is authentic.
Always obtain a trusted key fingerprint via other channels, and always check any key you download against your trusted copy of the fingerprint.
This step is required since by (security) default a TemplateVM do not have a
direct Internet connectivity. Users understanding the risks of enabling such
access can change this configuration in firewall settings for the TemplateVM.
**Note:** The prompt on each line indicates where each command should be entered
(`@dom0`, `@kali-rolling`, `@xxxx-dvm` or `@debian-<X>`).
1. Retrive the Kali Linux GPG key using a DispVM.
[user@xxxx-dvm ~]$ gpg --keyserver hkp://keys.gnupg.net --recv-key 44C6513A8E4FB3D30875F758ED444FF07D8D0BF6
[user@xxxx-dvm ~]$ gpg --list-keys --with-fingerprint 44C6513A8E4FB3D30875F758ED444FF07D8D0BF6
[user@xxxx-dvm ~]$ gpg --export --armor 44C6513A8E4FB3D30875F758ED444FF07D8D0BF6 > kali-key.asc
2. **DO NOT TURN OFF** the DispVM, the `kali-key.asc` file will be copied to
the Kali Linux template in a further step.
3. Make sure the key is the authentic Kali key.
See the [Kali website] for further advice and instructions on verification.
#### Create a Kali Linux (rolling) template
These instructions will show you how to upgrade a Debian TemplateVM to Kali Linux.
1. (Optional) Check for latest Debian stable template and install it (if not already done)
[user@dom0 ~]$ sudo qubes-dom0-update --action="search all" qubes-template-debian
[user@dom0 ~]$ sudo qubes-dom0-update <latest Debian template>
2. Start, update and close your latest Debian template
[user@dom0 ~]$ qvm-start debian-<X>
[user@dom0 ~]$ qvm-run -a debian-<X> gnome-terminal
[user@debian-<X> ~]$ sudo apt-get update
[user@debian-<X> ~]$ sudo apt-get upgrade
[user@dom0 ~]$ qvm-shutdown debian-<X>
3. Clone `debian-X` template
[user@dom0 ~]$ qvm-clone debian-<X> kali-rolling
4. Check the name of currently used repository in `/etc/apt/sources.list` and current testing [Debian release][Debian-releases]. Update repository list accordingly
[user@kali-rolling ~]$ sudo sed -i 's/<current stable>/<current testing>/g' /etc/apt/sources.list
[user@kali-rolling ~]$ sudo sed -i 's/<current stable>/<current testing>/g' /etc/apt/sources.list.d/qubes-r<X>.list
e.g. in this example we update `stretch` stable repository to `buster` testing repository
[user@kali-rolling ~]$ sudo sed -i 's/stretch/buster/g' /etc/apt/sources.list
[user@kali-rolling ~]$ sudo sed -i 's/stretch/buster/g' /etc/apt/sources.list.d/qubes-r<X>.list
5. Upgrade `kali-rolling` template to latest Debian testing release
[user@kali-rolling ~]$ sudo apt-get update
[user@kali-rolling ~]$ sudo apt-get dist-upgrade
[user@kali-rolling ~]$ sudo apt-get autoremove
**Note:** During execution of a `dist-upgrade` command read carefully list of packages to be removed. If it contains `qubes-*` packages, terminate operation and try to resolve `qubes-*` packages missing dependencies first.
6. Copy the Kali GPG key from the DispVM to the new template:
[user@xxxx-dvm ~]$ qvm-copy kali-key.asc
The DispVM can now be turned off.
7. Add the Kali GPG key to the list of keys trusted to authenticate packages:
[user@kali-rolling ~]$ cat /home/user/QubesIncoming/dispXXX/kali-key.asc | sudo apt-key add -
This command should return `OK` on a line by itself.
8. Attempt the upgrade process in the new template.
[user@kali-rolling ~]$ sudo cat <<EOF > /etc/apt/sources.list.d/kali.list
# Kali Linux repository
deb http://http.kali.org/kali kali-rolling main non-free contrib
EOF
[user@kali-rolling ~]$ sudo apt-get update
[user@kali-rolling ~]$ sudo apt-get dist-upgrade
[user@kali-rolling ~]$ sudo apt-get autoremove
9. Ensure a terminal can be opened in the new template.
[user@dom0 ~]$ qvm-run -a kali-rolling gnome-terminal
#### Install the Kali tools
At this point you should have a working template and you can install the tools you need.
1. [Resize the template disk image][qubes-resize-disk-image] if you plan on installing the full Kali distribution. For example to install `kali-linux-full` you must **grow** the size of the VM system from 10GB to at least 20GB.
2. Install Kali Linux tools:
[user@kali-rolling ~]$ sudo apt-get install kali-linux-full
3. (Optional) Customise the template's home directory (e.g. install your licensed copy of Burp Suite Professional)
#### Use the template
The template is ready to be used. You can now spin up AppVMs based on the `kali-rolling` template.
### Alternative Options to Kali Linux
* [PenTester Framework][PTF], with [PTF Qubes OS guide][qubes-ptf]
* BlackArch Linux, with [BA Qubes OS guide][qubes-blackarch]
* [KATOOLIN][katoolin-howto]
* more on the [Penetration Testing page][qubes-pentesting]
Notes
-----
## Notes
Thanks to the people in [the discussion thread](https://github.com/QubesOS/qubes-issues/issues/1981).
@ -293,3 +611,6 @@ Thanks to the people in [the discussion thread](https://github.com/QubesOS/qubes
[katoolin]: https://github.com/LionSec/katoolin
[katoolin-howto]: http://www.tecmint.com/install-kali-linux-tools-using-katoolin-on-ubuntu-debian/
[Debian-releases]: https://www.debian.org/releases/

88
managing-os/templates.md
View File

@ -3,6 +3,7 @@ layout: doc
title: Templates
permalink: /doc/templates/
redirect_from:
- /doc/template/
- /en/doc/templates/
- /doc/Templates/
- /wiki/Templates/
@ -18,10 +19,80 @@ There are also templates available with or without certain software preinstalled
The concept of TemplateVMs is initially described [here](/getting-started/#appvms-qubes-and-templatevms).
The technical details of this implementation are described in the developer documentation [here](/doc/template-implementation/).
Some templates are available in ready-to-use binary form, but some of them are available only as source code, which can be built using the [Qubes Builder](/doc/qubes-builder/). In particular, some template "flavors" are available in source code form only. Take a look at the [Qubes Builder documentation](/doc/qubes-builder/) for instructions on how to compile them.
Some templates are available in ready-to-use binary form, but some of them are available only as source code, which can be built using the [Qubes Builder](/doc/qubes-builder/).
In particular, some template "flavors" are available in source code form only.
Take a look at the [Qubes Builder documentation](/doc/qubes-builder/) for instructions on how to compile them.
How to install, uninstall, reinstall, and switch
------------------------------------------------
### How to install
Please refer to each TemplateVM's installation instructions below.
Usually, the installation method is to execute the following type of command in dom0:
$ sudo qubes-dom0-update qubes-template-<name>
(where `qubes-template-<name>` is the name of your TemplateVM package)
### How to uninstall
To uninstall a TemplateVM, execute the following type of command in dom0:
$ sudo dnf remove qubes-template-<name>
(where `qubes-template-<name>` is the name of your TemplateVM package)
If this doesn't work, you can [remove it manually](/doc/remove-vm-manually/).
### How to reinstall
To reinstall a currently installed TemplateVM, see [here](/doc/reinstall-template/).
### How to switch templates (3.2)
When you install a new template or upgrade a clone of a template, it is recommended that you switch everything that was set to the old template to the new template:
1. Make the new template the default template:
Qubes Manager --> Global settings --> Default template
2. Base AppVMs on the new template.
In Qubes Manager, for each VM that is currently based on `old-template` that you would like to base on `new-template`, enter its VM settings and change the Template selection:
Qubes Manager --> (Select a VM) --> VM settings --> Template
3. Base the [DVM Template](/doc/glossary/#dvm-template) on the new template.
If you have set the new template as your default template:
[user@dom0 ~]$ qvm-create-default-dvm --default-template
Otherwise:
[user@dom0 ~]$ qvm-create-default-dvm new-template
### How to switch templates (4.0)
When you install a new template or upgrade a clone of a template, it is recommended that you switch everything that was set to the old template to the new template:
1. Make the new template the default template:
Applications Menu --> System Tools --> Qubes Global Settings --> Default template
2. Base AppVMs on the new template.
In Qubes Manager, for each VM that is currently based on `old-template` that you would like to base on `new-template`, enter its VM settings and change the Template selection:
Applications Menu --> (select a VM) --> VM settings --> Template
3. Base the [DVM Template](/doc/glossary/#dvm-template) on the new template.
[user@dom0 ~]$ qvm-create -l red -t new-template new-template-dvm
[user@dom0 ~]$ qvm-prefs new-template-dvm template_for_dispvms True
[user@dom0 ~]$ qvm-features new-template-dvm appmenus-dispvm 1
[user@dom0 ~]$ qubes-prefs default-dispvm new-template-dvm
Invisible Things Lab (ITL) Supported templates
-----------------------
@ -55,11 +126,18 @@ Important Notes (R4.0)
subsequent changes to the parent TemplateVM's `/home` will not affect
the child TemplateBasedVM's `/home`.
* Template VMs are created in a thin pool, making `qvm-trim-template`
no longer necessary.
* `qvm-trim-template` is not necessary. All VMs are created in a thin pool
and trimming is handled automatically. No user action is required.
The root filesystems in Standalone VMs can employ
TRIM/discard on the root fs using normal tools and configuration options.
| | Inheritance (1) | Persistence (2)
|--------------------|-----------------------------------------------------------|------------------------------------------
|TemplateVM | n/a | Everything
|TemplateBasedVM (3) | `/etc/skel` to `/home`, `/usr/local.orig` to `/usr/local` | `/rw` (includes `/home`, `/usr/local` and `bind-dirs`)
|DisposableVM | `/rw` (includes `/home`, `/usr/local` and `bind-dirs`) | Nothing
(1) Upon creation
(2) Following shutdown
(3) Including [DVM Templates](/doc/disposablevm/#disposablevms-and-networking-r40-and-later)
Important Notes (R3.2 and earlier)
---------------

18
managing-os/templates/debian.md
View File

@ -25,6 +25,10 @@ can also obtain the key from [git
repository](https://github.com/QubesOS/qubes-core-agent-linux/blob/master/misc/qubes-archive-keyring.gpg),
which is also integrity-protected using signed git tags.
If you want a debian-minimal template, this can be built using [Qubes-builder](https://www.qubes-os.org/doc/qubes-builder/),by selecting a +minimal flavour in setup, and then
make qubes-vm && make template
Installing
----------
@ -40,22 +44,8 @@ Debian 8 (jessie) - oldstable:
Debian 9 (stretch) - stable:
In Qubes 4.0 -
[user@dom0 ~]$ sudo qubes-dom0-update qubes-template-debian-9
A prebuilt template is not available in Qubes 3.2, but there are two options for
achieving a stretch template:
1. Build an experimental stretch template from source.
2. Clone a `debian-8` template and then modify in the cloned template `/etc/apt/sources.list` and `/etc/apt/sources.list.d/qubes-r3.list` to pull from stretch repos rather than jessie repos.
Simply replace all instances of "jessie" with "stretch".
After that, an `apt-get dist-upgrade` followed by a reboot should "just work".
Unused packages will have to be removed or else it will conflict with the upgrade.
Full instructions are on [this page][stretch]
Upgrading
---------

5
managing-os/templates/debian/upgrade-8-to-9.md
View File

@ -74,7 +74,10 @@ any template based on the standard Debian 8 template.
[user@dom0 ~]$ qvm-trim-template debian-9
8. (Optional) Remove the old default template.
8. (Recommended) [Switch everything that was set to the old template to the new
template.](/doc/templates/#how-to-switch-templates-32)
9. (Optional) Remove the old default template.
[user@dom0 ~]$ sudo yum remove qubes-template-debian-8

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

@ -21,7 +21,7 @@ Installation
The Fedora minimal template can be installed with the following command:
~~~
[user@dom0 ~]$ sudo qubes-dom0-update qubes-template-fedora-26-minimal
[user@dom0 ~]$ sudo qubes-dom0-update qubes-template-fedora-27-minimal
~~~
The download may take a while depending on your connection speed.
@ -32,7 +32,7 @@ Duplication and first steps
It is highly recommended to clone the original template, and make any changes in the clone instead of the original template. The following command clones the template. Replace `your-new-clone` with your desired name.
~~~
[user@dom0 ~]$ qvm-clone fedora-26-minimal your-new-clone
[user@dom0 ~]$ qvm-clone fedora-27-minimal your-new-clone
~~~
You must start the template in order to customize it.
@ -49,6 +49,8 @@ As expected, the required packages are to be installed in the running template w
[user@your-new-clone ~]$ sudo dnf install packages
~~~
### Package table for Qubes 3.2
Use case | Description | Required steps
--- | --- | ---
**Standard utilities** | If you need the commonly used utilities | Install the following packages: `pciutils` `vim-minimal` `less` `psmisc` `gnome-keyring`
@ -60,26 +62,55 @@ Use case | Description | Required steps
**VPN** | You can use this template as basis for a [VPN](/doc/vpn/) qube | Use the `dnf search "NetworkManager VPN plugin"` command to look up the VPN packages you need, based on the VPN technology you'll be using, and install them. Some GNOME related packages may be needed as well. After creation of a machine based on this template, follow the [VPN howto](/doc/vpn/#set-up-a-proxyvm-as-a-vpn-gateway-using-networkmanager) to configure it.
**DVM Template** | If you want to use this VM as a [DVM Template](/doc/glossary/#dvm-template) | Install `perl-Encode`
### Package table for Qubes 4.0
Use case | Description | Required steps
--- | --- | ---
**Standard utilities** | If you need the commonly used utilities | Install the following packages: `pciutils` `vim-minimal` `less` `psmisc` `gnome-keyring`
**Audio** | If you want sound from your VM... | Install `pulseaudio-qubes`
**FirewallVM** | You can use the minimal template as a [FirewallVM](/doc/firewall/), such as the basis template for `sys-firewall` | Install at least `qubes-core-agent-networking`, and also `qubes-core-agent-dom0-updates` if you want to use it as the updatevm (which is normally sys-firewall).
**NetVM** | You can use this template as the basis for a NetVM such as `sys-net` | Install the following packages: `qubes-core-agent-networking` `qubes-core-agent-network-manager` `NetworkManager-wifi` `network-manager-applet` `wireless-tools` `dejavu-sans-fonts` `notification-daemon` `gnome-keyring` `polkit` `@hardware-support`.
**NetVM (extra firmware)** | If your network devices need extra packages for the template to work as a network VM | Use the `lspci` command to identify the devices, then run `dnf search firmware` (replace `firmware` with the appropriate device identifier) to find the needed packages and then install them.
**Network utilities** | If you need utilities for debugging and analyzing network connections | Install the following packages: `tcpdump` `telnet` `nmap` `nmap-ncat`
**USB** | If you want USB input forwarding to use this template as the basis for a [USB](/doc/usb/) qube such as `sys-usb` | Install `qubes-input-proxy-sender`
**VPN** | You can use this template as basis for a [VPN](/doc/vpn/) qube | Use the `dnf search "NetworkManager VPN plugin"` command to look up the VPN packages you need, based on the VPN technology you'll be using, and install them. Some GNOME related packages may be needed as well. After creation of a machine based on this template, follow the [VPN howto](/doc/vpn/#set-up-a-proxyvm-as-a-vpn-gateway-using-networkmanager) to configure it.
A comprehensive guide to customizing the minimal template is available [here][GUIDE]
Qubes 4.0
---------
In Qubes R4.0, sudo is not installed by default in the minimal template. To update or install packages to it, from a dom0 terminal window:
In Qubes R4.0 the minimal template is not configured for passwordless root. To update or install packages to it, from a dom0 terminal window:
~~~
[user@dom0 ~]$ qvm-run -u root fedora-26-minimal xterm
[user@dom0 ~]$ qvm-run -u root fedora-27-minimal xterm
~~~
to open a root terminal in the template, from which you can use dnf without sudo. You will have to do this every time if you choose not to enable passwordless root.
If you want the usual qubes `sudo dnf ...` commands, open the root terminal just this once using the above command, and in the root xterm window enter
~~~
bash-4.4# dnf install qubes-core-agent-passwordless-root polkit
~~~
Optionally check this worked: from the gui open the minimal template's xterm and give the command
~~~
[user@fed-min-clone ~]$ sudo -l
~~~
which should give you output that includes the NOPASSWD keyword.
In Qubes 4.0, additional packages from the `qubes-core-agent` suite may be needed to make the customized minimal template work properly. These packages are:
- `qubes-core-agent-qrexec`: Qubes qrexec agent. Installed by default.
- `qubes-core-agent-systemd`: Qubes unit files for SystemD init style. Installed by default.
- `qubes-core-agent-passwordless-root`, `polkit`: By default the 'fedora-26-minimal' template doesn't have passwordless root. These two packages fix the situation.
- `qubes-core-agent-passwordless-root`, `polkit`: By default the 'fedora-27-minimal' template doesn't have passwordless root. These two packages enable this feature. (Note from R4.0 a design choice was made that passwordless should be optional, so is left out of the minimal templates)
- `qubes-core-agent-nautilus`: This package provides integration with the Nautilus file manager (without it things like "copy to VM/open in disposable VM" will not be shown in Nautilus).
- `qubes-core-agent-sysvinit`: Qubes unit files for SysV init style or upstart.
- `qubes-core-agent-networking`: Networking support. Required if the template is to be used for a `sys-net` or `sys-firewall` VM.
- `qubes-core-agent-networking`: Networking support. Required for general network access and particularly if the template is to be used for a `sys-net` or `sys-firewall` VM.
- `qubes-core-agent-network-manager`: Integration for NetworkManager. Useful if the template is to be used for a `sys-net` VM.
- `network-manager-applet`: Useful (together with `dejavu-sans-fonts` and `notification-daemon`) to have a system tray icon if the template is to be used for a `sys-net` VM.
- `qubes-core-agent-dom0-updates`: Script required to handle `dom0` updates. Any template which the VM responsible for 'dom0' updates (e.g. `sys-firewall`) is based on must contain this package.

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

@ -17,16 +17,16 @@ Installing
The Fedora TemplateVM comes preinstalled with Qubes OS.
However, there may be times when you wish to install a fresh copy from the Qubes repositories, e.g.:
1. When a version of Fedora reaches EOL ([end-of-life]).
2. When a new version of Fedora you wish to use becomes [supported] as a TemplateVM.
3. When you suspect your Fedora TemplateVM has been compromised.
4. When you have made modifications to the Fedora TemplateVM that you no longer want.
* When a version of Fedora reaches EOL ([end-of-life]).
* When a new version of Fedora you wish to use becomes [supported] as a TemplateVM.
* When you suspect your Fedora TemplateVM has been compromised.
* When you have made modifications to the Fedora TemplateVM that you no longer want.
To install a specific Fedora TemplateVM that is not currently installed in your system, use the following command in dom0:
$ sudo qubes-dom0-update qubes-template-fedora-26
$ sudo qubes-dom0-update qubes-template-fedora-XX
(If necessary, replace `26` with your desired Fedora version.)
(Replace `XX` with the Fedora version number of the template you wish to install.)
To reinstall a Fedora TemplateVM that is already installed in your system, see [How to Reinstall a TemplateVM].
@ -37,12 +37,17 @@ After Installing
After installing a fresh Fedora TemplateVM, we recommend performing the following steps:
1. [Update the TemplateVM].
2. Switch any [TemplateBasedVMs] that are based on the old TemplateVM to the new one.
2. Switch any [TemplateBasedVMs] that are based on the old TemplateVM to the new one:
* [How to switch templates (3.2)](/doc/templates/#how-to-switch-templates-32)
* [How to switch templates (4.0)](/doc/templates/#how-to-switch-templates-40)
3. If desired, remove the old TemplateVM by running the following command in dom0:
$ sudo dnf remove qubes-template-fedora-26
$ sudo dnf remove qubes-template-fedora-XX
(If necessary, replace `26` with your desired Fedora version.)
(Replace `XX` with the Fedora version number of the template you wish to remove.)
Upgrading
@ -50,6 +55,8 @@ Upgrading
To upgrade your Fedora TemplateVM, please consult the guide that corresponds to your situation:
* [Upgrading the Fedora 27 Template to Fedora 28](/doc/template/fedora/upgrade-27-to-28/)
* [Upgrading the Fedora 26 Template to Fedora 27](/doc/template/fedora/upgrade-26-to-27/)
* [Upgrading the Fedora 25 Template to Fedora 26](/doc/template/fedora/upgrade-25-to-26/)
* [Upgrading the Fedora 24 Template to Fedora 25](/doc/template/fedora/upgrade-24-to-25/)
* [Upgrading the Fedora 23 Template to Fedora 24](/doc/template/fedora/upgrade-23-to-24/)

2
managing-os/templates/fedora/upgrade-23-to-24.md
View File

@ -235,4 +235,4 @@ In this case, you have several options:
[resize-disk-image]: /doc/resize-disk-image/
[Additional Information]: #additional-information
[Compacting the Upgraded Template]: #compacting-the-upgraded-template
[DispVM]: /doc/dispvm/
[DispVM]: /doc/disposablevm/

2
managing-os/templates/fedora/upgrade-24-to-25.md
View File

@ -238,4 +238,4 @@ In this case, you have several options:
[resize-disk-image]: /doc/resize-disk-image/
[Additional Information]: #additional-information
[Compacting the Upgraded Template]: #compacting-the-upgraded-template
[DispVM]: /doc/dispvm/
[DispVM]: /doc/disposablevm/

6
managing-os/templates/fedora/upgrade-25-to-26.md
View File

@ -73,7 +73,7 @@ should be entered (`@dom0` or `@fedora-26`).
**Note:** `dnf` might ask you to approve importing a new package signing
key. For example, you might see a prompt like this one:
warning: /var/cache/dnf/fedora-d02ca361e1b58501/packages/python2-babel-2.3.4-1.fc26.noarch.rpm: Header V3 RSA/SHA266 Signature, key ID 64dab85d: NOKEY
warning: /var/cache/dnf/fedora-d02ca361e1b58501/packages/python2-babel-2.3.4-1.fc26.noarch.rpm: Header V3 RSA/SHA256 Signature, key ID 64dab85d: NOKEY
Importing GPG key 0x64DAB85D:
Userid : "Fedora (26) <fedora-26-primary@fedoraproject.org>"
Fingerprint: E641 850B 77DF 4353 78D1 D7E2 812A 6B4B 64DA B85D
@ -247,7 +247,7 @@ should be entered (`@dom0` or `@fedora-26`).
**Note:** `dnf` might ask you to approve importing a new package signing
key. For example, you might see a prompt like this one:
warning: /var/cache/dnf/fedora-d02ca361e1b58501/packages/python2-babel-2.3.4-1.fc26.noarch.rpm: Header V3 RSA/SHA266 Signature, key ID 64dab85d: NOKEY
warning: /var/cache/dnf/fedora-d02ca361e1b58501/packages/python2-babel-2.3.4-1.fc26.noarch.rpm: Header V3 RSA/SHA256 Signature, key ID 64dab85d: NOKEY
Importing GPG key 0x64DAB85D:
Userid : "Fedora (26) <fedora-26-primary@fedoraproject.org>"
Fingerprint: E641 850B 77DF 4353 78D1 D7E2 812A 6B4B 64DA B85D
@ -382,5 +382,5 @@ In this case, you have several options:
[resize-disk-image]: /doc/resize-disk-image/
[Additional Information]: #additional-information
[Compacting the Upgraded Template]: #compacting-the-upgraded-template
[DispVM]: /doc/dispvm/
[DispVM]: /doc/disposablevm/

362
managing-os/templates/fedora/upgrade-26-to-27.md Normal file
View File

@ -0,0 +1,362 @@
---
layout: doc
title: Upgrading the Fedora 26 Template to Fedora 27
permalink: /doc/template/fedora/upgrade-26-to-27/
redirect_from:
- /doc/fedora-template-upgrade-26/
- /en/doc/fedora-template-upgrade-26/
- /doc/FedoraTemplateUpgrade26/
- /wiki/FedoraTemplateUpgrade26/
---
Upgrading the Fedora 26 Template to Fedora 27
=============================================
This page provides instructions for performing an in-place upgrade of an
installed Fedora 26 [TemplateVM] to Fedora 27. If you wish to install a new,
unmodified Fedora 27 template instead of upgrading a template that is already
installed in your system, please see the [Fedora TemplateVM] page instead.
These instructions can also be used to upgrade a Fedora 25 TemplateVM to
Fedora 27. Simply start by cloning `fedora-25` instead of `fedora-26` in the
instructions below.
Important information regarding RPM Fusion repos
------------------------------------------------
If your RPM Fusion repositories are **disabled** when you upgrade a TemplateVM from Fedora 26 to 27, all RPM Fusion packages and RPM Fusion repo definitions will be removed from that TemplateVM.
If your RPM Fusion repositories are **enabled** when upgrading, all RPM Fusion packages and repo definitions will be retained and updated as expected.
For most users, this behavior should not cause a problem, since a TemplateVM in which the RPM Fusion repos are disabled is probably a TemplateVM in which you never wish to use them.
However, if you wish to have the RPM Fusion repo definitions after upgrading in a TemplateVM in which they are currently disabled, you may wish to temporarily enable them prior to upgrading or manually create, copy, or download them after upgrading.
Qubes 3.2 Instructions
----------------------
### Summary: Upgrading the Standard Fedora 26 Template to Fedora 27 ###
**Note:** The prompt on each line indicates where each command should be entered
(`@dom0` or `@fedora-27`).
[user@dom0 ~]$ qvm-clone fedora-26 fedora-27
[user@dom0 ~]$ truncate -s 5GB /var/tmp/template-upgrade-cache.img
[user@dom0 ~]$ qvm-run -a fedora-27 gnome-terminal
[user@dom0 ~]$ qvm-block -A fedora-27 dom0:/var/tmp/template-upgrade-cache.img
[user@fedora-27 ~]$ sudo mkfs.ext4 /dev/xvdi
[user@fedora-27 ~]$ sudo mount /dev/xvdi /mnt/removable
[user@fedora-27 ~]$ sudo dnf clean all
[user@fedora-27 ~]$ sudo dnf --releasever=27 --setopt=cachedir=/mnt/removable --best --allowerasing distro-sync
(Shut down TemplateVM by any normal means.)
[user@dom0 ~]$ rm /var/tmp/template-upgrade-cache.img
[user@dom0 ~]$ qvm-trim-template fedora-27
(Optional cleanup: Switch everything over to the new template and delete the old
one. See instructions below for details.)
### Detailed: Upgrading the Standard Fedora 26 Template to Fedora 27 ###
These instructions will show you how to upgrade the standard Fedora 26
TemplateVM to Fedora 27. The same general procedure may be used to upgrade any
template based on the standard Fedora 26 template.
**Note:** The command-line prompt on each line indicates where each command
should be entered (`@dom0` or `@fedora-27`).
1. Ensure the existing template is not running.
[user@dom0 ~]$ qvm-shutdown fedora-26
2. Clone the existing template and start a terminal in the new template.
[user@dom0 ~]$ qvm-clone fedora-26 fedora-27
[user@dom0 ~]$ qvm-run -a fedora-27 gnome-terminal
3. Attempt the upgrade process in the new template.
[user@fedora-27 ~]$ sudo dnf clean all
[user@fedora-27 ~]$ sudo dnf --releasever=27 distro-sync --best --allowerasing
**Note:** `dnf` might ask you to approve importing a new package signing
key. For example, you might see a prompt like this one:
warning: /var/cache/dnf/fedora-d02ca361e1b58501/packages/python2-babel-2.3.4-1.fc27.noarch.rpm: Header V3 RSA/SHA256 Signature, key ID f5282ee4: NOKEY
Importing GPG key 0xF5282EE4:
Userid : "Fedora (27) <fedora-27-primary@fedoraproject.org>"
Fingerprint: 860E 19B0 AFA8 00A1 7518 81A6 F55E 7430 F528 2EE4
From : /etc/pki/rpm-gpg/RPM-GPG-KEY-fedora-27-x86_64
Is this ok [y/N]:
This key was already checked when it was installed (notice that the "From"
line refers to a location on your local disk), so you can safely say yes to
this prompt.
**Note:** If you encounter no errors, proceed to step 4. If you do encounter
errors, see the next two points first.
* If `dnf` reports that you do not have enough free disk space to proceed
with the upgrade process, create an empty file in dom0 to use as a cache
and attach it to the template as a virtual disk.
[user@dom0 ~]$ truncate -s 5GB /var/tmp/template-upgrade-cache.img
[user@dom0 ~]$ qvm-block -A fedora-27 dom0:/var/tmp/template-upgrade-cache.img
Then reattempt the upgrade process, but this time use the virtual disk
as a cache.
[user@fedora-27 ~]$ sudo mkfs.ext4 /dev/xvdi
[user@fedora-27 ~]$ sudo mount /dev/xvdi /mnt/removable
[user@fedora-27 ~]$ sudo dnf clean all
[user@fedora-27 ~]$ sudo dnf --releasever=27 --setopt=cachedir=/mnt/removable --best --allowerasing distro-sync
If this attempt is successful, proceed to step 4.
* `dnf` may complain:
At least X MB more space needed on the / filesystem.
In this case, one option is to [resize the TemplateVM's disk
image][resize-disk-image] before reattempting the upgrade process.
(See [Additional Information] below for other options.)
4. Shut down the new TemplateVM (from the command-line or Qubes VM Manager).
[user@dom0 ~]$ qvm-shutdown fedora-27
5. Remove the cache file, if you created one.
[user@dom0 ~]$ rm /var/tmp/template-upgrade-cache.img
6. Trim the new template (see [Compacting the Upgraded Template] for details
and other options).
[user@dom0 ~]$ qvm-trim-template fedora-27
7. (Recommended) [Switch everything that was set to the old template to the new
template.][switching-3.2]
8. (Optional) Remove the old template. (Make sure to type `fedora-26`, not
`fedora-27`.)
[user@dom0 ~]$ sudo dnf remove qubes-template-fedora-26
### Compacting the Upgraded Template ###
Neither `fstrim` nor the `discard` mount option works on the TemplateVM's root
filesystem, so when a file is removed in the template, space is not freed in
dom0. This means that the template will use about twice as much space as is
really necessary after upgrading.
You can use the `qvm-trim-template` tool:
[user@dom0 ~]$ qvm-trim-template fedora-27
### Upgrading StandaloneVMs ###
The procedure for upgrading a StandaloneVM from Fedora 26 to Fedora 27 is the
same as for a TemplateVM, except that `qvm-trim-template` does not work on
StandaloneVMs. Instead, you should run the following command inside the
StandaloneVM in order to compact it:
$ sudo fstrim -v -a
### Summary: Upgrading the Minimal Fedora 26 Template to Fedora 27 ###
**Note:** The prompt on each line indicates where each command should be entered
(`@dom0` or `@fedora-27`).
[user@dom0 ~]$ qvm-clone fedora-26-minimal fedora-27-minimal
[user@dom0 ~]$ qvm-run -u root -a fedora-27-minimal xterm
[root@fedora-27-minimal ~]# dnf clean all
[user@fedora-27-minimal ~]# dnf --releasever=27 --best --allowerasing distro-sync
(Shut down TemplateVM by any normal means.)
[user@dom0 ~]$ qvm-trim-template fedora-27-minimal
(If you encounter insufficient space issues, you may need to use the methods
described for the standard template above.)
Qubes 4.0 Instructions
----------------------
### Summary: Upgrading the Standard Fedora 26 Template to Fedora 27 ###
**Note:** The prompt on each line indicates where each command should be entered
(`@dom0` or `@fedora-27`).
[user@dom0 ~]$ qvm-clone fedora-26 fedora-27
[user@dom0 ~]$ truncate -s 5GB /var/tmp/template-upgrade-cache.img
[user@dom0 ~]$ qvm-run -a fedora-27 gnome-terminal
[user@dom0 ~]$ dev=$(sudo losetup -f --show /var/tmp/template-upgrade-cache.img)
[user@dom0 ~]$ qvm-block attach fedora-27 dom0:${dev##*/}
[user@fedora-27 ~]$ sudo mkfs.ext4 /dev/xvdi
[user@fedora-27 ~]$ sudo mount /dev/xvdi /mnt/removable
[user@fedora-27 ~]$ sudo dnf clean all
[user@fedora-27 ~]$ sudo dnf --releasever=27 --setopt=cachedir=/mnt/removable --best --allowerasing distro-sync
[user@fedora-27 ~]$ sudo fstrim -v /
(Shut down TemplateVM by any normal means.)
[user@dom0 ~]$ sudo losetup -d $dev
[user@dom0 ~]$ rm /var/tmp/template-upgrade-cache.img
(Optional cleanup: Switch everything over to the new template and delete the old
one. See instructions below for details.)
### Detailed: Upgrading the Standard Fedora 26 Template to Fedora 27 ###
These instructions will show you how to upgrade the standard Fedora 26
TemplateVM to Fedora 27. The same general procedure may be used to upgrade any
template based on the standard Fedora 26 template.
**Note:** The command-line prompt on each line indicates where each command
should be entered (`@dom0` or `@fedora-27`).
1. Ensure the existing template is not running.
[user@dom0 ~]$ qvm-shutdown fedora-26
2. Clone the existing template and start a terminal in the new template.
[user@dom0 ~]$ qvm-clone fedora-26 fedora-27
[user@dom0 ~]$ qvm-run -a fedora-27 gnome-terminal
3. Attempt the upgrade process in the new template.
[user@fedora-27 ~]$ sudo dnf clean all
[user@fedora-27 ~]$ sudo dnf --releasever=27 distro-sync --best --allowerasing
**Note:** `dnf` might ask you to approve importing a new package signing
key. For example, you might see a prompt like this one:
warning: /var/cache/dnf/fedora-d02ca361e1b58501/packages/python2-babel-2.3.4-1.fc27.noarch.rpm: Header V3 RSA/SHA256 Signature, key ID f5282ee4: NOKEY
Importing GPG key 0xF5282EE4:
Userid : "Fedora (27) <fedora-27-primary@fedoraproject.org>"
Fingerprint: 860E 19B0 AFA8 00A1 7518 81A6 F55E 7430 F528 2EE4
From : /etc/pki/rpm-gpg/RPM-GPG-KEY-fedora-27-x86_64
Is this ok [y/N]:
This key was already checked when it was installed (notice that the "From"
line refers to a location on your local disk), so you can safely say yes to
this prompt.
**Note:** If you encounter no errors, proceed to step 4. If you do encounter
errors, see the next two points first.
* If `dnf` reports that you do not have enough free disk space to proceed
with the upgrade process, create an empty file in dom0 to use as a cache
and attach it to the template as a virtual disk.
[user@dom0 ~]$ truncate -s 5GB /var/tmp/template-upgrade-cache.img
[user@dom0 ~]$ dev=$(sudo losetup -f --show /var/tmp/template-upgrade-cache.img)
[user@dom0 ~]$ qvm-block attach fedora-27 dom0:${dev##*/}
Then reattempt the upgrade process, but this time use the virtual disk
as a cache.
[user@fedora-27 ~]$ sudo mkfs.ext4 /dev/xvdi
[user@fedora-27 ~]$ sudo mount /dev/xvdi /mnt/removable
[user@fedora-27 ~]$ sudo dnf clean all
[user@fedora-27 ~]$ sudo dnf --releasever=27 --setopt=cachedir=/mnt/removable --best --allowerasing distro-sync
If this attempt is successful, proceed to step 4.
* `dnf` may complain:
At least X MB more space needed on the / filesystem.
In this case, one option is to [resize the TemplateVM's disk
image][resize-disk-image] before reattempting the upgrade process.
(See [Additional Information] below for other options.)
4. Trim the new template.
[user@fedora-27 ~]$ sudo fstrim -v /
5. Shut down the new TemplateVM (from the command-line or Qubes VM Manager).
[user@dom0 ~]$ qvm-shutdown fedora-27
6. Remove the cache file, if you created one.
[user@dom0 ~]$ sudo losetup -d $dev
[user@dom0 ~]$ rm /var/tmp/template-upgrade-cache.img
7. (Recommended) [Switch everything that was set to the old template to the new
template.][switching-4.0]
8. (Optional) Remove the old template. (Make sure to type `fedora-26`, not
`fedora-27`.)
[user@dom0 ~]$ sudo dnf remove qubes-template-fedora-26
### Upgrading StandaloneVMs ###
The procedure for upgrading a StandaloneVM from Fedora 26 to Fedora 27 is the
same as for a TemplateVM.
### Summary: Upgrading the Minimal Fedora 26 Template to Fedora 27 ###
**Note:** The prompt on each line indicates where each command should be entered
(`@dom0` or `@fedora-27`).
[user@dom0 ~]$ qvm-clone fedora-26-minimal fedora-27-minimal
[user@dom0 ~]$ qvm-run -u root -a fedora-27-minimal xterm
[root@fedora-27-minimal ~]# dnf clean all
[user@fedora-27-minimal ~]# dnf --releasever=27 --best --allowerasing distro-sync
[user@fedora-27-minimal ~]# fstrim -v /
(Shut down TemplateVM by any normal means.)
(If you encounter insufficient space issues, you may need to use the methods
described for the standard template above.)
Additional Information
----------------------
As mentioned above, you may encounter the following `dnf` error:
At least X MB more space needed on the / filesystem.
In this case, you have several options:
1. [Increase the TemplateVM's disk image size][resize-disk-image].
This is the solution mentioned in the main instructions above.
2. Delete files in order to free up space. One way to do this is by
uninstalling packages. You may then reinstalling them again after you
finish the upgrade process, if desired). However, you may end up having to
increase the disk image size anyway (see previous option).
3. Do the upgrade in parts, e.g., by using package groups. (First upgrade
`@core` packages, then the rest.)
4. Do not perform an in-place upgrade. Instead, simply download and install a
new template package, then redo all desired template modifications.
With regard to the last option, here are some useful messages from the
mailing list which also apply to TemplateVM management and migration in
general:
* [Marek](https://groups.google.com/d/msg/qubes-users/mCXkxlACILQ/dS1jbLRP9n8J)
* [Jason M](https://groups.google.com/d/msg/qubes-users/mCXkxlACILQ/5PxDfI-RKAsJ)
[TemplateVM]: /doc/templates/
[Fedora TemplateVM]: /doc/templates/fedora/
[resize-disk-image]: /doc/resize-disk-image/
[Additional Information]: #additional-information
[Compacting the Upgraded Template]: #compacting-the-upgraded-template
[switching-3.2]: /doc/templates/#how-to-switch-templates-32
[switching-4.0]: /doc/templates/#how-to-switch-templates-40
[DispVM]: /doc/disposablevm/

389
managing-os/templates/fedora/upgrade-27-to-28.md Normal file
View File

@ -0,0 +1,389 @@
---
layout: doc
title: Upgrading the Fedora 27 Template to Fedora 28
permalink: /doc/template/fedora/upgrade-27-to-28/
redirect_from:
- /doc/fedora-template-upgrade-27/
- /en/doc/fedora-template-upgrade-27/
- /doc/FedoraTemplateUpgrade27/
- /wiki/FedoraTemplateUpgrade27/
---
Upgrading the Fedora 27 Template to Fedora 28
=============================================
This page provides instructions for performing an in-place upgrade of an
installed Fedora 27 [TemplateVM] to Fedora 28. If you wish to install a new,
unmodified Fedora 28 template instead of upgrading a template that is already
installed in your system, please see the [Fedora TemplateVM] page instead.
These instructions can also be used to upgrade a Fedora 26 TemplateVM to
Fedora 28. Simply start by cloning `fedora-26` instead of `fedora-27` in the
instructions below.
Important information regarding RPM Fusion repos
------------------------------------------------
If your RPM Fusion repositories are **disabled** when you upgrade a TemplateVM from Fedora 27 to 28, all RPM Fusion packages and RPM Fusion repo definitions will be removed from that TemplateVM.
If your RPM Fusion repositories are **enabled** when upgrading, all RPM Fusion packages and repo definitions will be retained and updated as expected.
For most users, this behavior should not cause a problem, since a TemplateVM in which the RPM Fusion repos are disabled is probably a TemplateVM in which you never wish to use them.
However, if you wish to have the RPM Fusion repo definitions after upgrading in a TemplateVM in which they are currently disabled, you may wish to temporarily enable them prior to upgrading or manually create, copy, or download them after upgrading.
Workaround for `python2-xcffib` upgrade error
---------------------------------------------
When attempting to upgrade from Fedora 26 or 27 to Fedora 28, you may encounter an error similar to this:
Error: Transaction check error:
file /usr/lib/python2.7/site-packages/xcffib-0.5.1-py2.7.egg-info/PKG-INFO from install of python2-xcffib-0.5.1-5.fc28.noarch conflicts with file from package python-xcffib-0.5.1-1.fc26.noarch
file /usr/lib/python2.7/site-packages/xcffib/_ffi.pyc from install of python2-xcffib-0.5.1-5.fc28.noarch conflicts with file from package python-xcffib-0.5.1-1.fc26.noarch
file /usr/lib/python2.7/site-packages/xcffib/_ffi.pyo from install of python2-xcffib-0.5.1-5.fc28.noarch conflicts with file from package python-xcffib-0.5.1-1.fc26.noarch
file /usr/lib/python2.7/site-packages/xcffib/xinput.pyc from install of python2-xcffib-0.5.1-5.fc28.noarch conflicts with file from package python-xcffib-0.5.1-1.fc26.noarch
file /usr/lib/python2.7/site-packages/xcffib/xinput.pyo from install of python2-xcffib-0.5.1-5.fc28.noarch conflicts with file from package python-xcffib-0.5.1-1.fc26.noarch
To work around this error:
1. Upgrade while excluding the problematic packages by using `-x python2-xcffib -x qubes-gui-vm -x qubes-gui-agent`.
2. Upgrade `python2-xcffib` using `sudo dnf swap python-xcffib python2-xcffib`.
(This should automatically upgrade the other excluded packages too.)
Qubes 3.2 Instructions
----------------------
### Summary: Upgrading the Standard Fedora 27 Template to Fedora 28 ###
**Note:** The prompt on each line indicates where each command should be entered
(`@dom0` or `@fedora-28`).
[user@dom0 ~]$ qvm-clone fedora-27 fedora-28
[user@dom0 ~]$ truncate -s 5GB /var/tmp/template-upgrade-cache.img
[user@dom0 ~]$ qvm-run -a fedora-28 gnome-terminal
[user@dom0 ~]$ qvm-block -A fedora-28 dom0:/var/tmp/template-upgrade-cache.img
[user@fedora-28 ~]$ sudo mkfs.ext4 /dev/xvdi
[user@fedora-28 ~]$ sudo mount /dev/xvdi /mnt/removable
[user@fedora-28 ~]$ sudo dnf clean all
[user@fedora-28 ~]$ sudo dnf --releasever=28 --setopt=cachedir=/mnt/removable --best --allowerasing -x python2-tornado distro-sync
(Shut down TemplateVM by any normal means.)
[user@dom0 ~]$ rm /var/tmp/template-upgrade-cache.img
[user@dom0 ~]$ qvm-trim-template fedora-28
(Optional cleanup: Switch everything over to the new template and delete the old
one. See instructions below for details.)
### Detailed: Upgrading the Standard Fedora 27 Template to Fedora 28 ###
These instructions will show you how to upgrade the standard Fedora 27
TemplateVM to Fedora 28. The same general procedure may be used to upgrade any
template based on the standard Fedora 27 template.
**Note:** The command-line prompt on each line indicates where each command
should be entered (`@dom0` or `@fedora-28`).
1. Ensure the existing template is not running.
[user@dom0 ~]$ qvm-shutdown fedora-27
2. Clone the existing template and start a terminal in the new template.
[user@dom0 ~]$ qvm-clone fedora-27 fedora-28
[user@dom0 ~]$ qvm-run -a fedora-28 gnome-terminal
3. Attempt the upgrade process in the new template.
[user@fedora-28 ~]$ sudo dnf clean all
[user@fedora-28 ~]$ sudo dnf --releasever=28 distro-sync --best --allowerasing
**Note:** `dnf` might ask you to approve importing a new package signing
key. For example, you might see a prompt like this one:
warning: /var/cache/dnf/fedora-d02ca361e1b58501/packages/python2-babel-2.3.4-1.fc28.noarch.rpm: Header V3 RSA/SHA256 Signature, key ID 9db62fb1: NOKEY
Importing GPG key 0x9DB62FB1:
Userid : "Fedora (28) <fedora-28-primary@fedoraproject.org>"
Fingerprint: 128C F232 A937 1991 C8A6 5695 E08E 7E62 9DB6 2FB1
From : /etc/pki/rpm-gpg/RPM-GPG-KEY-fedora-28-x86_64
Is this ok [y/N]:
This key was already checked when it was installed (notice that the "From"
line refers to a location on your local disk), so you can safely say yes to
this prompt.
**Note:** If you encounter no errors, proceed to step 4. If you do encounter
errors, see the next two points first.
* If `dnf` reports that you do not have enough free disk space to proceed
with the upgrade process, create an empty file in dom0 to use as a cache
and attach it to the template as a virtual disk.
[user@dom0 ~]$ truncate -s 5GB /var/tmp/template-upgrade-cache.img
[user@dom0 ~]$ qvm-block -A fedora-28 dom0:/var/tmp/template-upgrade-cache.img
Then reattempt the upgrade process, but this time use the virtual disk
as a cache.
[user@fedora-28 ~]$ sudo mkfs.ext4 /dev/xvdi
[user@fedora-28 ~]$ sudo mount /dev/xvdi /mnt/removable
[user@fedora-28 ~]$ sudo dnf clean all
[user@fedora-28 ~]$ sudo dnf --releasever=28 --setopt=cachedir=/mnt/removable --best --allowerasing distro-sync
If this attempt is successful, proceed to step 4.
* `dnf` may complain:
At least X MB more space needed on the / filesystem.
In this case, one option is to [resize the TemplateVM's disk
image][resize-disk-image] before reattempting the upgrade process.
(See [Additional Information] below for other options.)
4. Check that you are on the correct (new) fedora release.
[user@fedora-28 ~]$ cat /etc/fedora-release
5. Shut down the new TemplateVM (from the command-line or Qubes VM Manager).
[user@dom0 ~]$ qvm-shutdown fedora-28
6. Remove the cache file, if you created one.
[user@dom0 ~]$ rm /var/tmp/template-upgrade-cache.img
7. Trim the new template (see [Compacting the Upgraded Template] for details
and other options).
[user@dom0 ~]$ qvm-trim-template fedora-28
8. (Recommended) [Switch everything that was set to the old template to the new
template.][switching-3.2]
9. (Optional) Remove the old template. (Make sure to type `fedora-27`, not
`fedora-28`.)
[user@dom0 ~]$ sudo dnf remove qubes-template-fedora-27
### Compacting the Upgraded Template ###
Neither `fstrim` nor the `discard` mount option works on the TemplateVM's root
filesystem, so when a file is removed in the template, space is not freed in
dom0. This means that the template will use about twice as much space as is
really necessary after upgrading.
You can use the `qvm-trim-template` tool:
[user@dom0 ~]$ qvm-trim-template fedora-28
### Upgrading StandaloneVMs ###
The procedure for upgrading a StandaloneVM from Fedora 27 to Fedora 28 is the
same as for a TemplateVM, except that `qvm-trim-template` does not work on
StandaloneVMs. Instead, you should run the following command inside the
StandaloneVM in order to compact it:
$ sudo fstrim -v -a
### Summary: Upgrading the Minimal Fedora 27 Template to Fedora 28 ###
**Note:** The prompt on each line indicates where each command should be entered
(`@dom0` or `@fedora-28`).
[user@dom0 ~]$ qvm-clone fedora-27-minimal fedora-28-minimal
[user@dom0 ~]$ qvm-run -u root -a fedora-28-minimal xterm
[root@fedora-28-minimal ~]# dnf clean all
[user@fedora-28-minimal ~]# dnf --releasever=28 --best --allowerasing distro-sync
(Shut down TemplateVM by any normal means.)
[user@dom0 ~]$ qvm-trim-template fedora-28-minimal
(If you encounter insufficient space issues, you may need to use the methods
described for the standard template above.)
Qubes 4.0 Instructions
----------------------
### Summary: Upgrading the Standard Fedora 27 Template to Fedora 28 ###
**Note:** The prompt on each line indicates where each command should be entered
(`@dom0` or `@fedora-28`).
[user@dom0 ~]$ qvm-clone fedora-27 fedora-28
[user@dom0 ~]$ truncate -s 5GB /var/tmp/template-upgrade-cache.img
[user@dom0 ~]$ qvm-run -a fedora-28 gnome-terminal
[user@dom0 ~]$ dev=$(sudo losetup -f --show /var/tmp/template-upgrade-cache.img)
[user@dom0 ~]$ qvm-block attach fedora-28 dom0:${dev##*/}
[user@fedora-28 ~]$ sudo mkfs.ext4 /dev/xvdi
[user@fedora-28 ~]$ sudo mount /dev/xvdi /mnt/removable
[user@fedora-28 ~]$ sudo dnf clean all
[user@fedora-28 ~]$ sudo dnf --releasever=28 --setopt=cachedir=/mnt/removable --best --allowerasing distro-sync
[user@fedora-28 ~]$ sudo fstrim -v /
(Shut down TemplateVM by any normal means.)
[user@dom0 ~]$ sudo losetup -d $dev
[user@dom0 ~]$ rm /var/tmp/template-upgrade-cache.img
(Optional cleanup: Switch everything over to the new template and delete the old
one. See instructions below for details.)
### Detailed: Upgrading the Standard Fedora 27 Template to Fedora 28 ###
These instructions will show you how to upgrade the standard Fedora 27
TemplateVM to Fedora 28. The same general procedure may be used to upgrade any
template based on the standard Fedora 27 template.
**Note:** The command-line prompt on each line indicates where each command
should be entered (`@dom0` or `@fedora-28`).
1. Ensure the existing template is not running.
[user@dom0 ~]$ qvm-shutdown fedora-27
2. Clone the existing template and start a terminal in the new template.
[user@dom0 ~]$ qvm-clone fedora-27 fedora-28
[user@dom0 ~]$ qvm-run -a fedora-28 gnome-terminal
3. Attempt the upgrade process in the new template.
[user@fedora-28 ~]$ sudo dnf clean all
[user@fedora-28 ~]$ sudo dnf --releasever=28 distro-sync --best --allowerasing
**Note:** `dnf` might ask you to approve importing a new package signing
key. For example, you might see a prompt like this one:
warning: /var/cache/dnf/fedora-d02ca361e1b58501/packages/python2-babel-2.3.4-1.fc28.noarch.rpm: Header V3 RSA/SHA256 Signature, key ID 9db62fb1: NOKEY
Importing GPG key 0x9DB62FB1:
Userid : "Fedora (28) <fedora-28-primary@fedoraproject.org>"
Fingerprint: 128C F232 A937 1991 C8A6 5695 E08E 7E62 9DB6 2FB1
From : /etc/pki/rpm-gpg/RPM-GPG-KEY-fedora-28-x86_64
Is this ok [y/N]:
This key was already checked when it was installed (notice that the "From"
line refers to a location on your local disk), so you can safely say yes to
this prompt.
**Note:** If you encounter no errors, proceed to step 4. If you do encounter
errors, see the next two points first.
* If `dnf` reports that you do not have enough free disk space to proceed
with the upgrade process, create an empty file in dom0 to use as a cache
and attach it to the template as a virtual disk.
[user@dom0 ~]$ truncate -s 5GB /var/tmp/template-upgrade-cache.img
[user@dom0 ~]$ dev=$(sudo losetup -f --show /var/tmp/template-upgrade-cache.img)
[user@dom0 ~]$ qvm-block attach fedora-28 dom0:${dev##*/}
Then reattempt the upgrade process, but this time use the virtual disk
as a cache.
[user@fedora-28 ~]$ sudo mkfs.ext4 /dev/xvdi
[user@fedora-28 ~]$ sudo mount /dev/xvdi /mnt/removable
[user@fedora-28 ~]$ sudo dnf clean all
[user@fedora-28 ~]$ sudo dnf --releasever=28 --setopt=cachedir=/mnt/removable --best --allowerasing distro-sync
If this attempt is successful, proceed to step 4.
* `dnf` may complain:
At least X MB more space needed on the / filesystem.
In this case, one option is to [resize the TemplateVM's disk
image][resize-disk-image] before reattempting the upgrade process.
(See [Additional Information] below for other options.)
4. Check that you are on the correct (new) fedora release.
[user@fedora-28 ~]$ cat /etc/fedora-release
5. Trim the new template.
[user@fedora-28 ~]$ sudo fstrim -v /
6. Shut down the new TemplateVM (from the command-line or Qubes VM Manager).
[user@dom0 ~]$ qvm-shutdown fedora-28
7. Remove the cache file, if you created one.
[user@dom0 ~]$ sudo losetup -d $dev
[user@dom0 ~]$ rm /var/tmp/template-upgrade-cache.img
8. (Recommended) [Switch everything that was set to the old template to the new
template.][switching-4.0]
9. (Optional) Remove the old template. (Make sure to type `fedora-27`, not
`fedora-28`.)
[user@dom0 ~]$ sudo dnf remove qubes-template-fedora-27
### Upgrading StandaloneVMs ###
The procedure for upgrading a StandaloneVM from Fedora 27 to Fedora 28 is the
same as for a TemplateVM.
### Summary: Upgrading the Minimal Fedora 27 Template to Fedora 28 ###
**Note:** The prompt on each line indicates where each command should be entered
(`@dom0` or `@fedora-28`).
[user@dom0 ~]$ qvm-clone fedora-27-minimal fedora-28-minimal
[user@dom0 ~]$ qvm-run -u root -a fedora-28-minimal xterm
[root@fedora-28-minimal ~]# dnf clean all
[user@fedora-28-minimal ~]# dnf --releasever=28 --best --allowerasing distro-sync
[user@fedora-28-minimal ~]# fstrim -v /
(Shut down TemplateVM by any normal means.)
(If you encounter insufficient space issues, you may need to use the methods
described for the standard template above.)
Additional Information
----------------------
As mentioned above, you may encounter the following `dnf` error:
At least X MB more space needed on the / filesystem.
In this case, you have several options:
1. [Increase the TemplateVM's disk image size][resize-disk-image].
This is the solution mentioned in the main instructions above.
2. Delete files in order to free up space. One way to do this is by
uninstalling packages. You may then reinstalling them again after you
finish the upgrade process, if desired). However, you may end up having to
increase the disk image size anyway (see previous option).
3. Do the upgrade in parts, e.g., by using package groups. (First upgrade
`@core` packages, then the rest.)
4. Do not perform an in-place upgrade. Instead, simply download and install a
new template package, then redo all desired template modifications.
With regard to the last option, here are some useful messages from the
mailing list which also apply to TemplateVM management and migration in
general:
* [Marek](https://groups.google.com/d/msg/qubes-users/mCXkxlACILQ/dS1jbLRP9n8J)
* [Jason M](https://groups.google.com/d/msg/qubes-users/mCXkxlACILQ/5PxDfI-RKAsJ)
[TemplateVM]: /doc/templates/
[Fedora TemplateVM]: /doc/templates/fedora/
[resize-disk-image]: /doc/resize-disk-image/
[Additional Information]: #additional-information
[Compacting the Upgraded Template]: #compacting-the-upgraded-template
[switching-3.2]: /doc/templates/#how-to-switch-templates-32
[switching-4.0]: /doc/templates/#how-to-switch-templates-40
[DispVM]: /doc/disposablevm/

3
managing-os/templates/ubuntu.md
View File

@ -32,7 +32,8 @@ want to build.
The build for Ubuntu 14.04 LTS (Trusty) should be straightforward.
The build for Ubuntu 16.04 LTS (Xenial) is straightforward.
The build for Ubuntu 16.04 LTS (Xenial) is straightforward. Note that packages perl-Digest-MD5 and perl-Digest-SHA are required for the build to succeed.
----------

12
managing-os/windows.md
View File

@ -7,10 +7,18 @@ permalink: /doc/windows/
Windows VMs in Qubes OS
=======================
Like any other unmodified OSes, Windows can be installed in Qubes as an [HVM](/doc/hvm/) domain.
Qubes Windows Tools are then usually installed to provide integration with the rest of the Qubes system; they also include Xen's paravirtualized (PV) drivers to increase performance compared to qemu emulated devices. Alternatively, only Xen's PV drivers can be installed if integration with Qubes isn't required or if the tools aren't supported on a give version of Windows. In the latter case, one would have to [enable inter-VM networking](https://www.qubes-os.org/doc/firewall/#enabling-networking-between-two-qubes) to be able to exchange files with HVMs.
For more information about Windows VMs in Qubes OS, please see the specific guides below:
* [Installing and Using Windows-based AppVMs (Qubes R2 Beta 3 and later)](/doc/windows-appvms/)
* [Installing and Using Windows-based VMs](/doc/windows-vm/)
* [Installing and Using Qubes Windows Tools (Qubes R2 Beta 3 up to R3.2)](/doc/windows-tools/)
* [Issue #3585 - Installation and know limitations of Qubes Windows Tools in Qubes R4.0](https://github.com/QubesOS/qubes-issues/issues/3585)
* [Advanced options and troubleshooting of Qubes Tools for Windows (R3)](/doc/windows-tools-3/)
* [Advanced options and troubleshooting of Qubes Tools for Windows (R2)](/doc/windows-tools-2/)
* [Uninstalling Qubes Tools for Windows 2.x](/doc/uninstalling-windows-tools-2/)
* [Creating and Using HVM and Windows Domains](/doc/hvm/)

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

@ -12,7 +12,7 @@ Qubes Windows Tools: advanced settings and troubleshooting
==========================================================
**This document only applies to Qubes R2 (tools version 2.x)**
*Only 64-bit Windows 7 (any edition) is supported currently. Windows 8+ support is under development.*
*Only 64-bit Windows 7 (any edition) is supported currently.*
Installable components
----------------------

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

@ -13,7 +13,7 @@ Qubes Windows Tools: advanced settings and troubleshooting
==========================================================
**This document only applies to Qubes R3 (tools version 3.x)**
*Only 64-bit Windows 7 (any edition) is supported currently. Windows 8+ support is under development.*
*Only 64-bit Windows 7 (any edition) is supported currently.*
Installable components
----------------------

23
managing-os/windows/windows-appvms.md → managing-os/windows/windows-tools.md
View File

@ -1,17 +1,16 @@
---
layout: doc
title: Windows AppVms
permalink: /doc/windows-appvms/
title: Qubes Windows Tools
permalink: /doc/windows-tools/
redirect_from:
- /doc/windows-appvms/
- /en/doc/windows-appvms/
- /doc/WindowsAppVms/
- /wiki/WindowsAppVms/
---
Installing and using Windows-based AppVMs
=========================================
Qubes provides special support for running Windows-based AppVMs. This requires the user to install Windows 7 x64 in a Qubes VM and subsequently install Qubes Windows Tools inside the VM (support for Windows 8+ is in development). This page describes this process in detail.
What are 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:
@ -23,12 +22,18 @@ Qubes Windows Tools are a set of programs and drivers that provide integration o
Qubes Windows Tools are open source and are distributed under a GPL license.
NOTE: 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 pass-through). There is currently no audio support for Windows HVMs.
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 pass-through).
- There is currently no audio support for Windows HVMs.
- There is currently no USB passsthrough support for Windows HVMs.
- __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
-----------------------------------
Please refer to [this page](/doc/hvm-create/) for instructions on how to install Windows in a Qubes VM.
Please refer to [this page](/doc/windows-vm/) for instructions on how to install Windows in a Qubes VM.
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.
@ -53,7 +58,7 @@ This package brings the ISO with Qubes Windows Tools that is passed to the VM wh
Before proceeding with the installation we need to disable Windows mechanism that allows only signed drivers to be installed, because currently (beta releases) the drivers we provide as part of the Windows Tools are not digitally signed with a publicly recognizable certificate. To do that:
- Start command prompt as Administrator, i.e. right click on the Command Prompt icon and choose "Run as administrator"
- Start command prompt as Administrator, i.e. right click on the Command Prompt icon (All Programs -> Accessories) and choose "Run as administrator"
- In the command prompt type `bcdedit /set testsigning on`
- Reboot your Windows VM

311
managing-os/windows/windows-vm.md Normal file
View File

@ -0,0 +1,311 @@
---
layout: doc
title: Installing a Windows VM
permalink: /doc/windows-vm/
---
Installing a Windows VM
=======================
Qubes 4.0 - importing a Windows VM from R3.2
-------------------------------------------
Importing should work, simply make sure that you are not using Xen's newer linux stubdomain and that the VM is in HVM mode (these steps should be done automatically when importing the VM):
~~~
qvm-features VMNAME linux-stubdom ''
qvm-prefs VMNAME virt_mode hvm
~~~
Note however that you are better off creating a new Windows VM to benefit from the more recent emulated hardware: R3.2 uses a MiniOS based stubdomain with an old and mostly unmaintained 'qemu-traditional' while R4.0 uses a Linux based stubdomain with a recent version of upstream qemu (see [this post](https://groups.google.com/d/msg/qubes-devel/tBqwJmOAJ94/xmFCGJnuAwAJ)).
Qubes 3.2 - Windows VM installation
-----------------------------------
### Summary ###
~~~
qvm-create win7new --hvm --label red
qvm-prefs -s win7new memory 4096
qvm-prefs -s win7new maxmem 4096
qvm-grow-root win7new 25g
qvm-prefs -s win7new debug true
cp /var/lib/qubes/appvms/win7new/win7new.conf /tmp
sed -i "s/<model \+type='xen' \+vram=/<model type='cirrus' vram=/" /tmp/win7new.conf
qvm-start --custom-config=/tmp/win7new.conf --cdrom=untrusted:/home/user/windows_install.iso win7new
# restart after the first part of the windows installation process ends
qvm-start --custom-config=/tmp/win7new.conf win7new
# once Windows is installed and working
qvm-prefs -s win7new memory 2048
qvm-prefs -s win7new maxmem 2048
rm /tmp/win7new.conf
qvm-prefs -s win7new qrexec_timeout 300
# with Qubes Windows Tools installed:
qvm-prefs -s win7new debug false
~~~
### Detailed instructions ###
MS Windows versions considerations:
- The instructions *may* work on other versions than Windows 7 x64 but haven't been tested.
- Qubes Windows Tools (QWT) only supports Windows 7 x64.
Create a VM named win7new in [HVM](/doc/hvm/) mode (Xen's current PVH limitations precludes from using PVH):
~~~
qvm-create win7new --hvm --label red
~~~
Windows' installer requires a significant amount of memory or else the VM will crash with such errors:
`/var/log/xen/console/hypervisor.log`:
> p2m_pod_demand_populate: Dom120 out of PoD memory! (tot=102411 ents=921600 dom120)
> (XEN) domain_crash called from p2m-pod.c:1218
> (XEN) Domain 120 (vcpu#0) crashed on cpu#3:
So, increase the VM's memory to 4096MB (memory = maxmem because we don't use memory balancing).
~~~
qvm-prefs -s win7new memory 4096
qvm-prefs -s win7new maxmem 4096
~~~
A typical Windows 7 installation requires between 15GB up to 19GB of disk space depending on the version (Home/Professional/...). Windows updates also end up using significant space. So, extend the root volume from the default 10GB to 25GB (note: it is straightforward to increase the root volume size after Windows is installed: simply extend the volume again in dom0 and then extend the system partition with Windows's disk manager).
~~~
qvm-grow-root win7new 25g
~~~
Set the debug flag in order to have a graphical console:
~~~
qvm-prefs -s win7new debug true
~~~
The second part of the installation process will crash with the standard VGA video adapter and the VM will stay in "transient" mode with the following error in `guest-win7new-dm.log`:
> qemu: /home/user/qubes-src/vmm-xen-stubdom-linux/build/qemu/exec.c:1187: cpu_physical_memory_snapshot_get_dirty: Assertion `start + length <= snap->end' failed.
To avoid that error we temporarily have to switch the video adapter to 'cirrus'. Backup the VM's configuration file and substitute the video driver from 'xen' to 'cirrus':
~~~
cp /var/lib/qubes/appvms/win7new/win7new.conf /tmp
sed -i "s/<model \+type='xen' \+vram=/<model type='cirrus' vram=/" /tmp/win7new.conf
# or edit the file manually ; either way, make sure the adapter is now cirrus !
~~~
The VM is now ready to be started; the best practice is to use an installation ISO [located in a VM](/doc/hvm/#installing-an-os-in-an-hvm-domain):
~~~
qvm-start --custom-config=/tmp/win7new.conf --cdrom=untrusted:/home/user/windows_install.iso win7new
~~~
Given the higher than usual memory requirements of Windows, you may get a `Not enough memory to start domain 'win7new'` error. In that case try to shutdown unneeded VMs to free memory before starting the Windows VM.
At this point you may open a tab in dom0 for debugging, in case something goes amiss:
~~~
tailf /var/log/qubes/vm-win7new.log \
/var/log/xen/console/hypervisor.log \
/var/log/xen/console/guest-win7new-dm.log
~~~
The VM will shutdown after the installer completes the extraction of Windows installation files. It's a good idea to clone the VM now (eg. `qvm-clone win7new win7newbkp1`). Then, (re)start the VM with
~~~
qvm-start --custom-config=/tmp/win7new.conf win7new
~~~
The second part of Windows' installer should then be able to complete successfully. You may then perform the following post-install steps:
Decrease the VM's memory to a more reasonable value (memory balancing on Windows is unstable so keep `memory` equal to `maxmen`).
~~~
qvm-prefs -s win7new memory 2048
qvm-prefs -s win7new maxmem 2048
~~~
We don't need to use the 'cirrus' video adapter anymore; simply starting the VM with `qvm-start win7new` will use the default XEN adapter, but to avoid any mistakes let's remove the temporary configuration file we created before:
~~~
rm /tmp/win7new.conf
~~~
Finally, increase the VM's `qrexec_timeout`: in case you happen to get a BSOD or a similar crash in the VM, utilities like chkdsk won't complete on restart before qrexec_timeout automatically halts the VM. That can really put the VM in a totally unrecoverable state, whereas with higher qrexec_timeout, chkdsk or the appropriate utility has plenty of time to fix the VM. Note that Qubes Windows Tools also require a larger timeout to move the user profiles to the private volume the first time the VM reboots after the tools' installation.
~~~
qvm-prefs -s win7new qrexec_timeout 300
~~~
At that point you should have a functional and stable Windows VM, although without updates, Xen's PV drivers nor Qubes integration (see sections [Windows Update](#windows-update) and [Xen PV drivers and Qubes Windows Tools](#xen-pv-drivers-and-qubes-windows-tools) below). It is a good time to clone the VM again.
Qubes 4.0 - Windows VM installation
-----------------------------------
### Summary ###
~~~
qvm-create --class StandaloneVM --label red --property virt_mode=hvm win7new
qvm-prefs win7new memory 4096
qvm-prefs win7new maxmem 4096
qvm-prefs win7new kernel ''
qvm-volume extend win7new:root 25g
qvm-prefs win7new debug true
qvm-features win7new video-model cirrus
qvm-start --cdrom=untrusted:/home/user/windows_install.iso win7new
# restart after the first part of the windows installation process ends
qvm-start win7new
# once Windows is installed and working
qvm-prefs win7new memory 2048
qvm-prefs win7new maxmem 2048
qvm-features --unset win7new video-model
qvm-prefs win7new qrexec_timeout 300
# with Qubes Windows Tools installed:
qvm-prefs win7new debug false
~~~
To install Qubes Windows Tools, follow instructions [below](#xen-pv-drivers-and-qubes-windows-tools).
### Detailed instructions ###
MS Windows versions considerations:
- The instructions *may* work on other versions than Windows 7 x64 but haven't been tested.
- Qubes Windows Tools (QWT) only supports Windows 7 x64. Note that there are [known issues](https://github.com/QubesOS/qubes-issues/issues/3585) with QWT on Qubes 4.x
Create a VM named win7new in [HVM](/doc/hvm/) mode (Xen's current PVH limitations precludes from using PVH):
~~~
qvm-create --class StandaloneVM --label red --property virt_mode=hvm win7new
~~~
Windows' installer requires a significant amount of memory or else the VM will crash with such errors:
`/var/log/xen/console/hypervisor.log`:
> p2m_pod_demand_populate: Dom120 out of PoD memory! (tot=102411 ents=921600 dom120)
> (XEN) domain_crash called from p2m-pod.c:1218
> (XEN) Domain 120 (vcpu#0) crashed on cpu#3:
So, increase the VM's memory to 4096MB (memory = maxmem because we don't use memory balancing).
~~~
qvm-prefs win7new memory 4096
qvm-prefs win7new maxmem 4096
~~~
Disable direct boot so that the VM will go through the standard cdrom/HDD boot sequence:
~~~
qvm-prefs win7new kernel ''
~~~
A typical Windows 7 installation requires between 15GB up to 19GB of disk space depending on the version (Home/Professional/...). Windows updates also end up using significant space. So, extend the root volume from the default 10GB to 25GB (note: it is straightforward to increase the root volume size after Windows is installed: simply extend the volume again in dom0 and then extend the system partition with Windows's disk manager).
~~~
qvm-volume extend win7new:root 25g
~~~
Set the debug flag in order to have a graphical console:
~~~
qvm-prefs win7new debug true
~~~
The second part of the installation process will crash with the standard VGA video adapter and the VM will stay in "transient" mode with the following error in `guest-win7new-dm.log`:
> qemu: /home/user/qubes-src/vmm-xen-stubdom-linux/build/qemu/exec.c:1187: cpu_physical_memory_snapshot_get_dirty: Assertion `start + length <= snap->end' failed.
To avoid that error we temporarily have to switch the video adapter to 'cirrus':
~~~
qvm-features win7new video-model cirrus
~~~
The VM is now ready to be started; the best practice is to use an installation ISO [located in a VM](/doc/hvm/#installing-an-os-in-an-hvm-domain):
~~~
qvm-start --cdrom=untrusted:/home/user/windows_install.iso win7new
~~~
Given the higher than usual memory requirements of Windows, you may get a `Not enough memory to start domain 'win7new'` error. In that case try to shutdown unneeded VMs to free memory before starting the Windows VM.
At this point you may open a tab in dom0 for debugging, in case something goes amiss:
~~~
tailf /var/log/qubes/vm-win7new.log \
/var/log/xen/console/hypervisor.log \
/var/log/xen/console/guest-win7new-dm.log
~~~
The VM will shutdown after the installer completes the extraction of Windows installation files. It's a good idea to clone the VM now (eg. `qvm-clone win7new win7newbkp1`). Then, (re)start the VM with `qvm-start win7new`.
The second part of Windows' installer should then be able to complete successfully. You may then perform the following post-install steps:
Decrease the VM's memory to a more reasonable value (memory balancing on Windows is unstable so keep `memory` equal to `maxmen`).
~~~
qvm-prefs win7new memory 2048
qvm-prefs win7new maxmem 2048
~~~
Revert to the standard VGA adapter :
~~~
qvm-features --unset win7new video-model
~~~
Finally, increase the VM's `qrexec_timeout`: in case you happen to get a BSOD or a similar crash in the VM, utilities like chkdsk won't complete on restart before qrexec_timeout automatically halts the VM. That can really put the VM in a totally unrecoverable state, whereas with higher qrexec_timeout, chkdsk or the appropriate utility has plenty of time to fix the VM. Note that Qubes Windows Tools also require a larger timeout to move the user profiles to the private volume the first time the VM reboots after the tools' installation.
~~~
qvm-prefs 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.
Windows update
--------------
Depending on how old your installation media is, fully updating your Windows VM may take *hours* (this isn't specific to Xen/Qubes) so make sure you clone your VM between the mandatory reboots in case something goes wrong. This [comment](https://github.com/QubesOS/qubes-issues/issues/3585#issuecomment-366471111) provides useful links on updating a Windows 7 SP1 VM.
Note: if you already have Qubes Windows Tools installed the video adapter in Windows will be "Qubes video driver" and you won't be able to see the Windows Update process when the VM is being powered off because Qubes services would have been stopped by then. Depending on the size of the Windows update packs it may take a bit of time until the VM shutdowns by itself, leaving one wondering if the VM has crashed or still finalizing the updates (in dom0 a changing CPU usage - eg. shown with `xentop` - usually indicates that the VM hasn't crashed).
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
---------------------
Please see the [Customizing Windows 7 templates](/doc/windows-template-customization/) page (despite the focus on preparing the VM for use as a template, most of the instructions are independent from how the VM will be used - ie. TemplateVM or StandaloneVM).

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

@ -17,18 +17,34 @@ The Network Manager method should work with both Qubes R4.0 and R3.2.
## Upgrading and configuring Network Manager in Qubes
Newer versions of Network Manager have a robust set of options for randomizing MAC addresses, and can handle the entire process across reboots, sleep/wake cycles and different connection states.
In particular, versions 1.4.2 and later should be well suited for Qubes.
In particular, versions 1.4.2 and later should be well suited for Qubes. Qubes R4.0's default sys-net should have 1.8.2-4 by default.
Network Manager 1.4.2 or later is available from the Fedora 25 repository as well as the Debian 9 repository, which you can install by [upgrading a Debian 8 template to version 9.](/doc/debian-template-upgrade-8/)
In the Debian 9 or Fedora 25 template you intend to use as a NetVM, check that Network Manager version is now at least 1.4.2:
Check that Network Manager version is now at least 1.4.2:
~~~
$ sudo NetworkManager -V
1.4.2
~~~
Write the settings to a new file in the `/etc/NetworkManager/conf.d/` directory, such as `mac.conf`.
## Randomize a single connection
Right click on the Network Manager icon of your NetVM in the tray and click 'Edit Connections..'.
Select the connection to randomize and click Edit.
Select the Cloned MAC Address drop down and set to Random or Stable.
Stable will generate a random address that persists until reboot, while Random will generate an address each time a link goes up.
![Edit Connection](/attachment/wiki/RandomizeMAC/networkmanager-mac-random.png)
Save the change and reconnect the connection (click on Network Manager tray icon and click disconnect under the connection, it should automatically reconnect).
## Randomize all Ethernet and Wifi connections
These steps should be done inside a template to be used to create a NetVM as it relies on creating a config file that would otherwise be deleted after a reboot due to the nature of AppVMs.
Write the settings to a new file in the `/etc/NetworkManager/conf.d/` directory, such as `00-macrandomize.conf`.
The following example enables Wifi and Ethernet MAC address randomization while scanning (not connected), and uses a randomly generated but persistent MAC address for each individual Wifi and Ethernet connection profile.
~~~
@ -46,8 +62,8 @@ connection.stable-id=${CONNECTION}/${BOOT}
To see all the available configuration options, refer to the man page: `man nm-settings`
Next, create a new NetVM using the new template and assign network devices to it.
Next, create a new NetVM using the edited template and assign network devices to it.
Finally, shutdown all VMs and change the settings of sys-firewall, etc. to use the new NetVM.
You can check the MAC address currently in use by looking at the status pages of your router device(s), or in the NetVM with the command `sudo ip link show`.
You can check the MAC address currently in use by looking at the status pages of your router device(s), or inside the NetVM with the command `sudo ip link show`.

10
privacy/signal.md
View File

@ -30,13 +30,13 @@ 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 8)
1. (Optional)Create a TemplateVM (Debian 9)
[user@dom0 ~]$ sudo qubes-dom0-update qubes-template-debian-8
[user@dom0 ~]$ sudo qubes-dom0-update qubes-template-debian-9
2. Open a terminal in Debian 8
2. Open a terminal in Debian 9
[user@dom0 ~]$ qvm-run -a debian-8 gnome-terminal
[user@dom0 ~]$ qvm-run -a debian-9 gnome-terminal
3. Use these commands in your terminal
@ -47,7 +47,7 @@ Always obtain a trusted key fingerprint via other channels, and always check any
5. Shutdown the TemplateVM :
[user@dom0 ~]$ qvm-shutdown debian-8
[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`

1
privacy/tails.md
View File

@ -25,6 +25,7 @@ To run Tails under Qubes:
- In Manager, click "VM menu" and select "Create VM"
- Name the new qube - "Tails"
- Select "HVM"
- Set "initial memory" and "max memory" as the same ([official documentation](https://tails.boum.org/doc/about/requirements/index.en.html) recommends at least 2048 MB)
- Configure networking
- Click "OK" to create new HVM.

91
privacy/whonix-customize.md
View File

@ -1,91 +0,0 @@
---
layout: doc
title: Customizing Whonix
permalink: /doc/whonix/customize/
redirect_from: /doc/privacy/customizing-whonix/
---
Customizing Whonix
==================
There are numerous ways to customize your Whonix install. All require a degree of technical knowledge and comfort with the command line.
### Enabling AppArmor
This is an optional security enhancement (for testers-only). If you're technical & interested, proceed, but do so *at your own risk!*
Note, if you want to use [Tor bridges](https://www.whonix.org/wiki/Bridges), AppArmor has been known in the past to cause problems with `obfsproxy` [see this issue](https://github.com/Whonix/Whonix/issues/67)
You will want to complete the following instructions in both the **Whonix-Gateway** referred to in Qubes VM Manager as `whonix-gw` and the **Whonix-Workstation** or `whonix-ws`. You only need to apply these settings to the TemplateVMs before creating any template based VMs from these Whonix templates.
(This is because, [since Qubes Q3, TemplateBasedVMs inherit the kernelopts setting of their TemplateVM](https://github.com/QubesOS/qubes-issues/issues/1091).)
### Configuring Whonix-Gateway
Launch the `dom0` terminal app `Konsole (konsole)`or `Terminal Emulator (xfce4-terminal)` from your Qubes App Launcher. Then get a list of current kernel parameters.
~~~
qvm-prefs -g whonix-gw kernelopts
~~~
In Qubes 3.2 and 4.0, this will show: `nopat`
Keep those existing kernel parameters and add `apparmor=1 security=apparmor` by entering:
~~~
qvm-prefs -s whonix-gw kernelopts "nopat apparmor=1 security=apparmor"
~~~
When running the command to get a list of current kernel parameters again (just hit the arrow up key twice, so you don't have to type the command again).
~~~
qvm-prefs -g whonix-gw kernelopts
~~~
It should show the old and the new kernel parameters. For example:
~~~
nopat apparmor=1 security=apparmor
~~~
Once you started the VM, you can check if AppArmor is now active.
```
sudo aa-status --enabled ; echo $?
```
It should show: `0`
### Configuring Whonix-Workstation
In `dom0` terminal Konsole or Terminal Emulator, get a list of current kernel parameters.
~~~
qvm-prefs -g whonix-ws kernelopts
~~~
In current version of Qubes, this will show `nopat` as a response. To keep those existing kernel parameters and add `apparmor=1 security=apparmor` do the following:
~~~
qvm-prefs -s whonix-ws kernelopts "nopat apparmor=1 security=apparmor"
~~~
When running the command to get a list of current kernel parameters again (just hit the arrow up key twice, so you don't have to type the command again).
~~~
qvm-prefs -g whonix-ws kernelopts
~~~
It should show the old and the new kernel parameters. For example:<br />
~~~
nopat apparmor=1 security=apparmor
~~~
Once you started the VM, you can check if AppArmor is now active by typing:
~~~
sudo aa-status --enabled ; echo $?
~~~
It should show: `0`

48
privacy/whonix-install.md
View File

@ -1,48 +0,0 @@
---
layout: doc
title: Install Whonix in Qubes
permalink: /doc/whonix/install/
redirect_from: /doc/privacy/install-whonix/
---
Install Whonix in Qubes
=======================
Installing Whonix in Qubes is simple and only requires a few simple steps.
### First Time Users
Using privacy and anonymization tools like Whonix is not a magical solution that instantly makes you anonymous online. Please consider:
* Do you know what metadata or a man-in-the-middle attack is?
* Do you think nobody can eavesdrop on your communications because you are using Tor?
* Do you know how Whonix works?
If you answered no, have a look at the [about](https://www.whonix.org/wiki/About), [warning](https://www.whonix.org/wiki/Warning) and [do not](https://www.whonix.org/wiki/DoNot) pages (on the Whonix website) to make sure Whonix is the right tool for you and you understand its limitations.
---
### Install Templates
Launch the `dom0` terminal `Konsole` from your Qubes App Launcher. Then enter the following command to install the Whonix-Gateway and Workstation TemplateVMs.
~~~
sudo qubesctl state.sls qvm.anon-whonix
~~~
Download will take a while and there will be no progress indicator.
After doing this, you should see two new TemplateVMs in the VM Manager called `whonix-gw` and `whonix-ws` as well as a `whonix-gw` TemplateBased ProxyVM called `sys-whonix` as well as a `whonix-ws` based AppVM called `anon-whonix`.
### Enabling AppArmor
This is an optional security enhancement (for testers-only). If you’re technical and interested, see [Enabling AppArmor](/doc/privacy/customizing-whonix/).
### Running Applications
To start an application in the **anon-whonix AppVM**, launch it like any other - open the `Qubes App Launcher` and then select an app such as `Tor Browser`.
### Advanced Information
You can learn more about [installing Whonix](https://www.whonix.org/wiki/Qubes/Install), [Qubes-Whonix](https://www.whonix.org/wiki/Qubes) or [Whonix generally](https://www.whonix.org).

67
privacy/whonix-uninstall.md
View File

@ -1,67 +0,0 @@
---
layout: doc
title: Uninstall Whonix from Qubes
permalink: /doc/whonix/uninstall/
redirect_from: /doc/privacy/uninstall-whonix/
---
Uninstall Whonix from Qubes
===========================
If you just want to remove your **Whonix-Gateway ProxyVMs** or **Whonix-Workstation AppVMs** this would not be the guide for doing that. Just use the Qubes VM Manager or command line tools for doing that.
*Warning: This guide will completely uninstall your underlying Whonix TemplateVMs. Only do this if you want to stop using Whonix or start over with a clean install of Whonix.*
### Unset or Remove Whonix TemplateVM from All VMs
In order to uninstall a Whonix TemplateVM, you first must ensure that no VMs have this TemplateVM set as its underlying template, or else the uninstall will not work. You can accomplish this by either unsetting the TemplateVM from VMs or simply by removing the VMs altogether. You only have to do this for VMs that use the TemplateVM that you will uninstall.
**Option 1a. Unsetting TemplateVM from VMs**
This option allows you to keep any VMs and their user storage contents. Note that the root storage will still be lost when uninstalling the TemplateVM, so you may want to backup anything important first.
```
dom0 -> Qubes VM Manager -> right click Whonix VM -> Shutdown VM
```
In Dom0 &raquo; Qubes VM Manager:
```
dom0 -> Qubes VM Manager -> right click Whonix VM -> VM Settings -> Basic tab -> Template -> Choose a different TemplateVM from the Template list, such as your Fedora TemplateVM.
```
**Option 1b. Removing VMs with TemplateVM**
This option will delete your user storage contents, so you may want to backup anything important first.
```
dom0 -> Qubes VM Manager -> right click Whonix VM -> Remove AppVM
```
### Uninstall Whonix TemplateVM
Note that if you have customized your TemplateVM, these will be lost when uninstalling the TemplateVM, so you may want to backup anything important first.
**Option 2a. Uninstall Whonix-Gateway TemplateVM**
Open the `dom0` terminal `Konsole`
```
Qubes App Launcher (blue/grey "Q") -> System Tools -> Konsole
```
Uninstall the qubes-template-whonix-gw template package.
~~~
sudo yum erase qubes-template-whonix-gw
~~~
**Option 2b. Uninstall Whonix-Workstation TemplateVM**
Open the `dom0` terminal `Konsole`
Uninstall the qubes-template-whonix-ws template package.
~~~
sudo yum erase qubes-template-whonix-ws
~~~

88
privacy/whonix-update.md
View File

@ -1,88 +0,0 @@
---
layout: doc
title: Updating Whonix in Qubes
permalink: /doc/whonix/update/
redirect_from: /doc/privacy/updating-whonix/
---
Updating Whonix in Qubes
========================
It is important to keep your Whonix templates current as to get important security updates.
### Configure Whonix TemplateVM proxy settings
![TemplateVM Proxy Settings](/attachment/wiki/Whonix/Qubes-Whonix-Gateway_TemplateVM_Qubes_VM_Manager_Settings.png)
### Open the Whonix Terminals
Launch `Terminal` for both `whonix-gw` and `whonix-ws` TemplateVMs and then perform the following steps to both TemplateVMs
~~~
sudo apt-get update && sudo apt-get dist-upgrade
~~~
The output should look similar to this.
~~~
Hit http://security.debian.org jessie/updates Release.gpg
Hit http://security.debian.org jessie/updates Release
Hit http://deb.torproject.org jessie Release.gpg
Hit http://ftp.us.debian.org jessie Release.gpg
Hit http://security.debian.org jessie/updates/main i386 Packages
Hit http://deb.torproject.org jessie Release
Hit http://security.debian.org jessie/updates/contrib i386 Packages
Hit http://ftp.us.debian.org jessie Release
Hit http://security.debian.org jessie/updates/non-free i386 Packages
Hit http://deb.torproject.org jessie/main i386 Packages
Hit http://security.debian.org jessie/updates/contrib Translation-en
Hit http://ftp.us.debian.org jessie/main i386 Packages
Hit http://security.debian.org jessie/updates/main Translation-en
Hit http://ftp.us.debian.org jessie/contrib i386 Packages
Hit http://security.debian.org jessie/updates/non-free Translation-en
Hit http://ftp.us.debian.org jessie/non-free i386 Packages
Ign http://ftp.us.debian.org jessie/contrib Translation-en
Ign http://ftp.us.debian.org jessie/main Translation-en
Ign http://ftp.us.debian.org jessie/non-free Translation-en
Ign http://deb.torproject.org jessie/main Translation-en_US
Ign http://deb.torproject.org jessie/main Translation-en
Reading package lists... Done
~~~
However, if what you see is different or you see the word `WARNING:` you should look at our troubleshooting documentation for [Debian and Whonix](/doc/troubleshooting/updating-debian-and-whonix/).
### Restart Services after Upgrading
The easy way to do this is to simply reboot.
~~~
sudo reboot
~~~
### Restart after Kernel Upgrades
When `linux-image-...` was upgraded, reboot is required to profit from security updates.
Shutdown Whonix TemplateVM
~~~
Qubes VM Manager -> right clock on TemplateVM -> Shutdown VM
~~~
### Restart / Update Whonix VMs
If new updates were available and installed, you will need to either simply restart your running Whonix-Gateway ProxyVMs and running Whonix-Workstation AppVMs for them to be updated -- or alternatively apply this same update process again to your running VMs if not wanting to restart them right away.

35
privacy/whonix.md
View File

@ -8,6 +8,14 @@ redirect_from:
- /en/doc/templates/whonix/
- /doc/Templates/Whonix/
- /wiki/Templates/Whonix/
- /doc/whonix/customize/
- /doc/privacy/customizing-whonix/
- /doc/whonix/install/
- /doc/privacy/install-whonix/
- /doc/whonix/uninstall/
- /doc/privacy/uninstall-whonix/
- /doc/whonix/update/
- /doc/privacy/updating-whonix/
---
Whonix for Privacy & Anonymity
@ -25,27 +33,26 @@ while the workstation is used for making AppVMs.
Whonix in Qubes replaces the deprecated [TorVM](/doc/torvm) service used in earlier
versions of Qubes.
## Getting Started with Whonix
* Note: To install Whonix in Qubes, you must already have a working Qubes machine.
* [Installing Whonix in Qubes](/doc/whonix/install/)
* [Updating Whonix in Qubes](/doc/whonix/update/)
## Customizing, Reinstalling, & Uninstalling Whonix
* [Customizing Whonix](/doc/whonix/customize/)
* [Uninstalling Whonix from Qubes](/doc/whonix/uninstall/)
*The following pages are written by the Whonix developers and are located on their website.*
* [Using Whonix with DisposableVMs](https://www.whonix.org/blog/qubes-whonix-dispvm)
## Getting Started with Whonix
Note: To install Whonix in Qubes, you must [install Qubes](/doc/installation-guide/) first.
* [Installing Whonix in Qubes](https://www.whonix.org/wiki/Qubes/Install)
* [Updating Whonix in Qubes](https://www.whonix.org/wiki/Qubes/Update)
* [Uninstalling Whonix from Qubes](https://www.whonix.org/wiki/Qubes/Uninstall)
## Configuring Whonix
* [Using Whonix with DisposableVMs](https://www.whonix.org/wiki/Qubes/Disposable_VM)
* [Post-Installation Security Advice](https://www.whonix.org/wiki/Post_Install_Advice)
* [How to set up Tor Bridges in Whonix on Qubes](https://www.whonix.org/wiki/Bridges#How_to_use_bridges_in_Whonix)
* [How to set up Tor Bridges in Whonix on Qubes](https://www.whonix.org/wiki/Bridges)
* [Using Multiple Whonix-Workstations with Whonix on Qubes](https://www.whonix.org/wiki/Multiple_Whonix-Workstations#Qubes-Whonix)
* [How to use Corridor (a Tor traffic whitelisting gateway) with Whonix](https://www.whonix.org/wiki/Corridor)
## Support for Whonix
*The following pages are written by the Whonix developers and are located on their website.*
* [Whonix Support](https://www.whonix.org/wiki/Support) - General Whonix, Debian, Tor, etc... related issues
* [Whonix Qubes Forum](https://forums.whonix.org/c/qubes) - Whonix specific issues

24
reference/glossary.md
View File

@ -111,28 +111,32 @@ Firewall Virtual Machine.
A type of [ProxyVM](#proxyvm) that is used to enforce network-level policies (a.k.a. "firewall rules").
A FirewallVM called `sys-firewall` is created by default in most Qubes installations.
DisposableVM
------------
[Disposable Virtual Machine]. A temporary [AppVM](#appvm) based on a [DVM Template](#dvm-template) that can quickly be created, used, and destroyed.
DispVM
------
[Disposable Virtual Machine]. A temporary [AppVM](#appvm) based on a [DVM Template](#dvm-template) that can quickly be created, used, and destroyed.
An older term for [DisposableVM](#disposablevm).
DVM
---
An abbreviation of [DispVM](#dispvm), typically used to refer to [DVM Templates](#dvm-template).
An abbreviation of [DisposableVM](#disposablevm), typically used to refer to [DVM Templates](#dvm-template).
DVM Template
------------
A type of [TemplateBasedVM](#templatebasedvm) on which [DispVMs](#dispvm) are based.
A type of [TemplateBasedVM](#templatebasedvm) on which [DisposableVMs](#disposablevm) are based.
By default, a DVM Template named `fedora-XX-dvm` is created on most Qubes installations (where `XX` is the Fedora version of the default TemplateVM).
DVM Templates are not [TemplateVMs](#templatevm), since (being TemplateBasedVMs) they do not have root filesystems of their own to provide to other VMs.
Rather, DVM Templates are complementary to TemplateVMs insofar as DVM Templates provide their own user filesystems to the DispVMs based on them.
Rather, DVM Templates are complementary to TemplateVMs insofar as DVM Templates provide their own user filesystems to the DisposableVMs based on them.
There are two main kinds of DVM Templates:
* **Dedicated** DVM Templates are intended neither for installing nor running software.
Rather, they are intended for *customizing* or *configuring* software that has already been installed on the TemplateVM on which the DVM Template is based (see [DispVM Customization]).
This software is then intended to be run (in its customized state) in DispVMs that are based on the DVM Template.
* **Non-dedicated** DVM Templates are typically [AppVMs](#appvm) on which DispVMs are based.
Rather, they are intended for *customizing* or *configuring* software that has already been installed on the TemplateVM on which the DVM Template is based (see [DisposableVM Customization]).
This software is then intended to be run (in its customized state) in DisposableVMs that are based on the DVM Template.
* **Non-dedicated** DVM Templates are typically [AppVMs](#appvm) on which DisposableVMs are based.
For example, an AppVM could be used to generate and store trusted data.
Then, a DispVM could be created based on the AppVM (thereby making the AppVM a DVM Template) so that the data can be analyzed by an untrusted program without jeopardizing the integrity of the original data.
Then, a DisposableVM could be created based on the AppVM (thereby making the AppVM a DVM Template) so that the data can be analyzed by an untrusted program without jeopardizing the integrity of the original data.
PV
--
@ -188,6 +192,6 @@ QWT
----
An abbreviation of Qubes [Windows Tools](#windows-tools).
[Disposable Virtual Machine]: /doc/dispvm/
[DispVM Customization]: /doc/dispvm-customization/
[Disposable Virtual Machine]: /doc/disposablevm/
[DisposableVM Customization]: /doc/disposablevm-customization/

2
reference/tools/3.2/dom0/qvm-prefs.md
View File

@ -88,7 +88,7 @@ netvm
dispvm_netvm
Accepted values: netvm name, ``default``, ``none``
Which NetVM should be used for Disposable VMs started by this one.
Which NetVM should be used for DisposableVMs started by this one.
``default`` is to use the same NetVM as the VM itself.
maxmem

2
reference/tools/3.2/domU/qrexec-client-vm.md
View File

@ -44,7 +44,7 @@ OPTIONS
This argument, can contain VM name, or one of special values:
* ``$dispvm`` - new Disposable VM
* ``$dispvm`` - new DisposableVM
This field is limited to 31 characters (alphanumeric, plus ``-_.$``).

4
reference/tools/4.0/domU/qrexec-client-vm.md
View File

@ -43,9 +43,9 @@ OPTIONS
* ``$default`` or empty string - let Qubes RPC policy decide, without giving any preference
* ``$dispvm`` - new Disposable VM
* ``$dispvm`` - new DisposableVM
* ``$dispvm:dispvm-template`` - new Disposable VM based on *dispvm-template*
* ``$dispvm:dispvm-template`` - new DisposableVM based on *dispvm-template*
This field is limited to 31 characters (alphanumeric, plus ``-_.$``).

2
releases/1.0/release-notes.md
View File

@ -20,7 +20,7 @@ Known issues
- Some keyboard layout set by KDE System Settings can cause [keyboard not working at all](https://groups.google.com/group/qubes-devel/browse_thread/thread/77d076b65dda7226). If you hit this issue, you can switch to console (by console login option) and manually edit `/etc/X11/xorg.conf.d/00-system-setup-keyboard.conf` (and `/etc/sysconfig/keyboard`) and place correct keyboard layout settings (details in linked thread). You can check if specific keyboard layout settings are proper using `setxkbmap` tool.
- On systems with more than 8GB of RAM there is problem with Disposable VM. To fix it, limit maximum memory allocation for DispVM to 3GB
- On systems with more than 8GB of RAM there is problem with DisposableVM. To fix it, limit maximum memory allocation for DispVM to 3GB
~~~
qvm-prefs -s fedora-17-x64-dvm maxmem 3072

2
releases/3.1/release-notes.md
View File

@ -71,6 +71,6 @@ using](/doc/releases/3.0/release-notes/#upgrading) first, then follow the
instructions above. This will be time consuming process.
[salt-doc]: /doc/salt/
[pvgrub-doc]: /doc/managing-vm-kernel/#using-kernel-installed-in-the-vm
[pvgrub-doc]: /doc/managing-vm-kernel/#using-kernel-installed-in-the-vm-r32
[input-proxy]: https://github.com/QubesOS/qubes-app-linux-input-proxy/blob/master/README.md
[github-release-notes]: https://github.com/QubesOS/qubes-issues/issues?q=is%3Aissue+sort%3Aupdated-desc+milestone%3A%22Release+3.1%22+label%3Arelease-notes+is%3Aclosed

32
releases/4.0/release-notes.md
View File

@ -16,7 +16,7 @@ New features since 3.2
* Renaming VM directly is prohibited, there is GUI to clone under new name and remove old VM
* Use [PVH][qsb-37] and [HVM][hvm-switch] by default to [mitigate Meltdown & Spectre][qsb-37] and lower the [attack surface on Xen][qsb-24]
* Create USB VM by default
* [Multiple Disposable VMs templates support][dispvm-ticket]
* [Multiple DisposableVMs templates support][dispvm-ticket]
* New [backup format][backup-format] using scrypt key-derivation function
* Non-encrypted backups no longer supported
* [split VM packages][packages-split], for better support minimal, specialized templates
@ -39,6 +39,35 @@ Security Notes
However, PV VMs migrated from any earlier 4.0 release candidate (RC1, RC2, or RC3) are not automatically set to PVH mode.
These must be set manually.
* The following steps may need to be applied in dom0 and Fedora 26 TemplateVMs in order to receive updates (see [#3737]).
Steps for dom0 updates:
1. Open the Qubes Menu by clicking on the "Q" icon in the top-left corner of the screen.
2. Select `Terminal Emulator`.
3. In the window that opens, enter this command:
sudo nano /etc/yum.repos.d/qubes-dom0.repo
4. This opens the nano text editor. Change all four instances of `http` to `https`.
5. Press `CTRL+X`, then `Y`, then `ENTER` to save changes and exit.
6. Check for updates normally.
Steps for Fedora 26 TemplateVM updates:
1. Open the Qubes Menu by clicking on the "Q" icon in the top-left corner of the screen.
2. Select `Template: fedora-26`, then `fedora-26: Terminal`.
3. In the window that opens, enter the command for your version:
[Qubes 3.2] sudo gedit /etc/yum.repos.d/qubes-r3.repo
[Qubes 4.0] sudo gedit /etc/yum.repos.d/qubes-r4.repo
4. This opens the gedit text editor in a window. Change all four instances of `http` to `https`.
5. Click the "Save" button in the top-right corner of the window.
6. Close the window.
7. Check for updates normally.
8. Shut down the TemplateVM.
Known issues
------------
@ -95,3 +124,4 @@ We also provide [detailed instruction][upgrade-to-r4.0] for this procedure.
[upgrade-to-r4.0]: /doc/upgrade-to-r4.0/
[locale-bug]: https://github.com/QubesOS/qubes-issues/issues/3753
[keyboard-layout-bug]: https://github.com/QubesOS/qubes-issues/issues/3352
[#3737]: https://github.com/QubesOS/qubes-issues/issues/3737

2
security-info/canaries.md
View File

@ -40,4 +40,6 @@ Qubes Canaries are published through the [Qubes Security Pack](/security/pack/).
----
- [Qubes Canary \#15](https://github.com/QubesOS/qubes-secpack/blob/master/canaries/canary-015-2018.txt)
- [Qubes Canary \#16](https://github.com/QubesOS/qubes-secpack/blob/master/canaries/canary-016-2018.txt)
- [Qubes Canary \#17](https://github.com/QubesOS/qubes-secpack/blob/master/canaries/canary-017-2018.txt)

7
security-info/security-bulletins.md
View File

@ -89,4 +89,11 @@ Qubes Security Bulletins are published through the [Qubes Security Pack](/securi
- [Qubes Security Bulletin \#37](https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-037-2018.txt) (Information leaks due to processor speculative execution bugs)
- [Qubes Security Bulletin \#38](https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-038-2018.txt) (Qrexec policy bypass and possible information leak)
- [Qubes Security Bulletin \#39](https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-039-2018.txt) (Xen vulnerability (XSA-260) and GUI daemon issue)
- [Qubes Security Bulletin \#40](https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-040-2018.txt) (Information leaks due to processor speculative store bypass (XSA-263))
- [Qubes Security Bulletin \#41](https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-041-2018.txt) (Speculative register leakage from lazy FPU context switching (XSA-267))
- [Qubes Security Bulletin \#42](https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-042-2018.txt) (Linux netback driver OOB access in hash handling (XSA-270))
- [Qubes Security Bulletin \#43](https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-043-2018.txt) (L1 Terminal Fault speculative side channel (XSA-273))
- [Qubes Security Bulletin \#44](https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-044-2018.txt) (Multiple Xen vulnerabilities (XSA-275, XSA-280))
- [Qubes Security Bulletin \#45](https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-045-2018.txt) (Insecure default Salt configuration)

20
security-info/security.md
View File

@ -37,6 +37,17 @@ We promise to treat any reported issue seriously and, if the investigation confi
The Qubes Security Team
-----------------------
The Qubes Security Team (QST) is the subset of the [Qubes Team] that is responsible for ensuring the security of Qubes OS and the Qubes OS Project.
In particular, the QST is responsible for:
- Responding to [reported security issues]
- Evaluating whether [XSAs][Xen Security Advisory (XSA) Tracker] affect the security of Qubes OS
- Writing, applying, and/or distributing security patches to fix vulnerabilities in Qubes OS
- Writing, signing, and publishing [Security Bulletins]
- Writing, signing, and publishing [Canaries]
- Generating, safeguarding, and using the project's [PGP Keys]
As a security-oriented operating system, the QST is fundamentally important to Qubes, and every Qubes user implicitly trusts the members of the QST by virtue of the actions listed above.
The Qubes Security Team can be contacted via email at the following address:
security at qubes-os dot org
@ -50,8 +61,9 @@ Please see [Why and How to Verify Signatures] for information about how to verif
### Members of the Security Team ###
- [Joanna Rutkowska]
- [Marek Marczykowski-Górecki]
- [Simon Gaiser (aka HW42)]
- [Joanna Rutkowska] ([emeritus, canaries only])
[Security FAQ]: /faq/#general--security
@ -62,8 +74,12 @@ Please see [Why and How to Verify Signatures] for information about how to verif
[Xen Security Advisory (XSA) Tracker]: /security/xsa/
[Why and How to Verify Signatures]: /security/verifying-signatures/
[PGP Keys]: https://keys.qubes-os.org/keys/
[Qubes Team]: /team/
[reported security issues]: #reporting-security-issues-in-qubes-os
[Security Team PGP Key]: https://keys.qubes-os.org/keys/qubes-os-security-team-key.asc
[Qubes Master Signing Key]: https://keys.qubes-os.org/keys/qubes-master-signing-key.asc
[Joanna Rutkowska]: /team/#joanna-rutkowska
[Marek Marczykowski-Górecki]: /team/#marek-marczykowski-górecki
[Simon Gaiser (aka HW42)]: /team/#simon-gaiser-aka-hw42
[Joanna Rutkowska]: /team/#joanna-rutkowska
[emeritus, canaries only]: /news/2018/11/05/qubes-security-team-update/

469
security-info/verifying-signatures.md
View File

@ -15,107 +15,91 @@ On Digital Signatures and Key Verification
What Digital Signatures Can and Cannot Prove
--------------------------------------------
Most people – even programmers – are confused about the basic concepts
underlying digital signatures. Therefore, most people should read this section,
even if it looks trivial at first sight.
Most people --- even programmers --- are confused about the basic concepts underlying digital signatures.
Therefore, most people should read this section, even if it looks trivial at first sight.
Digital signatures can prove both **authenticity** and **integrity** to a
reasonable degree of certainty. **Authenticity** ensures that a given file was
indeed created by the person who signed it (i.e., that it was not forged by a
third party). **Integrity** ensures that the contents of the file have not been
tampered with (i.e., that a third party has not undetectably altered its
contents *en route*).
Digital signatures can prove both **authenticity** and **integrity** to a reasonable degree of certainty.
**Authenticity** ensures that a given file was indeed created by the person who signed it (i.e., that it was not forged by a third party).
**Integrity** ensures that the contents of the file have not been tampered with (i.e., that a third party has not undetectably altered its contents *en route*).
Digital signatures **cannot** prove any other property, e.g., that the signed
file is not malicious. In fact, there is nothing that could stop someone from
signing a malicious program (and it happens from time to time in reality).
Digital signatures **cannot** prove any other property, e.g., that the signed file is not malicious.
In fact, there is nothing that could stop someone from signing a malicious program (and it happens from time to time in reality).
The point is, of course, that people must choose who they will trust (e.g.,
Linus Torvalds, Microsoft, the Qubes Project, etc.) and assume that if a given
file was signed by a trusted party, then it should not be malicious or buggy in
some horrible way. But the decision of whether to trust any given party is
beyond the scope of digital signatures. It's more of a sociological and
political decision.
The point is that we must decide who we will trust (e.g., Linus Torvalds, Microsoft, or the Qubes Project) and assume that if a given file was signed by a trusted party, then it should not be malicious or negligently buggy.
The decision of whether to trust any given party is beyond the scope of digital signatures.
It's more of a sociological and political decision.
Once we make the decision to trust certain parties, digital signatures are
useful, because they make it possible for us to limit our trust only to those
few parties we choose and not to worry about all the "Bad Things That Can
Happen In The Middle" between us and them, e.g., server compromises
(qubes-os.org will surely be compromised one day), dishonest IT staff at the
hosting company, dishonest staff at the ISPs, Wi-Fi attacks, etc.
Once we make the decision to trust certain parties, digital signatures are useful, because they make it possible for us to limit our trust only to those few parties we choose and not to worry about all the bad things that can happen between us and them, e.g., server compromises (qubes-os.org will surely be compromised one day, so [don't blindly trust the live version of this site][website-trust]), dishonest IT staff at the hosting company, dishonest staff at the ISPs, Wi-Fi attacks, etc.
We call this philosophy [Distrusting the Infrastructure].
By verifying all the files we download which purport to be authored by a party
we've chosen to trust, we eliminate concerns about the bad things discussed
above, since we can easily detect whether any files have been tampered with
(and subsequently choose to refrain from executing, installing, or opening
them).
By verifying all the files we download that purport to be authored by a party we've chosen to trust, we eliminate concerns about the bad things discussed above, since we can easily detect whether any files have been tampered with (and subsequently choose to refrain from executing, installing, or opening them).
However, for digital signatures to make any sense, we must ensure that the
public keys we use for signature verification are indeed the original ones.
Anybody can generate a GPG key pair that purports to belong to "The Qubes
Project," but of course only the key pair that we (i.e., the Qubes developers)
generated is the legitimate one. The next section explains how to verify the
validity of the Qubes signing keys.
However, for digital signatures to make any sense, we must ensure that the public keys we use for signature verification are indeed the original ones.
Anybody can generate a GPG key pair that purports to belong to "The Qubes Project," but of course only the key pair that we (i.e., the Qubes developers) generated is the legitimate one.
The next section explains how to verify the validity of the Qubes signing keys in the process of verifying a Qubes ISO.
(However, the same general principles apply to all cases in which you may wish to verify a PGP signature, such as [verifying repos], not just verifying ISOs.)
Importing Qubes Signing Keys
----------------------------
Every file published by the Qubes Project (ISO, RPM, TGZ files and git
repositories) is digitally signed by one of the developer or release signing
keys. Each such key is signed by the [Qubes Master Signing Key]
(`0xDDFA1A3E36879494`).
How to Verify Qubes ISO Signatures
----------------------------------
The public portion of the Qubes Master Signing Key can be imported directly
from a [keyserver] (specified on first use with `--keyserver <URI>`, keyserver
saved in `~/.gnupg/gpg.conf`), e.g.,
This section will guide you through the process of verifying a Qubes ISO by checking its PGP signature.
There are three basic steps in this process:
gpg --keyserver pool.sks-keyservers.net --recv-keys 0x427F11FD0FAA4B080123F01CDDFA1A3E36879494
1. [Get the Qubes Master Signing Key and verify its authenticity][QMSK]
2. [Get the Release Signing Key][RSK]
3. [Verify your Qubes ISO][signature file]
or downloaded [here][Qubes Master Signing Key] and imported with gpg,
If you run into any problems, please consult the [Troubleshooting FAQ] below.
$ gpg --import ./qubes-master-signing-key.asc
or fetched directly with gpg.
### 1. Get the Qubes Master Signing Key and verify its authenticity
Every file published by the Qubes Project (ISO, RPM, TGZ files and Git repositories) is digitally signed by one of the developer keys or Release Signing Keys.
Each such key is signed by the [Qubes Master Signing Key] (`0xDDFA1A3E36879494`).
The developer signing keys are set to expire after one year, while the Qubes Master Signing Key and Release Signing Keys have no expiration date.
This Qubes Master Signing Key was generated on and is kept only on a dedicated, air-gapped "vault" machine, and the private portion will (hopefully) never leave this isolated machine.
There are several ways to get the Qubes Master Signing Key.
- Fetch it with GPG:
$ gpg --fetch-keys https://keys.qubes-os.org/keys/qubes-master-signing-key.asc
For additional security we also publish the fingerprint of the Qubes Master
Signing Key here in this document:
- Download it as a [file][Qubes Master Signing Key], then import it with GPG:
$ gpg --import ./qubes-master-signing-key.asc
- Get it from a public [keyserver] (specified on first use with `--keyserver <URI>`, then saved in `~/.gnupg/gpg.conf`), e.g.:
$ gpg --keyserver pool.sks-keyservers.net --recv-keys 0x427F11FD0FAA4B080123F01CDDFA1A3E36879494
The Qubes Master Signing Key is also available in the [Qubes Security Pack] and in the archives of the project's [developer][devel-master-key-msg] and [user][user-master-key-msg] [mailing lists].
Once you have obtained the Qubes Master Signing Key, you should verify the fingerprint of this key very carefully by obtaining copies of the fingerprint from multiple independent sources and comparing them to the downloaded key's fingerprint to ensure they match.
Here are some ideas:
- Use the PGP Web of Trust.
- Check the key against different keyservers.
- Use different search engines to search for the fingerprint.
- Use Tor to view and search for the fingerprint on various websites.
- Use various VPNs and proxy servers.
- Use different Wi-Fi networks (work, school, internet cafe, etc.).
- Ask people to post the fingerprint in various forums and chat rooms.
- Check against PDFs and photographs in which the fingerprint appears
(e.g., slides from a talk or on a T-shirt).
- Repeat all of the above from different computers and devices.
In addition, some operating systems have built-in keyrings containing keys capable of validating the Qubes Master Signing Key.
For example, if you have a Debian system, then your keyring may already contain the necessary keys.
For additional security, we also publish the fingerprint of the Qubes Master Signing Key here (but [remember not to blindly trust the live version of this website][website-trust]):
pub 4096R/36879494 2010-04-01
Key fingerprint = 427F 11FD 0FAA 4B08 0123 F01C DDFA 1A3E 3687 9494
uid Qubes Master Signing Key
There should also be a copy of this key at the project's main website, in the
[Qubes Security Pack], and in the archives of the project's
[developer][devel-master-key-msg] and [user][user-master-key-msg] [mailing lists].
Once you have obtained the Qubes Master Signing Key,
you should verify the fingerprint of this key very carefully by obtaining
copies of the fingerprint from multiple independent sources and comparing
them to the downloaded key's fingerprint to ensure they match. Here are some
ideas:
* Use the PGP Web of Trust.
* Check the key against different keyservers.
* Use different search engines to search for the fingerprint.
* Use Tor to view and search for the fingerprint on various websites.
* Use various VPNs and proxy servers.
* Use different Wi-Fi networks (work, school, internet cafe, etc.).
* Ask people to post the fingerprint in various forums and chat rooms.
* Check against PDFs and photographs in which the fingerprint appears
(e.g., slides from a talk or on a T-shirt).
* Repeat all of the above from different computers and devices.
In addition, some operating systems have built-in keyrings containing keys
capable of validating the Qubes Master Signing Key. For example, if you have
a Debian system, then your debian-keyring may already contain the necessary
keys.
Once you're confident that you have the legitimate Qubes Master Signing Key,
set its trust level to "ultimate" (oh, well), so that it can be used to
automatically verify all the keys signed by the Qubes Master Signing Key:
Once you're confident that you have the legitimate Qubes Master Signing Key, set its trust level to "ultimate" so that it can be used to automatically verify all the keys signed by the Qubes Master Signing Key (in particular, Release Signing Keys).
$ gpg --edit-key 0x36879494
gpg (GnuPG) 1.4.18; Copyright (C) 2014 Free Software Foundation, Inc.
@ -157,72 +141,80 @@ automatically verify all the keys signed by the Qubes Master Signing Key:
gpg> q
Now you can easily download any of the developer or release signing keys that
happen to be used to sign particular ISO, RPM, TGZ files or git tags.
Now, when you import any of the legitimate Qubes developer keys and Release Signing Keys used to sign ISOs, RPMs, TGZs, Git tags, and Git commits, they will already be trusted in virtue of being signed by the Qubes Master Signing Key.
For example, the Qubes OS [Release 3 Signing Key] (`0xCB11CA1D03FA5082`) is
used for all Release 3 ISO images:
$ gpg --recv-keys 0xC52261BE0A823221D94CA1D1CB11CA1D03FA5082
gpg: requesting key 03FA5082 from hkp server keys.gnupg.net
gpg: key 03FA5082: public key "Qubes OS Release 3 Signing Key" imported
gpg: 3 marginal(s) needed, 1 complete(s) needed, PGP trust model
gpg: depth: 0 valid: 1 signed: 1 trust: 0-, 0q, 0n, 0m, 0f, 1u
gpg: depth: 1 valid: 1 signed: 0 trust: 1-, 0q, 0n, 0m, 0f, 0u
gpg: Total number processed: 1
gpg: imported: 1 (RSA: 1)
### 2. Get the Release Signing Key
You can also download all the currently used developers' signing keys and
current and older release signing keys (and also a copy of the Qubes Master
Signing Key) from the [Qubes OS Keyserver] and from the [Qubes Security Pack].
The filename of the Release Signing Key for your version is `qubes-release-X-signing-key.asc`, where `X` is the major version number of your Qubes release.
There are several ways to get the Release Signing Key for your Qubes release.
The developer signing keys are set to be valid for 1 year only, while the Qubes
Master Signing Key has no expiration date. This latter key was generated and is
kept only within a dedicated, air-gapped "vault" machine, and the private
portion will (hopefully) never leave this isolated machine.
- Fetch it with GPG:
You can now verify the ISO image (`Qubes-R3.2-x86_64.iso`) matches its
signature (`Qubes-R3.2-x86_64.iso.asc`):
$ gpg --fetch-keys https://keys.qubes-os.org/keys/qubes-release-X-signing-key.asc
$ gpg -v --verify Qubes-R3.2-x86_64.iso.asc Qubes-R3.2-x86_64.iso
- Download it as a file.
You can find the Release Signing Key for your Qubes version on the [Downloads] page.
You can also download all the currently used developers' signing keys, Release Signing Keys, and the Qubes Master Signing Key from the [Qubes Security Pack] and the [Qubes OS Keyserver].
Once you've downloaded your Release Signing Key, import it with GPG:
$ gpg --import ./qubes-release-X-signing-key.asc
The Release Signing Key should be signed by the Qubes Master Signing Key:
$ gpg --list-sigs "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
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.
It is not necessary to independently verify the authenticity of the Release Signing Key.
### 3. Verify your Qubes ISO
Every Qubes ISO is released with a detached PGP signature file, which you can find on the [Downloads] page alongside the ISO.
If the filename of your ISO is `Qubes-RX-x86_64.iso`, then the name of the signature file for that ISO is `Qubes-RX-x86_64.iso.asc`, where `X` is a specific version of Qubes.
The signature filename is always the same as the ISO filename followed by `.asc`.
Once you've downloaded both the ISO and its signature file, you can verify the ISO using GPG:
$ gpg -v --verify Qubes-RX-x86_64.iso.asc Qubes-RX-x86_64.iso
gpg: armor header: Version: GnuPG v1
gpg: Signature made Tue 08 Mar 2016 07:40:56 PM PST using RSA key ID 03FA5082
gpg: using PGP trust model
gpg: Good signature from "Qubes OS Release 3 Signing Key"
gpg: Good signature from "Qubes OS Release X Signing Key"
gpg: binary signature, digest algorithm SHA256
The Release 3 Signing Key used to sign this ISO image should be signed by the
Qubes Master Signing Key:
$ gpg --list-sig 03FA5082
pub 4096R/03FA5082 2014-11-19
uid Qubes OS Release 3 Signing Key
sig 3 03FA5082 2014-11-19 Qubes OS Release 3 Signing Key
sig 36879494 2014-11-19 Qubes Master Signing Key
This is just an example, so the output you receive will not look exactly the same.
What matters is the line that says `Good signature from "Qubes OS Release X Signing Key"`.
This confirms that the signature on the ISO is good.
Verifying Digests
-----------------
How to Verify Qubes ISO Digests
-------------------------------
Each ISO is also accompanied by a plain text file ending in `.DIGESTS`. This
file contains the output of running several different crytographic hash
functions on the ISO in order to obtain alphanumeric outputs known as "digests"
or "hash values." These hash values are provided as an alternative verification
method to PGP signatures (though the `.DIGESTS` file is itself also PGP-signed
--- see below). If you've already verified the signatures on the ISO directly,
then verifying digests is not necessary. You can always find all the `.DIGESTS`
files for every Qubes ISO in the [Qubes Security Pack].
Each Qubes ISO is also accompanied by a plain text file ending in `.DIGESTS`.
This file contains the output of running several different cryptographic hash functions on the ISO in order to obtain alphanumeric outputs known as "digests" or "hash values."
These hash values are provided as an alternative verification method to PGP signatures (though the digest file is itself also PGP-signed --- see below).
If you've already verified the signatures on the ISO directly, then verifying digests is not necessary.
You can find the `.DIGESTS` for your ISO on the [Downloads] page, and you can always find all the digest files for every Qubes ISO in the [Qubes Security Pack].
As an example, `Qubes-R3.2-x86_64.iso` is accompanied by
`Qubes-R3.2-x86_64.iso.DIGESTS` which has the following content:
If the filename of your ISO is `Qubes-RX-x86_64.iso`, then the name of the digest file for that ISO is `Qubes-RX-x86_64.iso.DIGESTS`, where `X` is a specific version of Qubes.
The digest filename is always the same as the ISO filename followed by `.DIGESTS`.
Since the digest file is a plain text file, you can open it with any text editor.
Inside, you should find text that looks similar to this:
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA256
3c951138b8b9867d8657f173c1b58b82 *Qubes-R3.2-x86_64.iso
1fc9508160d7c4cba6cacc3025165b0f996c843f *Qubes-R3.2-x86_64.iso
6b998045a513dcdd45c1c6e61ace4f1b4e7eff799f381dccb9eb0170c80f678a *Qubes-R3.2-x86_64.iso
de1eb2e76bdb48559906f6fe344027ece20658d4a7f04ba00d4e40c63723171c62bdcc869375e7a4a4499d7bff484d7a621c3acfe9c2b221baee497d13cd02fe *Qubes-R3.2-x86_64.iso
3c951138b8b9867d8657f173c1b58b82 *Qubes-RX-x86_64.iso
1fc9508160d7c4cba6cacc3025165b0f996c843f *Qubes-RX-x86_64.iso
6b998045a513dcdd45c1c6e61ace4f1b4e7eff799f381dccb9eb0170c80f678a *Qubes-RX-x86_64.iso
de1eb2e76bdb48559906f6fe344027ece20658d4a7f04ba00d4e40c63723171c62bdcc869375e7a4a4499d7bff484d7a621c3acfe9c2b221baee497d13cd02fe *Qubes-RX-x86_64.iso
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2
@ -241,74 +233,73 @@ As an example, `Qubes-R3.2-x86_64.iso` is accompanied by
=e9oD
-----END PGP SIGNATURE-----
Four digests have been computed for this ISO. The hash functions used, in order
from top to bottom, are MD5, SHA1, SHA256, and SHA512. One way to verify that
the ISO you downloaded matches any of these hash values is by using the
respective `*sum` programs:
Four digests have been computed for this ISO.
The hash functions used, in order from top to bottom, are MD5, SHA1, SHA256, and SHA512.
One way to verify that the ISO you downloaded matches any of these hash values is by using the respective `*sum` programs:
$ md5sum -c Qubes-R3.2-x86_64.iso.DIGESTS
Qubes-R3.2-x86_64.iso: OK
$ md5sum -c Qubes-RX-x86_64.iso.DIGESTS
Qubes-RX-x86_64.iso: OK
md5sum: WARNING: 23 lines are improperly formatted
$ sha1sum -c Qubes-R3.2-x86_64.iso.DIGESTS
Qubes-R3.2-x86_64.iso: OK
$ sha1sum -c Qubes-RX-x86_64.iso.DIGESTS
Qubes-RX-x86_64.iso: OK
sha1sum: WARNING: 23 lines are improperly formatted
$ sha256sum -c Qubes-R3.2-x86_64.iso.DIGESTS
Qubes-R3.2-x86_64.iso: OK
$ sha256sum -c Qubes-RX-x86_64.iso.DIGESTS
Qubes-RX-x86_64.iso: OK
sha256sum: WARNING: 23 lines are improperly formatted
$ sha512sum -c Qubes-R3.2-x86_64.iso.DIGESTS
Qubes-R3.2-x86_64.iso: OK
$ sha512sum -c Qubes-RX-x86_64.iso.DIGESTS
Qubes-RX-x86_64.iso: OK
sha512sum: WARNING: 23 lines are improperly formatted
The `OK` response tells us that the hash value for that particular hash
function matches. The program also warns us that there are 23 improperly
formatted lines, but this is to be expected. This is because each file contains
lines for several different hash values (as mentioned above), but each `*sum`
program verifies only the line for its own hash function. In addition, there
are lines for the PGP signature which the `*sum` programs do not know how to
read.
The `OK` response tells us that the hash value for that particular hash function matches.
The program also warns us that there are 23 improperly formatted lines, but this is to be expected.
This is because each file contains lines for several different hash values (as mentioned above), but each `*sum` program verifies only the line for its own hash function.
In addition, there are lines for the PGP signature that the `*sum` programs do not know how to read.
Therefore, it is safe to ignore these warning lines.
Another way is to use `openssl` to compute each hash value, then compare them
to the contents of the `.DIGESTS` file.:
Another way is to use `openssl` to compute each hash value, then compare them to the contents of the digest file.:
$ openssl dgst -md5 Qubes-R3.2-x86_64.iso
MD5(Qubes-R3.2-x86_64.iso)= 3c951138b8b9867d8657f173c1b58b82
$ openssl dgst -sha1 Qubes-R3.2-x86_64.iso
SHA1(Qubes-R3.2-x86_64.iso)= 1fc9508160d7c4cba6cacc3025165b0f996c843f
$ openssl dgst -sha256 Qubes-R3.2-x86_64.iso
SHA256(Qubes-R3.2-x86_64.iso)= 6b998045a513dcdd45c1c6e61ace4f1b4e7eff799f381dccb9eb0170c80f678a
$ openssl dgst -sha512 Qubes-R3.2-x86_64.iso
SHA512(Qubes-R3.2-x86_64.iso)= de1eb2e76bdb48559906f6fe344027ece20658d4a7f04ba00d4e40c63723171c62bdcc869375e7a4a4499d7bff484d7a621c3acfe9c2b221baee497d13cd02fe
$ openssl dgst -md5 Qubes-RX-x86_64.iso
MD5(Qubes-RX-x86_64.iso)= 3c951138b8b9867d8657f173c1b58b82
$ openssl dgst -sha1 Qubes-RX-x86_64.iso
SHA1(Qubes-RX-x86_64.iso)= 1fc9508160d7c4cba6cacc3025165b0f996c843f
$ openssl dgst -sha256 Qubes-RX-x86_64.iso
SHA256(Qubes-RX-x86_64.iso)= 6b998045a513dcdd45c1c6e61ace4f1b4e7eff799f381dccb9eb0170c80f678a
$ openssl dgst -sha512 Qubes-RX-x86_64.iso
SHA512(Qubes-RX-x86_64.iso)= de1eb2e76bdb48559906f6fe344027ece20658d4a7f04ba00d4e40c63723171c62bdcc869375e7a4a4499d7bff484d7a621c3acfe9c2b221baee497d13cd02fe
(Notice that the outputs match the values from the `.DIGESTS` file.)
(Notice that the outputs match the values from the digest file.)
However, it is possible that an attacker replaced `Qubes-R3.2-x86_64.iso` with
a malicious ISO, computed the hash values for that ISO, and replaced the values
in `Qubes-R3.2-x86_64.iso.DIGESTS` with his own set of values. Therefore,
ideally, we should also verify the authenticity of the listed hash values.
Since `Qubes-R3.2-x86_64.iso.DIGESTS` is a clearsigned PGP file, we can use
`gpg` to verify it from the command line:
However, it is possible that an attacker replaced `Qubes-RX-x86_64.iso` with a malicious ISO, computed the hash values for that ISO, and replaced the values in `Qubes-RX-x86_64.iso.DIGESTS` with his own set of values.
Therefore, ideally, we should also verify the authenticity of the listed hash values.
Since `Qubes-RX-x86_64.iso.DIGESTS` is a clearsigned PGP file, we can use GPG to verify it from the command line:
$ gpg -v --verify Qubes-R3.2-x86_64.iso.DIGESTS
1. [Get the Qubes Master Signing Key and verify its authenticity][QMSK]
2. [Get the Release Signing Key][RSK]
3. Verify the signature in the digest file:
$ gpg -v --verify Qubes-RX-x86_64.iso.DIGESTS
gpg: armor header: Hash: SHA256
gpg: armor header: Version: GnuPG v2
gpg: original file name=''
gpg: Signature made Tue 20 Sep 2016 10:37:03 AM PDT using RSA key ID 03FA5082
gpg: using PGP trust model
gpg: Good signature from "Qubes OS Release 3 Signing Key"
gpg: Good signature from "Qubes OS Release X Signing Key"
gpg: textmode signature, digest algorithm SHA256
The signature is good. Assuming our copy of the `Qubes OS Release 3 Signing
Key` is also authentic (see above), we can be confident that these hash values
came from the Qubes devs.
The signature is good.
If our copy of the `Qubes OS Release X Signing Key` is being validated by the authentic Qubes Master Signing Key (see [above][QMSK]), we can be confident that these hash values came from the Qubes devs.
Verifying Qubes Code
--------------------
Developers who fetch code from our Git server should always verify the PGP signature of the tag on the latest commit.
In some cases, commits themselves may also be signed.
Any unsigned commit that is not followed by a signed tag should not be trusted!
How to Verify Qubes Repos
-------------------------
To verify a signature on a git tag:
Whenever you use one of the [Qubes repositories], you should verify the PGP signature in a tag on the latest commit or on the latest commit itself.
(One or both may be present, but only one is required.)
If there is no trusted signed tag or commit on top, any commits after the latest trusted signed tag or commit should **not** be trusted.
If you come across a repo with any unsigned commits, you should not add any of your own signed tags or commits on top of them unless you personally vouch for the trustworthiness of the unsigned commits.
Instead, ask the person who pushed the unsigned commits to sign them.
To verify a signature on a Git tag:
$ git tag -v <tag name>
@ -316,7 +307,7 @@ or
$ git verify-tag <tag name>
To verify a signature on a git commit:
To verify a signature on a Git commit:
$ git log --show-signature <commit ID>
@ -324,13 +315,137 @@ or
$ git verify-commit <commit ID>
You should always perform this verification on a trusted local machine with properly validated keys (which are available in the [Qubes Security Pack]) rather than relying on a third party, such as GitHub.
While the GitHub interface may claim that a commit has a verified signature from a member of the Qubes team, this is only trustworthy if GitHub has performed the signature check correctly, the account identity is authentic, the user's key has not been replaced by an admin, GitHub's servers have not been compromised, and so on.
Since there's no way for you to be certain that all such conditions hold, you're much better off verifying signatures yourself.
Also see: [Distrusting the Infrastructure]
Troubleshooting FAQ
-------------------
### Why am I getting "Can't check signature: public key not found"?
You don't have the correct [Release Signing Key][RSK].
### Why am I getting "BAD signature from 'Qubes OS Release X Signing Key'"?
The problem could be one or more of the following:
- You're trying to verify the wrong file(s).
Read this page again carefully.
- You're using the wrong GPG command.
Follow the examples in [Verify your Qubes ISO][signature file] carefully.
- The ISO or [signature file] is bad (e.g., incomplete or corrupt download).
Try downloading the signature file again from a different source, then try verifying again.
If you still get the same result, try downloading the ISO again from a different source, then try verifying again.
### I'm getting "bash: gpg: command not found"
You don't have `gpg` installed.
Install it, or use `gpg2` instead.
### Why am I getting "can't open signed data `Qubes-RX-x86_64.iso' / can't hash datafile: file open error"?
The correct ISO is not in your working directory.
### Why am I getting "can't open `Qubes-RX-x86_64.iso.asc' / verify signatures failed: file open error"?
The correct [signature file] is not in your working directory.
### Why am I getting "no valid OpenPGP data found"?
Either you don't have the correct [signature file], or you inverted the arguments to `gpg`.
([The signature file goes first.][signature file])
### Why am I getting "WARNING: This key is not certified with a trusted signature! There is no indication that the signature belongs to the owner."?
Either you don't have the [Qubes Master Signing Key][QMSK], or you didn't [set its trust level correctly][QMSK].
### Why am I getting "X signature not checked due to a missing key"?
You don't have the keys that created those signatures in your keyring.
For present purposes, you don't need them as long as you have the [Qubes Master Signing Key][QMSK] and the [Release Signing Key][RSK] for your Qubes version.
### Why am I seeing additional signatures on a key with "[User ID not found]" or from a revoked key?
This is just a basic part of how OpenPGP works.
Anyone can sign anyone else's public key and upload the signed public key to keyservers.
Everyone is also free to revoke their own keys at any time (assuming they possess or can create a revocation certificate).
This has no impact on verifying Qubes ISOs, code, or keys.
### Why am I getting "verify signatures failed: unexpected data"?
You're not verifying against the correct [signature file].
### Why am I getting "not a detached signature"?
You're not verifying against the correct [signature file].
### Why am I getting "CRC error; [...] no signature found [...]"?
You're not verifying against the correct [signature file], or the signature file has been modified.
Try downloading it again or from a different source.
### Do I have to verify the ISO against both the [signature file] and the [digest file]?
No, either method is sufficient by itself.
### Why am I getting "no properly formatted X checksum lines found"?
You're not checking the correct [digest file].
### Why am I getting "WARNING: X lines are improperly formatted"?
Read [How to Verify Qubes ISO Digests][digest file] again.
### Why am I getting "WARNING: 1 listed file could not be read"?
The correct ISO is not in your working directory.
### I have another problem that isn't mentioned here.
Carefully read this page again to be certain that you didn't skip any steps.
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].
[website-trust]: /faq/#should-i-trust-this-website
[Distrusting the Infrastructure]: /faq/#what-does-it-mean-to-distrust-the-infrastructure
[verifying repos]: #how-to-verify-qubes-repos
[Qubes Master Signing Key]: https://keys.qubes-os.org/keys/qubes-master-signing-key.asc
[keyserver]: https://en.wikipedia.org/wiki/Key_server_%28cryptographic%29#Keyserver_examples
[Downloads]: /downloads/
[Qubes Security Pack]: /security/pack/
[Qubes OS Keyserver]: https://keys.qubes-os.org/keys/
[devel-master-key-msg]: https://groups.google.com/d/msg/qubes-devel/RqR9WPxICwg/kaQwknZPDHkJ
[user-master-key-msg]: https://groups.google.com/d/msg/qubes-users/CLnB5uFu_YQ/ZjObBpz0S9UJ
[mailing lists]: /support/
[Release 3 Signing Key]: https://keys.qubes-os.org/keys/qubes-release-3-signing-key.asc
[Qubes OS Keyserver]: https://keys.qubes-os.org/keys/
[Troubleshooting FAQ]: #troubleshooting-faq
[QMSK]: #1-get-the-qubes-master-signing-key-and-verify-its-authenticity
[RSK]: #2-get-the-release-signing-key
[signature file]: #3-verify-your-qubes-iso
[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

6
security-info/xsa.md
View File

@ -92,6 +92,12 @@ Tracker
{% if xsa.qsb %}
| <a href="https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-{{ xsa.qsb }}.txt" title="Qubes Security Bulletin {{ xsa.qsb }}">QSB-{{ xsa.qsb }}&nbsp;<span class="fa fa-external-link"></span></a>
{% endif %}
{% elsif xsa.affected == "tba" %}
{% if xsa.tba %}
<a href="{{ xsa.tba }}" title="To be announced. Click for more information.">TBA&nbsp;<span class="fa fa-external-link"></span></a>
{% else %}
<span title="To be announced">TBA</span>
{% endif %}
{% else %}
{% endif %}
</td>

2
security/data-leaks.md
View File

@ -22,7 +22,7 @@ For example, suppose you have an `email` AppVM. You have set the firewall rules
Note that physically air-gapped machines are not necessarily immune to this problem. Covert channels can potentially take many forms (e.g., sneakernet thumb drive, bluetooth, or even microphone and speakers).
For a further discussion of covert channels, see [this thread](https://groups.google.com/d/topic/qubes-users/AqZV65yZLuU/discussion) and ticket 817.
For a further discussion of covert channels, see [this thread](https://groups.google.com/d/topic/qubes-users/AqZV65yZLuU/discussion) and [#817](https://github.com/QubesOS/qubes-issues/issues/817).
Types of Data Leaks
-------------------

7
security/firewall.md
View File

@ -48,9 +48,10 @@ in that VM's directory in dom0:
/var/lib/qubes/appvms/<vm-name>/firewall.xml
Please note that there is a 3 kB limit to the size of the `iptables` script.
Please note that there is a 3 kB limit to the size of the `iptables` script in Qubes versions before R4.0.
This equates to somewhere between 35 and 39 rules.
If this limit is exceeded, the qube will not start.
The limit was removed in R4.0.
It is possible to work around this limit by enforcing the rules on the qube itself
by putting appropriate rules in `/rw/config`.
@ -194,6 +195,8 @@ network 192.168.x.0/24.
> Note: To have all interfaces available and configured, make sure the 3 qubes are up and running
> Note: [Issue #4028](https://github.com/QubesOS/qubes-issues/issues/4028) discusses adding a command to automate exposing the port.
**1. Route packets from the outside world to the FirewallVM**
From a Terminal window in sys-net VM, take note of the 'Interface name' and
@ -384,7 +387,7 @@ fi
# In Qubes OS R4
# If not already present
if nft -nn list table ip qubes-firewall | grep "tcp dport 443 ct state new"; then
if ! nft -nn list table ip qubes-firewall | grep "tcp dport 443 ct state new"; then
# Add a filtering rule
nft add rule ip qubes-firewall forward meta iifname eth0 ip saddr 192.168.x.0/24 ip daddr 10.137.0.y tcp dport 443 ct state new counter accept

63
security/split-gpg.md
View File

@ -14,11 +14,10 @@ redirect_from:
- /wiki/UserDoc/OpenPGP/
---
Qubes Split GPG
===============
# Qubes Split GPG #
## What is Split GPG and why should I use it instead of the standard GPG? ##
What is Split GPG and why should I use it instead of the standard GPG?
----------------------------------------------------------------------
Split GPG implements a concept similar to having a smart card with your
private GPG keys, except that the role of the "smart card" plays another Qubes
AppVM. This way one, not-so-trusted domain, e.g. the one where Thunderbird is
@ -72,12 +71,21 @@ details and plans how to get around this problem, as well as the section on
- It doesn't solve the problem of allowing the user to know what is to be
signed before the operation gets approved. Perhaps the GPG backend domain
could start a Disposable VM and have the to-be-signed document displayed
could start a DisposableVM and have the to-be-signed document displayed
there? To Be Determined.
- The Split GPG client will fail to sign or encrypt if the private key in the
GnuPG backend is protected by a passphrase. It will give an `Inappropriate ioctl
for device` error. Do not set passphrases for the private keys in the GPG
backend domain. Doing so won't provide any extra security anyway, as explained
[above][intro] and [below][using split GPG with subkeys]. If you are generating
a new key pair, or if you have a private key that already has a passphrase, you
can use `gpg2 --edit-key <key_id>` then `passwd` to set an empty passphrase.
Note that `pinentry` might show an error when you try to set an empty
passphrase, but it will still make the change. (See [this StackExchange
answer][se-pinentry] for more information.)
Configuring Split GPG
---------------------
## Configuring Split GPG ##
In dom0, make sure the `qubes-gpg-split-dom0` package is installed.
@ -117,6 +125,9 @@ for key access should be valid (default 5 minutes). This is adjustable via
[user@work-gpg ~]$ echo "export QUBES_GPG_AUTOACCEPT=86400" >> ~/.bash_profile
Please be aware of the caveat regarding passphrase-protected keys in the
[Current limitations][current-limitations] section.
### Configuring the client apps to use Split GPG backend ###
Normally it should be enough to set the `QUBES_GPG_DOMAIN` to the GPG backend
@ -146,7 +157,7 @@ only `gpg2`). If you encounter trouble while trying to set up Split-GPG, make
sure you're using `gpg2` for your configuration and testing, since keyring data
may differ between the two installations.
## Using Thunderbird + Enigmail with Split GPG ##
### Using Thunderbird + Enigmail with Split GPG ###
However, when using Thunderbird with Enigmail extension it is
not enough, because Thunderbird doesn't preserve the environment
@ -163,13 +174,18 @@ the name of the GPG backend VM. This file survives the AppVM reboot, of course.
[user@work ~]$ sudo bash
[root@work ~]$ echo "work-gpg" > /rw/config/gpg-split-domain
A note on passphrases:
#### Qubes 4.0 Specifics ####
You may experience trouble when attempting to use a PGP key *with a passphrase*
along with Split-GPG and Enigmail. If you do, you may need to remove the
passphrase from your (sub)key(s) in order to get Split-GPG working correctly.
As mentioned above, we do not believe PGP key passphrases to be significant
from a security perspective.
New qrexec policies in Qubes R4.0 by default require the user to enter the name
of the domain containing GPG keys each time it is accessed. To improve usability
for Thunderbird+Enigmail, in `dom0` place the following line at the top of the file
`/etc/qubes-rpc/policy/qubes.Gpg`:
```
work-email work-gpg allow
```
where `work-email` is the Thunderbird+Enigmail AppVM and `work-gpg` contains
your GPG keys.
## Using Git with Split GPG ##
@ -227,23 +243,9 @@ displayed to accept this.
<br />
Qubes 4.0
---------
New qrexec policies in Qubes R4.0 by default require the user to enter the name
of the domain containing GPG keys each time it is accessed. To improve usability
for Thunderbird+Enigmail, in `dom0` place the following line at the top of the file
`/etc/qubes-rpc/policy/qubes.Gpg`:
```
work-email work-gpg allow
```
where `work-email` is the Thunderbird+Enigmail AppVM and `work-gpg` contains
your GPG keys.
## Advanced: Using Split GPG with Subkeys ##
<br />
Advanced: Using Split GPG with Subkeys
--------------------------------------
Users with particularly high security requirements may wish to use Split
GPG with [​subkeys]. However, this setup
comes at a significant cost: It will be impossible to sign other people's keys
@ -392,6 +394,8 @@ exercise caution and use your good judgment.)
[#474]: https://github.com/QubesOS/qubes-issues/issues/474
[using split GPG with subkeys]: #advanced-using-split-gpg-with-subkeys
[intro]: #what-is-split-gpg-and-why-should-i-use-it-instead-of-the-standard-gpg
[se-pinentry]: https://unix.stackexchange.com/a/379373
[​subkeys]: https://wiki.debian.org/Subkeys
[copied]: /doc/copying-files#on-inter-qube-file-copy-security
[pasted]: /doc/copy-paste#on-copypaste-security
@ -402,4 +406,5 @@ exercise caution and use your good judgment.)
[cabal]: https://alexcabal.com/creating-the-perfect-gpg-keypair/
[luck]: https://gist.github.com/abeluck/3383449
[apapadop]: https://apapadop.wordpress.com/2013/08/21/using-gnupg-with-qubesos/
[current-limitations]: #current-limitations

210
security/u2f-proxy.md Normal file
View File

@ -0,0 +1,210 @@
---
layout: doc
title: The Qubes U2F Proxy
permalink: /doc/u2f-proxy/
---
# The Qubes U2F Proxy
The [Qubes U2F Proxy] is a secure proxy intended
to make use of U2F two-factor authentication devices with web browsers without
exposing the browser to the full USB stack, not unlike the [USB keyboard and
mouse proxies][USB] implemented in Qubes.
## What is U2F?
[U2F], which stands for "Universal 2nd Factor", is a framework for
authentication using hardware devices (U2F tokens) as "second factors", i.e.
*what you have* as opposed to *what you know*, like a passphrase. This
additional control provides [good protection][krebs] in cases in which the
passphrase is stolen (e.g. by phishing or keylogging). While passphrase
compromise may not be obvious to the user, a physical device that cannot be
duplicated must be stolen to be used outside of the owner's control.
Nonetheless, it is important to note at the outset that U2F cannot guarantee
security when the host system is compromised (e.g. a malware-infected operating
system under an adversary's control).
The U2F specification defines protocols for multiple layers from USB to the
browser API, and the whole stack is intended to be used with web applications
(most commonly websites) in browsers. In most cases, tokens are USB dongles.
The protocol is very simple, allowing the devices to store very little state
inside (so the tokens may be reasonably cheap) while simultaneously
authenticating a virtually unlimited number of services (so each person needs
only one token, not one token per application). The user interface is usually
limited to a single LED and a button that is pressed to confirm each
transaction, so the devices themselves are also easy to use.
Currently, the most common form of two-step authentication consists of a numeric
code that the user manually types into a web application. These codes are
typically generated by an app on the user's smartphone or sent via SMS. By now,
it is well-known that this form of two-step authentication is vulnerable to
phishing and man-in-the-middle attacks due to the fact that the application
requesting the two-step authentication code is typically not itself
authenticated by the user. (In other words, users can accidentally give their
codes to attackers because they do not always know who is really requesting the
code.) In the U2F model, by contrast, the browser ensures that the token
receives valid information about the web application requesting authentication,
so the token knows which application it is authenticating (for details, see
[here][u2f-details]). Nonetheless, [some attacks are still possible][wired] even
with U2F (more on this below).
## The Qubes approach to U2F
In a conventional setup, web browsers and the USB stack (to which the U2F token
is connected) are all running in the same monolithic OS. Since the U2F model
assumes that the browser is trustworthy, any browser in the OS is able to access
any key stored on the U2F token. The user has no way to know which keys have
been accessed by which browsers for which services. If any of the browsers are
compromised, it should be assumed that all of the token's keys have been
compromised. (This problem can be mitigated, however, if the U2F device has a
special display to show the user what's being authenticated.) Moreover, since
the USB stack is in the same monolithic OS, the system is vulnerable to attacks
like [BadUSB].
In Qubes OS, by contrast, it is possible to securely compartmentalise the
browser in one qube and the USB stack in another so that they are always kept
separate from each other. The Qubes U2F Proxy then allows the token connected to
the USB stack in one qube to communicate with the browser in a separate qube. We
operate under the assumption that the USB stack is untrusted from the point of
view of the browser and also that the browser is not to be trusted blindly by
the token. Therefore, the token is never in the same qube as the browser. Our
proxy forwards only the data necessary to actually perform the authentication,
leaving all unnecessary data out, so it won't become a vector of attack. This is
depicted in the diagram below (click for full size).
[![Qubes U2F Proxy diagram](/attachment/wiki/posts/u2f.svg)](/attachment/wiki/posts/u2f.svg)
The Qubes U2F Proxy has two parts: the frontend and the backend. The frontend
runs in the same qube as the browser and presents a fake USB-like HID device
using `uhid`. The backend runs in `sys-usb` and behaves like a browser. This is
done using the `u2flib_host` reference library. All of our code was written in
Python. The standard [qrexec] policy is responsible for directing calls to the
appropriate domains.
The `vault` qube with a dashed line in the bottom portion of the diagram depicts
future work in which we plan to implement the Qubes U2F Proxy with a software
token in an isolated qube rather than a physical hardware token. This is similar
to the manner in which [Split GPG] allows us to emulate the smart card model
without physical smart cards.
One very important assumption of U2F is that the browser verifies every request
sent to the U2F token --- in particular, that the web application sending an
authentication request matches the application that would be authenticated by
answering that request (in order to prevent, e.g., a phishing site from sending
an authentication request for your bank's site). With the WebUSB feature in
Chrome, however, a malicious website can [bypass][wired] this safeguard by
connecting directly to the token instead of using the browser's U2F API.
The Qubes U2F Proxy also prevents this class of attacks by implementing an
additional verification layer. This verification layer allows you to enforce,
for example, that the web browser in your `twitter` qube can only access the U2F
key associated with `https://twitter.com`. This means that if anything in your
`twitter` qube were compromised --- the browser or even the OS itself --- it
would still not be able to access the U2F keys on your token for any other
websites or services, like your email and bank accounts. This is another
significant security advantage over monolithic systems. (For details and
instructions, see the [Advanced usage] section below.)
For even more protection, you can combine this with the [Qubes firewall] to
ensure, for example, that the browser in your `banking` qube accesses only one
website (your bank's website). By configuring the Qubes firewall to prevent your
`banking` qube from accessing any other websites, you reduce the risk of another
website compromising the browser in an attempt to bypass U2F authentication.
## Installation
The Qubes U2F Proxy tool can be installed in Qubes 3.2 and 4.0. (However, the
[Advanced usage] features are only available in 4.0.) These instructions assume
that there is a `sys-usb` qube that holds the USB stack, which is the default
configuration in most Qubes OS installations.
In dom0:
```
$ sudo qubes-dom0-update qubes-u2f-dom0
$ qvm-service --enable work qubes-u2f-proxy
```
In Fedora TemplateVMs:
```
$ sudo dnf install qubes-u2f
```
In Debian TemplateVMs:
```
$ sudo apt install qubes-u2f
```
Repeat `qvm-service --enable` (or do this in VM settings -> Services in the Qube
Manager) for all qubes that should have the proxy enabled. As usual with
software updates, shut down the templates after installation, then restart
`sys-usb` and all qubes that use the proxy. After that, you may use your U2F
token (but see [Browser support] below).
## Advanced usage: per-qube key access
If you are using Qubes 4.0, you can further compartmentalise your U2F keys by
restricting each qube's access to specific keys. For example, you could make it
so that your `twitter` qube (and, therefore, all web browsers in your `twitter`
qube) can access only the key on your U2F token for `https://twitter.com`,
regardless of whether any of the web browsers in your `twitter` qube or the
`twitter` qube itself are compromised. If your `twitter` qube makes an
authentication request for your bank website, it will be denied at the Qubes
policy level.
To enable this, create a file in dom0 named
`/etc/qubes-rpc/policy/policy.RegisterArgument+u2f.Authenticate` with the
following content:
```
sys-usb @anyvm allow,target=dom0
```
Next, empty the contents of `/etc/qubes-rpc/policy/u2f.Authenticate` so that it
is a blank file. Do not delete the file itself. (If you do, the default file
will be recreated the next time you update, so it will no longer be empty.)
Finally, follow your web application's instructions to enroll your token and use
it as usual. (This enrollment process depends on the web application and is in
no way specific to Qubes U2F.)
The default model is to allow a qube to access all and only the keys that were
enrolled by that qube. For example, if your `banking` qube enrolls your banking
key, and your `twitter` qube enrolls your Twitter key, then your `banking` qube
will have access to your banking key but not your Twitter key, and your
`twitter` qube will have access to your Twitter key but not your banking key.
## TemplateVM and browser support
The large number of possible combinations of Qubes version (3.2, 4.0),
TemplateVM (Fedora 27, 28; Debian 8, 9), and browser (multiple Google Chrome
versions, multiple Chromium versions, multiple Firefox versions) made it
impractical for us to test every combination that users are likely to attempt
with the Qubes U2F Proxy. In some cases, you may be the first person to try a
particular combination. Consequently (and as with any new feature), users will
inevitably encounter bugs. We ask for your patience and understanding in this
regard. As always, please [report any bugs you encounter].
Please note that, in Firefox before Quantum (e.g. Firefox 52 in Debian 9), you
have to install the [U2F Support Add-on][ff-u2f-addon]. In Firefox post-Quantum
you may have to enable the `security.webauth.u2f` flag in `about:config`. Chrome
and Chromium do not require any special browser extensions.
[Qubes U2F Proxy]: https://github.com/QubesOS/qubes-app-u2f
[USB]: /doc/usb/
[U2F]: https://en.wikipedia.org/wiki/U2F
[krebs]: https://krebsonsecurity.com/2018/07/google-security-keys-neutralized-employee-phishing/
[u2f-details]: https://fidoalliance.org/specs/fido-u2f-v1.2-ps-20170411/fido-u2f-overview-v1.2-ps-20170411.html#site-specific-public-private-key-pairs
[wired]: https://www.wired.com/story/chrome-yubikey-phishing-webusb/
[BadUSB]: https://www.blackhat.com/us-14/briefings.html#badusb-on-accessories-that-turn-evil
[qrexec]: /doc/qrexec3/
[Split GPG]: /doc/split-gpg/
[Qubes firewall]: /doc/firewall/
[Advanced usage]: #advanced-usage-per-qube-key-access
[Browser support]: #templatevm-and-browser-support
[report any bugs you encounter]: /doc/reporting-bugs/
[ff-u2f-addon]: https://addons.mozilla.org/en-US/firefox/addon/u2f-support-add-on/?src=api
[qubes-devel]: /support/#qubes-devel

3
services/admin-api.md
View File

@ -90,6 +90,9 @@ to set the policy using current mechanism.
| `admin.vm.feature.List` | vm | - | - | `<feature>\n` |
| `admin.vm.feature.Get` | vm | feature | - | value |
| `admin.vm.feature.CheckWithTemplate` | vm | feature | - | value |
| `admin.vm.feature.CheckWithNetvm` | vm | feature | - | value |
| `admin.vm.feature.CheckWithAdminVM` | vm | feature | - | value |
| `admin.vm.feature.CheckWithTemplateAndAdminVM`| vm | feature | - | value |
| `admin.vm.feature.Remove` | vm | feature | - | - |
| `admin.vm.feature.Set` | vm | feature | value | - |
| `admin.vm.tag.List` | vm | - | - | `<tag>\n` |

8
services/dom0-secure-updates.md
View File

@ -32,17 +32,17 @@ Secure update mechanism we use in Qubes (starting from Beta 2)
Keeping Dom0 not connected to any network makes it hard, however, to provide updates for software in Dom0. For this reason we have come up with the following mechanism for Dom0 updates, which minimizes the amount of untrusted input processed by Dom0 software:
The update process is initiated by [qvm-dom0-update script](https://github.com/QubesOS/qubes-core-admin-linux/blob/release2/dom0-updates/qubes-dom0-update), running in Dom0.
The update process is initiated by [qubes-dom0-update script](https://github.com/QubesOS/qubes-core-admin-linux/blob/release2/dom0-updates/qubes-dom0-update), running in Dom0.
Updates (\*.rpm files) are checked and downloaded by UpdateVM, which by default is the same as the firewall VM, but can be configured to be any other, network-connected VM. This is done by [qubes-download-dom0-updates.sh script](https://github.com/QubesOS/qubes-core-agent-linux/blob/release2/misc/qubes-download-dom0-updates.sh) (this script is executed using qrexec by the previously mentioned qvm-dom0-update). Note that we assume that this script might get compromised and fetch maliciously compromised downloads -- this is not a problem as Dom0 verifies digital signatures on updates later. The downloaded rpm files are placed in a ~~~/var/lib/qubes/dom0-updates~~~ directory on UpdateVM filesystem (again, they might get compromised while being kept there, still this isn't a problem). This directory is passed to yum using the ~~~--installroot=~~~ option.
Updates (\*.rpm files) are checked and downloaded by UpdateVM, which by default is the same as the firewall VM, but can be configured to be any other, network-connected VM. This is done by [qubes-download-dom0-updates.sh script](https://github.com/QubesOS/qubes-core-agent-linux/blob/release2/misc/qubes-download-dom0-updates.sh) (this script is executed using qrexec by the previously mentioned qubes-dom0-update). Note that we assume that this script might get compromised and fetch maliciously compromised downloads -- this is not a problem as Dom0 verifies digital signatures on updates later. The downloaded rpm files are placed in a ~~~/var/lib/qubes/dom0-updates~~~ directory on UpdateVM filesystem (again, they might get compromised while being kept there, still this isn't a problem). This directory is passed to yum using the ~~~--installroot=~~~ option.
Once updates are downloaded, the update script that runs in UpdateVM requests an RPM service [qubes.ReceiveUpdates](https://github.com/QubesOS/qubes-core-admin-linux/blob/release2/dom0-updates/qubes.ReceiveUpdates) to be executed in Dom0. This service is implemented by [qubes-receive-updates script](https://github.com/QubesOS/qubes-core-admin-linux/blob/release2/dom0-updates/qubes-receive-updates) running in Dom0. The Dom0's qvm-dom0-update script (which originally initiated the whole update process) waits until qubes-receive-updates finished.
Once updates are downloaded, the update script that runs in UpdateVM requests an RPM service [qubes.ReceiveUpdates](https://github.com/QubesOS/qubes-core-admin-linux/blob/release2/dom0-updates/qubes.ReceiveUpdates) to be executed in Dom0. This service is implemented by [qubes-receive-updates script](https://github.com/QubesOS/qubes-core-admin-linux/blob/release2/dom0-updates/qubes-receive-updates) running in Dom0. The Dom0's qubes-dom0-update script (which originally initiated the whole update process) waits until qubes-receive-updates finished.
The qubes-receive-updates script processes the untrusted input from Update VM: it first extracts the received \*.rpm files (that are sent over qrexec data connection) and then verifies digital signature on each file. The qubes-receive-updates script is a security-critical component of the Dom0 update process (as is the [qfile-dom0-unpacker.c](https://github.com/QubesOS/qubes-core-admin-linux/blob/release2/dom0-updates/qfile-dom0-unpacker.c) and the rpm utility, both used by the qubes-receive-updates for processing the untrusted input).
Once qubes-receive-updates finished unpacking and verifying the updates, the updates are placed in ``qubes-receive-updates`` directory in Dom0 filesystem. Those updates are now trusted. Dom0 is configured (see /etc/yum.conf in Dom0) to use this directory as a default (and only) [yum repository](https://github.com/QubesOS/qubes-core-admin-linux/blob/release2/dom0-updates/qubes-cached.repo).
Finally, qvm-dom0-updates runs ``yum update`` that fetches the rpms from qubes-cached repo and installs them as usual.
Finally, qubes-dom0-update runs ``yum update`` that fetches the rpms from qubes-cached repo and installs them as usual.
Security benefit of our update mechanism
----------------------------------------

2
services/qfilecopy.md
View File

@ -14,7 +14,7 @@ InterVM file copy design
There are two cases when we need a mechanism to copy files between VMs:
- "regular" file copy - when user instructs file manager to copy a given files/directories to a different VM
- DispVM copy - user selects "open in DispVM" on a file; this file must be copied to a Disposable VM, edited by user, and possibly a modified file copied back from DispVM to VM.
- DispVM copy - user selects "open in DispVM" on a file; this file must be copied to a DisposableVM, edited by user, and possibly a modified file copied back from DispVM to VM.
Prior to Qubes Beta1, for both cases, a block device (backed by a file in dom0 with a vfat filesystem on it) was attached to VM, file(s) copied there, and then the device was detached and attached to target VM. In the DispVM case, if a edited file has been modified, another block device is passed to requester VM in order to update the source file.

Some files were not shown because too many files have changed in this diff Show More