diff --git a/_dev/index.rst b/_dev/index.rst
index 55c33dec..39488eb6 100644
--- a/_dev/index.rst
+++ b/_dev/index.rst
@@ -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 `_
* `core-admin-client `_
+
+Or see `the main Qubes OS documentation `_.
diff --git a/about/code-of-conduct.md b/about/code-of-conduct.md
index da9fa936..f6a33467 100644
--- a/about/code-of-conduct.md
+++ b/about/code-of-conduct.md
@@ -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
+
diff --git a/about/faq.md b/about/faq.md
index feed5f28..3afde8b2 100644
--- a/about/faq.md
+++ b/about/faq.md
@@ -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.
diff --git a/about/join.md b/about/join.md
index e8e3a09a..ef195556 100644
--- a/about/join.md
+++ b/about/join.md
@@ -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/).
diff --git a/about/screenshots.md b/about/screenshots.md
index 45dcd963..fc3cb6b5 100644
--- a/about/screenshots.md
+++ b/about/screenshots.md
@@ -85,7 +85,7 @@ Qubes also supports secure file copying between AppVMs.
[](/attachment/wiki/QubesScreenshots/r2b2-open-in-dispvm-1.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.
* * * * *
diff --git a/about/statistics.md b/about/statistics.md
index bc06393f..e46e155d 100644
--- a/about/statistics.md
+++ b/about/statistics.md
@@ -10,10 +10,61 @@ redirect_from:
-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).
diff --git a/about/support.md b/about/support.md
index 1f3124e5..1251f6ea 100644
--- a/about/support.md
+++ b/about/support.md
@@ -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.`, 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.`, 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/
diff --git a/about/video-tours.html b/about/video-tours.html
index b60eee97..381ede16 100644
--- a/about/video-tours.html
+++ b/about/video-tours.html
@@ -5,6 +5,38 @@ permalink: /video-tours/
---
+
+
+
Micah Lee presents "Qubes OS: The Operating System That Can Protect You Even If You Get Hacked"
diff --git a/basics_dev/code-signing.md b/basics_dev/code-signing.md
index caecf566..e826561e 100644
--- a/basics_dev/code-signing.md
+++ b/basics_dev/code-signing.md
@@ -78,6 +78,15 @@ uid Bilbo Baggins
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 -m ""
~~~
- 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
+ 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
diff --git a/basics_dev/gsoc.md b/basics_dev/gsoc.md
index f821e3cc..f3988a5c 100644
--- a/basics_dev/gsoc.md
+++ b/basics_dev/gsoc.md
@@ -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
diff --git a/basics_dev/usability-ux.md b/basics_dev/usability-ux.md
index 03747bd0..d703ec76 100644
--- a/basics_dev/usability-ux.md
+++ b/basics_dev/usability-ux.md
@@ -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
diff --git a/basics_user/doc-guidelines.md b/basics_user/doc-guidelines.md
index 36700c49..4aef9550 100644
--- a/basics_user/doc-guidelines.md
+++ b/basics_user/doc-guidelines.md
@@ -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.
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.
@@ -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
diff --git a/basics_user/getting-started.md b/basics_user/getting-started.md
index 31d345ea..db10e49b 100644
--- a/basics_user/getting-started.md
+++ b/basics_user/getting-started.md
@@ -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.
@@ -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: \**.
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
----------------------------------
diff --git a/basics_user/intro.md b/basics_user/intro.md
index ade01e72..ab259012 100644
--- a/basics_user/intro.md
+++ b/basics_user/intro.md
@@ -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/
diff --git a/basics_user/reporting-bugs.md b/basics_user/reporting-bugs.md
index b75e6e9b..a4d1f408 100644
--- a/basics_user/reporting-bugs.md
+++ b/basics_user/reporting-bugs.md
@@ -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/
diff --git a/building/building-archlinux-template.md b/building/building-archlinux-template.md
index a9989c0d..88f3caf3 100644
--- a/building/building-archlinux-template.md
+++ b/building/building-archlinux-template.md
@@ -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**
@@ -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….
diff --git a/building/building-non-fedora-template.md b/building/building-non-fedora-template.md
index 7dea47dc..182634a4 100644
--- a/building/building-non-fedora-template.md
+++ b/building/building-non-fedora-template.md
@@ -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)
diff --git a/building/building-whonix-template.md b/building/building-whonix-template.md
index da3b93af..6588b973 100644
--- a/building/building-whonix-template.md
+++ b/building/building-whonix-template.md
@@ -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.
diff --git a/building/qubes-builder.md b/building/qubes-builder.md
index c36edcce..7cabbc29 100644
--- a/building/qubes-builder.md
+++ b/building/qubes-builder.md
@@ -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.
diff --git a/building/qubes-r3-building.md b/building/qubes-r3-building.md
index c626462d..95ec587d 100644
--- a/building/qubes-r3-building.md
+++ b/building/qubes-r3-building.md
@@ -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:
diff --git a/common-tasks/backup-emergency-restore-v2.md b/common-tasks/backup-emergency-restore-v2.md
index 05398919..159607f7 100644
--- a/common-tasks/backup-emergency-restore-v2.md
+++ b/common-tasks/backup-emergency-restore-v2.md
@@ -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
diff --git a/common-tasks/backup-emergency-restore-v3.md b/common-tasks/backup-emergency-restore-v3.md
index 05a84017..c2774ee9 100644
--- a/common-tasks/backup-emergency-restore-v3.md
+++ b/common-tasks/backup-emergency-restore-v3.md
@@ -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
diff --git a/common-tasks/backup-emergency-restore-v4.md b/common-tasks/backup-emergency-restore-v4.md
index 3b94a75a..a0199af9 100644
--- a/common-tasks/backup-emergency-restore-v4.md
+++ b/common-tasks/backup-emergency-restore-v4.md
@@ -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
@@ -65,34 +128,56 @@ Recovery - format version 3](/doc/backup-emergency-restore-v3/)
compressed=True
compression-filter=gzip
backup_id=20161020T123455-1234
-
- 6. Verify the integrity and decrypt the `private.img` file which houses your data.
- [user@restore ~]$ backup_id=20161020T123455-1234 # see backup-header above
+ 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 ~]$ 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/
+
diff --git a/common-tasks/disposablevm.md b/common-tasks/disposablevm.md
new file mode 100644
index 00000000..8f1025f3
--- /dev/null
+++ b/common-tasks/disposablevm.md
@@ -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 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 default_dispvm
+
+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.
+
+ 
+
+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.
+
+
+
+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
+
diff --git a/common-tasks/dispvm.md b/common-tasks/dispvm.md
deleted file mode 100644
index 31e477a6..00000000
--- a/common-tasks/dispvm.md
+++ /dev/null
@@ -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 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 default_dispvm
-
-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.
-
- 
-
-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.
-
-
-
-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/).
diff --git a/common-tasks/full-screen-mode.md b/common-tasks/full-screen-mode.md
index e5542918..3ebd6a94 100644
--- a/common-tasks/full-screen-mode.md
+++ b/common-tasks/full-screen-mode.md
@@ -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.
diff --git a/common-tasks/managing-appvm-shortcuts.md b/common-tasks/managing-appvm-shortcuts.md
index e4353e10..8bfc9211 100644
--- a/common-tasks/managing-appvm-shortcuts.md
+++ b/common-tasks/managing-appvm-shortcuts.md
@@ -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
-----------------
diff --git a/common-tasks/software-update-dom0.md b/common-tasks/software-update-dom0.md
index 17cb4491..6bc63a4d 100644
--- a/common-tasks/software-update-dom0.md
+++ b/common-tasks/software-update-dom0.md
@@ -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
diff --git a/common-tasks/software-update-vm.md b/common-tasks/software-update-vm.md
index a34be8da..adc7911b 100644
--- a/common-tasks/software-update-vm.md
+++ b/common-tasks/software-update-vm.md
@@ -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
-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).
diff --git a/about/support.md b/about/support.md
index 1f3124e5..1251f6ea 100644
--- a/about/support.md
+++ b/about/support.md
@@ -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.