Git-Mirrors/qubes-doc
1
0
Fork 0
mirror of https://github.com/QubesOS/qubes-doc.git synced 2024-10-01 01:25:40 -04:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #3 from QubesOS/master

Browse Source 
update
This commit is contained in:
tasket 2017-07-10 06:42:10 -04:00 committed by GitHub
commit 4d392ac225
183 changed files with 8580 additions and 3316 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
.travis.yml Normal file
View File

@ -0,0 +1,6 @@
language: ruby
dist: trusty
rvm:
- 2.1
install: git clone https://github.com/${TRAVIS_REPO_SLUG%%/*}/qubesos.github.io ~/qubesos.github.io
script: ~/qubesos.github.io/_utils/travis.sh

59
CONTRIBUTING.md
View File

@ -2,58 +2,9 @@ Contributing to `qubes-doc`
===========================
Thank you for your interest in contributing to `qubes-doc`, the Qubes OS
Project's dedicated documentation repository! Please take a moment to
familiarize yourself with the terms defined in the [glossary], and try to use
these terms consistently and accurately throughout your writing and editing.
Please report all documentation issues in [qubes-issues].
Markdown Conventions
--------------------
All the documentation is written in Markdown for maximum accessibility. When
making contributions, please try to observe the following style conventions:
* Use spaces instead of tabs.
* Hard wrap Markdown lines at 80 characters.
* If appropriate, make numerals in numbered lists match between Markdown
source and HTML output.
* Rationale: In the event that a user is required to read the Markdown source
directly, this will make it easier to follow, e.g., numbered steps in a set
of instructions.
* Use hanging indentations
where appropriate.
* Use underline headings (`=====` and `-----`) if possible. If this is not
possible, use Atx-style headings on both the left and right sides
(`### H3 ###`).
* Use `[reference-style][ref]` links.
`[ref]: https://daringfireball.net/projects/markdown/syntax#link`
([This][md] is a great source for learning about Markdown.)
Git Conventions
---------------
Please attempt to follow these conventions when writing your Git commit
messages:
* Separate the subject line from the body with a blank line.
* Limit the subject line to approximately 50 characters.
* Capitalize the subject line.
* Do not end the subject line with a period.
* Use the imperative mood in the subject line.
* Wrap the body at 72 characters.
* Use the body to explain *what* and *why* rather than *how*.
For details, examples, and the rationale behind each of these conventions,
please see [this blog post][git-commit], which is the source of this list.
[glossary]: https://www.qubes-os.org/doc/glossary/
[qubes-issues]: https://github.com/QubesOS/qubes-issues/issues
[md]: https://daringfireball.net/projects/markdown/
[git-commit]: http://chris.beams.io/posts/git-commit/
Project's dedicated documentation repository! Please take a moment to read our
[Documentation Guidelines] before you begin writing. These guidelines are
important to maintaining high quality documentation, and following them will
increase the likelihood that your contribution will be accepted.
[Documentation Guidelines]: https://www.qubes-os.org/doc/doc-guidelines/

177
_dev/Makefile Normal file
View File

@ -0,0 +1,177 @@
# Makefile for Sphinx documentation
#
# You can set these variables from the command line.
SPHINXOPTS =
SPHINXBUILD = sphinx-build
PAPER =
BUILDDIR = _build
# User-friendly check for sphinx-build
ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)
endif
# Internal variables.
PAPEROPT_a4 = -D latex_paper_size=a4
PAPEROPT_letter = -D latex_paper_size=letter
ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
# the i18n builder cannot share the environment and doctrees with the others
I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
help:
@echo "Please use \`make <target>' where <target> is one of"
@echo " html to make standalone HTML files"
@echo " dirhtml to make HTML files named index.html in directories"
@echo " singlehtml to make a single large HTML file"
@echo " pickle to make pickle files"
@echo " json to make JSON files"
@echo " htmlhelp to make HTML files and a HTML help project"
@echo " qthelp to make HTML files and a qthelp project"
@echo " devhelp to make HTML files and a Devhelp project"
@echo " epub to make an epub"
@echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
@echo " latexpdf to make LaTeX files and run them through pdflatex"
@echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx"
@echo " text to make text files"
@echo " man to make manual pages"
@echo " texinfo to make Texinfo files"
@echo " info to make Texinfo files and run them through makeinfo"
@echo " gettext to make PO message catalogs"
@echo " changes to make an overview of all changed/added/deprecated items"
@echo " xml to make Docutils-native XML files"
@echo " pseudoxml to make pseudoxml-XML files for display purposes"
@echo " linkcheck to check all external links for integrity"
@echo " doctest to run all doctests embedded in the documentation (if enabled)"
clean:
rm -rf $(BUILDDIR)/*
html:
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
dirhtml:
$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
singlehtml:
$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
@echo
@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
pickle:
$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
@echo
@echo "Build finished; now you can process the pickle files."
json:
$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
@echo
@echo "Build finished; now you can process the JSON files."
htmlhelp:
$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
@echo
@echo "Build finished; now you can run HTML Help Workshop with the" \
".hhp project file in $(BUILDDIR)/htmlhelp."
qthelp:
$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
@echo
@echo "Build finished; now you can run "qcollectiongenerator" with the" \
".qhcp project file in $(BUILDDIR)/qthelp, like this:"
@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/QubesOSDeveloper.qhcp"
@echo "To view the help file:"
@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/QubesOSDeveloper.qhc"
devhelp:
$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
@echo
@echo "Build finished."
@echo "To view the help file:"
@echo "# mkdir -p $$HOME/.local/share/devhelp/QubesOSDeveloper"
@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/QubesOSDeveloper"
@echo "# devhelp"
epub:
$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
@echo
@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
latex:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo
@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
@echo "Run \`make' in that directory to run these through (pdf)latex" \
"(use \`make latexpdf' here to do that automatically)."
latexpdf:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo "Running LaTeX files through pdflatex..."
$(MAKE) -C $(BUILDDIR)/latex all-pdf
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
latexpdfja:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo "Running LaTeX files through platex and dvipdfmx..."
$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
text:
$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
@echo
@echo "Build finished. The text files are in $(BUILDDIR)/text."
man:
$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
@echo
@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
texinfo:
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
@echo
@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
@echo "Run \`make' in that directory to run these through makeinfo" \
"(use \`make info' here to do that automatically)."
info:
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
@echo "Running Texinfo files through makeinfo..."
make -C $(BUILDDIR)/texinfo info
@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
gettext:
$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
@echo
@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
changes:
$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
@echo
@echo "The overview file is in $(BUILDDIR)/changes."
linkcheck:
$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
@echo
@echo "Link check complete; look for any errors in the above output " \
"or in $(BUILDDIR)/linkcheck/output.txt."
doctest:
$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
@echo "Testing of doctests in the sources finished, look at the " \
"results in $(BUILDDIR)/doctest/output.txt."
xml:
$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
@echo
@echo "Build finished. The XML files are in $(BUILDDIR)/xml."
pseudoxml:
$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
@echo
@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."

0
_dev/_build/.gitignore vendored Normal file
View File

0
_dev/_static/.gitignore vendored Normal file
View File

0
_dev/_templates/.gitignore vendored Normal file
View File

193
_dev/conf.py Normal file
View File

@ -0,0 +1,193 @@
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
#
# Qubes OS developer's documentation build configuration file, created by
# sphinx-quickstart on Tue May 30 16:30:03 2017.
#
# This file is execfile()d with the current directory set to its
# containing dir.
#
# Note that not all possible configuration values are present in this
# autogenerated file.
#
# All configuration values have a default; values that are commented out
# serve to show the default.
import os
import sys
import datetime
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#sys.path.insert(0, os.path.abspath('.'))
# -- General configuration ------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
#needs_sphinx = '1.0'
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
'sphinx.ext.intersphinx',
'sphinx.ext.todo',
]
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
# The suffix of source filenames.
source_suffix = '.rst'
# The encoding of source files.
#source_encoding = 'utf-8-sig'
# The master toctree document.
master_doc = 'index'
# General information about the project.
project = 'Qubes OS'
copyright = '2010-{:%Y}, Invisible Things Lab'.format(datetime.date.today())
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
# The short X.Y version.
version = 'R4'
# The full version, including alpha/beta/rc tags.
release = 'R4.0'
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#language = None
# There are two options for replacing |today|: either, you set today to some
# non-false value, then it is used:
#today = ''
# Else, today_fmt is used as the format for a strftime call.
today_fmt = '%Y-%m-%d'
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
exclude_patterns = ['_build']
# The reST default role (used for this markup: `text`) to use for all
# documents.
#default_role = None
# If true, '()' will be appended to :func: etc. cross-reference text.
#add_function_parentheses = True
# If true, the current module name will be prepended to all description
# unit titles (such as .. function::).
#add_module_names = True
# If true, sectionauthor and moduleauthor directives will be shown in the
# output. They are ignored by default.
#show_authors = False
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'
# A list of ignored prefixes for module index sorting.
#modindex_common_prefix = []
# If true, keep warnings as "system message" paragraphs in the built documents.
#keep_warnings = False
# -- Options for HTML output ----------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
html_theme = 'nature'
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
#html_theme_options = {}
# Add any paths that contain custom themes here, relative to this directory.
#html_theme_path = []
# The name for this set of Sphinx documents. If None, it defaults to
# "<project> v<release> documentation".
#html_title = None
# A shorter title for the navigation bar. Default is the same as html_title.
#html_short_title = None
# The name of an image file (relative to this directory) to place at the top
# of the sidebar.
#html_logo = None
# The name of an image file (within the static path) to use as favicon of the
# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
# pixels large.
#html_favicon = None
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']
# Add any extra paths that contain custom files (such as robots.txt or
# .htaccess) here, relative to this directory. These files are copied
# directly to the root of the documentation.
#html_extra_path = []
# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
# using the given strftime format.
#html_last_updated_fmt = '%b %d, %Y'
# If true, SmartyPants will be used to convert quotes and dashes to
# typographically correct entities.
#html_use_smartypants = True
# Custom sidebar templates, maps document names to template names.
#html_sidebars = {}
# Additional templates that should be rendered to pages, maps page names to
# template names.
#html_additional_pages = {}
# If false, no module index is generated.
#html_domain_indices = True
# If false, no index is generated.
#html_use_index = True
# If true, the index is split into individual pages for each letter.
#html_split_index = False
# If true, links to the reST sources are added to the pages.
#html_show_sourcelink = True
# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
#html_show_sphinx = True
# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
#html_show_copyright = True
# If true, an OpenSearch description file will be output, and all pages will
# contain a <link> tag referring to it. The value of this option must be the
# base URL from which the finished HTML is served.
#html_use_opensearch = ''
# This is the file name suffix for HTML files (e.g. ".xhtml").
#html_file_suffix = None
# Output file base name for HTML help builder.
htmlhelp_basename = 'QubesOSdev'
# Example configuration for intersphinx: refer to the Python standard library.
intersphinx_mapping = {
'python': ('http://docs.python.org/', None),
# 'core-admin': ('https://dev.qubes-os.org/projects/core-admin/en/latest/', None),
}
# vim: ts=4 sts=4 sw=4 et

15
_dev/index.rst Normal file
View File

@ -0,0 +1,15 @@
Welcome to Qubes OS developer's documentation!
==============================================
Contents:
.. toctree::
:maxdepth: 2
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

265
basics/user-faq.md
View File

@ -1,265 +0,0 @@
---
layout: doc
title: Users' FAQ
permalink: /doc/user-faq/
redirect_from:
- /en/doc/user-faq/
- /doc/UserFaq/
- /wiki/UserFaq/
---
Qubes Users' FAQ
================
[General Questions](#general-questions)
---------------------------------------
* [Is Qubes just another Linux distribution?](#is-qubes-just-another-linux-distribution)
* [How is Qubes different from other security solutions?](#how-is-qubes-different-from-other-security-solutions)
* [What is the main concept behind Qubes?](#what-is-the-main-concept-behind-qubes)
* [What about other approaches to security?](#what-about-other-approaches-to-security)
* [What about safe languages and formally verified microkernels?](#what-about-safe-languages-and-formally-verified-microkernels)
* [Why does Qubes use virtualization?](#why-does-qubes-use-virtualization)
* [What do all these terms mean?](#what-do-all-these-terms-mean)
* [Does Qubes run every app in a separate VM?](#does-qubes-run-every-app-in-a-separate-vm)
* [Why does Qubes use Xen instead of KVM or some other hypervisor?](#why-does-qubes-use-xen-instead-of-kvm-or-some-other-hypervisor)
* [What about this other/new (micro)kernel/hypervisor?](#what-about-this-othernew-microkernelhypervisor)
* [What's so special about Qubes' GUI virtualization?](#whats-so-special-about-qubes-gui-virtualization)
* [Can I watch YouTube videos in qubes?](#can-i-watch-youtube-videos-in-qubes)
* [Can I run applications, like games, which require 3D support?](#can-i-run-applications-like-games-which-require-3d-support)
* [Is Qubes a multi-user system?](#is-qubes-a-multi-user-system)
* [Why passwordless sudo?](#why-passwordless-sudo)
* [How should I report documentation issues?](#how-should-i-report-documentation-issues)
* [Will Qubes seek to get certified on the GNU Free System Distribution Guidelines (GNU FSDG)?](#will-qubes-seek-gnu-fsdg)
[Installation & Hardware Compatibility](#installation--hardware-compatibility)
------------------------------------------------------------------------------
* [How much disk space does each qube require?](#how-much-disk-space-does-each-qube-require)
* [How much memory is recommended for Qubes?](#how-much-memory-is-recommended-for-qubes)
* [Can I install Qubes on a system without VT-x?](#can-i-install-qubes-on-a-system-without-vt-x)
* [Can I install Qubes on a system without VT-d?](#can-i-install-qubes-on-a-system-without-vt-d)
* [Can I use AMD-v instead of VT-x?](#can-i-use-amd-v-instead-of-vt-x)
* [Can I install Qubes in a virtual machine (e.g., on VMWare)?](#can-i-install-qubes-in-a-virtual-machine-eg-on-vmware)
* [Why does my network adapter not work?](#why-does-my-network-adapter-not-work)
* [Can I install Qubes OS together with other operating system (dual-boot/multi-boot)?](#can-i-install-qubes-os-together-with-other-operating-system-dual-bootmulti-boot)
[Common Problems](#common-problems)
-----------------------------------
* [My qubes lost Internet access after a TemplateVM update. What should I do?](#my-qubes-lost-internet-access-after-a-templatevm-update-what-should-i-do)
* [My keyboard layout settings are not behaving correctly. What should I do?](#my-keyboard-layout-settings-are-not-behaving-correctly-what-should-i-do)
* [My dom0 and/or TemplateVM update stalls when attempting to update via …](#my-dom0-andor-templatevm-update-stalls-when-attempting-to-update-via-the-gui-tool-what-should-i-do)
* [How do I run a Windows HVM in non-seamless mode (i.e., as a single window)?](#how-do-i-run-a-windows-hvm-in-non-seamless-mode-ie-as-a-single-window)
* [I created a usbVM and assigned usb controllers to it. Now the usbVM wont boot.](#i-created-a-usbvm-and-assigned-usb-controllers-to-it-now-the-usbvm-wont-boot)
* [I assigned a PCI device to a qube, then unassigned it/shut down the …](#i-assigned-a-pci-device-to-a-qube-then-unassigned-itshut-down-the-qube`-why-isnt-the-device-available-in-dom0)
* [How do I install Flash in a Debian qube?](#how-do-i-install-flash-in-a Debian-qube)
-----------------
General Questions
-----------------
### Is Qubes just another Linux distribution?
If you really want to call it a distribution, then it's more of a "Xen distribution" than a Linux one. But Qubes is much more than just Xen packaging. It has its own VM management infrastructure, with support for template VMs, centralized VM updating, etc. It also has a very unique GUI virtualization infrastructure.
### How is Qubes different from other security solutions?
Please see [this article](http://theinvisiblethings.blogspot.com/2012/09/how-is-qubes-os-different-from.html) for a thorough discussion.
### What is the main concept behind Qubes?
To build security on the “Security by Compartmentalization (or Isolation)” principle.
### What about other approaches to security?
The other two popular [approaches](http://theinvisiblethings.blogspot.com/2008/09/three-approaches-to-computer-security.html) are “Security by Correctness” and “Security by Obscurity.” We don't believe either of these approaches are capable of providing reasonable security today, nor do we believe that they will be capable of doing so in the foreseeable future.
### What about safe languages and formally verified microkernels?
In short: these are non-realistic solutions today. We discuss this in further depth in our [Architecture Specification document](/attachment/wiki/QubesArchitecture/arch-spec-0.3.pdf).
### Why does Qubes use virtualization?
We believe that this is currently the only practically viable approach to implementing strong isolation while simultaneously providing compatibility with existing applications and drivers.
### What do all these terms mean?
All Qubes-specific terms are defined in the [glossary](/doc/glossary/).
### Does Qubes run every app in a separate VM?
No! This would not make much sense. Qubes uses lightweight VMs to create security qubes (e.g., "work," "personal," and "banking,"). A typical user would likely need around five qubes. Very paranoid users, or those who are high-profile targets, might use a dozen or more qubes.
### Why does Qubes use Xen instead of KVM or some other hypervisor?
In short: we believe the Xen architecture allows for the creation of more secure systems (i.e. with a much smaller TCB, which translates to a smaller attack surface). We discuss this in much greater depth in our [Architecture Specification document](/attachment/wiki/QubesArchitecture/arch-spec-0.3.pdf).
### What about this other/new (micro)kernel/hypervisor?
Whenever starting a discussion about another (micro)kernel or hypervisor in relation to Qubes, we strongly suggest including answers to the following questions first:
1. What kinds of containers does it use for isolation? Processes? PV VMs? Fully virtualized VMs (HVMs)? And what underlying h/w technology is used (ring0/3, VT-x)?
2. Does it require specially written/built applications (e.g. patched Firefox)?
3. Does it require custom drivers, or can it use Linux/Windows ones?
4. Does it support VT-d, and does it allow for the creation of untrusted driver domains?
5. Does it support S3 sleep?
6. Does it work on multiple CPUs/Chipsets?
7. What are the performance costs, more or less? (e.g. "XYZ prevents concurrent execution of two domains/processes on shared cores of a single processor", etc.)
8. Other special features? E.g. eliminates cooperative covert channels between VMs?
Here are the answers for Xen 4.1 (which we use as of 2014-04-28):
1. PV and HVM Virtual Machines (ring0/3 for PV domains, VT-x/AMD-v for HVMs).
2. Runs unmodified usermode apps (binaries).
3. Runs unmodified Linux drivers (dom0 and driver domains). PV VMs require special written pvdrivers.
4. Full VT-d support including untrusted driver domains.
5. S3 sleep supported well.
6. Works on most modern CPUs/Chipsets.
7. Biggest performance hit on disk operations (especially in Qubes when complex 2-layer mapping used for Linux qubes). No GPU virtualization.
8. Mostly Works<sup>TM</sup> :)
### What's so special about Qubes' GUI virtualization?
We have designed the GUI virtualization subsystem with two primary goals: security and performance. Our GUI infrastructure introduces only about 2,500 lines of C code (LOC) into the privileged domain (Dom0), which is very little, and thus leaves little space for bugs and potential attacks. At the same time, due to the smart use of Xen shared memory, our GUI implementation is very efficient, so most virtualized applications really feel as if they were executed natively.
### Can I watch YouTube videos in qubes?
Absolutely.
### Can I run applications, like games, which require 3D support?
Those won’t fly. We do not provide OpenGL virtualization for qubes. This is mostly a security decision, as implementing such a feature would most likely introduce a great deal of complexity into the GUI virtualization infrastructure. However, Qubes does allow for the use of accelerated graphics (OpenGL) in Dom0’s Window Manager, so all the fancy desktop effects should still work.
For further discussion about the potential for GPU passthorugh on Xen/Qubes, please see the following threads:
- [GPU passing to HVM](https://groups.google.com/group/qubes-devel/browse_frm/thread/31f1f2da39978573?scoring=d&q=GPU&)
- [Clarifications on GPU security](https://groups.google.com/group/qubes-devel/browse_frm/thread/31e2d8a47c8b4474?scoring=d&q=GPU&)
### Is Qubes a multi-user system?
No. Qubes does not pretend to be a multi-user system. Qubes assumes that the user who controls Dom0 controls the whole system. It would be very difficult to **securely** implement multi-user support. See [here](https://groups.google.com/group/qubes-devel/msg/899f6f3efc4d9a06) for details.
### Why passwordless sudo?
Please refer to [this page](https://www.qubes-os.org/doc/vm-sudo/).
### How should I report documentation issues?
Please see the [documentation guidelines](/doc/doc-guidelines).
### Will Qubes seek to get certified under the GNU Free System Distribution Guidelines (GNU FSDG)?
Not currently, for the same reasons that [Debian is not certified](https://www.gnu.org/distros/common-distros.en.html).
Installation & Hardware Compatibility
-------------------------------------
(See also: [System Requirements](/doc/system-requirements/), [Hardware Compatibility List](/hcl/), and [Certified Laptops](/doc/certified-laptops/).)
### How much disk space does each qube require?
Each qube is created from a TemplateVM and shares the root filesystem with this TemplateVM (in a read-only manner). This means that each qube needs only as much disk space as is necessary to store its own private data. This also means that it is possible to update the software for several qubes simultaneously by running a single update process in the TemplateVM upon which those qubes are based. (These qubes will then have to be restarted in order for the update to take effect in them.)
### How much memory is recommended for Qubes?
At least 4 GB. It is possible to install Qubes on a system with 2 GB of RAM, but the system would probably not be able to run more than three qubes at a time.
### Can I install Qubes on a system without VT-x?
Yes. Xen doesn't use VT-x (or AMD-v) for PV guest virtualization. (It uses ring0/3 separation instead.) However, without VT-x, you won't be able to use fully virtualized VMs (e.g., Windows-based qubes), which were introduced in Qubes 2. In addition, if your system lacks VT-x, then it also lacks VT-d. (See next question.)
### Can I install Qubes on a system without VT-d?
Yes. You can even run a NetVM, but you will not benefit from DMA protection for driver domains. On a system without VT-d, everything should work in the same way, except there will be no real security benefit to having a separate NetVM, as an attacker could always use a simple DMA attack to go from the NetVM to Dom0. **Nonetheless, all of Qubes' other security mechanisms, such as qube separation, work without VT-d. Therefore, a system running Qubes will still be significantly more secure than one running Windows, Mac, or Linux, even if it lacks VT-d.**
### Can I use AMD-v instead of VT-x?
See [this message](http://groups.google.com/group/qubes-devel/msg/6412170cfbcb4cc5).
### Can I install Qubes in a virtual machine (e.g., on VMWare)?
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!)
### 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.
Open a terminal and run `sudo yum install linux-firmware` in the TemplateVM upon which your NetVM is based. You have to restart the NetVM after the TemplateVM has been shut down.
### Can I install Qubes OS together with other operating system (dual-boot/multi-boot)?
You shouldn't do that, because it pose a security risk for your Qubes OS
installation. But if you understand the risk and accept it, read [documentation
on multibooting](/doc/multiboot/). It starts with explanation what is wrong
with using such setup.
Common Problems
---------------
### My qubes lost Internet access after a TemplateVM update. What should I do?
Run `systemctl enable NetworkManager-dispatcher.service` in the TemplateVM upon which your NetVM is based. You may have to reboot afterward for the change to take effect. (Note: This is an upstream problem. See [here](https://bugzilla.redhat.com/show_bug.cgi?id=974811). For details, see the qubes-users mailing list threads [here](https://groups.google.com/d/topic/qubes-users/xPLGsAJiDW4/discussion) and [here](https://groups.google.com/d/topic/qubes-users/uN9G8hjKrGI/discussion).)
### My keyboard layout settings are not behaving correctly. What should I do?
Please read [this discussion](https://groups.google.com/d/topic/qubes-devel/d8ZQ_62asKI/discussion).
### My dom0 and/or TemplateVM update stalls when attempting to update via the GUI tool. What should I do?
This can usually be fixed by updating via the command line.
In dom0, open a terminal and run `sudo qubes-dom0-update`.
In your TemplateVMs, open a terminal and run `sudo yum upgrade`.
### How do I run a Windows HVM in non-seamless mode (i.e., as a single window)?
Enable "debug mode" in the qube's settings, either by checking the box labeled "Run in debug mode" in the Qubes VM Manager qube settings menu or by running the [qvm-prefs command](/doc/dom0-tools/qvm-prefs/).)
### I created a usbVM and assigned usb controllers to it. Now the usbVM wont boot.
This is probably because one of the controllers does not support reset. In Qubes R2 any such errors were ignored but in Qubes R3.0 they are not.
A device that does not support reset is not safe and generally should not be assigned to a VM.
Most likely the offending controller is a USB3.0 device. You can remove this controller from the usbVM, and see if this allows the VM to boot.
Alternatively you may be able to disable USB 3.0 in the BIOS.
Another solution would be to set the pci_strictreset option using qvm-prefs in dom0:
`qvm-prefs usbVM -s pci_strictreset false`
This option allows the VM to ignore the error and the VM will start.
Please review the note on [this page](https://www.qubes-os.org/doc/Dom0Tools/QvmPrefs/) and be aware of the potential risk.
### I assigned a PCI device to a qube, then unassigned it/shut down the qube. Why isn't the device available in dom0?
This is an intended feature. A device which was previously assigned to a less trusted qube could attack dom0 if it were automatically reassigned there. In order to re-enable the device in dom0, either:
* Reboot the physical machine.
or
* Go to the sysfs (`/sys/bus/pci`), find the right device, detach it from the pciback driver and attach back to the original driver. Replace `<BDF>` with your device, for example `00:1c.2`:
echo 0000:<BDF> > /sys/bus/pci/drivers/pciback/unbind
MODALIAS=`cat /sys/bus/pci/devices/0000:<BDF>/modalias`
MOD=`modprobe -R $MODALIAS | head -n 1`
echo 0000:<BDF> > /sys/bus/pci/drivers/$MOD/bind
### How do I install Flash in a Debian qube?
The Debian way is to install the flashplugin-nonfree package. Do this in a Debian template. You will have to allow Full access in the firewall prior to installation. This will make Flash available to every qube using that template.
If you only want Flash available in one qube:
- download the Flash Player for linux (64 bit) .tar.gz from [Adobe](https://get.adobe.com/flashplayer/otherversions).
- untar the downloaded file ```tar xf install_flash_player_11_linux.x86_64.tar.gz```
- create ~/.mozilla/plugins if it does not exist
- move libflashhplayer.so to ~/.mozilla/plugins, and restart iceweasel.

9
developers/code-signing.md → basics_dev/code-signing.md
View File

@ -7,8 +7,7 @@ permalink: /doc/code-signing/
Code Signing
============
All contributions to the Qubes OS [source code] must be cryptographically signed
by the author's PGP key.
All contributions to the Qubes OS [source code] must be cryptographically signed by the author's PGP key.
Generating a Key
@ -127,9 +126,9 @@ your Git commits.
Using PGP with Email
--------------------
If you're submitting a patch via email (to the developer [mailing list]), simply
sign your email with your PGP key. (One good way to do this is with a program
like [Enigmail].)
If you're submitting a patch by emailing the developer [mailing list], simply sign your email with your PGP key.
One good way to do this is with a program like [Enigmail].
Enigmail is a security addon for the Mozilla Thunderbird email client that allows you to easily digitally encrypt and sign your emails.
[guide]: https://alexcabal.com/creating-the-perfect-gpg-keypair/

43
developers/coding-style.md → basics_dev/coding-style.md
View File

@ -15,39 +15,39 @@ Coding Guidelines for Qubes Developers
Rationale
---------
Maintaining proper coding style is very important for any larger software project, such as Qubes. Here's why:
Maintaining proper coding style is very important for any large software project, such as Qubes. Here's why:
- It eases maintenance, such as adding new functionality or generalization later,
- It allows others (as well as the original author after some time!) to easily understand fragments of code, what they were supposed to do, and so makes it easier to later extend them with newer functionality or bug fixes,
- It eases maintenance tasks, such as adding new functionality or generalizing code later,
- It allows others (as well as the future you!) to easily understand fragments of code and what they were supposed to do, and thus makes it easier to later extend them with newer functionality or bug fixes,
- It allows others to easily review the code and catch various bugs,
- It provides for an aesthetically pleasing experience when one reads the code...
Often, developers, usually smart developers, neglect the value of proper coding style, thinking that it's most important how their code works, and expecting that if it solves some problem using a nice and neat trick, then it's all that is really required. Such thinking shows, however, immaturity and is a signal that the developer, however bright and smart, might not be a good fit for any larger project. Writing a clever exploit, that is to be used at one Black Hat show is one thing, while writing a useful software that is to be used and maintained for years, is quite a different story. If you want to show off what a smart programmer you are, then you should become a researcher and write exploits. If, on the other hand, you want to be part of a team that makes real, useful software, you should ensure your coding style is impeccable. We often, at Qubes project, often took shortcuts, and often wrote nasty code, and this always back fired at us, sometime months, sometime years later, the net result being we had to spend time fixing code, rather than implementing new functionality.
Often, developers, usually smart ones, undersell the value of proper coding style, thinking that it's much more important how their code works. These developers expect that if their code solves some problem using a nice and neat trick, then that's all that is really required. Such thinking shows, however, immaturity and is a signal that the developer, no matter how bright and smart, might not be a good fit for larger projects. Writing a clever exploit for a Black Hat show is one thing - writing useful software supposed to be used and maintained for years is quite a different story. If you want to show off what a smart programmer you are, then you should become a researcher and write exploits. If, on the other hand, you want to be part of a team that makes real, useful software, you should ensure your coding style is impeccable. At Qubes project, we often took shortcuts and wrote nasty code, and this has always back fired at us, sometime months, sometime years later, the net result being we had to spend time fixing code, rather than implementing new functionality.
And here's a [link to the real case](https://groups.google.com/forum/#!msg/qubes-devel/XgTo6L8-5XA/JLOadvBqnqMJ) (one Qubes Security Bulletin) demonstrating how the above described problem lead to a real security bug. Never assume you're smart enough that you can disregard clean and rigorous coding!
And here's a [link to the real case](https://groups.google.com/forum/#!msg/qubes-devel/XgTo6L8-5XA/JLOadvBqnqMJ) (one Qubes Security Bulletin) demonstrating how the lackadaisical coding style lead to a real security bug. Never assume you're smart enough to disregard clean and rigorous coding!
General typographic conventions
-------------------------------
- **Use space-expanded tabs that equal 4 spaces.** Yes, we know, there are many arguments for using "real" tabs, instead of space-expanded tabs, but we need to pick one convention to make the project consistent. One argument for using space-expanded tabs is that this way the programmer is in control of how the code will look like, despite how other users have configured their editors to visualize the tabs (of course, we assume any sane person uses a fixed-width font for viewing the source code). Anyway, if this makes you feel better, assume this is just an arbitrary choice.
- **Use space-expanded tabs that equal 4 spaces.** Yes, we know, there are many arguments for using "real" tabs instead of space-expanded tabs, but we need to pick one convention to make the project consistent. One argument for using space-expanded tabs is that this way the programmer is in control of how the code will look like, despite how other users have configured their editors to visualize the tabs (of course, we assume any sane person uses a fixed-width font for viewing the source code). If it makes you feel any better, assume this is just an arbitrary choice made to enforce a unified style.
- **Maintain max. line length of 80 characters**. Even though today's monitors often are very wide and it's often not a problem to have 120 characters displayed in an editor, still maintaining shorter line lengths improves readability. It also allows to have two parallel windows open, side by side, each with different parts of the source code.
- **Maintain max. line length of 80 characters**. Even though today's monitors often are very wide and it's often not a problem to have 120 characters displayed in an editor, maintaining shorter line lengths improves readability. It also allows others to have two parallel windows open, side by side, each with different parts of the source code.
- Class, functions, variables, and arguments naming convention for any OS other than Windows:
- **Naming conventions for any OS *other than Windows***:
- `ClassName`
- `some_variable`, `some_function`, `some_argument`
- Class, functions, variables, and arguments naming convention for **Windows OS** -- exceptionally to preserve Windows conventions please use the following:
- **Naming convention *for Windows OS*** -- exceptionally to preserve Windows conventions please use the following:
- `ClassName`, `FunctionName`
- `pszArgumentOne`, `hPipe` -- use Hungarian notation for argument and variables
- Horizontal spacing -- maintain at least decent amount of horizontal spacing, such as e.g. add obligatory space after `if` or before `{` in C, and similar in other languages. Whether to also use spaces within expressions, such as (x\*2+5) vs. (x \* 2 + 5) is left to the developer's judgment. Do not put spaces immediately after and before the brackets in expressions, so avoid constructs like this: `if ( condition )` and use `if (condition)` instead.
- **Maintain a decent amount of horizontal spacing**, e.g. add a space after `if` or before `{` in C, and similar in other languages. Whether and where to also use spaces within expressions, such as (x\*2+5) vs. (x \* 2 + 5) is left to the developer's judgment. Do not put spaces immediately after or before the brackets in expressions, so avoid constructs like this: `if ( condition )` and use ones like this: `if (condition)` instead.
- **Use single new lines** ('\\n' aka LF) in any non-Windows source code. On Windows, exceptionally, use the CRLF line endings -- this will allow the source code to be easily view-able in various Windows-based programs.
- **Use single new lines** ('\\n' aka LF) in any non-Windows source code. On Windows, exceptionally, use the CRLF line endings (--). This will allow the source code to be easily viewable in various Windows-based programs.
- **Use descriptive names for variables and functions**! Really, these days, when most editors have auto-completion feature, there is no excuse for using short variable names.
- **Use descriptive names for variables and functions**! Really, at a time when most editors have auto-completion features, there is no excuse for using short variable names.
- Comments should be indent together with the code, e.g. like this:
- **Comments should be indented together with the code**, e.g. like this:
~~~
for (...) {
@ -130,7 +130,22 @@ Source Code management (Git) guidelines
- This creates natural boundaries between different code blocks, enforcing proper interfaces, and easing independent development to be conducted on various code parts at the same time, without the fear of running into conflicts.
- By maintaining relatively small git repositories, it is easy for new developers to understand the code and contribute new patches, without the need to understand all the other code.
- Code repositories represent also licensing boundaries. So, e.g. because `core-agent-linux` and `core-agent-windows` are maintained in two different repositories, it is possible to have the latter under a proprietary, non-GPL license, while keeping the former fully open source.
- We have drastically changes the layout and naming of the code repositories shortly after Qubes OS R2 Beta 2 release. For details on the current code layout, please read [this article](http://theinvisiblethings.blogspot.com/2013/03/introducing-qubes-odyssey-framework.html).
- We have drastically changes the layout and naming of the code repositories shortly after Qubes OS R2 Beta 2 release. For details on the current code layout, please read [this article](https://blog.invisiblethings.org/2013/03/21/introducing-qubes-odyssey-framework.html).
Commit message guidelines
-------------------------
Please attempt to follow these conventions when writing your Git commit messages:
* Separate the subject line from the body with a blank line.
* Limit the subject line to approximately 50 characters.
* Capitalize the subject line.
* Do not end the subject line with a period.
* Use the imperative mood in the subject line.
* Wrap the body at 72 characters.
* Use the body to explain *what* and *why* rather than *how*.
For details, examples, and the rationale behind each of these conventions, please see [this blog post](https://chris.beams.io/posts/git-commit/), which is the source of this list.
Security coding guidelines
--------------------------

29
basics_dev/devel-books.md Normal file
View File

@ -0,0 +1,29 @@
---
layout: doc
title: Developer Books
permalink: /doc/devel-books/
redirect_from:
- /en/doc/devel-books/
- /doc/DevelBooks/
- /wiki/DevelBooks/
---
Below is a list of various books that might be useful in learning some basics needed for Qubes development.
- A must-read about Xen internals:
* _[The Definitive Guide to the Xen Hypervisor](https://www.amazon.com/Definitive-Guide-Xen-Hypervisor/dp/013234971X)_, by David Chisnall
- Some good books about the Linux kernel:
* _[Linux Kernel Development](https://www.amazon.com/Linux-Kernel-Development-Robert-Love/dp/0672329468)_, by Robert Love
* _[Linux Device Drivers](https://www.amazon.com/Linux-Device-Drivers-Jonathan-Corbet/dp/0596005903)_, by Jonathan Corbet
- Solid intro into Trusted Computing:
* _[Dynamics of a Trusted Platform](https://www.amazon.com/Dynamics-Trusted-Platform-Buildin-Grawrock/dp/1934053082)_, by David Grawrock (original Intel architect for TXT)
- Good book about GIT:
* _[Pro Git](https://git-scm.com/book/en/v2)_, by Scott Chacon and Ben Straub (complete book available free online)
- Useful books about Python:
* _[Programming in Python 3](http://www.qtrac.eu/py3book.html)_, by Mark Summerfield
* _[Rapid GUI Programming with Python and Qt](http://www.qtrac.eu/pyqtbook.html)_, by Mark Summerfield
(Although note that [Qt is being replaced by GTK](/doc/usability-ux/#gnome-kde-and-xfce) in Qubes code.)

62
basics_dev/devel-faq.md Normal file
View File

@ -0,0 +1,62 @@
---
layout: doc
title: Developers' FAQ
permalink: /doc/devel-faq/
redirect_from:
- /en/doc/devel-faq/
- /doc/DevelFaq/
- /wiki/DevelFaq/
---
Qubes Developers' FAQ
=====================
Why does dom0 need to be 64-bit?
--------------------------------
Since 2013 [Xen has not supported 32-bit x86 architecture](https://wiki.xenproject.org/wiki/Xen_Project_Release_Features) and Intel VT-d, which Qubes uses to isolate devices and drivers, is available on Intel 64-bit processors only.
In addition, with features like improved ASLR, it is often more difficult to exploit a bug on x64 Linux than x86 Linux.
While we designed Qubes from the beginning to limit potential attack vectors, we still realize that some of the code running in Dom0, e.g. our GUI daemon or xen-store daemon, however simple, might contain some bugs.
Plus since we haven't implemented a separate storage domain, the disk backends are in Dom0 and are "reachable" from the VMs, which adds up to the potential attack surface.
So, having faced a choice between 32-bit and 64-bit OS for Dom0, it was almost a no-brainer.
The 64-bit option provides some (little perhaps, but some) more protection against some classes of attacks, and at the same time does not have any disadvantages except the extra requirement of a 64 bit processor.
And even though Qubes now "needs" a 64 bit processor, it didn't make sense to run Qubes on a system without 3-4GB of memory, and those have 64-bit CPUs anyway.
What is the recommended build environment for Qubes OS?
------------------------------------------
Any rpm-based, 64-bit environment, the preferred OS being Fedora.
How do I build Qubes from sources?
--------------------------------
See [these instructions](/doc/qubes-builder/).
How do I submit a patch?
------------------------
See the [Qubes Source Code Repositories](/doc/source-code/) article.
What is Qubes' attitude toward changing guest distros?
------------------------------------------------------
We try to respect each distro's culture, where possible.
See the discussion on issue [#1014](https://github.com/QubesOS/qubes-issues/issues/1014) for an example.
The policy is there mostly to ease maintenance, on several levels:
* Less modifications means easier migration to new upstream distribution
releases.
* The upstream documentation matches the distribution running in the Qubes VM.
* We're less likely to introduce Qubes-specific issues.
* Each officially supported distribution (ideally) should offer the same set of
Qubes-specific features - a change in one supported distribution should be
followed also in others, including new future distributions.
Is I/O emulation component (QEMU) part of the Trusted Computing Base (TCB)?
------------------------
No. Unlike many other virtualization systems, Qubes takes special effort to keep QEMU _outside_ of the TCB.
This has been achieved thanks to the careful use of Xen's stub domain feature.
For more details about how we improved on Xen's native stub domain use, see [here](https://blog.invisiblethings.org/2012/03/03/windows-support-coming-to-qubes.html).

21
basics_dev/license.md Normal file
View File

@ -0,0 +1,21 @@
---
layout: doc
title: License
permalink: /doc/license/
redirect_from:
- /en/doc/license/
- /doc/QubesLicensing/
- /wiki/QubesLicensing/
---
Qubes OS License
================
Qubes is a compilation of software packages, each under its own license. The compilation is made available under the GNU General Public License version 2.
The full text of the GPL v2 license can be found [here](http://www.gnu.org/licenses/gpl-2.0.html).
Note on rights to double-licensing of the Qubes code
----------------------------------------------------
Invisible Things Lab (ITL), who has funded and run the Qubes project since the beginning, and who has contributed the majority of Qubes-specific code (specifically: `core-*`, `gui-*`, and `qubes-*` repositories) would like to have a right to redistribute parts of this code under proprietary licenses. This is especially important for Qubes R3 and later, where the new architecture allows the creation of many editions of Qubes, using different hypervisors, some of which might not be open source. That's why we ask every developer who contributes code to Qubes project to grant ITL permission to reuse the code under a different license, and to express this consent by including the [standard signed-off line](https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/Documentation/process/submitting-patches.rst?id=HEAD#n416) in the commit.

100
basics_dev/package-contributions.md Normal file
View File

@ -0,0 +1,100 @@
---
layout: doc
title: Package Contributions
permalink: /doc/package-contributions/
---
Package Contributions
=====================
**Notice:** *This is an unofficial draft. Once this information is official, this notice will be removed.*
We're very grateful to the talented and hard-working community members who contribute software packages to Qubes OS.
This page explains the inclusion criteria and procedures for such packages, as well as the roles and responsibilities of those involved.
Inclusion Criteria
------------------
In order to be accepted, packages must:
* In no way weaken the security of Qubes OS.
* Be published under an open-source license (read about the [Qubes OS License]).
* Follow our [coding guidelines].
* Be thoroughly tested.
* Have a clearly-defined use case for Qubes users.
* Not be unduly burdensome to review.
(Please note that we always reserve the right add criteria to this list.)
Contribution Procedure
----------------------
Before you start putting serious work into a package, we recommend that you discuss your idea with the Qubes developers and the broader community on the [qubes-devel mailing list].
Once you have a package that's ready to become part of Qubes OS, please follow this procedure:
1. Ensure that your package satisfies the [Inclusion Criteria].
2. If your code isn't already on GitHub, create a GitHub repo that contains your code.
3. If you haven't already, [sign your code][sig].
4. Create an issue in [qubes-issues] with the title `[Contribution] your-package-name`.
Include a link to your repo, a brief description of your package, and a brief explanation of why you think it should be included in Qubes.
Please note that the Qubes core developers are very busy.
If they are under heavy load when you submit your contribution, it may be a very long time before they have time to review your package.
If this happens, please do not be discouraged.
If you think they may have forgotten about your pending contribution, you may "bump" your request by commenting on your issue, but please do this *very* sparingly (i.e., no more than once a month).
We appreciate your understanding!
5. You may be asked followup questions.
If we decide to accept your contribution, you will be invited to join the [QubesOS-contrib] organization on GitHub as public recognition of your contribution (but without push access; see [Review Procedure]), and [QubesOS-contrib] will fork your repo.
If we decide not to accept your contribution, we will state the reason and close the issue.
Update Procedure
----------------
*Anyone* can provide an update (patch) to a contributed package, not just the person who contributed that package!
The update procedure is the same for everyone, including the original package contributor.
If you would like to update an already-contributed package (specifically, a fork owned by [QubesOS-contrib]), please submit a [signed][sig], fast-forwardable pull request to that repo with your changes.
Please note that your pull request **must** be both [signed][sig] and fast-forwardable, or else it will be closed without further review.
One or more reviewers may post comments on your pull request.
Please be prepared to read and respond to these comments.
Review Procedure
----------------
This review procedure covers both original package contributions (see [Contribution Procedure]) and all subsequent updates to those packages, including updates from the original package contributor (see [Update Procedure]).
All changes will be reviewed by a Qubes Core Reviewer (QCR) and the [Package Maintainer] (PM).
In all cases, the QCR will be a core Qubes developer.
In some cases, the QCR and the PM will be the same person.
For example, if someone contributes a package, then disappears, and no suitable replacement has been found, then it is likely that a core Qubes developer will play both the QCR and PM roles for that package, at least until another suitable candidate volunteers to become the PM for that package.
The review procedure is as follows:
1. Someone, S, wishes to make a change to a package, P.
2. S submits a fast-forwardable pull request against the fork of P's repo owned by [QubesOS-contrib].
3. The PM reviews the pull request.
If the the pull request passes the PM's review, the PM adds a [signed][sig] *comment* on the pull request stating that it has passed review.
(In cases in which S = PM, the PM can simply add a [signed][sig] *tag* to the HEAD commit prior to submitting the pull request.)
If the pull request does not pass the PM's review, the PM leaves a comment on the pull request explaining why not.
4. The QCR reviews the pull request.
If the pull request passes the QCR's review, the QCR pushes a [signed][sig] tag to the HEAD commit stating that it has passed review and fast-forward merges the pull request.
If the pull request does not pass the QCR's review, the QCR leaves a comment on the pull request explaining why not, and the QCR may decide to close the pull request.
Package Maintainers
-------------------
If you contribute a package, we assume that you will be the maintainer of that package, unless you tell us otherwise.
As the maintainer of the package, it is your privilege and responsibility to:
* [Review][Review Procedure] each pull request made against the package.
* Decide when the package has reached a new version, and notify the Qubes core developers when this occurs.
If you do not wish to be the maintainer of your package, please let us know.
If you do not act on your maintainer duties for a given package for an extended period of time and after at least one reminder, we will assume that you no longer wish to be the maintainer for that package.
[Inclusion Criteria]: #inclusion-criteria
[Contribution Procedure]: #contribution-procedure
[Update Procedure]: #update-procedure
[Review Procedure]: #review-procedure
[Package Maintainer]: #package-maintainers
[Qubes OS License]: /doc/license/
[sig]: /doc/code-signing/
[coding guidelines]: /doc/coding-style/
[qubes-devel mailing list]: /mailing-lists/#qubes-devel
[QubesOS-contrib]: https://github.com/QubesOS-contrib
[qubes-issues]: https://github.com/QubesOS/qubes-issues/issues/

13
developers/source-code.md → basics_dev/source-code.md
View File

@ -53,11 +53,17 @@ find . -mindepth 1 -maxdepth 1 -type d -exec git -C {} fetch --tags --recurse-su
How to Send Patches
-------------------
If you want to contribute code to the project, there are two ways. Whichever
If you want to [contribute code] to the project, there are two ways. Whichever
method you choose, you must [sign your code] before it can be accepted.
* **Preferred**: Use GitHub's [fork & pull requests].
* Send a patch to our developer [mailing list] (`git format-patch`).
Opening a pull request on GitHub greatly eases the code review and tracking
process. In addition, especially for bigger changes, it's a good idea to send
a message to the [qubes-devel mailing list] in order to notify people who
do not receive GitHub notifications.
* Send a patch to the [qubes-devel mailing list] (`git format-patch`).
1. Make all the changes in your working directory, i.e. edit files, move them
around (you can use 'git mv' for this), etc.
@ -75,7 +81,8 @@ method you choose, you must [sign your code] before it can be accepted.
[QubesOS GitHub account]: https://github.com/QubesOS/
[contribute code]: /doc/contributing/#contributing-code
[sign your code]: /doc/code-signing/
[fork & pull requests]: https://guides.github.com/activities/forking/
[mailing list]: /doc/mailing-lists/
[qubes-devel mailing list]: /mailing-lists/#qubes-devel

6
developers/style-guide.md → basics_dev/style-guide.md
View File

@ -9,7 +9,7 @@ Style Guide
## Fonts
Currently Qubes OS is using the following fonts for our website, branding, and other public facing (non-OS) materials. The OS itself uses what is normal for a users desktop environment of choice.
Currently Qubes OS is using the following fonts for our website, branding, and other public facing (non-OS) materials. The OS itself uses what is normal for a user's desktop environment of choice.
<div class="styleguide">
{% for font in site.data.styleguide.fonts %}
@ -28,7 +28,7 @@ Currently Qubes OS is using the following fonts for our website, branding, and o
## Colors
The following **grayscale** colors are currently used on the Qubes website, documentation, and will eventually match colors within the OS itself.
The following **grayscale** colors are currently used on the Qubes website and documentation, and they will eventually match colors within the OS itself.
<div class="styleguide">
{% for color in site.data.styleguide.colors %}
@ -42,7 +42,7 @@ The following **grayscale** colors are currently used on the Qubes website, docu
{% endfor %}
</div>
The following **colors** are currently being used on the Qubes website, documentation, and will eventually match the colors within the OS itself!
The following **colors** are currently being used on the Qubes website and documentation, and they will eventually match the colors within the OS itself!
<div class="styleguide">
{% for color in site.data.styleguide.colors %}

12
basics_dev/system-doc.md Normal file
View File

@ -0,0 +1,12 @@
---
layout: doc
title: System Documentation
permalink: /doc/system-doc/
redirect_from:
- /en/doc/system-doc/
- /doc/SystemDoc/
- /wiki/SystemDoc/
redirect_to:
- /doc/#developer-documentation
---

84
developers/usability-ux.md → basics_dev/usability-ux.md
View File

@ -7,26 +7,26 @@ permalink: /doc/usability-ux/
Usability & UX
==============
Software that is too complicated to use, is often unused. Thus, usability and user experience of Qubes OS is an utmost priority for us, as we want as many people as possible to benefit from the unique security properties of Qubes OS!
Software that is too complicated to use, is often unused. Because we want as many people as possible to benefit from its unique security properties, the usability and user experience of Qubes OS is an utmost priority!
We ask anyone developing for Qubes OS to please read through this guide to better understand the user experience we strive to achieve. Also, please review [our style guide](/doc/style-guide/) for other design related information.
We ask anyone developing for Qubes OS to please read through this guide to better understand the user experience we strive to achieve. We also ask them to review [our style guide](/doc/style-guide/) for other design related information.
---
## Easy To Use
An ideal user experience is friendly and welcomes a new user to explore the interface and in this process easily discover *how* to use the software. Additionally, security focused software has the responsibility of providing safety to a user and their data.
An ideal user experience is friendly, and it beckons a new user to explore the interface. In this process, they can naturally discover how to use the software. Below are some guidelines that will help you design a user interface that accomplishes this goal.
<div class="focus">
<i class="fa fa-times"></i> <strong>Interfaces Should Not</strong>
</div>
- Require numerous settings to be entered before a user can *begin* doing things
- Require extensive configuration before a user can *begin* doing things
- Make it possible to break provided features or actions in unrecoverable ways
- Perform actions which compromise security and data
- Overwhelm with too much information and cognitive load
- Overwhelm the user with too much information and cognitive load
Perhaps the most common cause of mistakes is complexity. Thus, if there is a configuration setting that will significantly affect the user experience, choose a safe and smart default then tuck this setting in an `Advanced Settings` panel.
Perhaps the most common cause of mistakes is complexity. If there is a configuration setting that will significantly affect the user's experience, choose a safe and smart default then tuck this setting in an `Advanced Settings` panel.
<div class="focus">
<i class="fa fa-check"></i> <strong>Interfaces Should</strong>
@ -37,39 +37,39 @@ Perhaps the most common cause of mistakes is complexity. Thus, if there is a con
- Offer the ability to easily undo mistakes
- Choose intelligent defaults for settings
A crucial thing in making software easy to use, is being mindful of [cognitive load](https://en.wikipedia.org/wiki/Cognitive_load) which dictates that *"humans are generally able to hold only seven +/- two units of information in short-term memory."* This short-term memory limit is perhaps the most important factor in helping a user feel comfortable instead of overwhelmed.
In making software easy to use, it is crucial to be mindful of [cognitive load](https://en.wikipedia.org/wiki/Cognitive_load) which dictates that *"humans are generally able to hold only seven +/- two units of information in short-term memory."* Making sure your interfaces don't pass this short-term memory limit is perhaps the most important factor in helping a user feel comfortable instead of overwhelmed.
---
## Easy to Understand
There will always be the need to communicate things to users. In these cases, an interface should aim to make this information easy to understand. The following are simple guides to help achieve this- none these are absolute maxims!
There will always be the need to communicate things to users. In these cases, an interface should aim to make this information easy to understand. The following are simple guides to help achieve this - none these are absolute maxims!
<div class="focus">
<i class="fa fa-times"></i> <strong>Avoid Acronyms</strong>
</div>
Acronyms are short and make good names for command line tools. Acronyms do not make graphical user interfaces more intuitive for non-technical users. Until one learns an acronyms meaning, it is otherwise meaningless. Avoid acronyms whenever possible!
Acronyms are compact and make good names for command line tools. They do not make graphical user interfaces more intuitive for non-technical users. Until one learns an acronym's meaning, it is gibberish. Avoid acronyms in your interfaces whenever possible!
- `DVM` - Disposable Virtual Machine
- `GUID` - Global Unique Identifier
- `PID` - Process Identification
- `PID` - Process Identification Number
- `NetVM` - Networking Virtual Machine
Despite this rule, some acronyms like `USB` are widely used and understood due to being in common use for over a decade. It is good to use these acronyms when the full words like `Universal Serial Bus` are more likely to confuse users.
<div class="focus">
<i class="fa fa-check"></i> <strong> Use Simple Words</strong>
</div>
Use the minimum amount of words needed to be descriptive, but also informative. Go with common words that are as widely understood as possible. Sometimes, inventing a word such as `Qube` to describe a `virutal machine` in the context of Qubes OS, is a good idea.
Use the minimum amount of words needed to be descriptive, but also informative. Go with common words that are as widely understood. Sometimes, inventing a word such as `Qube` to describe a `virtual machine` makes the life of the user much easier.
- Use `Disposable Qube` instead of `DVM`
- Use `interface` instead of `GUI`
- Use `application` instead of `PID`
- Use `Disposable Qube` instead of `DVM` or `Disposable Virtual Machine`
- Use `interface` instead of `GUI` or `Graphical User Interface`
- Use `application number` instead of `PID` or `Process Identification Number`
- Use `Networking` or `Networking Qube` instead of `NetVM` given context
However, acronyms like `USB` are widely used and understood due to being in common use for over a decade. It is good to use these acronyms, as the full words `Universal Serial Bus` is more likely to confuse users.
---
<div class="focus">
@ -82,7 +82,7 @@ Technical words are usually more accurate, but they often *only* make sense to t
- `savefile`
- `qrexec-daemon`
These are all terms that have at some point showed up in notification messages presented users. Each term is very accurate, but requires understanding virtualization
These are all terms that have at some point showed up in users' notification messages. Each term is very specific, but requires the user to understand virtualization to interpet.
<div class="focus">
<i class="fa fa-check"></i> <strong> Use Common Concepts</strong>
@ -90,9 +90,9 @@ These are all terms that have at some point showed up in notification messages p
Large amounts of the global population have been using computers for one or two decades and have formed some mental models of how things work. Leveraging these mental models are a huge gain.
- Use `disk space` instead of `root.img` while not quite accurate, it makes contextual sense
- Use`saving` instead of `savefile` as the former is the action trying to be completed
- Use `Qubes` instead of `qrexec-daemon` as it is the larger context what is happening
- Use `disk space` instead of `root.img`, since while not quite accurate, it makes contextual sense
- Use `saving` instead of `savefile` as the former is the action trying to be completed
- Use `Qubes` instead of `qrexec-daemon` as it gives better context on what is happening
These words are more abstract and user relevant- they help a user understand what is happening based on already known concepts (disk space) or start to form a mental model of something new (Qubes).
@ -126,7 +126,7 @@ By using the same term throughout an interface, a user can create a mental model
<i class="fa fa-times"></i> <strong>Avoid Duplicate Words</strong>
</div>
It is easy when trying to be descriptive and accurate to add words like `Domain` before items in a list or menu such as:
It is easy to add words like `Domain` before items in a list or menu in an attempt to be descriptive, such as:
~~~
Menu
@ -135,13 +135,13 @@ Menu
- Domain: personal
~~~
The repeated use of the word `Domain` requires a user to read it for each item in the list, which takes extra time for the eye to parse out the relevant word like `work, banking, or personal`. This also affects horizontal space on fixed width lines.
The repeated use of the word `Domain` requires a user to read it for each item in the list, which makes extra work for the eye in parsing out the relevant word like `work, banking, or personal`. This also affects horizontal space on fixed width lines.
<div class="focus">
<i class="fa fa-check"></i> <strong> Create Groups & Categories</strong>
</div>
It is more efficient to group things under headings like `Domains` as this allows the eye to easily scan the uniqueness of the items.
It is more efficient to group things under headings instead as this allows the eye to easily scan the uniqueness of the items. (As per our previous example:)
~~~
Domains
@ -154,32 +154,34 @@ Domains
## Easy To Complete
Lastly, expected (and unexpected) situations will happen which require user actions or input. Make resolving of these actions as easy as possible to complete the action or find.
Lastly, expected (and unexpected) situations often require user actions or input. Make resolving these occurences as easy as possible to complete the action.
<div class="focus">
<i class="fa fa-times"></i> <strong>Don't Leave Users Stranded</strong>
<i class="fa fa-times"></i><strong>Don't Leave Users Stranded</strong>
</div>
Consider the following notifications which are shown to a user:
Consider the following notifications:
- `The disk space of your Qube "Work" is full`
- `There was an error saving Qube "Personal"`
Instead of displaying solvable errors like these and neglecting to provide a fix:
<div class="focus">
<i class="fa fa-check"></i> <strong> Offer Actionable Solutions</strong>
<i class="fa fa-check"></i><strong>Offer Actionable Solutions</strong>
</div>
An error message or limit such as that can be greatly improved upon by adding buttons or links to helpful information.
Error messages and limits such as those in the previous example can be greatly improved by adding buttons or links to helpful information.
- Add a button `Increase Disk Space`
- Add a link to documentation `Troubleshoot saving data`
- Add a button to `Increase Disk Space`
- Add a link to a documentation page called `Troubleshoot saving data`
Adhering to these principles, make undesirable situations more manageable for users instead of feeling stranded.
In adhering to these principles, you'll make undesirable situations more manageable for users instead of feeling stranded.
---
<div class="focus">
<i class="fa fa-times"></i> <strong>Avoid Repetitive Tasks</strong>
<i class="fa fa-check"></i><strong>Minimize Repetitive Steps</strong>
</div>
There are many cases where a user wants to perform an action on more than one file or folder. However in order to do the action, the user must repeat certain steps such as:
@ -193,26 +195,24 @@ There are many cases where a user wants to perform an action on more than one fi
3. Select proper file
4. Complete task on file
That subtle act of clicking through a file system can prove to be significant if a user needs to open more than a couples files in the same directory.
<div class="focus">
<i class="fa fa-check"></i> <strong>Minimize Repetitive Steps</strong>
</div>
That subtle act of clicking through a file system can prove to be significant if a user needs to open more than a couples files in the same directory. We can alleviate some of the work by changing the process:
1. Click on `Open File` from a menu or button
2. Remember last open file system
2. Remember last open folder/file system
3. Select proper file
4. Complete task
Clearly, cutting out navigating through the file system can save a user quite a bit of time. Alternatively, adding a button or menu item `Open Multiple Files` could be even better, as using hot keys to select multiple files is often a thing only power users know how to do!
Clearly, cutting out something as simple as navigating through the file system can save a user quite a bit of time. Alternatively, adding a button or menu item like `Open Multiple Files` might be even better, because remembering and using relevant hotkeys is often something only power users know how to do!
---
## GNOME, KDE, and Xfce
The the desktop GUIs which QubesOS versions 1 - 3.1 offer are [KDE](https://www.kde.org), as well as [Xfce](https://xfce.org). We are currently migrating towards using [GNOME](https://www.gnome.org). We know some people prefer KDE, however, we believe the overalluser experience of GNOME is more focused on simplicity and ease of use for average non-technical users. Xfce will always be supported, and technical users will always be able to still use KDE or other desktop environments.
The desktop GUIs that QubesOS versions 1 - 3.1 offer are [KDE](https://www.kde.org) and [Xfce](https://xfce.org). We are currently migrating towards using [GNOME](https://www.gnome.org). We know some people prefer KDE, but we believe Gnome is easier to use for average non-technical users. Xfce will always be supported, and technical users will always have the choice to use KDE or other desktop environments.
All three desktop environments have their own [human interface guidelines](https://en.wikipedia.org/wiki/Human_interface_guidelines) and we suggest you familiarize yourself with the platform you developing for.
This change means you should use [GTK](https://www.gtk.org/) rather than Qt for new GUIs.
All three of these mentioned desktop environments have their own [human interface guidelines](https://en.wikipedia.org/wiki/Human_interface_guidelines), and we suggest you familiarize yourself with the platform you developing for.
- [GNOME Human Interface Guidelines](https://developer.gnome.org/hig/3.18/)
- [KDE HIG](https://techbase.kde.org/Projects/Usability/HIG)
@ -222,7 +222,7 @@ All three desktop environments have their own [human interface guidelines](https
## Further Learning & Inspiration
Learning to make well designing intuitive interfaces and software is specialized skillset that can take years to cultivate, but if you are interested in furthering your understanding of usability and experience, we suggest the following resources.
Learning to make well designing intuitive interfaces and software is specialized skillset that can take years to cultivate, but if you are interested in furthering your understanding, we suggest the following resources:
- [Learn Design Principles](http://learndesignprinciples.com) by Melissa Mandelbaum
- [Usability in Free Software](http://jancborchardt.net/usability-in-free-software) by Jan C. Borchardt

78
basics_user/contributing.md Normal file
View File

@ -0,0 +1,78 @@
---
layout: doc
title: Contributing to the Qubes OS Project
permalink: /doc/contributing/
redirect_from:
- /en/doc/contributing/
- /doc/ContributingHowto/
- /wiki/ContributingHowto/
---
How to Contribute to the Qubes OS Project
=========================================
Thank you for your interest in contributing to Qubes! Here are some of the many
ways in which you can help:
* Audit the [source code]
* [Report security issues]
* [Send patches][patch] to fix bugs or implement features
* [Report bugs]
* [Test new releases and updates]
* Submit [HCL reports] for your hardware
* Record [video tours]
* Create [artwork] (plymouth themes, installer themes, wallpapers, etc.)
* [Write and edit the documentation]
* [Donate] to the project
* If you represent an organization, become a [Qubes partner]
* Answer questions on the [mailing lists]
* Engage with us on social media:
* Follow us on [Twitter]
* Join us on [Reddit]
* Like us on [Facebook]
* Support our [StackExchange] proposal
* And last but not least, tell your friends and colleagues about how Qubes
can help them secure their digital lives!
Contributing Code
-----------------
If you're interested in contributing code, the best starting point is to have a
look at our [GitHub issues] to see which tasks are the most urgent. You can
filter issues depending on your interest and experience. For example, here are
some common issue labels:
* [Help wanted](https://github.com/QubesOS/qubes-issues/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22&utf8=%E2%9C%93)
* [UX and usability](https://github.com/QubesOS/qubes-issues/issues?q=is%3Aissue+is%3Aopen+label%3AUX)
* [Windows tools](https://github.com/QubesOS/qubes-issues/issues?q=is%3Aissue+is%3Aopen+label%3A%22C%3A+windows+tools%22)
* [Documentation](https://github.com/QubesOS/qubes-issues/issues?q=is%3Aissue+is%3Aopen+label%3A%22C%3A+doc%22)
* [Privacy](https://github.com/QubesOS/qubes-issues/issues?utf8=%E2%9C%93&q=is%3Aissue%20is%3Aopen%20label%3A%22privacy%22%20)
* [Debian](https://github.com/QubesOS/qubes-issues/issues?q=is%3Aissue+is%3Aopen+label%3A%22C%3A+Debian%22)
Before you engage in an activity that will take you a significant amount of
time, like implementing a new feature, it's always good to contact us first,
preferably via the [qubes-devel] mailing list. Once we've worked out the
details, we'll add you to our [Community-Developed Feature Tracker]. We'll then
be grateful to [receive your patch][patch].
[source code]: /doc/source-code/
[Report security issues]: /security/
[patch]: /doc/source-code/#how-to-send-patches
[Report bugs]: /doc/reporting-bugs/
[Test new releases and updates]: /doc/testing/
[HCL reports]: /doc/hcl/
[video tours]: /video-tours/
[artwork]: https://github.com/QubesOS/qubes-artwork
[Write and edit the documentation]: /doc/doc-guidelines
[mailing lists]: /mailing-lists/
[Donate]: /donate/
[Qubes partner]: /partners/
[Twitter]: https://twitter.com/QubesOS
[Reddit]: https://www.reddit.com/r/Qubes/
[Facebook]: https://www.facebook.com/QubesOS
[StackExchange]: https://area51.stackexchange.com/proposals/98519/qubes-os
[GitHub issues]: https://github.com/QubesOS/qubes-issues/issues
[qubes-devel]: /mailing-lists/#qubes-devel
[Community-Developed Feature Tracker]: https://www.qubes-os.org/qubes-issues/

55
developers/doc-guidelines.md → basics_user/doc-guidelines.md
View File

@ -16,18 +16,17 @@ dedicated [qubes-doc] repository. By cloning and regularly pulling from
this repo, users can maintain their own up-to-date offline copy of all Qubes
documentation rather than relying solely on the Web.
The documentation is a community effort in which volunteers work hard trying to
The documentation is a community effort. Volunteers work hard trying to
keep everything accurate and comprehensive. If you notice a problem with the
documentation or some way it can be improved, please [report] it! Better
yet, you can [edit the documentation][contribute] yourself, both to add new
content and to edit existing content.
yet, you can [edit the documentation][contribute] yourself, both to add or improve existing content.
How to Report Issues
--------------------
To report an issue, please create an issue in [qubes-issues], but before you do,
please make sure your issue does **not** already exist. Documentation-related
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.
@ -79,7 +78,7 @@ they'll be formatted by clicking the "Preview changes" tab.
![edit](/attachment/wiki/doc-edit/06-edit.png)
Once you're finish, describe your changes at the bottom and click "Propose file
Once you're finished, describe your changes at the bottom and click "Propose file
change".
![commit](/attachment/wiki/doc-edit/07-commit-msg.png)
@ -106,6 +105,26 @@ pull request, we'll post a comment explaining why we can't.
![done](/attachment/wiki/doc-edit/10-done.png)
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
----------------
@ -120,7 +139,11 @@ All the documentation is written in Markdown for maximum accessibility. When
making contributions, please try to observe the following style conventions:
* Use spaces instead of tabs.
* Hard wrap Markdown lines at 80 characters.
* Insert a newline at the end of each sentence.
* Rationale: This practice is most appropriate for source that consists
primarily of natural language text. It results in the most useful diffs
and facilitates translation into other languages while mostly preserving
source readability.
* If appropriate, make numerals in numbered lists match between Markdown
source and HTML output.
* Rationale: In the event that a user is required to read the Markdown source
@ -141,19 +164,8 @@ making contributions, please try to observe the following style conventions:
Git Conventions
---------------
Please attempt to follow these conventions when writing your Git commit
messages:
* Separate the subject line from the body with a blank line.
* Limit the subject line to approximately 50 characters.
* Capitalize the subject line.
* Do not end the subject line with a period.
* Use the imperative mood in the subject line.
* Wrap the body at 72 characters.
* Use the body to explain *what* and *why* rather than *how*.
For details, examples, and the rationale behind each of these conventions,
please see [this blog post][git-commit], which is the source of this list.
Please try to write good commit messages, according to the
[instructions in our coding style guidelines][git-commit].
[qubes-doc]: https://github.com/QubesOS/qubes-doc
@ -164,5 +176,6 @@ please see [this blog post][git-commit], which is the source of this list.
[gh-fork]: https://guides.github.com/activities/forking/
[gh-pull]: https://help.github.com/articles/using-pull-requests/
[GitHub]: https://github.com/
[mailing lists]: /mailing-lists/
[md]: https://daringfireball.net/projects/markdown/
[git-commit]: http://chris.beams.io/posts/git-commit/
[git-commit]: /doc/coding-style/#commit-message-guidelines

107
basics_user/reporting-bugs.md Normal file
View File

@ -0,0 +1,107 @@
---
layout: doc
title: Reporting Bugs
permalink: /doc/reporting-bugs/
redirect_from:
- /en/doc/reporting-bugs/
- /doc/BugReportingGuide/
- /wiki/BugReportingGuide/
- /reporting-bugs/
- /bug/
- /bugs/
- /bug-report/
- /bug-reports/
---
Reporting Bugs
==============
One of the most important ways in which you can [contribute to the Qubes OS Project] is by reporting any bugs you have found.
Please note that there is a separate process for [reporting security issues](/security/).
Before you submit a report
--------------------------
Before you submit a bug report, please take a moment to:
* Check whether your issue has already been reported.
* Determine which venue is most appropriate for it.
* Read the [documentation] to see whether what you've found is really a bug.
* Search through the existing [Qubes issues][qubes-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. 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.
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.
* Search through our [mailing list] archives by visiting the Google Groups web
interfaces for both [qubes-users] and [qubes-devel].
Where to submit your report
---------------------------
Our [GitHub issues][qubes-issues] tracker is not intended for personal,
localized troubleshooting questions, such as problems that affect only a
specific laptop model. Those questions are more likely to be answered in
[qubes-users], which receives much more traffic. Instead, GitHub issues are
meant to track more general bugs and enhancements that affect a broad range of
Qubes users.
How to copy information out of Dom0
-----------------------------------
See [Copying from (and to) dom0](/doc/copy-from-dom0/).
How to submit a report on the mailing lists
-------------------------------------------
Please see the [mailing list guidelines][mailing list].
How to submit a report on GitHub
--------------------------------
We track all bugs in the [qubes-issues] tracker on GitHub.
When you file a new issue, you should be sure to include the version of Qubes
your'e using, as well as versions of related software packages. 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!
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/
[documentation]: /doc/
[qubes-issues]: https://github.com/QubesOS/qubes-issues/issues
[mailing list]: https://www.qubes-os.org/mailing-lists/
[qubes-users]: https://groups.google.com/group/qubes-users
[qubes-devel]: https://groups.google.com/group/qubes-devel
[testing]: /doc/testing/
[updates-status]: https://github.com/QubesOS/updates-status/issues
[how to contribute code]: /doc/contributing/#contributing-code

50
basics_user/testing.md Normal file
View File

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

469
basics_user/user-faq.md Normal file
View File

@ -0,0 +1,469 @@
---
layout: doc
title: Users' FAQ
permalink: /doc/user-faq/
redirect_from:
- /en/doc/user-faq/
- /doc/UserFaq/
- /wiki/UserFaq/
---
Qubes Users' FAQ
================
[General Questions](#general-questions)
---------------------------------------
* [Is Qubes just another Linux distribution?](#is-qubes-just-another-linux-distribution)
* [How is Qubes different from other security solutions?](#how-is-qubes-different-from-other-security-solutions)
* [Does Qubes use full disk encryption (FDE)?](#does-qubes-use-full-disk-encryption-fde)
* [What is the main concept behind Qubes?](#what-is-the-main-concept-behind-qubes)
* [What about other approaches to security?](#what-about-other-approaches-to-security)
* [What about safe languages and formally verified microkernels?](#what-about-safe-languages-and-formally-verified-microkernels)
* [Why does Qubes use virtualization?](#why-does-qubes-use-virtualization)
* [What do all these terms mean?](#what-do-all-these-terms-mean)
* [Does Qubes run every app in a separate VM?](#does-qubes-run-every-app-in-a-separate-vm)
* [Why does Qubes use Xen instead of KVM or some other hypervisor?](#why-does-qubes-use-xen-instead-of-kvm-or-some-other-hypervisor)
* [What about this other/new (micro)kernel/hypervisor?](#what-about-this-othernew-microkernelhypervisor)
* [What's so special about Qubes' GUI virtualization?](#whats-so-special-about-qubes-gui-virtualization)
* [Can I watch YouTube videos in qubes?](#can-i-watch-youtube-videos-in-qubes)
* [Can I run applications, like games, which require 3D support?](#can-i-run-applications-like-games-which-require-3d-support)
* [Is Qubes a multi-user system?](#is-qubes-a-multi-user-system)
* [Why passwordless sudo?](#why-passwordless-sudo)
* [How should I report documentation issues?](#how-should-i-report-documentation-issues)
* [Will Qubes seek to get certified on the GNU Free System Distribution Guidelines (GNU FSDG)?](#will-qubes-seek-to-get-certified-under-the-gnu-free-system-distribution-guidelines-gnu-fsdg)
* [Should I trust this website?](#should-i-trust-this-website)
* [What does it mean to "distrust the infrastructure"?](#what-does-it-mean-to-distrust-the-infrastructure)
* [Why does this website use Cloudflare?](#why-does-this-website-use-cloudflare)
* [Why doesn't this website have security feature X?](#why-doesnt-this-website-have-security-feature-x)
[Installation & Hardware Compatibility](#installation--hardware-compatibility)
------------------------------------------------------------------------------
* [How much disk space does each qube require?](#how-much-disk-space-does-each-qube-require)
* [How much memory is recommended for Qubes?](#how-much-memory-is-recommended-for-qubes)
* [Can I install Qubes on a system without VT-x?](#can-i-install-qubes-on-a-system-without-vt-x)
* [Can I install Qubes on a system without VT-d?](#can-i-install-qubes-on-a-system-without-vt-d)
* [What is a DMA attack?](#what-is-a-dma-attack)
* [Can I use AMD-v instead of VT-x?](#can-i-use-amd-v-instead-of-vt-x)
* [Can I install Qubes in a virtual machine (e.g., on VMWare)?](#can-i-install-qubes-in-a-virtual-machine-eg-on-vmware)
* [Why does my network adapter not work?](#why-does-my-network-adapter-not-work)
* [Can I install Qubes OS together with other operating system (dual-boot/multi-boot)?](#can-i-install-qubes-os-together-with-other-operating-system-dual-bootmulti-boot)
[Common Problems](#common-problems)
-----------------------------------
* [My qubes lost Internet access after a TemplateVM update. What should I do?](#my-qubes-lost-internet-access-after-a-templatevm-update-what-should-i-do)
* [My keyboard layout settings are not behaving correctly. What should I do?](#my-keyboard-layout-settings-are-not-behaving-correctly-what-should-i-do)
* [My dom0 and/or TemplateVM update stalls when attempting to update via …](#my-dom0-andor-templatevm-update-stalls-when-attempting-to-update-via-the-gui-tool-what-should-i-do)
* [How do I run a Windows HVM in non-seamless mode (i.e., as a single window)?](#how-do-i-run-a-windows-hvm-in-non-seamless-mode-ie-as-a-single-window)
* [I created a usbVM and assigned usb controllers to it. Now the usbVM wont boot.](#i-created-a-usbvm-and-assigned-usb-controllers-to-it-now-the-usbvm-wont-boot)
* [I assigned a PCI device to a qube, then unassigned it/shut down the …](#i-assigned-a-pci-device-to-a-qube-then-unassigned-itshut-down-the-qube-why-isnt-the-device-available-in-dom0)
* [How do I install Flash in a Debian qube?](#how-do-i-install-flash-in-a-debian-qube)
* [How do I play video files?](#how-do-i-play-video-files)
* [How do I access my external drive?](#how-do-i-access-my-external-drive)
* [My encrypted drive doesn't appear in Debian qube?](#my-encrypted-drive-doesnt-appear-in-debian-qube)
* [Windows Update is stuck.](#windows-update-is-stuck)
* [Fullscreen Firefox is frozen.](#fullscreen-firefox-is-frozen)
* [I have weird graphics glitches like the screen turning partially black.](#i-have-weird-graphics-glitches-like-the-screen-turning-partially-black)
-----------------
General Questions
-----------------
### Is Qubes just another Linux distribution?
If you really want to call it a distribution, then it's more of a "Xen distribution" than a Linux one.
But Qubes is much more than just Xen packaging.
It has its own VM management infrastructure, with support for template VMs, centralized VM updating, etc. It also has a very unique GUI virtualization infrastructure.
### How is Qubes different from other security solutions?
Please see [this article](https://blog.invisiblethings.org/2012/09/12/how-is-qubes-os-different-from.html) for a thorough discussion.
### Does Qubes use full disk encryption (FDE)?
Yes, of course!
Full disk encryption is enabled by default.
Specifically, we use [`LUKS`](https://en.wikipedia.org/wiki/Linux_Unified_Key_Setup)/[`dm-crypt`](https://en.wikipedia.org/wiki/Dm-crypt).
You can even [manually configure your encryption parameters](/doc/encryption-config/), if you like!
### What is the main concept behind Qubes?
To build security on the “Security by Compartmentalization (or Isolation)” principle.
### What about other approaches to security?
The other two popular [approaches](https://blog.invisiblethings.org/2008/09/02/three-approaches-to-computer-security.html) are “Security by Correctness” and “Security by Obscurity.”
We don't believe either of these approaches are capable of providing reasonable security today, nor do we believe that they will be capable of doing so in the foreseeable future.
### What about safe languages and formally verified microkernels?
In short: these are non-realistic solutions today. We discuss this in further depth in our [Architecture Specification document](/attachment/wiki/QubesArchitecture/arch-spec-0.3.pdf).
### Why does Qubes use virtualization?
We believe that this is currently the only practically viable approach to implementing strong isolation while simultaneously providing compatibility with existing applications and drivers.
### What do all these terms mean?
All Qubes-specific terms are defined in the [glossary](/doc/glossary/).
### Does Qubes run every app in a separate VM?
No! This would not make much sense. Qubes uses lightweight VMs to create security qubes (e.g., "work," "personal," and "banking,").
A typical user would likely need around five qubes. Very paranoid users, or those who are high-profile targets, might use a dozen or more qubes.
### Why does Qubes use Xen instead of KVM or some other hypervisor?
In short: we believe the Xen architecture allows for the creation of more secure systems (i.e. with a much smaller TCB, which translates to a smaller attack surface).
We discuss this in much greater depth in our [Architecture Specification document](/attachment/wiki/QubesArchitecture/arch-spec-0.3.pdf).
### What about this other/new (micro)kernel/hypervisor?
Whenever starting a discussion about another (micro)kernel or hypervisor in relation to Qubes, we strongly suggest including answers to the following questions first:
1. What kinds of containers does it use for isolation? Processes? PV VMs? Fully virtualized VMs (HVMs)? And what underlying h/w technology is used (ring0/3, VT-x)?
2. Does it require specially written/built applications (e.g. patched Firefox)?
3. Does it require custom drivers, or can it use Linux/Windows ones?
4. Does it support VT-d, and does it allow for the creation of untrusted driver domains?
5. Does it support S3 sleep?
6. Does it work on multiple CPUs/Chipsets?
7. What are the performance costs, more or less? (e.g. "XYZ prevents concurrent execution of two domains/processes on shared cores of a single processor", etc.)
8. Other special features? E.g. eliminates cooperative covert channels between VMs?
Here are the answers for Xen 4.1 (which we use as of 2014-04-28):
1. PV and HVM Virtual Machines (ring0/3 for PV domains, VT-x/AMD-v for HVMs).
2. Runs unmodified usermode apps (binaries).
3. Runs unmodified Linux drivers (dom0 and driver domains). PV VMs require special written pvdrivers.
4. Full VT-d support including untrusted driver domains.
5. S3 sleep supported well.
6. Works on most modern CPUs/Chipsets.
7. Biggest performance hit on disk operations (especially in Qubes when complex 2-layer mapping used for Linux qubes). No GPU virtualization.
8. Mostly Works<sup>TM</sup> :)
### What's so special about Qubes' GUI virtualization?
We have designed the GUI virtualization subsystem with two primary goals: security and performance.
Our GUI infrastructure introduces only about 2,500 lines of C code (LOC) into the privileged domain (Dom0), which is very little, and thus leaves little space for bugs and potential attacks.
At the same time, due to the smart use of Xen shared memory, our GUI implementation is very efficient, so most virtualized applications really feel as if they were executed natively.
### Can I watch YouTube videos in qubes?
Absolutely.
### Can I run applications, like games, which require 3D support?
Those won’t fly.
We do not provide OpenGL virtualization for Qubes.
This is mostly a security decision, as implementing such a feature would most likely introduce a great deal of complexity into the GUI virtualization infrastructure.
However, Qubes does allow for the use of accelerated graphics (OpenGL) in Dom0’s Window Manager, so all the fancy desktop effects should still work.
For further discussion about the potential for GPU passthorugh on Xen/Qubes, please see the following threads:
- [GPU passing to HVM](https://groups.google.com/group/qubes-devel/browse_frm/thread/31f1f2da39978573?scoring=d&q=GPU&)
- [Clarifications on GPU security](https://groups.google.com/group/qubes-devel/browse_frm/thread/31e2d8a47c8b4474?scoring=d&q=GPU&)
### Is Qubes a multi-user system?
No.
Qubes does not pretend to be a multi-user system.
Qubes assumes that the user who controls Dom0 controls the whole system.
It would be very difficult to **securely** implement multi-user support.
See [here](https://groups.google.com/group/qubes-devel/msg/899f6f3efc4d9a06) for details.
### Why passwordless sudo?
Please refer to [this page](https://www.qubes-os.org/doc/vm-sudo/).
### How should I report documentation issues?
Please see the [documentation guidelines](/doc/doc-guidelines).
### Will Qubes seek to get certified under the GNU Free System Distribution Guidelines (GNU FSDG)?
Not currently, for the same reasons that [Debian is not certified](https://www.gnu.org/distros/common-distros.en.html).
### Should I trust this website?
This website is hosted via GitHub Pages behind Cloudflare ([why?](#why-does-this-website-use-cloudflare)).
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).
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"?
A core tenet of the Qubes philosophy is "distrust the infrastructure," where "the infrastructure" refers to things like hosting providers, CDNs, DNS services, package repositories, email servers, PGP keyservers, etc.
As a project, we focus on securing endpoints instead of attempting to secure "the middle" (i.e., the infrastructure), since one of our primary goals is to free users from being forced to entrust their security to unknown third parties.
Instead, our aim is for users to be required to trust as few entities as possible (ideally, only themselves and any known persons whom they voluntarily decide to trust).
Users can never fully control all the infrastructure they rely upon, and they can never fully trust all the entities who do control it.
Therefore, we believe the best solution is not to attempt to make the infrastructure trustworthy, but instead to concentrate on solutions that obviate the need to do so.
We believe that many attempts to make the infrastructure appear trustworthy actually provide only the illusion of security and are ultimately a disservice to real users.
Since we don't want to encourage or endorse this, we make our distrust of the infrastructure explicit.
Also see: [Should I trust this website?](#should-i-trust-this-website)
### Why does this website use Cloudflare?
Three main reasons:
1. We [distrust the infrastructure](#what-does-it-mean-to-distrust-the-infrastructure), including Cloudflare.
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.
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).
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.
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!)
Installation & Hardware Compatibility
-------------------------------------
(See also: [System Requirements](/doc/system-requirements/), [Hardware Compatibility List](/hcl/), and [Certified Laptops](/doc/certified-laptops/).)
### How much disk space does each qube require?
Each qube is created from a TemplateVM and shares the root filesystem with this TemplateVM (in a read-only manner).
This means that each qube needs only as much disk space as is necessary to store its own private data.
This also means that it is possible to update the software for several qubes simultaneously by running a single update process in the TemplateVM upon which those qubes are based.
(These qubes will then have to be restarted in order for the update to take effect in them.)
### How much memory is recommended for Qubes?
At least 4 GB.
It is possible to install Qubes on a system with 2 GB of RAM, but the system would probably not be able to run more than three qubes at a time.
### Can I install Qubes on a system without VT-x?
Yes.
Xen doesn't use VT-x (or AMD-v) for PV guest virtualization.
(It uses ring0/3 separation instead.)
However, without VT-x, you won't be able to use fully virtualized VMs (e.g., Windows-based qubes), which were introduced in Qubes 2.
In addition, if your system lacks VT-x, then it also lacks VT-d. (See next question.)
### Can I install Qubes on a system without VT-d?
Yes.
You can even run a NetVM, but you will not benefit from DMA protection for driver domains.
On a system without VT-d, everything should work in the same way, except there will be no real security benefit to having a separate NetVM, as an attacker could always use a simple DMA attack to go from the NetVM to Dom0.
**Nonetheless, all of Qubes' other security mechanisms, such as qube separation, work without VT-d.
Therefore, a system running Qubes will still be significantly more secure than one running Windows, Mac, or Linux, even if it lacks VT-d.**
### What is a DMA attack?
DMA is mechanism for PCI devices to access system memory (read/write).
Without VT-d, any PCI device can access all the memory, regardless to which VM it is assigned (or if it is left in dom0).
Most PCI devices allow the driver to request an arbitrary DMA operation (like "put received network packets at this address in memory", or "get this memory area and send it to the network").
So, without VT-d, it gives unlimited access to the whole system.
Now, it is only a matter of knowing where to read/write to take over the system, instead of just crashing.
But since you can read the whole memory, it isn't that hard.
Now, how does this apply to Qubes OS?
The above attack requires access to a PCI device, which means that it can be performed only from NetVM / UsbVM, so someone must first break into one of those VMs.
But this isn't that hard, because there is a lot of complex code handling network traffic.
Recent bugs includes DHCP client, DNS client, etc.
Most attacks on NetVM / UsbVM (but not all!) require being somewhat close to the target system - for example connected to the same WiFi network, or in the case of a UsbVM, having physical acccess to a USB port.
### Can I use AMD-v instead of VT-x?
See [this message](http://groups.google.com/group/qubes-devel/msg/6412170cfbcb4cc5).
### Can I install Qubes in a virtual machine (e.g., on VMWare)?
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!)
### 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.
Open a terminal and run `sudo yum install linux-firmware` in the TemplateVM upon which your NetVM is based. You have to restart the NetVM after the TemplateVM has been shut down.
### Can I install Qubes OS together with other operating system (dual-boot/multi-boot)?
You shouldn't do that, because it pose a security risk for your Qubes OS installation.
But if you understand the risk and accept it, read [documentation on multibooting](/doc/multiboot/).
It starts with explanation what is wrong with using such setup.
Common Problems
---------------
### My qubes lost Internet access after a TemplateVM update. What should I do?
Run `systemctl enable NetworkManager-dispatcher.service` in the TemplateVM upon which your NetVM is based.
You may have to reboot afterward for the change to take effect.
(Note: This is an upstream problem. See [here](https://bugzilla.redhat.com/show_bug.cgi?id=974811).
For details, see the qubes-users mailing list threads [here](https://groups.google.com/d/topic/qubes-users/xPLGsAJiDW4/discussion) and [here](https://groups.google.com/d/topic/qubes-users/uN9G8hjKrGI/discussion).)
### My keyboard layout settings are not behaving correctly. What should I do?
The best approach is to choose the right keyboard layout during the installation process. But if you want to change things afterwards, you can try this workaround.
Assuming XFCE desktop: in `Q` → `System Tools` → `Keyboard` → `Layout`, leave the checkbox "`Use system defaults`" checked. Do not customize the keyboard layout here.
Set the system-wide layout and options for `xorg` with the `localectl` command in `dom0`. You can use `localectl --help` as a starting point.
Example: `localectl set-x11-keymap us dell ,qwerty compose:caps`.
This generates the appropriate configuration in `/etc/X11/xorg.conf.d/00-keyboard.conf`. This file is auto-generated. Do not edit it by hand, unless you know what you are doing.
Restarting `xorg` is required. The most straightforward way is to reboot the system.
More information in [this discussion](https://groups.google.com/d/topic/qubes-devel/d8ZQ_62asKI/discussion) and [this issue](https://github.com/QubesOS/qubes-issues/issues/1396).
### My dom0 and/or TemplateVM update stalls when attempting to update via the GUI tool. What should I do?
This can usually be fixed by updating via the command line.
In dom0, open a terminal and run `sudo qubes-dom0-update`.
In your TemplateVMs, open a terminal and run `sudo yum upgrade`.
### How do I run a Windows HVM in non-seamless mode (i.e., as a single window)?
Enable "debug mode" in the qube's settings, either by checking the box labeled "Run in debug mode" in the Qubes VM Manager qube settings menu or by running the [qvm-prefs command](/doc/dom0-tools/qvm-prefs/).)
### I created a usbVM and assigned usb controllers to it. Now the usbVM wont boot.
This is probably because one of the controllers does not support reset.
In Qubes R2 any such errors were ignored but in Qubes R3.0 they are not.
A device that does not support reset is not safe and generally should not be assigned to a VM.
Most likely the offending controller is a USB3.0 device.
You can remove this controller from the usbVM, and see if this allows the VM to boot.
Alternatively you may be able to disable USB 3.0 in the BIOS.
Errors suggesting this issue:
- in `xl dmesg` output:
(XEN) [VT-D] It's disallowed to assign 0000:00:1a.0 with shared RMRR at dbe9a000 for Dom19.
(XEN) XEN_DOMCTL_assign_device: assign 0000:00:1a.0 to dom19 failed (-1)
- during `qvm-start sys-usb`:
internal error: Unable to reset PCI device [...] no FLR, PM reset or bus reset available.
Another solution would be to set the pci_strictreset option using qvm-prefs in dom0:
`qvm-prefs usbVM -s pci_strictreset false`
This option allows the VM to ignore the error and the VM will start.
Please review the note on [this page](https://www.qubes-os.org/doc/Dom0Tools/QvmPrefs/) and be aware of the potential risk.
### I assigned a PCI device to a qube, then unassigned it/shut down the qube. Why isn't the device available in dom0?
This is an intended feature.
A device which was previously assigned to a less trusted qube could attack dom0 if it were automatically reassigned there.
In order to re-enable the device in dom0, either:
* Reboot the physical machine.
or
* Go to the sysfs (`/sys/bus/pci`), find the right device, detach it from the pciback driver and attach back to the original driver. Replace `<BDF>` with your device, for example `00:1c.2`:
echo 0000:<BDF> > /sys/bus/pci/drivers/pciback/unbind
MODALIAS=`cat /sys/bus/pci/devices/0000:<BDF>/modalias`
MOD=`modprobe -R $MODALIAS | head -n 1`
echo 0000:<BDF> > /sys/bus/pci/drivers/$MOD/bind
### How do I install Flash in a Debian qube?
The Debian way is to install the flashplugin-nonfree package.
Do this in a Debian template. You will have to allow Full access in the firewall prior to installation.
This will make Flash available to every qube using that template.
If you only want Flash available in one qube:
- download the Flash Player for linux (64 bit) .tar.gz from [Adobe](https://get.adobe.com/flashplayer/otherversions).
- untar the downloaded file ```tar xf install_flash_player_11_linux.x86_64.tar.gz```
- create `~/.mozilla/plugins` if it does not exist
- move `libflashhplayer.so` to `~/.mozilla/plugins`, and restart iceweasel.
### How do I play video files?
If you're having trouble playing a video file in a qube, you're probably missing the required codecs.
The easiest way to resolve this is to install VLC Media Player and use that to play your video files.
You can do this in multiple different TemplateVM distros (Fedora, Debian, etc.).
For Debian:
1. (Recommended) Clone an existing Debian TemplateVM
2. Install VLC in that TemplateVM:
$ sudo apt install vlc
3. Use VLC to play your video files
For Fedora:
1. (Recommended) Clone an existing Fedora TemplateVM
2. [Enable the appropriate RPMFusion repos in the desired Fedora TemplateVM.](/doc/software-update-vm/#rpmfusion-for-a-fedora-templatevm)
3. Install VLC in that TemplateVM:
$ sudo dnf install vlc
4. Use VLC to play your video files.
### How do I access my external drive?
External media such as external hard drives or flash drives plugged in via USB are available in the sys-usb VM.
They can either be manually mounted with the `mount` command, or accessed conveniently via the graphical file manager which mounts them under `/run/media/user`.
Devices which are passed from one VM to another via `qvm-block` show up as `/dev/xvd*` and must be mounted manually.
See ["How to attach USB drives"](/doc/usb/#how-to-attach-usb-drives) for more information.
### My encrypted drive doesn't appear in Debian qube.
This is an issue that affects qubes based on Debian Jessie.
The problem is fixed in Stretch, and does not affect Fedora-based qubes.
A mixed drive with some encrypted partitions appears correctly in Nautilus.
The encrypted partitions are identified and the user is prompted for password on attempting to mount the partition.
A fully encrypted drive does not appear in Nautilus.
The work round is to manually decrypt and mount the drive:
1. attach usb device to qube - it should be attached as /dev/xvdi or similar.
2. sudo cryptsetup open /dev/xvdi bk --type luks
3. sudo cryptsetup status /dev/mapper/bk [Shows useful status]
4. sudo mount /dev/mapper/bk /mnt
The decrypted device is now available at `/mnt` - when you have finished using it unmount and close the drive.
1. sudo umount /mnt
2. sudo cryptsetup close bk --type luks
3. remove usb from qube
### Windows Update is stuck.
This has nothing to do with Qubes.
[It's a longstanding Windows bug.](https://superuser.com/questions/951960/windows-7-sp1-windows-update-stuck-checking-for-updates)
### Fullscreen Firefox is frozen.
Press `F11` twice.
### I have weird graphics glitches like the screen turning partially black.
If it seems like the issue described in [this thread](https://github.com/QubesOS/qubes-issues/issues/2399), try disabling the window compositor:
- Q → System Tools → Window Manager Tweaks → Compositor → uncheck "Enable display compositing"
Please report (via the mailing lists) if you experience this issue, and whether disabling the compositor fixes it for you or not.

490
building/building-archlinux-template.md Normal file
View File

@ -0,0 +1,490 @@
---
layout: doc
title: Building Archlinux Template
permalink: /doc/building-archlinux-template/
redirect_from:
- /en/doc/building-archlinux-template/
- /doc/BuildingArchlinuxTemplate/
- /wiki/BuildingArchlinuxTemplate/
---
# Archlinux template building instructions
**These are the instructions for Qubes 3.2. They will take you step by step through the entire process start to finish**
*Note: These instructions have not been tested for Qubes 3.1. However they could be working.*
*Note: No binary package for the archlinux template exists for Qubes 3.1.*
## 1: Create and configure VM to use for template building
* The VM should be based on a Fedora template. It's best to use a standalone VM. I created a standalone VM based on
the Fedora 23 template. I named the VM “**development**”. These instructions assume a standalone VM based on a Fedora template is being used.
<br>
<br>
![arch-template-01](/attachment/wiki/ArchlinuxTemplate/arch-template-01.png)
<br>
<br>
* Ensure there is at least 25GB preferably 30GB of free space in the private storage. I made the private storage 30GB to be safe.
<br>
<br>
![arch-template-02](/attachment/wiki/ArchlinuxTemplate/arch-template-02.png)
<br>
<br>
*Note: Unless otherwise noted, all commands are from within the “development” VM or whatever you named your standalone VM used for building the template.*
## 2: Create GitHub Account (optional)
* It can be helpful. Creating only a basic account is all that is needed. This will allow you to help, going forward, with the Qubes project. You could be help edit errors in documentation. It can also be of use building other templates.
* Create user account here https://github.com
<br>
<br>
![arch-template-03](/attachment/wiki/ArchlinuxTemplate/arch-template-03.png)
<br>
<br>
## 3: Install necessary packages to 'development' VM for "Qubes Automated Build System"
* Necessary packages to install:
* git
* createrepo
* rpm-build
* make
* rpmdevtools
* python-sh
* dialog
* rpm-sign
* gnupg
* 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**
<br>
<br>
![arch-template-04](/attachment/wiki/ArchlinuxTemplate/arch-template-04.png)
<br>
<br>
## 4: Downloading and verifying the "Qubes Automated Build System"
* Import the Qubes master key
gpg --recv-keys 0xDDFA1A3E36879494
* Verify its fingerprint, set as 'trusted'. [This is described here](https://www.qubes-os.org/doc/VerifyingSignatures).
* Download the Qubes developers' keys.
wget https://keys.qubes-os.org/keys/qubes-developers-keys.asc
gpg --import qubes-developers-keys.asc
* Download the latest stable qubes-builder repository:
git clone git://github.com/QubesOS/qubes-builder.git qubes-builder
![arch-template-05](/attachment/wiki/ArchlinuxTemplate/arch-template-05.png)
* Copy your gpg keyrings to your local copy of the repository. (Otherwise you will be asked to download the keys again.)
# Assuming qubes-builder is in your home directory
cp .gnupg/pubring.gpg qubes-builder/keyrings/git/
cp .gnupg/trustdb.gpg qubes-builder/keyrings/git/
* Verify the integrity of the downloaded repository. The last line should read `gpg: Good signature from`...
cd qubes-builder
git tag -v `git describe`
## 5: Configuring setup script to create builder.conf file
* You will be creating the builder.conf file which tells where and what to use. The most automated, and in this case the easiest, way to create this is to use the script that is provided in Qubes Builder. Its named '**setup**'. Before running the script you need to edit one file it uses.
*In the future this should not be needed once a change is made to the 'setup' script.*
* 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/**
* **$ nano -W qubes-os-r3.2.conf** or **$ gedit qubes-os-r3.2.conf** or etc….
<br>
<br>
![arch-template-06](/attachment/wiki/ArchlinuxTemplate/arch-template-06.png)
<br>
<br>
* Go to the first line containing '**DISTS_VM ?= fc23**' it will be preceeded by line '**DIST_DOM0 ?= fc20**'. Remove '**fc23**' or whatever is listed there leaving only '**DISTS_VM ?=**'. Then save the file and close the text editor.
<br>
<br>
![arch-template-07](/attachment/wiki/ArchlinuxTemplate/arch-template-07.png)
<br>
<br>
<br>
## 6: Run the 'setup' script to build the builder.conf file
* Run the 'setup' script located in '**/home/user/qubes-builder/**' Make sure you are in directory '**qubes-builder**'
* **$ cd /home/user/qubes-builder/**
* **$ ./setup**
<br>
<br>
![arch-template-08](/attachment/wiki/ArchlinuxTemplate/arch-template-08.png)
<br>
<br>
* First screen will ask you to import 'Qubes-Master-Signing-key.asc'. The 'setup' script not only downloads but confirms the key to that of the key on Qubes-OS website.
* Select '**YES**'
* Select '**OK**' Press '**Enter**'
<br>
<br>
![arch-template-09](/attachment/wiki/ArchlinuxTemplate/arch-template-09.png)
<br>
<br>
* Next screen will ask you to import Marek Marczykowski-Goracki (Qubes OS signing key). Again 'setup' will confirm this key to the fingerprint.
* Select '**YES**'
* Select '**OK**' Press '**Enter**'
<br>
<br>
![arch-template-10](/attachment/wiki/ArchlinuxTemplate/arch-template-10.png)
<br>
<br>
* This screen will give you the choice of which Qubes Release to build the template for.
* Select '**Qubes Release 3.2**'
* Select '**OK**' Press '**Enter**'
<br>
<br>
![arch-template-11](/attachment/wiki/ArchlinuxTemplate/arch-template-11.png)
<br>
<br>
* Screen "**Choose Repos To Use To Build Packages**"
* Select 'QubesOS/qubes- Stable - Default Repo'
* Select '**OK**' Press '**Enter**'
<br>
<br>
![arch-template-12](/attachment/wiki/ArchlinuxTemplate/arch-template-12.png)
<br>
<br>
* Screen "**Build Template Only?**"
* Select '**Yes**' Press '**Enter**'
<br>
<br>
![arch-template-12](/attachment/wiki/ArchlinuxTemplate/arch-template-12a.png)
<br>
<br>
* Screen '**Builder Plugin Selection**' will give choices of builder plugins to use for the build.
* Deselect '**Fedora**'
* Deselect '**mgmt_salt**'
* Select '**builder-archlinux**'
* Select '**OK**' Press **Enter**
<br>
<br>
![arch-template-13](/attachment/wiki/ArchlinuxTemplate/arch-template-13.png)
<br>
<br>
* Screen '**Get sources**' wants to download additional packages needed for the choosen plugin/s.
* Select '**Yes**' Press '**Enter**'
<br>
<br>
![arch-template-14](/attachment/wiki/ArchlinuxTemplate/arch-template-14.png)
<br>
<br>
* Then wait for download to finish and press '**OK**'
<br>
<br>
![arch-template-14](/attachment/wiki/ArchlinuxTemplate/arch-template-15.png)
<br>
<br>
* Screen '**Template Distribution Selection**' allows you to choose the actual template/s you wish to build.
* Scroll Down to the very bottom (it is off the screen at first)
* Select '**archlinux**'
* Select '**OK**' Press '**Enter**'
<br>
<br>
![arch-template-16](/attachment/wiki/ArchlinuxTemplate/arch-template-16.png)
<br>
<br>
*Note: 'Setup' will close and will output the text of the created build.conf file as well as the needed **make** commands to build the template*
<br>
<br>
![arch-template-17](/attachment/wiki/ArchlinuxTemplate/arch-template-17.png)
<br>
<br>
## 7: Install all the dependencies
*Note: make sure you are in the “qubes-builder” directory to run the following cmds*
* **$ make install-deps**
<br>
<br>
![arch-template-18](/attachment/wiki/ArchlinuxTemplate/arch-template-18.png)
<br>
<br>
## 8: Get all the require sources for the build: (Note: this may take some time)
* **$ make get-sources**
<br>
<br>
![arch-template-19](/attachment/wiki/ArchlinuxTemplate/arch-template-19.png)
<br>
<br>
<br>
## 9: Make all the require Qubes Components
* **Note:** You can run a single command to build all the Qubes components or you can run them each individually.
Both ways below:
* Single command to build all Qubes components together: (this command can take a long time to process depending of your pc proccessing power)
* **$ make qubes-vm**
<br>
<br>
![arch-template-20](/attachment/wiki/ArchlinuxTemplate/arch-template-20.png)
<br>
<br>
* These are the indivual component 'make' commands:
* **$ make vmm-xen-vm**
* **$ make core-vchan-xen-vm**
* **$ make core-qubesdb-vm**
* **$ make linux-utils-vm**
* **$ make core-agent-linux-vm**
* **$ make gui-common-vm**
* **$ make gui-agent-linux-vm**
<br>
<br>
## 10: Make the actual Archlinux template
* **$ make template**
<br>
<br>
![arch-template-21](/attachment/wiki/ArchlinuxTemplate/arch-template-21.png)
<br>
<br>
## 11: Transfer Template into Dom0
* You need to ensure these two files are in the '**noarch**' directory
* **$ cd /home/user/qubes-builder/qubes-src/linux-template-builder/rpm/**
* **$ ls** *(confirm the below two files are there)*
* **install-templates.sh** (script to install template in dom0)
* **$ cd noarch**
* **$ ls**
* **qubes-template-archlinux-X.X.X-XXXXXXXXXXXX.noarch.rpm** (this is the template package 'X' replaces version and build digits)
<br>
<br>
![arch-template-22](/attachment/wiki/ArchlinuxTemplate/arch-template-22.png)
<br>
<br>
* **Transfer the install-templates.sh script file into Dom0**
*Note: as there is not a typical file transfer method for Dom0, for security reasons, this less than simple transfer function has to be used*
* Switch to Domo and open a terminal window.
**Note:** Take care when entering these cmd strings. They are very long and have a number of characters that are easy to mix '**-**' vs '**.**' '**<u>T</u>emplates** (correct) vs **<u>t</u>emplates** (wrong) or **Template_**'(also wrong) This script will also take care of transfering the actual template.rpm to Dom0 as well.
* **$ qvm-run --pass-io development 'cat /home/user/qubes-builder/qubes-src/linux-template-builder/rpm/install-templates.sh' > install-templates.sh**
* **$ chmod +x install-templates.sh**
* **$ ./install-templates.sh**
<br>
<br>
![arch-template-23](/attachment/wiki/ArchlinuxTemplate/arch-template-23.png)
<br>
<br>
![arch-template-24](/attachment/wiki/ArchlinuxTemplate/arch-template-24.png)
<br>
<br>
* If everything went correct there should be a Archlinux template listed in your Qubes VM Manager *
# Known problems in building with Qubes R3.X
## Build fails when fetching qubes-mgmt-salt
The `qubes-mgmt-salt` repo is not currently forked under the marmarek user on
GitHub, to whom the above instructions set the `GIT_PREFIX`. As Archlinux is
not yet supported by mgmt-salt, simply leave it out of the build (when building
the Archlinux template on it's own) by appending the following to your `override.conf` file:
`BUILDER_PLUGINS := $(filter-out mgmt-salt,$(BUILDER_PLUGINS))`
## The nm-applet (network manager icon) fails to start when archlinux is defined as a template-vm
In fact /etc/dbus-1/system.d/org.freedesktop.NetworkManager.conf does not allow a standard user to run network manager clients. To allow this, one need to change inside \<policy context="default"\>:
`<deny send_destination="org.freedesktop.NetworkManager"/>`
to
`<allow send_destination="org.freedesktop.NetworkManager"/>`
## DispVM, Yum proxy and most Qubes addons (thunderbird ...) have not been tested at all
## Error when building the gui-agent-linux with pulsecore error
```
module-vchan-sink.c:62:34: fatal error: pulsecore/core-error.h: No such file or directory
#include <pulsecore/core-error.h>
```
This error is because Archlinux update package too quickly. Probably, a new version of pulseaudio has been released, but the qubes team has not imported the new development headers yet.
You can create fake new headers just by copying the old headers:
```
cd qubes-builder/qubes-src/gui-agent-linux/pulse
ls
cp -r pulsecore-#lastversion pulsecore-#archlinuxversion
```
You can check the current archlinux pulseaudio version like this:
`sudo chroot chroot-archlinux/ pacman -Qi pulseaudio`
## chroot-archlinux/dev/pts has not been unmounted
This is a known problem when there are errors during building. Check what is mounted using the command mount (with no parameters). Just unmount what you can (or reboot your vm if you are too lazy :) )
# Known problems in building with Qubes R2-B2
## xen-vmm-vm fail to build with a PARSETUPLE related error (FIXED)
Commenting out "\#define HAVE\_ATTRIBUTE\_FORMAT\_PARSETUPLE" from chroot\_archlinux/usr/include/python2.7/pyconfig.h fixes the problem, but it isn't the right solution [1]...
A better fix is planned for the next python release (the bug is considered release blocking), and will be updated in archlinux chroot as soon as available.
[1] [https://bugs.python.org/issue17547](https://bugs.python.org/issue17547)
## The boot process fails without visible errors in the logs, but spawn a recovery shell
The problem is new conflict between systemd and the old sysvinit style. To fix this, you can change the master xen template in dom0 to remove sysvinit remains: Edit **INSIDE DOM0** /usr/share/qubes/vm-template.conf, and change the variable 'extra' that contains the kernel variables: from:
`extra="ro nomodeset 3 console=hvc0 rd_NO_PLYMOUTH {kernelopts}"`
to:
`extra="ro nomodeset console=hvc0 rd_NO_PLYMOUTH {kernelopts}"`
## Qubes-OS is now using different xenstore variable names, which makes to archlinux VM failing to boot
Apply the following fix in the template to revert the variable name to the old Qubes version.
You can edit the template the following way:
```
sudo mkdir /mnt/vm
sudo mount /var/lib/qubes/vm-templates/archlinux-x64/root.img /mnt/vm
sudo chroot /mnt/vm
```
Then apply the fix:
```
sudo sed 's:qubes-keyboard:qubes_keyboard:g' -i /etc/X11/xinit/xinitrc.d/qubes-keymap.sh
sudo sed 's:qubes-netvm-domid:qubes_netvm_domid:g' -i /etc/NetworkManager/dispatcher.d/30-qubes-external-ip
sudo sed 's:qubes-netvm-external-ip:qubes_netvm_external_ip:g' -i /etc/NetworkManager/dispatcher.d/30-qubes-external-ip
sudo sed 's:qubes-netvm-network:qubes_netvm_network:g' -i /usr/lib/qubes/init/network-proxy-setup.sh
sudo sed 's:qubes-netvm-gateway:qubes_netvm_gateway:g' -i /usr/lib/qubes/init/network-proxy-setup.sh
sudo sed 's:qubes-netvm-netmask:qubes_netvm_netmask:g' -i /usr/lib/qubes/init/network-proxy-setup.sh
sudo sed 's:qubes-netvm-secondary-dns:qubes_netvm_secondary_dns:g' -i /usr/lib/qubes/init/network-proxy-setup.sh
sudo sed 's:qubes-vm-type:qubes_vm_type:g' -i /usr/lib/qubes/init/qubes-sysinit.sh
sudo sed 's:qubes-ip:qubes_ip:g' -i /usr/lib/qubes/setup-ip
sudo sed 's:qubes-netmask:qubes_netmask:g' -i /usr/lib/qubes/setup-ip
sudo sed 's:qubes-gateway:qubes_gateway:g' -i /usr/lib/qubes/setup-ip
sudo sed 's:qubes-secondary-dns:qubes_secondary_dns:g' -i /usr/lib/qubes/setup-ip
sudo sed 's:qubes-netvm-network:qubes_netvm_network:g' -i /usr/lib/qubes/setup-ip
sudo sed 's:qubes-netvm-gateway:qubes_netvm_gateway:g' -i /usr/lib/qubes/setup-ip
sudo sed 's:qubes-netvm-netmask:qubes_netvm_netmask:g' -i /usr/lib/qubes/setup-ip
sudo sed 's:qubes-netvm-secondary-dns:qubes_netvm_secondary_dns:g' -i /usr/lib/qubes/setup-ip
sudo sed 's:qubes-iptables-domainrules:qubes_iptables_domainrules:g' -i /usr/bin/qubes-firewall
sudo sed 's:qubes-iptables-header:qubes_iptables_header:g' -i /usr/bin/qubes-firewall
sudo sed 's:qubes-iptables-error:qubes_iptables_error:g' -i /usr/bin/qubes-firewall
sudo sed 's:qubes-iptables:qubes_iptables:g' -i /usr/bin/qubes-firewall
sudo sed 's:qubes-netvm-domid:qubes_netvm_domid:g' -i /usr/bin/qubes-netwatcher
sudo sed 's:qubes-netvm-external-ip:qubes_netvm_external_ip:g' -i /usr/bin/qubes-netwatcher
sudo sed 's:qubes-vm-updateable:qubes_vm_updateable:g' -i /usr/lib/qubes/qubes_trigger_sync_appmenus.sh
sudo sed 's:qubes-vm-type:qubes_vm_type:g' -i /usr/bin/qubes-session
sudo sed 's:qubes-vm-updateable:qubes_vm_updateable:g' -i /usr/bin/qubes-session
```
Do not forgot to unmount the VM:
`umount /mnt/vm`
## Installing the template in dom0 fails because of a missing dependency (qubes-core-dom0-linux)
Again you built a template based on a recent Qubes API which has not been released yet. So skip the dependency for now
`sudo rpm -U --nodeps yourpackage.rpm`
# Qubes Mailing List Threads on the Archlinux build process
* [Qubes-Devel](https://groups.google.com/forum/#!forum/qubes-devel): [Qubes Builder failed Archlinux repository is missing](https://groups.google.com/forum/#!topic/qubes-devel/tIFkS-rPVx8)
* [Qubes-Users](https://groups.google.com/forum/#!forum/qubes-users): [Trying to compile archlinux template](https://groups.google.com/forum/#!topic/qubes-users/7wuwr3LgkQQ)
<br>

23
developers/building/building-non-fedora-template.md → building/building-non-fedora-template.md
View File

@ -89,17 +89,12 @@ You will be able to test these script when making the first Qubes packages. Don'
Qubes packages
--------------
### vmm-xen-vm
### core-vchan-xen-vm
### linux-utils-vm
### core-agent-linux-vm
### gui-common-vm
### gui-agent-linux-vm
* [vmm-xen](https://github.com/QubesOS/qubes-vmm-xen)
* [core-vchan-xen](https://github.com/QubesOS/qubes-core-vchan-xen)
* [linux-utils](https://github.com/QubesOS/qubes-linux-utils)
* [core-agent-linux](https://github.com/QubesOS/qubes-core-agent-linux)
* [gui-common](https://github.com/QubesOS/qubes-gui-common)
* [gui-agent-linux](https://github.com/QubesOS/qubes-gui-agent-linux)
Additional Installation scripts
-------------------------------
@ -137,15 +132,15 @@ As soon as you manage to make qrexec and qubes-gui-agent working, it should be s
### 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 git://git.qubes-os.org/marmarek/xen`
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 'xen-vm'. For example, a PKGBUILD has been created for [ArchLinux](/doc/templates/archlinux/) and can be found on [http://aur.archlinux.org/packages/qu/qubes-vm-xen/PKGBUILD](http://aur.archlinux.org/packages/qu/qubes-vm-xen/PKGBUILD).
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`
Now install the package you built and mount /proc/xen. Verify that xenstore-read works by running: `xenstore-read qubes_vm_type` That should give you the current VM type such as HVM or AppVM.
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...)

2
developers/building/development-workflow.md → building/development-workflow.md
View File

@ -541,6 +541,6 @@ Usage: add this line to `/etc/apt/sources.list` on test machine (adjust host and
deb http://local-test.lan/linux-deb/r3.1 jessie-unstable main
~~~
[port-forwarding]: /doc/qubes-firewall/#tocAnchor-1-1-5
[port-forwarding]: /doc/firewall/#port-forwarding-to-a-qube-from-the-outside-world
[linux-yum]: https://github.com/QubesOS/qubes-linux-yum
[linux-deb]: https://github.com/QubesOS/qubes-linux-deb

0
developers/building/qubes-builder-details.md → building/qubes-builder-details.md
View File

23
developers/building/qubes-builder.md → building/qubes-builder.md
View File

@ -8,6 +8,8 @@ redirect_from:
- /wiki/QubesBuilder/
---
**Note: The build system has been improved since this how-to was last updated. The [Archlinux template building instructions](https://www.qubes-os.org/doc/building-archlinux-template/) contain more up-to-date and detailed information on how to use the build system.**
Building Qubes from scratch
===========================
@ -17,6 +19,8 @@ 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
- git
- createrepo
- rpm-build
@ -26,28 +30,31 @@ In order to use it one should use an rpm-based distro, like Fedora :) and should
- python-sh
- dialog
- rpm-sign
- dpkg-dev
- debootstrap
- PyYAML
Unusually one can install those packages by just issuing:
Usually one can install those packages by just issuing:
sudo yum install git createrepo rpm-build make wget rpmdevtools python-sh dialog rpm-sign
sudo dnf install gpg git createrepo rpm-build make wget rpmdevtools python-sh dialog rpm-sign dpkg-dev debootstrap PyYAML
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.
The build system is configured via builder.conf file -- one should copy the attached builder.conf.default, and modify it as needed, e.g.:
The build system is configured via builder.conf file -- one should copy the provided default builder.conf, and modify it as needed, e.g.:
cp example-configs/qubes-os-master.conf builder.conf
# edit the builder.conf file and set the following variables:
NO_SIGN=1
One additional useful requirement is that 'sudo root' work without any prompt, which is default on most distros (e.g. 'sudo bash' brings you the root shell without asking for any password). This is important as the builder needs to switch to root and then back to user several times during the build process.
One additional useful requirement is that 'sudo root' must work without any prompt, which is default on most distros (e.g. 'sudo bash' brings you the root shell without asking for any password). This is important as the builder needs to switch to root and then back to user several times during the build process.
Additionally, if building with signing enabled (so NO\_SIGN is not set), one must adjust \~/.rpmmacro file so that it point to the GPG key used for package signing, e.g.:
Additionally, if building with signing enabled (NO\_SIGN is not set), one must adjust \~/.rpmmacro file so that it points to the GPG key used for package signing, e.g.:
%_signature gpg
%_gpg_path /home/user/.gnupg
%_gpg_name AC1BF9B3 # <-- Key ID used for signing
It is also recommended to use an empty passphrase for the private key used for signing. Contrary to a popular belief, this doesn't affect your key or sources security -- if somebody compromised your system, then the game is over, whether you use additional passphrase for the key or not.
It is also recommended to use an empty passphrase for the private key used for signing. Contrary to a popular belief, this doesn't affect your key or sources security -- if somebody compromised your system, then the game is over anyway, whether you have used an additional passphrase for the key or not.
So, to build Qubes one would do:
@ -89,7 +96,7 @@ You can also build selected component separately. Eg. to compile only gui virtua
make gui-daemon
Full list you can get from make help. For advanced use and preparing sources
You can get a full list from make help. For advanced use and preparing sources
for use with [QubesBuilder](/doc/qubes-builder/) take a look at [doc directory
in QubesBuilder](https://github.com/marmarek/qubes-builder/tree/master/doc) or
[QubesBuilderDetails](/doc/qubes-builder-details/) page.
@ -126,7 +133,7 @@ If you want to somehow modify sources, you can also do it, here are some basic s
make iso
Code verification keys management
=================================
---------------------------------
[QubesBuilder](/doc/qubes-builder/) by default verifies signed tags on every downloaded code. Public keys used for that are stored in `keyrings/git`. By default Qubes developers' keys are imported automatically, but if you need some additional keys (for example your own), you can add them using:

0
developers/building/qubes-r3-building.md → building/qubes-r3-building.md
View File

98
common-tasks/backup-emergency-restore-v4.md Normal file
View File

@ -0,0 +1,98 @@
---
layout: doc
title: Emergency Backup Recovery - format version 4
permalink: /doc/backup-emergency-restore-v4/
redirect_from:
- /en/doc/backup-emergency-restore-v4/
- /doc/BackupEmergencyRestoreV4/
---
Emergency Backup Recovery without Qubes - format version 4
==========================================================
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).
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`.
2. Untar the main backup file.
[user@restore ~]$ tar -i -xvf qubes-backup-2015-06-05T123456
backup-header
backup-header.hmac
qubes.xml.000.enc
vm1/private.img.000.enc
vm1/private.img.001.enc
vm1/private.img.002.enc
vm1/icon.png.000.enc
vm1/firewall.xml.000.enc
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.
read backup_pass
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 ~]$ echo "backup-header!$backup_pass" |\
scrypt -P dec 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/)
5. 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=4
encrypted=True
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
[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; \
done
**Note:** If the above fail, most likely your backup is corrupted, or 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).
8. Mount the private.img file 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.
**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

32
common-tasks/backup-restore.md
View File

@ -24,20 +24,20 @@ Creating a Backup
1. In **Qubes VM Manager**, click **System** on the menu bar, then click **Backup VMs** in the drop-down list. This brings up the **Qubes Backup VMs** window.
2. Move the AppVMs which you desire to back up to the right-hand **Selected** column. AppVMs in the left-hand **Available** column will not be backed up.
2. Move the VMs that you want to back up to the right-hand **Selected** column. VMs in the left-hand **Available** column will not be backed up.
**Note:** An AppVM must be shut down in order to be backed up. Currently running AppVMs appear in red.
**Note:** A VM must be shut down in order to be backed up. Currently running VMs appear in red.
Once you have selected all desired AppVMs, click **Next**.
Once you have selected all desired VMs, click **Next**.
3. Select the destination for the backup:
- If you wish to send your backup to a [USB mass storage device](/doc/stick-mounting/), select the device in the drop-down box next to **Device** (feature removed in R3, select appropriate **Target AppVM** and mount the stick with one click in file selection dialog).
- If you wish to send your backup to a (currently running) AppVM, select the AppVM in the drop-down box next to **Target AppVM**.
If you wish to send your backup to a (currently running) VM, select the VM in the drop-down box next to **Target AppVM**.
If you wish to send your backup to a [USB mass storage device](/doc/stick-mounting/), first mount the device in a VM, then select the mount point inside that VM as the backup destination.
You must also specify a directory on the device or in the AppVM, or a command to be executed in the AppVM as a destination for your backup. For example, if you wish to send your backup to the `~/backups` folder in the target AppVM, you would simply type `backups` in this field. This destination directory must already exist. If it does not exist, you must create it manually prior to backing up.
You must also specify a directory on the device or in the VM, or a command to be executed in the VM as a destination for your backup. For example, if you wish to send your backup to the `~/backups` folder in the target VM, you would simply type `backups` in this field. This destination directory must already exist. If it does not exist, you must create it manually prior to backing up.
By specifying the appropriate directory as the destination in an AppVM, it is possible to send the backup directly to, e.g., a USB mass storage device attached to the AppVM. Likewise, it is possible to enter any command as a backup target by specifying the command as the destination in the AppVM. This can be used to send your backup directly to, e.g., a remote server using SSH.
By specifying the appropriate directory as the destination in a VM, it is possible to send the backup directly to, e.g., a USB mass storage device attached to the VM. Likewise, it is possible to enter any command as a backup target by specifying the command as the destination in the VM. This can be used to send your backup directly to, e.g., a remote server using SSH.
At this point, you must also choose whether to encrypt your backup by checking or unchecking the **Encrypt backup** box.
@ -56,14 +56,14 @@ Restoring from a Backup
2. Select the source location of the backup to be restored:
- If your backup is located on a [USB mass storage device](/doc/stick-mounting/), select the device in the drop-down box next to **Device**.
- If your backup is located in a (currently running) AppVM, select the AppVM in the drop-down box next to **AppVM**.
- If your backup is located in a (currently running) VM, select the VM in the drop-down box next to **AppVM**.
You must also specify the directory in which the backup resides (or a command to be executed in an AppVM). If you followed the instructions in the previous section, "Creating a Backup," then your backup is most likely in the location you chose as the destination in step 3. For example, if you had chosen the `~/backups` directory of an AppVM as your destination in step 3, you would now select the same AppVM and again type `backups` into the **Backup directory** field.
You must also specify the directory in which the backup resides (or a command to be executed in a VM). If you followed the instructions in the previous section, "Creating a Backup," then your backup is most likely in the location you chose as the destination in step 3. For example, if you had chosen the `~/backups` directory of a VM as your destination in step 3, you would now select the same VM and again type `backups` into the **Backup directory** field.
**Note:** After you have typed the directory location of the backup in the **Backup directory** field, click the ellipsis button `...` to the right of the field.
3. There are three options you may select when restoring from a backup:
1. **ignore missing**: If any of the AppVMs in your backup depended upon a NetVM, ProxyVM, or TemplateVM which is not present in (i.e., "missing from") the current system, checking this box will ignore the fact that they are missing and restore the AppVMs anyway.
1. **ignore missing**: If any of the VMs in your backup depended upon a NetVM, ProxyVM, or TemplateVM that is not present in (i.e., "missing from") the current system, checking this box will ignore the fact that they are missing and restore the VMs anyway.
2. **ignore username mismatch**: This option applies only to the restoration of dom0's home directory. If your backup was created on a Qubes system which had a different dom0 username than the dom0 username of the current system, then checking this box will ignore the mismatch between the two usernames and proceed to restore the home directory anyway.
3. **skip dom0**: If this box is checked, dom0's home directory will not be restored from your backup.
@ -71,7 +71,7 @@ Restoring from a Backup
**Note:** The passphrase which was supplied when the backup was created was used for **both** encryption/decryption and integrity verification. If the backup was not encrypted, the supplied passphrase is used only for integrity verification.
**Note:** An AppVM cannot be restored from a backup if an AppVM with the same name already exists on the current system. You must first remove or change the name of any AppVM with the same name in order to restore such an AppVM.
**Note:** A VM cannot be restored from a backup if a VM with the same name already exists on the current system. You must first remove or change the name of any VM with the same name in order to restore such a VM.
5. When you are ready, click **Next**. Qubes will proceed to restore from your backup. Once the progress bar has completed, you may click **Finish**.
@ -87,8 +87,16 @@ For emergency restore of backup created on Qubes R2 or newer take a look [here](
Migrating Between Two Physical Machines
---------------------------------------
In order to migrate your Qubes system from one physical machine to another, simply follow the backup procedure on the old machine, [install Qubes](/doc/downloads/) on the new machine, and follow the restoration procedure on the new machine. All of your settings and data will be preserved!
In order to migrate your Qubes system from one physical machine to another, simply follow the backup procedure on the old machine, [install Qubes](/downloads/) on the new machine, and follow the restoration procedure on the new machine. All of your settings and data will be preserved!
Choosing a Backup Passphrase
----------------------------
Here are some things to consider when selecting a passphrase for your backups:
* If you plan to store the backup for a long time or on third-party servers, you should make sure to use a very long, high-entropy passphrase. (Depending on the decryption passphrase you use for your system drive, this may necessitate selecting a stronger passphrase. If your system drive decryption passphrase is already sufficiently strong, it may not.)
* An adversary who has access to your backups may try to substitute one backup for another. For example, when you attempt to retrieve a recent backup, the adversary may instead give you a very old backup containing a compromised VM. If you're concerned about this type of attack, you may wish to use a different passphrase for each backup, e.g., by appending a number or date to the passphrase.
* If you're forced to enter your system drive decryption passphrase in plain view of others (where it can be shoulder-surfed), then you may want to use a different passphrase for your backups (even if your system drive decryption passphrase is already maximally strong). On the othe hand, if you're careful to avoid shoulder-surfing and/or have a passphrase that's difficult to detect via shoulder-surfing, then this may not be a problem for you.
Notes
-----

15
common-tasks/copy-from-dom0.md
View File

@ -39,12 +39,19 @@ Ctrl-Shift-V, then Ctrl-V).
### Copy/paste from Dom0 ###
For data other than logs, there are two options:
For data other than logs, there are several options:
1. Copy it as a file (see above)
2. Paste the data to `/var/run/qubes/qubes-clipboard.bin`, then write "dom0" to
`/var/run/qubes/qubes-clipboard.bin.source`. Then use Ctrl-Shift-V to paste the
data to the desired VM.
2. Since updated versions of 3.2 you can copy text to the dom0 clipboard
(Ctrl-C as normal), then click "Copy Dom0 clipboard" in the Qubes menu:
![copy-dom0-clipboard](/attachment/wiki/QubesScreenshots/r3.2-dom0-copyout.png)
which is equivelant to Ctrl-Shift-C from a normal AppVM.
Then you can use Ctrl-Shift-V and Ctrl-V to paste the copied text into an
AppVM as normal.
3. In older versions, write the data you wish to copy into
`/var/run/qubes/qubes-clipboard.bin`, then write "dom0" to
`/var/run/qubes/qubes-clipboard.bin.source`.
Then use Ctrl-Shift-V to paste the data to the desired VM.
Copying **to** Dom0

16
common-tasks/copy-paste.md
View File

@ -29,26 +29,14 @@ On Copy/Paste Security
The scheme is *secure* because it doesn't allow other VMs to steal the content of the clipboard. However, one should keep in mind that performing a copy and paste operation from *less trusted* to *more trusted* domain can always be potentially insecure, because the data that we insert might potentially try to exploit some hypothetical bug in the destination VM (e.g. the seemingly innocent link that we copy from untrusted domain, might turn out to be, in fact, a large buffer of junk that, when pasted into the destination VM's word processor could exploit a hypothetical bug in the undo buffer). This is a general problem and applies to any data transfer between *less trusted to more trusted* domains. It even applies to copying files between physically separate machines (air-gapped) systems. So, you should always copy clipboard and data only from *more trusted* to *less trusted* domains.
See also [this article](http://theinvisiblethings.blogspot.com/2011/03/partitioning-my-digital-life-into.html) for more information on this topic, and some ideas of how we might solve this problem in some future version of Qubes.
See also [this article](https://blog.invisiblethings.org/2011/03/13/partitioning-my-digital-life-into.html) for more information on this topic, and some ideas of how we might solve this problem in some future version of Qubes.
And [this message](https://groups.google.com/group/qubes-devel/msg/48b4b532cee06e01) from qubes-devel.
Copy/Paste between dom0 and other domains
-----------------------------------------
Copy/Paste between dom0 and other domains is intentionally prohibited by default. There should normally be no reason for any data exchange between dom0 and other VMs (except for the reporting of error logs). In order to easily copy/paste the contents of logs from dom0 to the inter-VM clipboard:
1. Right-click on the desired VM in the Qubes VM Manager.
2. Click "Logs."
3. Click on the desired log.
4. Click "Copy to Qubes clipboard."
You may now paste the log contents to any VM as you normally would (i.e., Ctrl-Shift-V, then Ctrl-V).
For data other than logs, there are two options:
1. [Copy it as a file.](/doc/copy-to-dom0/)
2. Paste the data to `/var/run/qubes/qubes-clipboard.bin`, then write "dom0" to `/var/run/qubes/qubes-clipboard.bin.source`. Then use Ctrl-Shift-V to paste the data to the desired VM.
See ["Copying from (and to) dom0"](/doc/copy-from-dom0/).
Clipboard automatic policy enforcement
--------------------------------------

6
common-tasks/copying-files.md
View File

@ -37,10 +37,10 @@ CLI
On inter-qube file copy security
----------------------------------
The scheme is *secure* because it doesn't allow other qubes to steal the files that are being copying, and also doesn't allow the source qube to overwrite arbitrary file on the destination qube. Also, Qubes file copy scheme doesn't use any sort of virtual block devices for file copy -- instead we use Xen shared memory, which eliminates lots of processing of untrusted data. For example, the receiving qube is *not* forced to parse untrusted partitions or file systems. In this respect our file copy mechanism provides even more security than file copy between two physically separated (air-gapped) machines!
The scheme is *secure* because it doesn't allow other qubes to steal the files that are being copied, and also doesn't allow the source qube to overwrite arbitrary files on the destination qube. Also, Qubes's file copy scheme doesn't use any sort of virtual block devices for file copy -- instead we use Xen shared memory, which eliminates lots of processing of untrusted data. For example, the receiving qube is *not* forced to parse untrusted partitions or file systems. In this respect our file copy mechanism provides even more security than file copy between two physically separated (air-gapped) machines!
However, one should keep in mind that performing a data transfer from *less trusted* to *more trusted* qubes can always be potentially insecure, because the data that we insert might potentially try to exploit some hypothetical bug in the destination qube (e.g. a seemingly innocent JPEG that we copy from an untrusted qube might contain a specially crafted exploit for a bug in JPEG parsing application in the destination qube). This is a general problem and applies to any data transfer between *less trusted to more trusted* qubes. It even applies to the scenario of copying files between air-gapped machines. So, you should always copy data only from *more trusted* to *less trusted* qubes.
See also [this article](http://theinvisiblethings.blogspot.com/2011/03/partitioning-my-digital-life-into.html) for more information on this topic, and some ideas of how we might solve this problem in some future version of Qubes.
See also [this article](https://blog.invisiblethings.org/2011/03/13/partitioning-my-digital-life-into.html) for more information on this topic, and some ideas of how we might solve this problem in some future version of Qubes.
You may also want to read how to [revoke "Yes to All" authorization](/doc/Qrexec/#revoking-yes-to-all-authorization)
You may also want to read how to [revoke "Yes to All" authorization](/doc/qrexec3/#revoking-yes-to-all-authorization)

9
common-tasks/dispvm.md
View File

@ -14,13 +14,14 @@ Disposable VMs (DispVMs)
Background
----------
See [this article](http://theinvisiblethings.blogspot.com/2010/06/disposable-vms.html) for a background on why would one want to use a Disposable VM and what it is.
A Disposable VM (DispVM) is a lightweight VM that can be created quickly and which will disappear when it is finished with. Usually a Disposable VM is created in order to host a single application, like a viewer or an editor. This means that you can safely work with files without risk of compromising any of your VMs. Changes made to a file opened in a disposable VM are passed back to the originating VM. See [this article](https://blog.invisiblethings.org/2010/06/01/disposable-vms.html) for more on why would one want to use a Disposable VM.
A DisposableVM is a lightweight VM that can be created quickly and which will disappear when it is finished with. Usually a Disposable VM is created in order to host a single application, like a viewer or an editor. This means that you can safely work with files without risk of compromising any of your VMs. Changes made to a file opened in a disposable VM are passed back to the originating VM.
By default a Disposable VM will inherit the NetVM and firewall settings of the ancestor VM, that is the VM it is launched from. Thus if an AppVM uses sys-net as NetVM (instead of, say, sys-whonix), any DispVM launched from this AppVM will also have sys-net as its NetVM. You can change this behaviour for individual VMs: in the Qubes 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.
By default a Disposable VM will inherit the netVM and firewall settings of the ancestor VM. You can change this behaviour: in the Qubes Manager go to the advanced tab of VM Settings where you can set the default netVM to be used for DisposableVMs created from that VM.
A Disposable VM launched from the Start Meny inherits the NetVM of a so-called internal TempVM, the *[DVM Template](https://www.qubes-os.org/doc/glossary/#dvm-template).* By default it is named `fedora-XX-dvm` (where `XX` is the Fedora version of the default TemplateVM) and hidden in Qubes VM Manager; it can be shown by selecting "Show/Hide internal VMs". Notice that changing the "NetVM for DispVM" setting for the DVM Template does *not* affect the NetVM of DispVMs launched from the Start Meny; only changing the DVM Template's own NetVM does.
Once a DispVM has been created it will appear in the Qubes Manager with the name "dispX", and NetVM and firewall rules can be set as for a normal VM.
Once a dispVM has been created it will appear in the Qubes Manager with the name "dispX", and NetVM and firewall rules can be set as for a normal VM.
Opening a file in a Disposable VM (via GUI)
-------------------------------------------

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

@ -30,7 +30,15 @@ Another option is to use Alt+Tab for switching windows. This shortcut is also ha
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:
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))

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

@ -25,13 +25,24 @@ After that, select the *Add more shortcuts* entry in VM's submenu to customize w
The above image shows that Windows HVMs are also supported (provided that Qubes Tools are installed).
What about applications in DispVMs?
-----------------------------------
[See here](/doc/dispvm-customization/#adding-arbitrary-programs-to-disposable-vm-application-menu).
Behind the scenes
-----------------
List of installed applications for each AppVM is stored in its template's `/var/lib/qubes/vm-templates/templatename/apps.templates` (or in case of StandaloneVM: `/var/lib/qubes/appvms/vmname/apps.templates`). Each menu entry is a file that follows the [.desktop file format](http://standards.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html) with some wildcards (*%VMNAME%*, *%VMDIR%*). Applications selected to appear in the menu are stored in `/var/lib/qubes/appvms/vmname/apps`.
The list of installed applications for each AppVM is stored in dom0's `/var/lib/qubes/vm-templates/templatename/apps.templates` (or in case of StandaloneVM: `/var/lib/qubes/appvms/vmname/apps.templates`). Each menu entry is a file that follows the [.desktop file format](https://standards.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html) with some wildcards (*%VMNAME%*, *%VMDIR%*). Applications selected to appear in the menu are stored in `/var/lib/qubes/appvms/vmname/apps`.
Actual command lines for the menu shortcuts involve `qvm-run` command which starts a process in another domain. Example: `qvm-run -q --tray -a w7s 'cmd.exe /c "C:\\ProgramData\\Microsoft\\Windows\\Start Menu\\Programs\\Accessories\\Calculator.lnk"'` or `qvm-run -q --tray -a untrusted 'firefox %u'`
Actual command lines for the menu shortcuts involve `qvm-run` command which starts a process in another domain. Examples: `qvm-run -q --tray -a w7s 'cmd.exe /c "C:\\ProgramData\\Microsoft\\Windows\\Start Menu\\Programs\\Accessories\\Calculator.lnk"'` or `qvm-run -q --tray -a untrusted 'firefox %u'`
Note that you can create a shortcut that points to a .desktop file in your AppVM with e.g. `qvm-run -q --tray -a personal -- 'qubes-desktop-run /home/user/application.desktop'`
`qvm-sync-appmenus` works by invoking *GetAppMenus* [Qubes service](/doc/qrexec/) in the target domain. This service enumerates installed applications and sends formatted info back to the dom0 script (`/usr/libexec/qubes-appmenus/qubes-receive-appmenus`) which creates .desktop files in the AppVM/TemplateVM directory.
For Linux VMs the service script is in `/etc/qubes-rpc/qubes.GetAppMenus`. In Windows it's a PowerShell script located in `c:\Program Files\Invisible Things Lab\Qubes OS Windows Tools\qubes-rpc-services\get-appmenus.ps1` by default.
What if my application has not been automatically included in the list of available apps?
-----------------------------------------------------------------------------------------
You can manually create new entries in the "available applications" list of shortcuts. See [Signal](/doc/signal/) for a worked example of creating a new menu item for a Chrome .desktop shortcut.

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

@ -60,26 +60,68 @@ Of course, command line tools are still available for accomplishing various upda
Yum will say that there is no update, but the package will nonetheless be downloaded to dom0.
1. Downgrade the packge:
2. Downgrade the package:
~~~
sudo yum downgrade package-version
~~~
### How to re-install a package
You can re-install in a similar fashion to downgrading.
1. Download the package:
~~~
sudo qubes-dom0-update package
~~~
Yum will say that there is no update, but the package will nonetheless be downloaded to dom0.
2. Re-install the package:
~~~
sudo yum reinstall package
~~~
Note that yum will only re-install if the installed and downloaded versions match. You can ensure they match by either updating the package to the latest version, or specifying the package version in the first step using the form `package-version`.
### How to uninstall a package
If you've installed a package such as anti-evil-maid, you can remove it with the following command:
~~~
sudo yum remove anti-evil-maid
~~~
### Testing repositories
There are three Qubes dom0 testing repositories:
* `qubes-dom0-current-testing` -- testing packages that will eventually land in the stable
(`current`) repository
* `qubes-dom0-security-testing` -- a subset of `qubes-dom0-current-testing` that contains packages
that qualify as security fixes
* `qubes-dom0-unstable` -- packages that are not intended to land in the stable (`qubes-dom0-current`)
repository; mostly experimental debugging packages
To temporarily enable any of these repos, use the `--enablerepo=<repo-name>`
option. Example commands:
~~~
sudo qubes-dom0-update --enablerepo=qubes-dom0-current-testing
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
`/etc/yum.repos.d/qubes-dom0.repo`.
### Kernel Upgrade ###
Install newer kernel. The following example installs kernel 3.19 and was tested on Qubes R3 RC1.
Install newer kernel for dom0 and VMs. The package `kernel` is for dom0 and the package `kernel-qubes-vm`
is needed for the VMs. (Note that the following example enables the unstable repo.)
~~~
sudo qubes-dom0-update kernel-3.19*
sudo qubes-dom0-update --enablerepo=qubes-dom0-unstable kernel kernel-qubes-vm
~~~
Rebuild grub config.
@ -90,6 +132,10 @@ sudo grub2-mkconfig -o /boot/grub2/grub.cfg
Reboot required.
If you wish to upgrade to a kernel that is not available from the repos, then
there is no easy way to do so, but [it may still be possible if you're willing
to do a lot of work yourself](https://groups.google.com/d/msg/qubes-users/m8sWoyV58_E/HYdReRIYBAAJ).
### Upgrading over Tor ###
Requires installed [Whonix](/doc/privacy/whonix/).

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

@ -11,20 +11,20 @@ redirect_from:
Installing and updating software in VMs
=======================================
How Template VM works in Qubes
How TemplateVMs work in Qubes
------------------------------
Most of the AppVMs (domains) are based on a *template VM*, which means that their root filesystem (i.e. all the programs and system files) is based on the root filesystem of the corresponding template VM. This dramatically saves disk space, because each new AppVM needs disk space only for storing the user's files (i.e. the home directory). Of course the AppVM has only read-access to the template's filesystem -- it cannot modify it in any way.
Most of the AppVMs (domains) are based on a *TemplateVM*, which means that their root filesystem (i.e. all the programs and system files) is based on the root filesystem of the corresponding template VM. This dramatically saves disk space, because each new AppVM needs disk space only for storing the user's files (i.e. the home directory). Of course the AppVM has only read-access to the template's filesystem -- it cannot modify it in any way.
In addition to saving on the disk space, and reducing domain creation time, another advantage of such scheme is the possibility for centralized software update. It's just enough to do the update in the template VM, and then all the AppVMs based on this template get updates automatically after they are restarted.
The default template is called **fedora-14-x64** in Qubes R1 and **fedora-20-x64** in Qubes R2.
The side effect of this mechanism is, of course, that if you install any software in your AppVM, more specifically in any directory other than `/home` or `/usr/local` then it will disappear after the AppVM reboot (as the root filesystem for this AppVM will again be "taken" from the Template VM). **This means one normally install software in the Template VM, not in AppVMs.**
The side effect of this mechanism is, of course, that if you install any software in your AppVM, more specifically in any directory other than `/home` or `/usr/local` then it will disappear after the AppVM reboot (as the root filesystem for this AppVM will again be "taken" from the TemplateVM). **This means one normally install software in the TemplateVM, not in AppVMs.**
Unlike VM private filesystems, the template VM root filesystem does not support discard, so deleting files does not free the space in dom0. See [these instructions](/doc/FedoraTemplateUpgrade/#compacting-templates-rootimg) to recover space in dom0.
Unlike VM private filesystems, the template VM root filesystem does not support discard, so deleting files does not free the space in dom0. See [these instructions](/doc/template/fedora/upgrade-23-to-24/#compacting-the-upgraded-template) to recover space in dom0.
Installing (or updating) software in the template VM
Installing (or updating) software in the TemplateVM
----------------------------------------------------
In order to permanently install new software, you should:
@ -33,16 +33,89 @@ In order to permanently install new software, you should:
- Install/update software as usual (e.g. using yum, or the dedicated GUI application). Then, shutdown the template VM,
- You will see now that all the AppVMs based on this template (by default all your VMs) will be marked as "outdated" in the manager. This is because their fielsystems have not been yet updated -- in order to do that, you must restart each VM. You don't need to restart all of them at the same time -- e.g. if you just need the newly installed software to be available in your 'personal' domain, then restart only this VM. You will restart others whenever this will be convenient to you.
- You will see now that all the AppVMs based on this template (by default all your VMs) will be marked as "outdated" in the manager. This is because their filesystems have not been yet updated -- in order to do that, you must restart each VM. You don't need to restart all of them at the same time -- e.g. if you just need the newly installed software to be available in your 'personal' domain, then restart only this VM. You will restart others whenever this will be convenient to you.
Notes on trusting your Template VM(s)
Testing repositories
--------------------
### Fedora ###
There are three Qubes VM testing repositories (where `*` denotes the Release):
* `qubes-vm-*-current-testing` -- testing packages that will eventually land in the stable
(`current`) repository
* `qubes-vm-*-security-testing` -- a subset of `qubes-vm-*-current-testing` that contains packages
that qualify as security fixes
* `qubes-vm-*-unstable` -- packages that are not intended to land in the stable (`qubes-vm-*-current`)
repository; mostly experimental debugging packages
To temporarily enable any of these repos, use the `--enablerepo=<repo-name>`
option. Example commands:
~~~
sudo dnf upgrade --enablerepo=qubes-vm-*-current-testing
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`.
### Debian ###
Debian also has three Qubes VM testing repositories (where `*` denotes the Release):
* `*-testing` -- testing packages that will eventually land in the stable
(`current`) repository
* `*-securitytesting` -- a subset of `*-testing` that contains packages
that qualify as security fixes
* `*-unstable` -- packages that are not intended to land in the stable
repository; mostly experimental debugging packages
To enable or disable any of these repos permanently, uncomment the corresponding `deb` line in
`/etc/apt/sources.list.d/qubes-r3.list`
Reverting changes to a TemplateVM
---------------------------------
Perhaps you've just updated your TemplateVM, and the update broke your template.
Or perhaps you've made a terrible mistake, like accidentally confirming the
installation of an unsigned package that could be malicious. Fortunately,
it's easy to revert changes to TemplateVMs using the
`qvm-revert-template-changes` command.
**Important:** This command will roll back any changes made *during the last
time the TemplateVM was run, but **not** before.* This means that if you have
already restarted the TemplateVM, using this command is unlikely to help, and
you'll likely want to reinstall it from the repository instead. On the other
hand, if the template is already broken or compromised, it won't hurt to try
reverting first. Just make sure to **back up** all of your data and changes
first!
For example, to revert changes to the `fedora-23` TemplateVM:
1. Shut down all VMs based on `fedora-23`.
2. Shut down `fedora-23`. If you've already just shut it down, do **not** start
it again (see above).
3. In a dom0 terminal, type:
qvm-revert-template-changes fedora-23
If you want to skip the confirmation check, you can add the `--force` option:
qvm-revert-template-changes --force fedora-23
For the technical details about how this command works and the steps it
performs, see [here](/doc/template-implementation/#rollback-template-changes).
Notes on trusting your TemplateVM(s)
-------------------------------------
As the template VM is used for creating filesystems for other AppVMs, where you actually do the work, it means that the template VM is as trusted as the most trusted AppVM based on this template. In other words, if your template VM gets compromised, e.g. because you installed an application, whose *installer's scripts* were malicious, then *all* your AppVMs (based on this template) will inherit this compromise.
As the TemplateVM is used for creating filesystems for other AppVMs, where you actually do the work, it means that the TemplateVM is as trusted as the most trusted AppVM based on this template. In other words, if your template VM gets compromised, e.g. because you installed an application, whose *installer's scripts* were malicious, then *all* your AppVMs (based on this template) will inherit this compromise.
There are several ways to deal with this problem:
- Only install packages from trusted sources -- e.g. from the pre-configured Fedora repositories. All those packages are signed by Fedora, and as we expect that at least the package's installation scripts are not malicious. This is enforced by default (at the [firewall VM level](/doc/qubes-firewall/)), by not allowing any networking connectivity in the default template VM, except for access to the Fedora repos.
- Only install packages from trusted sources -- e.g. from the pre-configured Fedora repositories. All those packages are signed by Fedora, and as we expect that at least the package's installation scripts are not malicious. This is enforced by default (at the [firewall VM level](/doc/firewall/)), by not allowing any networking connectivity in the default template VM, except for access to the Fedora repos.
- Use *standalone VMs* (see below) for installation of untrusted software packages.
@ -52,7 +125,7 @@ Some popular questions:
- So, why should we actually trust Fedora repos -- it also contains large amount of 3rd party software that might buggy, right?
As long as template's compromise is considered, it doesn't really matter whether /usr/bin/firefox is buggy and can be exploited, or not. What matters is whether its *installation* scripts (such as %post in the rpm.spec) are benign or not. Template VM should be used only for installation of packages, and nothing more, so it should never get a chance to actually run the /usr/bin/firefox and got infected from it, in case it was compromised. Also, some of your more trusted AppVMs, would have networking restrictions enforced by the [firewall VM](/doc/qubes-firewall/), and again they should not fear this proverbial /usr/bin/firefox being potentially buggy and easy to compromise.
As long as template's compromise is considered, it doesn't really matter whether /usr/bin/firefox is buggy and can be exploited, or not. What matters is whether its *installation* scripts (such as %post in the rpm.spec) are benign or not. Template VM should be used only for installation of packages, and nothing more, so it should never get a chance to actually run the /usr/bin/firefox and got infected from it, in case it was compromised. Also, some of your more trusted AppVMs, would have networking restrictions enforced by the [firewall VM](/doc/firewall/), and again they should not fear this proverbial /usr/bin/firefox being potentially buggy and easy to compromise.
- But why trusting Fedora?
@ -60,7 +133,7 @@ Because we chose to use Fedora as a vendor for the Qubes OS foundation (e.g. for
- So, are the template VMs as trusted as Dom0?
Not quite. Dom0 compromise is absolutely fatal, and it leads to Game Over<sup>TM</sup>. However, a compromise of a template affects only a subset of all your AppVMs (in case you use more than one template, or also some standalone VMs). Also, if your AppVMs are network disconnected, even though their filesystems might got 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.
Not quite. Dom0 compromise is absolutely fatal, and it leads to Game Over<sup>TM</sup>. However, a compromise of a template affects only a subset of all your AppVMs (in case you use more than one template, or also some standalone VMs). 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
--------------

54
common-tasks/tips-and-tricks.md Normal file
View File

@ -0,0 +1,54 @@
---
layout: doc
title: Tips and Tricks
permalink: /doc/tips-and-tricks/
---
Tips and Tricks
===============
This section provides user suggested tips that aim to increase Qubes OS usability, security or that allow users to discover new ways to use your computer that are unique to Qubes OS.
Opening links in your preferred AppVM
-------------------------------------
To increase both security and usability you can set an AppVM so that it automatically opens any link in an different AppVM of your choice. You can do this for example in the email AppVM, in this way you avoid to make mistakes like opening links in it. to learn more you can check [security guidelines](/doc/security-guidelines/) and [security goals](/security/goals/).
The command `qvm-open-in-vm` lets you open a document or a URL in another VM, it takes two parameters: vmname and filename.
For example, if you launch this command from your email AppVM:
`qvm-open-in-vm untrusted https://duckduckgo.com`
it will open duckduckgo.com in the `untrusted` AppVM (after you confirmed the request).
If you want this to happen automatically you can creatte a .desktop file that advertises itself as a handler for http/https links, and then setting this as your default browser.
Open a text editor and copy and paste this into it:
[Desktop Entry]
Encoding=UTF-8
Name=BrowserVM
Exec=qvm-open-in-vm APPVMNAME %u
Terminal=false
X-MultipleArgs=false
Type=Application
Categories=Network;WebBrowser;
MimeType=x-scheme-handler/unknown;x-scheme-handler/about;text/html;text/xml;application/xhtml+xml;application/xml;application/vnd.mozilla.xul+xml;application/rss+xml;application/rdf+xml;image/gif;image/jpeg;image/png;x-scheme-handler/http;x-scheme-handler/https;
Replace `APPVMNAME` with the AppVM name you want to open links in. Now save, in the AppVM that you want to modify, this file to `~/.local/share/applications/browser_vm.desktop`
Finally, set it as your default browser:
`xdg-settings set default-web-browser browser_vm.desktop`
Credit: [Micah Lee](https://micahflee.com/2016/06/qubes-tip-opening-links-in-your-preferred-appvm/)
Preventing data leaks
---------------------
First make sure to read [Understanding and Preventing Data Leaks](/doc/data-leaks/) section to understand the limits of this tip.
Suppose that you have a not so trusted enviroment, for example a Windows VM, an application that track and report it's usage or you simply want to protect your data.
Start Windows template VM (which has no user data), install/upgrade apps; then start Windows AppVM (with data) in offline mode. So, if you worry (hypothetically) that your Windows or app updater might want to send your data away, this Qubes OS trick will prevent this.
This applies also to any TemplateBasedVM relative to its parent TemplateVM, but the privacy risk is especially high in the case of Windows.
Credit: [Joanna Rutkovska](https://twitter.com/rootkovska/status/832571372085850112)

319
common-tasks/usb.md
View File

@ -7,6 +7,10 @@ redirect_from:
- /en/doc/stick-mounting/
- /doc/StickMounting/
- /wiki/StickMounting/
- /doc/external-device-mount-point/
- /en/doc/external-device-mount-point/
- /doc/ExternalDeviceMountPoint/
- /wiki/ExternalDeviceMountPoint/
- /doc/usbvm/
- /en/doc/usbvm/
- /doc/USBVM/
@ -17,6 +21,174 @@ redirect_from:
Using and Managing USB Devices
==============================
Creating and Using a USB qube
-----------------------------
The connection of an untrusted USB device to dom0 is a security risk since dom0,
like almost every OS, reads partition tables automatically and since the whole
USB stack is put to work to parse the data presented by the USB device in order
to determine if it is a USB mass storage device, to read its configuration, etc.
This happens even if the drive is then assigned and mounted in another qube.
To avoid this risk, it is possible to prepare and utilize a USB qube.
A USB qube acts as a secure handler for potentially malicious USB devices,
preventing them from coming into contact with dom0 (which could otherwise be
fatal to the security of the whole system). With a USB qube, every time you
connect an untrusted USB drive to a USB port managed by that USB controller, you
will have to attach it to the qube in which you wish to use it (if different
from the USB qube itself), either by using Qubes VM Manager or the command line
(see instructions above).
You can create a USB qube using the management stack by performing the following
steps as root in dom0:
1. Enable `sys-usb`:
qubesctl top.enable qvm.sys-usb
2. Apply the configuration:
qubesctl state.highstate
Alternatively, you can create a USB qube manually as follows:
1. Read the [Assigning Devices] page to learn how to list and identify your
USB controllers. Carefully check whether you have a USB controller that
would be appropriate to assign to a USB qube. Note that it should be free
of input devices, programmable devices, and any other devices that must be
directly available to dom0. If you find a free controller, note its name
and proceed to step 2.
2. Create a new qube. Give it an appropriate name and color label
(recommended: `sys-usb`, red). If you need to attach a networking device,
it might make sense to create a NetVM. If not, an AppVM might make more
sense. (The default `sys-usb` is a NetVM.)
3. In the qube's settings, go to the "Devices" tab. Find the USB controller
that you identified in step 1 in the "Available" list. Move it to the
"Selected" list.
**Caution:** By assigning a USB controller to a USB qube, it will no longer
be available to dom0. This can make your system unusable if, for example,
you have only one USB controller, and you are running Qubes off of a USB
drive.
4. Click "OK." Restart the qube.
5. Recommended: Check the box on the "Basic" tab which says "Start VM
automatically on boot." (This will help to mitigate attacks in which
someone forces your system to reboot, then plugs in a malicious USB
device.)
If the USB qube will not start, see [here][faq-usbvm].
How to hide all USB controllers from dom0
-----------------------------------------
If you create a USB qube manually, there will be a brief period of time during the
boot process during which dom0 will be exposed to your USB controllers (and any
attached devices). This is a potential security risk, since even brief exposure
to a malicious USB device could result in dom0 being compromised. There are two
approaches to this problem:
1. Physically disconnect all USB devices whenever you reboot the host.
2. Hide (i.e., blacklist) all USB controllers from dom0.
**Warning:** If you use a USB [AEM] device, do not use the second option. Using
a USB AEM device requires dom0 to have access to the USB controller to which
your USB AEM device is attached. If dom0 cannot read your USB AEM device, AEM
will hang.
The procedure to hide all USB controllers from dom0 is as follows:
1. Open the file `/etc/default/grub` in dom0.
2. Find the line that begins with `GRUB_CMDLINE_LINUX`.
3. Add `rd.qubes.hide_all_usb` to that line.
4. Save and close the file.
5. Run the command `grub2-mkconfig -o /boot/grub2/grub.cfg` in dom0.
6. Reboot.
(Note: Beginning with R3.2, `rd.qubes.hide_all_usb` is set automatically if you
opt to create a USB qube during installation. This also occurs automatically if
you choose to [create a USB qube] using the `qubesctl` method, which is the
first pair of steps in the linked section.)
**Warning** USB keyboard cannot be used to type the disk passphrase
if USB controllers were hidden from dom0. Before hiding USB controllers
make sure your laptop keyboard is not internally connected via USB
(by checking output of `lsusb` command) or that you have a PS/2 keyboard at hand
(if using a desktop PC). Failure to do so will render your system unusable.
Removing a USB qube
-------------------
**Warning:** This procedure will result in your USB controller(s) being attached
directly to dom0.
1. Shut down the USB qube.
2. In Qubes Manager, right-click on the USB qube and select "Remove VM."
3. Open the file `/etc/default/grub` in dom0.
4. Find the line(s) that begins with `GRUB_CMDLINE_LINUX`.
5. If `rd.qubes.hide_all_usb` appears anywhere in those lines, remove it.
6. Save and close the file.
7. Run the command `grub2-mkconfig -o /boot/grub2/grub.cfg` in dom0.
8. Reboot.
Security Warning about USB Input Devices
----------------------------------------
**Important security warning. Please read this section carefully!**
If you connect USB input devices (keyboard and mouse) to a VM, that VM will effectively have control over your system.
Because of this, the benefits of using a USB qube are much smaller than using a fully untrusted USB qube.
In addition to having control over your system, such VM can also sniff all the input you enter there (for example, passwords in the case of a USB keyboard).
There is no simple way to protect against sniffing, but you can make it harder to exploit control over input devices.
If you have only a USB mouse connected to a USB qube, but the keyboard is connected directly to dom0 (using a PS/2 connector, for example), you simply need to lock the screen when you are away from your computer.
You must do this every time you leave your computer unattended, even if there no risk of anyone else having direct physical access to your computer.
This is because you are guarding the system not only against anyone with local access, but also against possible actions from a potentially compromised USB qube.
If your keyboard is also connected to a USB qube, things are much harder.
Locking the screen (with a traditional password) does not solve the problem, because the USB qube can simply sniff this password and later easily unlock the screen.
One possibility is to set up the screen locker to require an additional step to unlock (i.e., two-factor authentication).
One way to achieve this is to use a [YubiKey], or some other hardware token, or even to manually enter a one-time password.
How to use a USB keyboard
-------------------------
**Caution:** Please carefully read the [Security Warning about USB Input Devices] before proceeding.
In order to use a USB keyboard, you must first attach it to a USB qube, then give that qube permission to pass keyboard input to dom0.
Edit the `qubes.InputKeyboard` policy file in dom0, which is located here:
/etc/qubes-rpc/policy/qubes.InputKeyboard
Add a line like this one to the top of the file:
sys-usb dom0 ask,user=root
(Change `sys-usb` to your desired USB qube.)
You can now use your USB keyboard.
How to use a USB mouse
----------------------
**Caution:** Please carefully read the [Security Warning about USB Input Devices] before proceeding.
In order to use a USB mouse, you must first attach it to a USB qube, then give that qube permission to pass mouse input to dom0.
Edit the `qubes.InputMouse` policy file in dom0, which is located here:
/etc/qubes-rpc/policy/qubes.InputMouse
Add a line like this to the op of the file:
sys-usb dom0 ask,user=root
(Change `sys-usb` to your desired USB qube.)
You can now use your USB mouse.
How to attach USB drives
------------------------
@ -28,7 +200,7 @@ Qubes OS supports the ability to attach a USB drive (or just one or more of its
partitions) to any qube easily, no matter which qube actually handles the USB
controller. (The USB controller may be assigned on the **Devices** tab of a
qube's settings page in Qubes VM Manager or by using the
[qvm-pci][assigning-devices] command. For guidance on finding the correct USB
[qvm-pci][Assigning Devices] command. For guidance on finding the correct USB
controller, see [here][usb-controller].)
USB drive mounting is integrated into the Qubes VM Manager GUI. Simply insert
@ -64,7 +236,7 @@ follows:
sudo udevadm trigger --action=change
3. Assuming your USB drive is attached to dom0 and is `sdb`, we attach the
device to a qube like so:
device to a qube with the name `personal` like so:
qvm-block -a personal dom0:sdb
@ -88,9 +260,13 @@ follows:
5. When you finish using your USB drive, click the eject button or right-click
and select **Unmount**.
6. In a dom0 console, detach the stick:
6. In a dom0 console, detach the stick
qvm-block -d <device> <vmname>
qvm-block -d <device>
or
qvm-block -d <vmname>
7. You may now remove the device.
@ -98,11 +274,7 @@ follows:
Otherwise, you will not be able to attach it anywhere later. See issue [1082]
for details.
There have been reports that when attaching a single partition, the Nautilus
file manager would not see it and automatically mount it (see issue [623]).
This problem seems to be resolved (see [this comment on issue 1072][1072-comm1]).
If, however, the device does not appear in Nautilus, you will need to mount it
If the device does not appear in Nautilus, you will need to mount it
manually. The device will show up as `/dev/xvdi` (or `/dev/xvdj` if there is
already one device attached -- if two, `/dev/xvdk`, and so on).
@ -143,112 +315,63 @@ steps:
`qvm-block -d` command.
Creating and Using a USB qube
-----------------------------
Attaching a single USB device to a qube (USB passthrough)
---------------------------------------------------------
The connection of an untrusted USB device to dom0 is a security risk since dom0,
like almost every OS, reads partition tables automatically and since the whole
USB stack is put to work to parse the data presented by the USB device in order
to determine if it is a USB mass storage device, to read its configuration, etc.
This happens even if the drive is then assigned and mounted in another qube.
Starting with Qubes 3.2, it is possible to attach a single USB device to any
Qube. While this is useful feature, it should be used with care, because there
are [many security implications][usb-challenges] from using USB devices and USB
passthrough will **expose your target qube** for most of them. If possible, use
method specific for particular device type (for example block devices described
above), instead of this generic one.
To avoid this risk, it is possible to prepare and utilize a USB qube. However,
Xen does not yet provide working PVUSB functionality, so only USB mass storage
devices can be passed to individual qubes.
To use this feature, you need to install `qubes-usb-proxy` package in the
templates used for USB qube and qubes you want to connect USB devices to. Note
you cannot pass through devices from dom0 (in other words: USB VM is required).
For this reason, you may wish to avoid using a USB qube if you do not have a USB
controller free of input devices and programmable devices, although Qubes R3.1
introduced support for USB mice and keyboards (see below).
Listing available USB devices:
A USB qube acts as a secure handler for potentially malicious USB devices,
preventing them from coming into contact with dom0 (which could otherwise be
fatal to the security of the whole system). With a USB qube, every time you
connect an untrusted USB drive to a USB port managed by that USB controller, you
will have to attach it to the qube in which you wish to use it (if different
from the USB qube itself), either by using Qubes VM Manager or the command line
(see instructions above). Again, this works only for USB mass storage devices.
Other devices cannot currently be virtualized.
[user@dom0 ~]$ qvm-usb
sys-usb:2-4 04ca:300d 04ca_300d
sys-usb:2-5 058f:3822 058f_USB_2.0_Camera
sys-usb:2-1 03f0:0641 PixArt_HP_X1200_USB_Optical_Mouse
You can create a USB qube using the management stack by performing the following
steps as root in dom0:
Attaching selected USB device:
1. Enable `sys-usb`:
[user@dom0 ~]$ qvm-usb -a conferences sys-usb:2-5
[user@dom0 ~]$ qvm-usb
conferences:2-1 058f:3822 058f_USB_2.0_Camera
sys-usb:2-4 04ca:300d 04ca_300d
sys-usb:2-5 058f:3822 058f_USB_2.0_Camera (attached to conferences)
sys-usb:2-1 03f0:0641 PixArt_HP_X1200_USB_Optical_Mouse
qubesctl top.enable qvm.sys-usb
Now, you can use your USB device (camera in this case) in `conferences` qube.
2. Apply the configuration:
When you finish, detach the device:
qubesctl state.highstate
[user@dom0 ~]$ qvm-usb -d sys-usb:2-5
[user@dom0 ~]$ qvm-usb
sys-usb:2-4 04ca:300d 04ca_300d
sys-usb:2-5 058f:3822 058f_USB_2.0_Camera
sys-usb:2-1 03f0:0641 PixArt_HP_X1200_USB_Optical_Mouse
Alternatively, you can create a USB qube manually as follows:
1. In a dom0 terminal, type `lsusb` to check if you have a USB controller free
of input devices or programmable devices. If you find such free controller,
note its name and proceed to step 2.
2. Create a new qube. Give it an appropriate name and color label
(recommended: `sys-usb`, red).
3. In the qube's settings, go to the "Devices" tab. Find your USB controller
in the "Available" list. Move it to the "Selected" list.
4. Click "OK." Restart the qube.
5. Recommended: Check the box on the "Basic" tab which says "Start VM
automatically on boot." (This will help to mitigate attacks in which
someone forces your system to reboot, then plugs in a malicious USB
device.)
If the USB qube will not start, see [here][faq-usbvm].
Supported USB device types
--------------------------
As of Qubes R3.1, it is possible to attach:
* USB mice
* USB keyboards (see below)
* USB block devices (such as USB mass storage devices)
* When attaching one of these, you should get a notification about the
new device, then you should be able to attach it to a qube in Qubes VM
Manager.
Other devices, such as USB webcams, will also work, but they will be
accessible only from the USB qube itself, as explained above.
How to use a USB keyboard
-------------------------
In order to use a USB keyboard, you must first attach it to a USB qube, then
give that qube permission to pass keyboard input to dom0. Note that allowing
keyboard access from a USB qube gives it great power. In short:
* It will see whatever you type on that keyboard (including passwords).
* It will be able to inject keystrokes, which basically means that it will be
able to enter any command. For example, if some malware catches your
screenlocker password, it will be able to unlock the screen when you are not
present. (For more details, see [here][input-proxy].)
If you are sure you wish to proceed, then you must edit the
`qubes.InputKeyboard` policy file in dom0, which is located here:
/etc/qubes-rpc/policy/qubes.InputKeyboard
Add a line like this one to the top of the file:
sys-usb dom0 ask
(Change `sys-usb` to your desired USB qube.)
You can now use your USB keyboard.
This feature is not yet available in Qubes Manager however, if you would like to contribute to Qubes OS project by implementing it and are a student please consider applying for the [Google Summer of Code][gsoc-page] scholarship and choosing QubesOS Project as a mentor organization. You can find list of our our Project Ideas [here][project-page].
[mass-storage]: https://en.wikipedia.org/wiki/USB_mass_storage_device_class
[devices]: /doc/assigning-devices/
[Assigning Devices]: /doc/assigning-devices/
[usb-controller]: /doc/assigning-devices/#finding-the-right-usb-controller
[623]: https://github.com/QubesOS/qubes-issues/issues/623
[1072-comm1]: https://github.com/QubesOS/qubes-issues/issues/1072#issuecomment-124270051
[1072-comm2]: https://github.com/QubesOS/qubes-issues/issues/1072#issuecomment-124119309
[1082]: https://github.com/QubesOS/qubes-issues/issues/1082
[hide-usb]: #how-to-hide-all-usb-controllers-from-dom0
[faq-usbvm]: /doc/user-faq/#i-created-a-usbvm-and-assigned-usb-controllers-to-it-now-the-usbvm-wont-boot
[AEM]: /doc/anti-evil-maid/
[1618]: https://github.com/QubesOS/qubes-issues/issues/1618
[input-proxy]: https://github.com/qubesos/qubes-app-linux-input-proxy
[create a USB qube]: #creating-and-using-a-usb-qube
[usb-challenges]: https://blog.invisiblethings.org/2011/05/31/usb-security-challenges.html
[project-page]: /gsoc/
[gsoc-page]: https://summerofcode.withgoogle.com/organizations/6239659689508864/
[YubiKey]: /doc/YubiKey/
[Security Warning about USB Input Devices]: #security-warning-about-usb-input-devices

6
configuration/assigning-devices.md
View File

@ -173,7 +173,7 @@ or
[usb]: /doc/usb/
[ml1]: https://groups.google.com/group/qubes-devel/browse_thread/thread/631c4a3a9d1186e3
[ml2]: https://groups.google.com/forum/\#!topic/qubes-users/Fs94QAc3vQI
[PCI passthrough]: http://wiki.xen.org/wiki/Xen_PCI_Passthrough
[Software Attacks on Intel VT-d]: http://www.invisiblethingslab.com/resources/2011/Software%20Attacks%20on%20Intel%20VT-d.pdf
[ml2]: https://groups.google.com/forum/#!topic/qubes-users/Fs94QAc3vQI
[PCI passthrough]: https://wiki.xen.org/wiki/Xen_PCI_Passthrough
[Software Attacks on Intel VT-d]: https://invisiblethingslab.com/resources/2011/Software%20Attacks%20on%20Intel%20VT-d.pdf

55
configuration/config-files.md
View File

@ -12,9 +12,13 @@ redirect_from:
Qubes specific VM config files
==============================
Those files are placed in /rw, which survives VM restart, so can be used to customize single VM (not all VMs based on the same template).
Those files are placed in /rw, which survives VM restart, so can be
used to customize single VM (not all VMs based on the same template).
The scripts here all run as root.
- `/rw/config/rc.local` - script run at VM startup. Good place to change some service settings, replace config files with its copy stored in /rw/config etc. Example usage:
- `/rw/config/rc.local` - script run at VM startup. Good place to
change some service settings, replace config files with its copy stored
in /rw/config etc. Example usage:
~~~
# Store bluetooth keys in /rw to keep them across VM restarts
@ -22,16 +26,29 @@ Those files are placed in /rw, which survives VM restart, so can be used to cust
ln -s /rw/config/var-lib-bluetooth /var/lib/bluetooth
~~~
- `/rw/config/qubes-ip-change-hook` - script run in NetVM after external IP change (or connection to the network)
- `/rw/config/qubes-firewall-user-script` - script run in ProxyVM after firewall update. Good place to write own custom firewall rules
- `/rw/config/suspend-module-blacklist` - list of modules (one per line) to be unloaded before system going to sleep. The file is used only in VM with some PCI devices attached. Supposed to be used for problematic device drivers.
- `/rw/config/qubes-ip-change-hook` - script run in NetVM after
external IP change (or connection to the network)
- `/rw/config/qubes-firewall-user-script` - script run in ProxyVM
after each firewall update. Good place to write own custom firewall
rules
- `/rw/config/suspend-module-blacklist` - list of modules (one per
line) to be unloaded before system going to sleep. The file is used
only in VM with some PCI devices attached. Supposed to be used for
problematic device drivers.
Note that scripts need to be executable (chmod +x) to be used.
Also take a look at [bind-dirs][/doc/bind-dirs] for instruction how to easily
modify arbitrary system file in AppVM and have those changes persistent.
GUI and audio configuration in dom0
===================================
GUI configuration file `/etc/qubes/guid.conf` in one of few not managed by qubes-prefs nor Qubes Manager tool. Sample config (included in default installation):
GUI configuration file `/etc/qubes/guid.conf` in one of few not managed
by qubes-prefs nor Qubes Manager tool. Sample config (included in
default installation):
~~~
# Sample configuration file for Qubes GUI daemon
@ -61,9 +78,25 @@ VM: {
Currently supported settings:
- `allow_fullscreen` - allow VM to request its windows to go fullscreen (without any colorful frame). Regardless of this setting, you can also set window fullscreen using trusted window manager settings (right click on title bar).
- `allow_utf8_titles` - allow to use UTF-8 in window titles, otherwise non-ASCII characters are replaced by underscore.
- `secure_copy_sequence` and `secure_paste_sequence` - key sequences used to trigger secure copy and paste
- `windows_count_limit` - limit on concurrent windows count.
- `audio_low_latency` - force low-latency audio mode (about 40ms compared to 200-500ms by default). Note that this will cause much higher CPU usage in dom0.
- `allow_fullscreen` - allow VM to request its windows to go
fullscreen (without any colorful frame).
**Note:** Regardless of this setting, 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".
- `allow_utf8_titles` - allow to use UTF-8 in window titles,
otherwise non-ASCII characters are replaced by underscore.
- `secure_copy_sequence` and `secure_paste_sequence` - key sequences
used to trigger secure copy and paste
- `windows_count_limit` - limit on concurrent windows count.
- `audio_low_latency` - force low-latency audio mode (about 40ms
compared to 200-500ms by default). Note that this will cause much
higher CPU usage in dom0.

2
configuration/disk-trim.md
View File

@ -8,7 +8,7 @@ redirect_from:
- /wiki/DiskTRIM/
---
VMs have already TRIM enabled by default, but dom0 doesn't. There are some security implications (read for example [this article](http://asalor.blogspot.com/2011/08/trim-dm-crypt-problems.html)), but IMO not very serious.
VMs have already TRIM enabled by default, but dom0 doesn't. There are some security implications (read for example [this article](https://asalor.blogspot.com/2011/08/trim-dm-crypt-problems.html)), but IMO not very serious.
To enable TRIM in dom0 you need:

17
configuration/external-device-mount-point.md
View File

@ -1,17 +0,0 @@
---
layout: doc
title: External Device Mount Point
permalink: /doc/external-device-mount-point/
redirect_from:
- /en/doc/external-device-mount-point/
- /doc/ExternalDeviceMountPoint/
- /wiki/ExternalDeviceMountPoint/
---
All external storage devices connected to an AppVM using the Fedora template can be found under
~~~
/run/media/user/
~~~
...of that AppVM's filesystem.

18
configuration/fetchmail.md
View File

@ -23,7 +23,7 @@ Configuration
Assuming you have more than one account (safe assumption these days), you need to spawn multiple fetchmail instances, one for each IMAP/POP3 server (though one instance can watch over several accounts on one server). The easiest way is to create template systemd unit and start it several times. Fedora does not supply any, so we have to write one anyway.
**NOTE:** this assumes you use [Postfix](/doc/postfix/) as your local MTA.
**NOTE:** this assumes you use [Postfix](/doc/postfix/) or Exim4 as your local MTA.
In TemplateVM create `/etc/systemd/system/fetchmail@.service`:
@ -39,6 +39,20 @@ ExecStart=/bin/fetchmail -f /usr/local/etc/fetchmail/%I.rc -d 60 -i /usr/local/e
RestartSec=1
~~~
Alternatively, in Debian with Exim4:
~~~
[Unit]
Description=Mail Retrieval Agent
After=network.target
Requires=exim4.service
[Service]
User=user
ExecStart=/usr/bin/fetchmail -f /usr/local/etc/fetchmail/%I.rc -d 60 -i /usr/local/etc/fetchmail/.%I.fetchids --pidfile /usr/local/etc/fetchmail/.%I.pid
RestartSec=1
~~~
Then shutdown TemplateVM, start AppVM and create directory `/usr/local/etc/fetchmail`. In it, create one `.rc` file for each instance of fetchmail, ie. `personal1.rc` and `personal2.rc`. Sample configuration file:
~~~
@ -72,7 +86,7 @@ Next, add this to `/rw/config/rc.local`:
for rc in /usr/local/etc/fetchmail/*.rc; do
instance=${rc%.*}
instance=${instance##*/}
echo systemctl --no-block start fetchmail@${instance}
systemctl --no-block start fetchmail@${instance}
done
~~~

8
configuration/http-filtering-proxy.md
View File

@ -4,7 +4,7 @@ title: HTTP Filtering Proxy
permalink: /doc/config/http-filtering-proxy/
---
How to run an HTTP filtering proxy in a FirwallVM
How to run an HTTP filtering proxy in a FirewallVM
=================================================
Introduction
@ -162,7 +162,7 @@ Setup
to restart all proxy processes.
7. To make sure that the proxy is started automatically when the AppVM
starts change `/rw/config/qubes_firewall_user_script` to include the
starts change `/rw/config/qubes-firewall-user-script` to include the
following line:
/rw/config/tinyproxy/proxyctl.py update
@ -174,8 +174,8 @@ Setup
Make sure that the script is owned by root and executable:
sudo chown root:root /rw/config/qubes_firewall_user_script
sudo chmod 755 /rw/config/qubes_firewall_user_script
sudo chown root:root /rw/config/qubes-firewall-user-script
sudo chmod 755 /rw/config/qubes-firewall-user-script
8. In Qubes VM manager adjust Firewall rules for each AppVM with a
proxy. In a typical case when only HTTP proxy should be used for

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

@ -7,7 +7,7 @@ redirect_from:
---
VM kernel managed by dom0
-------------------------
=========================
By default VMs kernels are provided by dom0. This means that:
@ -47,7 +47,7 @@ updatevm : sys-firewall
~~~
Installing different kernel using Qubes kernel package
==================================
----------------------------------
VM kernels are packages by Qubes team in `kernel-qubes-vm` packages. Generally system will keep the 3 newest available versions. You can list them with the `rpm` command:
@ -135,7 +135,7 @@ In the above example, it tries to remove 3.18.10-2.pvops.qubes kernel (to keep o
The newly installed package is set as default VM kernel.
Installing different VM kernel based on dom0 kernel
===================================================
---------------------------------------------------
It is possible to package kernel installed in dom0 as VM kernel. This makes it
possible to use VM kernel, which is not packaged by Qubes team. This includes:
@ -203,7 +203,7 @@ mke2fs 1.42.12 (29-Aug-2014)
~~~
Using kernel installed in the VM
================================
--------------------------------
**This option is available only in Qubes R3.1 or newer**
@ -239,8 +239,10 @@ sudo yum install qubes-kernel-vm-support grub2-tools
Then install whatever kernel you want. If you are using distribution kernel
package (`kernel` package), initramfs and kernel module should be handled
automatically. If you are using manually build kernel, you need to handle this
on your own. Take a look at `dkms` and `dracut` documentation.
automatically, but you need to ensure you have `kernel-devel` package for the
same kernel version installed. If you are using manually build kernel, you need
to handle this on your own. Take a look at `dkms` and `dracut` documentation.
Especially `dkms autoinstall` command may be useful.
When kernel is installed, you need to create GRUB configuration.
You may want to adjust some settings in `/etc/default/grub`, for example lower
@ -278,8 +280,28 @@ Ignore warnings about `version '...' has bad syntax`.
Then install whatever kernel you want. If you are using distribution kernel
package (`linux-image-amd64` package), initramfs and kernel module should be
handled automatically. If you are using manually build kernel, you need to
handle this on your own. Take a look at `dkms` and `initramfs-tools` documentation.
handled automatically. If not, or you are building kernel manually, do this on
using `dkms` and `initramfs-tools`:
sudo dkms autoinstall -k <kernel-version> # replace this <kernel-version> with actual kernel version
sudo update-initramfs -u
The output should look like this:
$ sudo dkms autoinstall -k 3.16.0-4-amd64
u2mfn:
Running module version sanity check.
- Original module
- No original module exists within this kernel
- Installation
- Installing to /lib/modules/3.16.0-4-amd64/updates/dkms/
depmod....
DKMS: install completed.
$ sudo update-initramfs -u
update-initramfs: Generating /boot/initrd.img-3.16.0-4-amd64
When kernel is installed, you need to create GRUB configuration.
You may want to adjust some settings in `/etc/default/grub`, for example lower
@ -300,6 +322,8 @@ grub2-probe: error: cannot find a GRUB drive for /dev/mapper/dmroot. Check your
Then shutdown the VM. From now you can set `pvgrub2` as VM kernel and it will
start kernel configured within VM.
When starting the VM you can safely ignore any warnings about a missing module 'dummy-hcd'
### Troubleshooting
In case of problems, you can access VM console (using `sudo xl console VMNAME` in dom0) to access

28
configuration/multiboot.md
View File

@ -40,18 +40,6 @@ If you are really paranoid clone your disc.
Make sure you have install discs to hand for the existing operating system.
Qubes 3.0 does not support UEFI boot. If you are already using it the first step
is to change boot mode.
Most PCs using UEFI firmware and bootloader can be configured to disable
UEFI entirely and instead revert to legacy MBR boot mode.
Two separate steps are often required to achieve this:
* Enabling legacy boot mode
* Disabling Secure Boot
Qubes by default does not include other systems in the generated grub menu,
because handling of other systems has been disabled. This means
that you will have to manually add grub entries for any other OS.
@ -97,9 +85,10 @@ menuentry "Windows" {
insmod ntfs
ntldr (hd1,X)/bootmgr
}
(Change X to reflect the relevant system partition.)
~~~
(Change `X` to reflect the relevant system partition.)
Then update the grub config:
~~~
@ -108,6 +97,19 @@ sudo grub2-mkconfig -o /boot/grub2/grub.cfg
There is no need to reinstall grub itself.
If the above stanza does not work, you may try this one (at your own risk!)
instead:
~~~
menuentry "Windows" {
insmod part_msdos
insmod ntfs
set root='(hd0,msdosX)'
chainloader +1
}
~~~
(Change `X` to reflect the relevant system partition.)
Linux

2
configuration/mutt.md
View File

@ -56,7 +56,7 @@ set pgp_clearsign_command="qubes-gpg-client-wrapper --batch --armor --textmode -
# I found no option to add Charset armor header when it is UTF-8, since this is
# default (as specified in RFC4880). This is needed to workaround bug in
# Enigmail, which ignores RFC and without this header Thunderbird interprets
# plaintext as us-ascii. See http://sourceforge.net/p/enigmail/bugs/38/.
# plaintext as us-ascii. See https://sourceforge.net/p/enigmail/bugs/38/.
### also note you must specify absolute path of pgpewrap when using debian
### e.g. /usr/lib/mutt/pgpewrap

10
configuration/postfix.md
View File

@ -16,9 +16,11 @@ Postfix is full featured MTA (Message Transfer Agent). Here we will configure it
Installation
------------
`yum install postfix procmail make`
`yum install postfix procmail make cyrus-sasl cyrus-sasl-plain`
Procmail is not strictly necessary, but is useful to sort your incoming mail, for example to put each mailing list in its own directory. Make is also not necessary, but is used to keep Postfix lookup tables. You should also check `alternatives` command, to see if it is the default `mta`. It probably is not. You may need to `yum remove ssmtp` or something.
Cyrus-sasl is installed to authenticate to remote servers. Procmail is not strictly necessary, but is useful to sort your incoming mail, for example to put each mailing list in its own directory. Make is also not necessary, but is used to keep Postfix lookup tables.
You should also check `alternatives` command, to see if it is the default `mta`. It probably is not. You may need to `yum remove ssmtp` or something
Configuration
-------------
@ -33,7 +35,7 @@ and run `newaliases`.
This is the only thing to do in TemplateVM, as MTA configuration is AppVM specific, so we will keep it in `/usr/local` (ie. `/rw/usrlocal`) in each AppVM.
Now shutdown TemplateVM, start AppVM. Create directory `/usr/local/etc/postfix` and copy `/etc/postfix/master.cf` there.
Now shutdown TemplateVM, start AppVM. Create directory `/usr/local/etc/postfix` and copy `/etc/postfix/master.cf` and `/etc/postfix/postfix-files` there.
### Makefile
@ -150,4 +152,4 @@ mount --bind /usr/local/etc/postfix /etc/postfix
systemctl --no-block start postfix
~~~
Reboot your AppVM and you are done.
Make sure `/rw/config/rc.local` is executable (i.e., `chmod a+x /rw/config/rc.local`). Reboot your AppVM and you are done.

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

@ -100,7 +100,9 @@ truncate -s 30GB root.img
ls -lh root.img (<--verify new size of disk image)
~~~
The partition table and file-system must be adjusted after this change:
The partition table and file-system must be adjusted after this change.
Use tools appropriate to the OS in your HVM. Brief instructions for Windows 7,
FreeBSD, and Linux are provided below.
#### Windows 7
@ -119,3 +121,8 @@ sysctl kern.geom.debugflags=0x10
gpart resize -i index ada0
zpool online -e poolname ada0
~~~
#### Linux
You will see that there is unallocated free space at the end of your primary disk.
You can use standard linux tools like fdisk and mkfs to make this space available.

4
configuration/rxvt.md
View File

@ -122,6 +122,10 @@ URxvt.print-pipe: cat > $(TMPDIR=$HOME mktemp urxvt.XXXXXX)
! is no need for w32-style intuition and virtually no need to "paste over".
URxvt.perl-ext-common: default,selection-to-clipboard
! Prevent rxvt from entering Keyboard symbols entry mode whenever you press
! ctrl+shift, e.g. to copy or paste something to/from Qubes' clipboard.
URxvt.iso14755_52: false
URxvt.insecure: False
! some termcap-aware software sometimes throw '$TERM too long'

425
configuration/salt.md
View File

@ -3,113 +3,248 @@ layout: doc
title: Management stack
permalink: /doc/salt/
---
# Management infrastructure
Since Qubes R3.1 release we have included `salt` (also called SaltStack)
management engine in dom0 as default with some states already configured. salt
allows administrators to easily configure their systems. In this guide we will
show how it is set up and how you can modify it for your own purpose.
# Management Infrastructure
Since the Qubes R3.1 release we have included the Salt (also called SaltStack)
management engine in dom0 as default (with some states already configured).
Salt allows administrators to easily configure their systems.
In this guide we will show how it is set up and how you can modify it for your
own purpose.
In the current form the **API is provisional** and subject to change between
*minor* releases.
## Understanding `salt`
## Understanding Salt
This document is not meant to be comprehensive salt documentation, however
This document is not meant to be comprehensive Salt documentation; however,
before writing anything it is required you have at least *some* understanding of
basic salt-related vocabulary. For more exhaustive documentation, visit
[official site][salt-doc], though we must warn you that it is not easy to read
if you just start working with salt and know nothing.
basic Salt-related vocabulary.
For more exhaustive documentation, visit [official site][salt-doc], though we
must warn you that it is not easy to read if you just start working with Salt
and know nothing.
Salt has client-server architecture, where server (called *master*) manages its
clients (called *minions*). In typical situation it is intended that
administrator interacts only with master and keeps the configuration there. In
Qubes OS we don't have master though, since we have only one minion, which
resides in `dom0` and manages domains from there. This is also supported by
salt.
### The Salt Architecture
Salt is a management engine, that enforces particular state of the system, where
minion runs. A *state* is an end effect *declaratively* expressed by the
administrator. This is the most important concept in the whole package. All
configuration (ie. the states) are written in YAML.
Salt is a client-server model, where the server (called *master*) manages
its clients (called *minions*).
In typical situations, it is intended that the administrator interacts only
with the master and keeps the configurations there.
In Qubes, we don't have a master.
Instead we have one minion which resides in `dom0` and manages domains from
there.
This setup is also supported by Salt.
A *pillar* is a data backend declared by administrator. When states became
repetitive, instead of pure YAML they can be written with help of some template
engine (preferably jinja2), which can use data structures specified in pillars.
Salt is a management engine (similar to Ansible, Puppet, and Chef), that
enforces a particular state of a minion system.
A *state* is an end effect *declaratively* expressed by the administrator.
This is the most important concept in the entire engine.
All configurations (i.e., the states) are written in YAML.
A *formula* is a ready to use, packaged solution that combines state and pillar,
possibly with some file templates and other auxiliary files. There are many of
those made by helpful people all over the Internet.
A *pillar* is a data back-end declared by the administrator.
When states become repetitive, instead of pure YAML they can be written using a
template engine (preferably Jinja2); which can use data structures specified in
pillars.
A *formula* is a ready to use, packaged solution that combines a state and a
pillar (possibly with some file templates and other auxiliary files).
There are many formulas made by helpful people all over the Internet.
A *grain* is some data that is also available in templates, but its value is not
directly specified by administrator. For example the distribution (like
`"Debian"` or `"Gentoo"`) is a value of the grain `"os"`. It also contains other
info about kernel, hardware etc.
directly specified by administrator.
For example, the distribution (e.g., `"Debian"` or `"Gentoo"`) is a value of
the grain `"os"`. It also contains other information about the kernel,
hardware, etc.
A *module* is a Python extension to salt that is responsible for actually
enforcing the state in a particular area. It exposes some *imperative* functions
for administrator. For example there is `system` module that has `system.halt`
function that, when issued, will immediately halt the computer. There is another
function called `state.highstate` which will synchronize the state of the system
with the administrator's will.
A *module* is a Python extension to Salt that is responsible for actually
enforcing the state in a particular area.
It exposes some *imperative* functions for the administrator.
For example, there is a `system` module that has a `system.halt` function that,
when issued, will immediately halt a domain.
There is another function called `state.highstate` which will synchronize the
state of the system with the administrator's configuration/desires.
### Configuration
## Salt configuration, Qubes OS layout
#### States
All salt configuration in `/srv/` directory, as usual. The main directory is
`/srv/salt/` where all state files reside. States are contained in `*.sls`
files. However the states that are part of standard Qubes distribution are
mostly templates and the configuration is done in pillars from formulas.
The smallest unit of configuration is a state.
A state is written in YAML and looks like this:
The formulas are in `/srv/formulas`, including stock formula for domains in
stateid:
cmd.run: #this is the execution module. in this case it will execute a command on the shell
- name: echo 'hello world' #this is a parameter of the state.
The stateid has to be unique throughout all states running for a minion and can
be used to order the execution of the references state.
`cmd.run` is an execution module.
It executes a command on behalf of the administrator.
`name: echo 'hello world'` is a parameter for the execution module `cmd.run`.
The module used defines which parameters can be passed to it.
There is a list of [officially available states][salt-doc-states].
There are many very useful states:
* For [managing files][salt-doc-states-file]: Use this to create files or
directories and change them (append lines, replace text, set their content etc.)
* For [installing and uninstalling][salt-doc-states-pkg] packages.
* For [executing shell commands][salt-doc-states-cmd].
With these three states you can define most of the configuration of a VM.
You can also [order the execution][salt-doc-states-order] of your states:
D:
cmd.run:
- name: echo 1
- order: last
C:
cmd.run:
- name: echo 1
B:
cmd.run:
- name: echo 1
- require:
- cmd: A
- require_in:
- cmd:C
A:
cmd.run:
- name: echo 1
- order: 1
The order of execution will be `A, B, C, D`.
The official documentation has more details on the
[require][salt-doc-states-req] and [order][salt-doc-states-ord] arguments.
#### State Files
When configuring a system you will write one or more state files (`*.sls`) and
put (or symlink) them into the main Salt directory `/srv/salt/`.
Each state file contains multiple states and should describe some unit of
configuration (e.g., a state file `mail.sls` could setup a VM for e-mail).
#### Top Files
After you have several state files, you need something to assign them to a VM.
This is done by `*.top` files ([official documentation][salt-doc-top]).
Their structure looks like this:
environment:
target_matching_clause:
- statefile1
- folder2.statefile2
In most cases, the environment will be called `base`.
The `target_matching_clause` will be used to select your minions (VMs).
It can be either the name of a VM or a regular expression.
If you are using a regular expressions, you need to give Salt a hint you are
doing so:
environment:
^app-(work|(?!mail).*)$:
- match: pcre
- statefile
For each target you can write a list of state files.
Each line is a path to a state file (without the `.sls` extension) relative to
the main directory.
Each `/` is exchanged with a `.`, so you can't reference files or directories
with a `.` in their name.
### Enabling Top Files and Applying the States
Now, because we use custom extensions to manage top files (instead of just
enabling them all), to enable a particular top file you should issue command:
$ qubesctl top.enable my-new-vm
To list all enabled top files:
$ qubesctl top.enabled
And to disable one:
$ qubesctl top.disable my-new-vm
To apply the states to dom0 and all VMs:
$ qubesctl --all state.highstate
(More information on the `qubesctl` command further down.)
### Template Files
You will sometimes find yourself writing repetitive states.
To solve this, there is the ability to template files or states.
This is most commonly done with [Jinja][jinja].
Jinja is similar to Python and in many cases behaves in a similar fashion, but
there are sometimes differences when, for example, you set some variable inside
a loop: the variable outside will not get changed.
Instead, to get this behavior, you would use a `do` statement.
So you should take a look at the [Jinja API documentation][jinja-tmp].
Documentation about using Jinja to directly call Salt functions and get data
about your system can be found in the official
[Salt documentation][jinja-call-salt-functions].
## Salt Configuration, QubesOS layout
All Salt configuration files are in the `/srv/` directory, as usual.
The main directory is `/srv/salt/` where all state files reside.
States are contained in `*.sls` files.
However, the states that are part of the standard Qubes distribution are mostly
templates and the configuration is done in pillars from formulas.
The formulas are in `/srv/formulas`, including stock formulas for domains in
`/srv/formulas/dom0/virtual-machines-formula/qvm`, which are used by firstboot.
Because we use some code that is not found in older versions of salt, there is
a tool called `qubesctl` that should be run instead of `salt-call --local`. It
accepts all arguments of the vanilla tool.
Because we use some code that is not found in older versions of Salt, there is
a tool called `qubesctl` that should be run instead of `salt-call --local`.
It accepts all the same arguments of the vanilla tool.
## Configuring a VM's System from Dom0
## Configuring system inside of VMs
Starting with Qubes 3.2, Salt in Qubes can be used to configure VMs. Salt
formulas can be used normal way. Simply set VM name as target minion name in
top file. You can also use `qubes` pillar module to select VMs with a
particular property (see below). Then you need to pass additional arguments to
`qubesctl` tool:
Starting with Qubes R3.2, Salt in Qubes can be used to configure VMs from dom0.
Simply set the VM name as the target minion name in the top file.
You can also use the `qubes` pillar module to select VMs with a particular
property (see below).
If you do so, then you need to pass additional arguments to the `qubesctl` tool:
usage: qubesctl [-h] [--show-output] [--force-color] [--skip-dom0]
[--targets TARGETS | --templates | --app | --all]
...
positional arguments:
command Salt command to execute (for example: state.highstate)
command Salt command to execute (e.g., state.highstate)
optional arguments:
-h, --help show this help message and exit
--show-output Show output of management commands
--force-color Force color output, allow control characters from VM,
UNSAFE
--skip-dom0 Skip dom0 condifuration (VM creation etc)
--skip-dom0 Skip dom0 configuration (VM creation etc)
--targets TARGETS Coma separated list of VMs to target
--templates Target all templates
--app Target all AppVMs
--all Target all non-disposable VMs (TemplateVMs and AppVMs)
To apply the configuration to all the templates, call `qubesctl --templates
state.highstate`.
To apply a state to all templates, call `qubesctl --templates state.highstate`.
Actual configuration is applied using `salt-ssh` (running over `qrexec` instead
of `ssh`). Which means you don't need to install anything special in a VM you
want to manage. Additionally for each target VM, `salt-ssh` is started from a
temporary VM. This way dom0 doesn't directly interact with potentially
malicious target VM.
The actual configuration is applied using `salt-ssh` (running over `qrexec`
instead of `ssh`).
Which means you don't need to install anything special in a VM you want to
manage.
Additionally, for each target VM, `salt-ssh` is started from a temporary VM.
This way dom0 doesn't directly interact with potentially malicious target VMs;
and in the case of a compromised Salt VM, because they are temporary, the
compromise cannot spread from one VM to another.
## Writing your own configuration
## Writing Your Own Configurations
Let's start with quick example:
Let's start with quick a example:
my new and shiny vm:
my new and shiny VM:
qvm.present:
- name: salt-test # can be omitted when same as ID
- template: fedora-21
@ -119,84 +254,82 @@ Let's start with quick example:
- flags:
- proxy
It uses Qubes-specific `qvm.present` state, which ensures that domain is
created. The name should be `salt-test` (and not `my new and shiny vm`),
the rest are domains properties, same as in `qvm-prefs`. `proxy` flag informs
salt that the domain should be a ProxyVM.
It uses the Qubes-specific `qvm.present` state, which ensures that the domain is
present (if not, it creates it).
This should be put in `/srv/salt/my-new-vm.sls` or another `.sls` file. Separate
`*.top` file should be also written:
* The `name` flag informs Salt that the domain should be named `salt-test` (not
`my new and shiny VM`).
* The `template` flag informs Salt which template should be used for the domain.
* The `label` flag informs Salt what color the domain should be.
* The `mem` flag informs Salt how much RAM should be allocated to the domain.
* The `vcpus` flag informs Salt how many Virtual CPUs should be allocated to the
domain
* The `proxy` flag informs Salt that the domain should be a ProxyVM.
As you will notice, the options are the same (or very similar) to those used in
`qvm-prefs`.
This should be put in `/srv/salt/my-new-vm.sls` or another `.sls` file.
A separate `*.top` file should be also written:
base:
dom0:
- my-new-vm
The third line should contain the name of the previous file, without `.sls`.
**Note** The third line should contain the name of the previous state file,
without the `.sls` extension.
Now because we use custom extension to manage top files (instead of just
enabling them all) to enable the particular top file you should issue command:
To enable the particular top file you should issue the command:
qubesctl top.enable my-new-vm
$ qubesctl top.enable my-new-vm
To list all enabled tops:
To apply the state:
qubesctl top.enabled
$ qubesctl state.highstate
And to disable one:
### Example of Configuring a VM's System from Dom0
qubesctl top.disable my-new-vm
To actually apply the state:
qubesctl state.highstate
### Example of VM system configuration
It is also possible to configure system inside the VM. Lets make sure that `mc`
package is installed in all the templates. Similar to previous example, you
need to create state file (`/srv/salt/mc-everywhere.sls`):
Lets make sure that the `mc` package is installed in all templates.
Similar to the previous example, you need to create a state file
(`/srv/salt/mc-everywhere.sls`):
mc:
pkg.installed: []
Then appropriate top file (`/srv/salt/mc-everywhere.top`):
Then the appropriate top file (`/srv/salt/mc-everywhere.top`):
base:
- qubes:type:template:
qubes:type:template:
- match: pillar
- mc-everywhere
Now you need to enable the configuration:
Now you need to enable the top file:
qubesctl top.enable mc-everywhere
$ qubesctl top.enable mc-everywhere
And apply the configuration:
qubesctl --all state.highstate
$ qubesctl --all state.highstate
## All Qubes-specific States
## All Qubes-specific states
### `qvm.present`
### qvm.present
As in the example above, it creates a domain and sets its properties.
As in example above, it creates domain and sets its properties.
### `qvm.prefs`
### qvm.prefs
You can set properties of existing domain:
You can set properties of an existing domain:
my preferences:
qvm.prefs:
- name: salt-test2
- netvm: sys-firewall
Note that `name:` is a matcher, ie. it says the domain which properties will be
manipulated is called `salt-test2`. The implies that you currently cannot rename
domains this way.
***Note*** The `name:` option will not change the name of a domain, it will only
be used to match a domain to apply the configurations to it.
### qvm.service
### `qvm.service`
services in my domain:
qvm.service:
@ -210,46 +343,100 @@ domains this way.
- default:
- service5
This enables, disables, or sets to default, the services as in qvm-service.
This enables, disables, or sets to default, services as in `qvm-service`.
### qvm.running
### `qvm.running`
Ensures the domain is running:
Ensures the specified domain is running:
domain is running:
qvm.running:
- name: salt-test4
## qubes pillar module
## The `qubes` Pillar Module
Additional pillar data is available to ease targeting configuration (for
example all the templates). List here may be subject to changes in future
releases.
Additional pillar data is available to ease targeting configurations (for
example all templates).
***Note*** List here may be subject to changes in future releases.
### qubes:type
### `qubes:type`
VM type. Possible values:
- `admin` - administration domain (`dom0`)
- `admin` - Administration domain (`dom0`)
- `template` - Template VM
- `standalone` - Standalone VM
- `app` - template based AppVM
- `app` - Template based AppVM
### qubes:template
### `qubes:template`
Template name on which given VM is based (if any).
Template name on which a given VM is based (if any).
### qubes:netvm
### `qubes:netvm`
VM which provides network to the given VM
## Further reading
## Debugging
The output for each VM is logged in `/var/log/qubes/mgmt-VM_NAME.log`.
If the log does not contain useful information:
1. Run `sudo qubesctl --skip-dom0 --target=VM_NAME state.highstate`
2. When your VM is being started (yellow) press Ctrl-z on qubesctl.
3. Open terminal in disp-mgmt-VM_NAME.
4. Look at /etc/qubes-rpc/qubes.SaltLinuxVM - this is what is
executed in the management VM.
5. Get the last two lines:
$ export PATH="/usr/lib/qubes-vm-connector/ssh-wrapper:$PATH"
$ salt-ssh "$target_vm" $salt_command
Adjust $target_vm (VM_NAME) and $salt_command (state.highstate).
6. Execute them, fix problems, repeat.
## Known Pitfalls
### Using fedora-24-minimal
The fedora-24-minimal package is missing the `sudo` package.
You can install it via:
$ qvm-run -p -u root fedora-24-minimal-template 'dnf install -y sudo'
The `-p` will cause the execution to wait until the package is installed.
Having the `-p` flag is important when using a state with `cmd.run`.
### Disk Quota Exceeded (When Installing Templates)
If you install multiple templates you may encounter this error.
The solution is to shut down the updateVM between each install:
install template and shutdown updateVM:
cmd.run:
- name: sudo qubes-dom0-update -y fedora-24; qvm-shutdown {% raw %}{{ salt.cmd.run(qubes-prefs updateVM) }}{% endraw %}
## Further Reading
* [Salt documentation][salt-doc]
* [Salt states][salt-doc-states] ([files][salt-doc-states-file], [commands][salt-doc-states-cmd],
[packages][salt-doc-states-pkg], [ordering][salt-doc-states-order])
* [Top files][salt-doc-top]
* [Jinja templates][jinja]
* [Qubes specific modules][salt-qvm-doc]
* [Formula for default Qubes VMs][salt-virtual-machines-doc] ([and actual states][salt-virtual-machines-states])
* [Formulas for default Qubes VMs][salt-virtual-machines-doc] ([and actual states][salt-virtual-machines-states])
[salt-doc]: https://docs.saltstack.com/en/latest/
[salt-qvm-doc]: https://github.com/QubesOS/qubes-mgmt-salt-dom0-qvm/blob/master/README.rst
[salt-virtual-machines-doc]: https://github.com/QubesOS/qubes-mgmt-salt-dom0-virtual-machines/blob/master/README.rst
[salt-virtual-machines-states]: https://github.com/QubesOS/qubes-mgmt-salt-dom0-virtual-machines/tree/master/qvm
[salt-doc-states]: https://docs.saltstack.com/en/latest/ref/states/all/
[salt-doc-states-file]: https://docs.saltstack.com/en/latest/ref/states/all/salt.states.file.html
[salt-doc-states-pkg]: https://docs.saltstack.com/en/latest/ref/states/all/salt.states.pkg.html
[salt-doc-states-cmd]: https://docs.saltstack.com/en/latest/ref/states/all/salt.states.file.html
[salt-doc-states-order]: https://docs.saltstack.com/en/latest/ref/states/ordering.html
[salt-doc-states-req]: https://docs.saltstack.com/en/latest/ref/states/requisites.html
[salt-doc-states-ord]: https://docs.saltstack.com/en/latest/ref/states/ordering.html#the-order-option
[salt-doc-top]:https://docs.saltstack.com/en/latest/ref/states/top.html
[jinja]: http://jinja.pocoo.org/
[jinja-tmp]: http://jinja.pocoo.org/docs/2.9/templates/
[jinja-call-salt-functions]: https://docs.saltstack.com/en/getstarted/config/jinja.html#get-data-using-salt

3
configuration/secondary-storage.md
View File

@ -32,7 +32,8 @@ Known Issues
The same problem may occur if the above procedure is attempted on a
[TemplateVM][]. [[1]]
* After implementing the above procedure, starting `my-new-appvm` will cause
* This issue applies only to R3.1, not R3.2 or later:
After implementing the above procedure, starting `my-new-appvm` will cause
dom0 notifications to occur stating that loop devices have been attached to
dom0. This is normal. (No untrusted devices are actually being mounted to
dom0.) Do not attempt to detach these disks. (They will automatically be

207
configuration/vpn.md
View File

@ -10,11 +10,11 @@ redirect_from:
---
How To make a VPN Gateway in Qubes
----------------------------------
==================================
Setting up a VPN connection is really not Qubes specific and is documented in your operating system documentation. The relevant documentation for the Qubes default Guest OS (Fedora) is [Establishing a VPN Connection](https://docs.fedoraproject.org/en-US/Fedora/23/html/Networking_Guide/sec-Establishing_a_VPN_Connection.html)
Although setting up a VPN connection is not by itself Qubes specific, Qubes includes a number of tools that can make the client-side setup of your VPN more versatile and secure. This document is a Qubes-specific outline for choosing the type of VM to use, and shows how to prepare a ProxyVM for either NetworkManager or a set of fail-safe VPN scripts.
The Qubes specific part is to choose the right VM for the VPN client:
Please refer to your guest OS and VPN service documentation when considering the specific steps and parameters for your connection(s); The relevant documentation for the Qubes default guest OS (Fedora) is [Establishing a VPN Connection.](https://docs.fedoraproject.org/en-US/Fedora/23/html/Networking_Guide/sec-Establishing_a_VPN_Connection.html)
### NetVM
@ -29,22 +29,18 @@ While the NetworkManager service is not started here (for a good reason), you ca
### ProxyVM
**WARNING:** *You need to use Qubes 3.1-rc2 (or later)! In the previous releases the NetworkManager service was not working in ProxyVMs as expected.* ([#1052](https://github.com/QubesOS/qubes-issues/issues/1052))
One of the best thing in Qubes is that you can use a special type of VM called a ProxyVM (or FirewallVM). The special thing is that your AppVMs see this as a NetVM, and your NetVMs see it as an AppVM. Because of this, you can place a ProxyVM between your AppVMs and your NetVM. This is how the default FirewallVM functions.
One of the best unique features of Qubes OS is its special type of VM called a ProxyVM. The special thing is that your AppVMs see this as a NetVM (or uplink), and your NetVMs see it as a downstream AppVM. Because of this, you can place a ProxyVM between your AppVMs and your NetVM. This is how the default sys-firewall VM functions.
Using a ProxyVM to set up a VPN client gives you the ability to:
- Separate your VPN credentials from Your NetVM
- Separate your VPN credentials from Your AppVM data.
- Separate your VPN credentials from your NetVM.
- Separate your VPN credentials from your AppVM data.
- Easily control which of your AppVMs are connected to your VPN by simply setting it as a NetVM of the desired AppVM.
#### Setup a ProxyVM as a VPN gateway
Set up a ProxyVM as a VPN gateway using NetworkManager
------------------------------------------------------
**Using NetworkManager**
1. Create a new VM and check the ProxyVM radio button.
1. Create a new VM, name it, click the ProxyVM radio button, and choose a color and template.
![Create\_New\_VM.png](/attachment/wiki/VPN/Create_New_VM.png)
@ -60,73 +56,168 @@ Using a ProxyVM to set up a VPN client gives you the ability to:
5. Optionally, you can install some [custom icons](https://github.com/Zrubi/qubes-artwork-proxy-vpn) for your VPN
**Using iptables and openvpn**
You need an openvpn server and a DNS server accessible through the vpn (use one from your vpn provider / a public one).
Set up a ProxyVM as a VPN gateway using iptables and CLI scripts
----------------------------------------------------------------
1. Create a new VM and check the ProxyVM radio button.
This method is more involved than the one above, but has anti-leak features that also make the connection _fail closed_ should it be interrupted. It has been tested with Fedora 23 and Debian 8 templates.
1. Create a new VM, name it, click the ProxyVM radio button, and choose a color and template.
![Create\_New\_VM.png](/attachment/wiki/VPN/Create_New_VM.png)
2. Setup openvpn:
Copy your openvpn config file to `/home/user/vpn.cfg`.
Note: Do not enable NetworkManager in the ProxyVM, as it can interfere with the scripts' DNS features. If you enabled NetworkManager or used other methods in a previous attempt, do not re-use the old ProxyVM... Create a new one according to this step.
It should have one line starting with `dev` and one starting with `proto`.
The first describes the connection type (`tun` or `tap`) and the second the used protocol (`tcp` or `udp`).
Depending on your connection type, openvpn will create a new network device (probably `tap0` or `tun0`).
If your choice of template VM doesn't already have the VPN client software, you'll need to install the software in the template before proceeding. Disable any auto-starting service that comes with the software package: for example `sudo systemctl disable openvpn.service`.
It also contains a line `remote X.X.X.X 1194`, where `X.X.X.X` is the ip of your openvpn server.
You may also wish to install `nano` or another simple text editor for entering the scripts below.
If it does not contain a line `redirect-gateway def1`, add it.
This will route all traffic through your vpn's network device, after a connection was created.
If the connection breaks down all traffic will be routed through the original network device (we will stop this with iptables).
2. Set up and test the VPN client.
If your vpn config file contains `auth-user-pass`, change it to `auth-user-pass /home/user/auth.txt` and create a file `/home/user/auth.txt` containing the user name in the first line and the password in the second.
This will enable the vpn to login without requiring you to enter your username and password.
If a different authentication method is used, set it up to require no user input.
The vpn should now start by calling `sudo openvpn --config /home/user/vpn.cfg` and require no additional user input.
Make sure the VPN VM and its template VM are not running.
In the following, we use the following placeholder:
`$DEV` For the device created for the connection.
`$PROT` For the protocol used for connection
`$SVR` For the openvpn server's ip.
`$DNS` For the dns server's ip.
Run a terminal (CLI) in the VPN VM -- this will start the VM. Then make a new 'vpn' folder with `sudo mkdir /rw/config/vpn` and copy your VPN config files here (the example config filename used here is `openvpn-client.ovpn`). Files accompanying the main config such as *.crt and *.pem should also go here, and should not be referenced in the main config by absolute paths such as '/etc/...'.
Notes about VPN config options: The VPN scripts here are intended to work with commonly used `tun` interfaces, whereas `tap` mode is untested. Also, the config should route all traffic through your VPN's interface after a connection is created; For openvpn the directive for this is `redirect-gateway def1`. Lastly, the VPN client may not be able to prompt you for credentials when connecting to the server: Creating a file in the 'vpn' folder with your credentials and using a directive such as openvpn's `auth-user-pass <filename>` is recommended.
3. Setup iptables:
Edit `/rw/config/qubes-firewall-user-script` and add:
__Test your client configuration:__ Run the client from a CLI prompt in the 'vpn' folder, preferably as root. For example:
```
sudo openvpn --cd /rw/config/vpn --config openvpn-client.ovpn
```
`iptables -P OUTPUT DROP`
This blocks all outgoing traffic, if not specified otherwise.
Watch for status messages that indicate whether the connection is successful and test from another VPN VM terminal window with `ping` and `traceroute`. DNS may be tested at this point by replacing addresses in `/etc/resolv.conf` with ones appropriate for your VPN (although this file will not be used when setup is complete). Diagnose any connection problems using resources such as client documentation and help from your VPN service provider.
`iptables -I OUTPUT -o $DEV -j ACCEPT`
This allows the local system to connect through the vpn (you dont need this).
Proceed to the next step when you're sure the basic VPN connection is working.
`iptables -I OUTPUT -o eth0 -d $SVR -p $PROT --dport 1194 -j ACCEPT`
This allows your system to connect to the vpn server with the protocol `$PROT` under the port 1194.
3. Create the DNS-handling script.
Use `sudo nano /rw/config/vpn/qubes-vpn-handler.sh` to edit and add:
`iptables -I OUTPUT -o lo -j ACCEPT`
This allows connections from the system to the system.
~~~
#!/bin/bash
set -e
export PATH="$PATH:/usr/sbin:/sbin"
`iptables -I FORWARD -o eth0 -j DROP`
`iptables -I FORWARD -i eth0 -j DROP`
This blocks forwarding of connections through your plain network device (in case the vpn tunnel breaks).
case "$1" in
`iptables -t nat -I PR-QBS -p udp --dport 53 -j DNAT --to-destination $DNS`
`iptables -t nat -I PR-QBS -p tcp --dport 53 -j DNAT --to-destination $DNS`
This will rewrite the DNS destination, and the traffic will be routed down the vpn tunnel. (to prevent DNS leaks)
up)
# To override DHCP DNS, assign DNS addresses to 'vpn_dns' env variable before calling this script;
# Format is 'X.X.X.X Y.Y.Y.Y [...]'
if [[ -z "$vpn_dns" ]] ; then
# Parses DHCP foreign_option_* vars to automatically set DNS address translation:
for optionname in ${!foreign_option_*} ; do
option="${!optionname}"
unset fops; fops=($option)
if [ ${fops[1]} == "DNS" ] ; then vpn_dns="$vpn_dns ${fops[2]}" ; fi
done
fi
Now save `/rw/config/qubes-firewall-user-script` and make it executable:
iptables -t nat -F PR-QBS
if [[ -n "$vpn_dns" ]] ; then
# Set DNS address translation in firewall:
for addr in $vpn_dns; do
iptables -t nat -A PR-QBS -i vif+ -p udp --dport 53 -j DNAT --to $addr
iptables -t nat -A PR-QBS -i vif+ -p tcp --dport 53 -j DNAT --to $addr
done
su - -c 'notify-send "$(hostname): LINK IS UP." --icon=network-idle' user
else
su - -c 'notify-send "$(hostname): LINK UP, NO DNS!" --icon=dialog-error' user
fi
;;
down)
su - -c 'notify-send "$(hostname): LINK IS DOWN !" --icon=dialog-error' user
;;
esac
~~~
Now save the script and make it executable:
`sudo chmod +x /rw/config/vpn/qubes-vpn-handler.sh`
4. Configure client to use the DNS handling script. Using openvpn as an example, edit the config with `sudo nano /rw/config/vpn/openvpn-client.ovpn` and add these lines:
~~~
script-security 2
up 'qubes-vpn-handler.sh up'
down 'qubes-vpn-handler.sh down'
~~~
**Restart the client and test the connection again** ...this time from an AppVM!
5. Set up iptables anti-leak rules.
Edit the firewall script with `sudo nano /rw/config/qubes-firewall-user-script` then clear out the existing lines and add:
~~~
#!/bin/bash
# Block forwarding of connections through upstream network device
# (in case the vpn tunnel breaks):
iptables -I FORWARD -o eth0 -j DROP
iptables -I FORWARD -i eth0 -j DROP
# Block all outgoing traffic
iptables -P OUTPUT DROP
iptables -F OUTPUT
iptables -I OUTPUT -o lo -j ACCEPT
# Add the `qvpn` group to system, if it doesn't already exist
if ! grep -q "^qvpn:" /etc/group ; then
groupadd -rf qvpn
sync
fi
sleep 2s
# Allow traffic from the `qvpn` group to the uplink interface (eth0);
# Our VPN client will run with group `qvpn`.
iptables -I OUTPUT -p all -o eth0 -m owner --gid-owner qvpn -j ACCEPT
~~~
Now save the script and make it executable:
`sudo chmod +x /rw/config/qubes-firewall-user-script`
4. Setup the vpn's autostart:
Edit to `/rw/config/rc.local`, make it executable (`sudo chmod +x /rw/config/rc.local`) and add:
5. Set up the VPN's autostart.
ln -s /home/user/vpn.cfg /etc/openvpn/vpn.conf;
systemctl --no-block start openvpn@vpn.service;
Use `sudo nano /rw/config/rc.local` to clear out the existing lines and add:
5. Configure your AppVMs to use the new VM as a NetVM.
~~~
#!/bin/bash
VPN_CLIENT='openvpn'
VPN_OPTIONS='--cd /rw/config/vpn/ --config openvpn-client.ovpn --daemon'
![Settings-NetVM.png](/attachment/wiki/VPN/Settings-NetVM.png)
su - -c 'notify-send "$(hostname): Starting $VPN_CLIENT..." --icon=network-idle' user
groupadd -rf qvpn ; sleep 2s
sg qvpn -c "$VPN_CLIENT $VPN_OPTIONS"
~~~
6. Optionally, you can install some [custom icons](https://github.com/Zrubi/qubes-artwork-proxy-vpn) for your VPN
Change the `VPN_CLIENT` and `VPN_OPTIONS` variables to match your VPN software.
Now save the script and make it executable:
`sudo chmod +x /rw/config/rc.local`
6. Restart the new VM! The link should then be established automatically with a popup notification to that effect.
Usage
-----
Configure your AppVMs to use the VPN VM as a NetVM...
![Settings-NetVM.png](/attachment/wiki/VPN/Settings-NetVM.png)
If you want to be able to use the [Qubes firewall](/doc/firewall), create a new FirewallVM (as a ProxyVM) and set it to use the VPN VM as its NetVM.
Then, configure AppVMs to use your new FirewallVM as their NetVM.
If you want to update your TemplateVMs through the VPN, enable the `qubes-updates-proxy` service in your new FirewallVM.
You can do this in the Services tab in Qubes VM Manager or on the command-line:
$ qvm-service -e <name> qubes-updates-proxy
Then, configure your templates to use your new FirewallVM as their NetVM.
Troubleshooting
---------------
* Always test your basic VPN connection before adding scripts.
* Test DNS: Ping a familiar domain name from an appVM. It should print the IP address for the domain.
* For scripting: Ping external IP addresses from inside the VPN VM using `sudo sg qvpn -c 'ping ...'`, then from an appVM using just `ping ...`. Once the firewall rules are in place, you will have to use `sudo sg` to run any IP network commands in the VPN VM.
* Use `iptables -L -v` and `iptables -L -v -t nat` to check firewall rules. The latter shows the critical PR-QBS chain that enables DNS forwarding.

97
customization/bind-dirs.md Normal file
View File

@ -0,0 +1,97 @@
---
layout: doc
title: How to make any file in a TemplateBasedVM persistent using bind-dirs
permalink: /doc/bind-dirs/
redirect_from:
- /en/doc/bind-dirs/
---
# How to make any file in a TemplateBasedVM persistent using bind-dirs #
## What is bind-dirs? ##
With [bind-dirs](https://github.com/QubesOS/qubes-core-agent-linux/blob/master/vm-systemd/bind-dirs.sh)
any arbitrary files or folders can be made persistent in TemplateBasedVMs.
## What is it useful for? ##
In a TemplateBasedVM all of the file system comes from the template except /home and /usr/local.
This means that changes in the rest of the filesystem are lost when the TemplateBasedVM is shutdown.
bind-dirs provides a mechanism whereby files usually taken from the template can be persisted across reboots.
For example, in Whonix, [Tor's data dir /var/lib/tor has been made persistent in the TemplateBased ProxyVM sys-whonix](https://github.com/Whonix/qubes-whonix/blob/8438d13d75822e9ea800b9eb6024063f476636ff/usr/lib/qubes-bind-dirs.d/40_qubes-whonix.conf#L5).
In this way sys-whonix can benefit from the Tor anonymity feature 'persistent Tor entry guards' but does not have to be a StandaloneVM.
## Minimum Qubes Version ##
bind-dirs.sh works with Qubes R3.2 and above.
## How to use bind-dirs.sh? ##
Inside your TemplateBasedVM.
1. Make sure folder `/rw/config/qubes-bind-dirs.d` exists.
sudo mkdir -p /rw/config/qubes-bind-dirs.d
2. Create a file `/rw/config/qubes-bind-dirs.d/50_user.conf` with root rights inside a TemplateBasedVM.
3. Edit the file 50_user.conf to append a folder or file name to the `binds` variable. (In the following example we are using folder `/var/lib/tor`. You can replace that name with a folder or file name of your choice.)
binds+=( '/var/lib/tor' )
binds+=( '/etc/tor/torrc' )
Multiple entries are possible, each on a separate line.
4. Save.
5. Reboot the TemplateBasedVM.
6. Done.
If you added for example folder `/var/lib/tor` to the `binds` variable, from now any files within that folder would persist reboots. If you added for example file `/etc/tor/torrc` to the `binds` variable, from now any modifications to that file would persist reboots.
## Other Configuration Folders ##
* `/usr/lib/qubes-bind-dirs.d` (lowest priority, for packages)
* `/etc/qubes-bind-dirs.d` (intermediate priority, for template wide configuration)
* `/rw/config/qubes-bind-dirs.d` (highest priority, for per VM configuration)
## How does it work? ##
bind-dirs.sh is called on startup of a TemplateBasedVM, and configuration files in the configuration folders above are parsed to build a bash array.
Files or folders identified in the array are copied to /rw/bind-dirs if they do not already exist there, and are then bind mounted over the original files/folders.
Creation of the file and folders in /rw/bind-dirs should be automatic the first time the TemplateBasedVM is restarted after configuration.
If you want to circumvent this process, you can create the relevant filestructure under /rw/bind-dirs and make any changes at the same time that you perform the configuration, before reboot.
## Limitations ##
* Files that exist in the TemplateVM root image cannot be deleted in the TemplateBasedVMs root image using bind-dirs.sh.
* Re-running `sudo /usr/lib/qubes/bind-dirs.sh` without a previous `sudo /usr/lib/qubes/bind-dirs.sh umount` does not work.
* Running 'sudo /usr/lib/qubes/bind-dirs.sh umount' after boot (before shutdown) is probably not sane and nothing can be done about that.
* Many editors create a temporary file and copy it over the original file. If you have bind mounted an individual file this will break the mount.
Any changes you make will not survive a reboot. If you think it likely you will want to edit a file, then either include the parent directory in bind-dirs.rather than the file, or perform the file operation on the file in /rw/bind-dirs.
* Some files are altered when a qube boots - e.g. /etc/hosts. If you try to use bind-dirs on such files you may break your qube in unpredictable ways.
## How to remove binds from bind-dirs.sh? ##
`binds` is actually just a bash variable (an array) and the bind-dirs.sh configuration folders are `source`d as bash snippets in lexical order.
Therefore if you wanted to remove an existing entry from the `binds` array, you could do that by using a lexically higher configuration file.
For example, if you wanted to make `/var/lib/tor` non-persistant in `sys-whonix` without manually editing [`/usr/lib/qubes-bind-dirs.d/40_qubes-whonix.conf`](https://github.com/Whonix/qubes-whonix/blob/master/usr/lib/qubes-bind-dirs.d/40_qubes-whonix.conf), you could use the following.
`/rw/config/qubes-bind-dirs.d/50_user.conf`
~~~
binds=( "${binds[@]/'/var/lib/tor'}" )
~~~
(Editing `/usr/lib/qubes-bind-dirs.d/40_qubes-whonix.conf` directly is recommended against, since such changes get lost when that file is changed in the package on upgrades.)
## Discussion ##
[TemplateBasedVMs: make selected files and folders located in the root image persistent- review bind-dirs.sh](https://groups.google.com/forum/#!topic/qubes-devel/tcYQ4eV-XX4/discussion)

191
customization/dark-theme.md Normal file
View File

@ -0,0 +1,191 @@
---
layout: doc
title: Dark Theme in Dom0 and DomU
permalink: /doc/dark-theme/
---
Dark Theme in Dom0
==================
Dark KDE in Dom0
----------------
The following text describes how to change the default light theme to a dark theme. This is just an example, feel free to adjust the appearance to your taste.
The image below shows the default light theme after installation.
![begin light theme](/attachment/wiki/Dark-Theme/kde-fresh-installed-standard.png)
This is the result after applying the steps described here.
![end result dark theme](/attachment/wiki/Dark-Theme/kde-end-result.png)
1. Change `Workspace Appearance`
1. Open the `Workspace Appearance` window
Qubes Menu -> System Tools -> System Settings -> Workspace Appearance
![Workspace Appearance](/attachment/wiki/Dark-Theme/kde-app-appearance-menu-style.png)
2. Go to `Desktop Theme`
![Desktop Menu](/attachment/wiki/Dark-Theme/kde-appearance-settings-desktop-theme-oxygen.png)
3. Select `Oxygen` and `Apply` the change
2. (Optional) Remove blue glowing task items
![blue glowing task bar items](/attachment/wiki/Dark-Theme/kde-taskbar-blue-glowing-border.png)
1. Adjust Oxygen `Details`
Qubes Menu -> System Tools -> System Settings -> Workspace Appearance -> Desktop Theme -> Details (Tab)
2. Select `Oxygen`
3. Change `Theme Item -> Task Items` from `Oxygen Task Items` to `Air Task Items`
![Change Task items look](/attachment/wiki/Dark-Theme/kde-desktop-theme-details.png)
4. Apply changes
![task bar items blue glowing removed](/attachment/wiki/Dark-Theme/kde-taskbar-blue-glowing-removed.png)
3. Change `Application Appearance`
1. Open the `Application Appearance` window
Qubes Menu -> System Tools -> System Settings -> Application Appearance
2. Go to `Colors`
![colors tab](/attachment/wiki/Dark-Theme/kde-app-appearance-menu-colors.png)
3. Select `Obsidian Coast`
![set to Obsidian Coast](/attachment/wiki/Dark-Theme/kde-app-appearance-menu-colors-set.png)
4. Apply Changes
Qubes VM Manager should now look like the image below.
![result black Qubes Manager](/attachment/wiki/Dark-Theme/kde-black-qubes-manager.png)
**Note:** Chaning the `Window Decorations` from `Plastik for Qubes` will remove the border color and the VM name. The problem with `Plastik for Qubes` is, that it does not overwrite the background and text color for Minimize, Maximize and Close buttons. The three button are therefor hard to read.
Dark XCFE in Dom0
-----------------
The following text describes how to change the default light theme to a dark theme. This is just an example, feel free to adjust the appearance to your taste.
The image below shows the default light theme after installation.
![begin light theme](/attachment/wiki/Dark-Theme/xfce-fresh-installed.png)
This is the result after applying the steps described here.
![end result dark theme](/attachment/wiki/Dark-Theme/xfce-end-result.png)
1. Change Appearance
1. Open the `Appearance` dialog
Qubes Menu -> System Tools -> Appearance
![appearance dialog](/attachment/wiki/Dark-Theme/xfce-appearance-dialog.png)
2. Change Style to `Albatross`
**Note:** The black appearance theme `Xfce-dusk` makes the VM names in the `Qubes OS Manager` unreadable.
2. *(Optional)* Change Window Manager Style
1. Open the `Window Manager` dialog
Qubes Menu -> System Tools -> Appearance
![window manager dialog](/attachment/wiki/Dark-Theme/xfce-window-manager-theme.png)
2. Change the Theme in the `Style` Tab (e. g. Defcon-IV). All available themes work.
Dark App VM, Template VM, Standalone VM, HVM (Linux Gnome)
==========================================================
Almost all Qubes VM's are based on the Gnome desktop. Therefor the description below is focused on the Gnome Desktop Environment.
Using "Gnome-Tweak-Tool"
------------------------
The advantage of creating a dark themed Template VM is, that each AppVM which is derived from the Template VM will be dark themed by default.
**Note:** Gnome-Tweak-Tool crashes under Archlinux. A workaround is to assign the AppVM to another TemplateVM (Debian, Fedora) which has Gnome-Tweak-Tool installed. Start the AppVM and configure the settings. Shutdown the machine and switch the template VM back to Archlinux.
1. Start VM
**Note:** In case of App VM start the Template on which the AppVM is based on.
2. Install `Gnome-Tweak-Tool`
- Fedora
sudo dnf install gnome-tweak-tool
- Debian
sudo apt-get install gnome-tweak-tool
3. *(Only AppVM)* Stop template and start AppVM
4. Add `Gnome-Tweak-Tool` to the Application Menu
1. `Right-click` on VM entry in `Qubes VM Manager` select `Add/remove app shortcuts`
2. Select `Tweak Tool` and press the `>` button to add it
![Application Dialog](/attachment/wiki/Dark-Theme/dialog-add-gnome-tweak-tool.png)
5. Enable `Global Dark Theme`
1. *Debian only*
cd ~/.config/
mkdir gtk-3.0
cd gtk-3.0/
touch settings.ini
2. Start `Tweak Tool` from the VM application menu and set the `Global Dark Theme` switch to `on`
![Global Dark Theme enabled](/attachment/wiki/Dark-Theme/gnome-tweak-tool.png)
6. *(Optional)* Modify Firefox
**Note:** Firefox uses GTK style settings by default. This can create side effects such as unusable forms or search fields. There are two different ways to avoid this. Either by using a add-on or by overwriting the defaults.
- use the theme [GTK+ Dark Theme Global Fixes](https://userstyles.org/styles/111694/gtk-dark-theme-global-fixes) and the [Stylish](https://addons.mozilla.org/en-US/firefox/addon/stylish/) addon
- or add the following line to `/rw/config/rc.local`
sed -i.bak "s/Exec=firefox %u/Exec=bash -c 'GTK_THEME=Adwaita:light firefox %u'/g" /usr/share/applications/firefox.desktop
7. Restart VM or all application
Manually
--------
Manually works for Debian, Fedora and Archlinux.
1. Start VM
**Note:** In case of App VM start the Template on which the AppVM is based on.
2. Enable `Global Dark Theme`
cd ~/.config/
mkdir gtk-3.0
cd gtk-3.0/
touch settings.ini
add the following lines to `settings.ini`
[Settings]
gtk-application-prefer-dark-theme=1
3. follow step 6 and 7 in: Using `Gnome-Tweak-Tool`

61
customization/dispvm-customization.md
View File

@ -1,6 +1,6 @@
---
layout: doc
title: DispVM Customization
title: Disposable VM Customization
permalink: /doc/dispvm-customization/
redirect_from:
- /en/doc/dispvm-customization/
@ -9,14 +9,17 @@ redirect_from:
- /wiki/UserDoc/DispVMCustomization/
---
Changing the template used as a basis for Disposable VM
========================================================
Disposable VM Customization
====================
You may want to use a non-default template as a basis for Disposable VM. One example is to use a less-trusted template with some less trusted, 3rd party, often unsigned, applications installed, such as e.g. 3rd part printer drivers.
Changing the DVM Template
-------------------------
You may want to use a non-default template the [DVM Template](/doc/glossary/#dvm-template). One example is to use a less-trusted template with some less trusted, 3rd party, often unsigned, applications installed, such as e.g. 3rd part printer drivers.
In order to regenerate the Disposable VM "snapshot" (called 'savefile' on Qubes) one can use the following command in Dom0:
[joanna@dom0 ~]$ qvm-create-default-dvm <custom-template-name>
[user@dom0 ~]$ qvm-create-default-dvm <custom-template-name>
This would create a new Disposable VM savefile based on the custom template. Now, whenever one opens a file (from any AppVM) in a Disposable VM, a Disposable VM based on this template will be used.
@ -24,23 +27,24 @@ This would create a new Disposable VM savefile based on the custom template. Now
One can easily verify if the new Disposable VM template is indeed based on a custom template (in the example below the template called "f17-yellow" was used as a basis for the Disposable VM):
[joanna@dom0 ~]$ ll /var/lib/qubes/dvmdata/
[user@dom0 ~]$ ll /var/lib/qubes/dvmdata/
total 0
lrwxrwxrwx 1 joanna joanna 45 Mar 11 13:59 default_dvm.conf -> /var/lib/qubes/appvms/f17-yellow-dvm/dvm.conf
lrwxrwxrwx 1 joanna joanna 49 Mar 11 13:59 default_savefile -> /var/lib/qubes/appvms/f17-yellow-dvm/dvm-savefile
lrwxrwxrwx 1 joanna joanna 47 Mar 11 13:59 savefile_root -> /var/lib/qubes/vm-templates/f17-yellow/root.img
lrwxrwxrwx 1 user user 45 Mar 11 13:59 default_dvm.conf -> /var/lib/qubes/appvms/f17-yellow-dvm/dvm.conf
lrwxrwxrwx 1 user user 49 Mar 11 13:59 default_savefile -> /var/lib/qubes/appvms/f17-yellow-dvm/dvm-savefile
lrwxrwxrwx 1 user user 47 Mar 11 13:59 savefile_root -> /var/lib/qubes/vm-templates/f17-yellow/root.img
If you wish to use the `fedora-minimal` template as a DVM Template, see the "DVM Template" use case under [fedora-minimal customization](/doc/templates/fedora-minimal/#customization).
Customization of Disposable VM
==============================
------------------------------
It is possible to change the settings of each new Disposable VM (DispVM). This can be done by customizing the DispVM template:
1. Start a terminal in the `fedora-20-x64-dvm` TemplateVM by running the following command in a dom0 terminal. (By default, this TemplateVM is not shown in Qubes VM Manager. However, it can be shown by selecting "Show/Hide internal VMs.")
1. Start a terminal in the `fedora-23-dvm` TemplateVM by running the following command in a dom0 terminal. (By default, this TemplateVM is not shown in Qubes VM Manager. However, it can be shown by selecting "Show/Hide internal VMs.")
[user@dom0 ~]$ qvm-run -a fedora-20-x64-dvm gnome-terminal
[user@dom0 ~]$ qvm-run -a fedora-23-dvm gnome-terminal
2. Change the VM's settings and/or applications, as desired. Note that currently Qubes supports exactly one DispVM template, so any changes you make here will affect all DispVMs. Some examples of changes you may want to make include:
- Changing Firefox's default startup settings and homepage.
@ -50,16 +54,45 @@ It is possible to change the settings of each new Disposable VM (DispVM). This c
3. Create an empty `/home/user/.qubes-dispvm-customized` file in the VM (not in dom0):
[user@fedora-20-x64-dvm ~]$ touch /home/user/.qubes-dispvm-customized
[user@fedora-23-dvm ~]$ touch /home/user/.qubes-dispvm-customized
4. Shutdown the VM (either by `poweroff` from VM terminal, or `qvm-shutdown` from dom0 terminal).
5. Regenerate the DispVM template using the default template:
[user@dom0 ~]$ qvm-create-default-dvm --default-template
Or, if you're [using a non-default template](#changing-the-template-used-as-a-basis-for-disposable-vm), regenerate the DispVM using your custom template:
Or, if you're [using a non-default template](#changing-the-dvm-template), regenerate the DispVM using your custom template:
[user@dom0 ~]$ qvm-create-default-dvm <custom-template-name>
**Note:** All of the above requires at least qubes-core-vm \>= 2.1.2 installed in template.
Adding arbitrary programs to Disposable VM Application Menu
-----------------------------------------------------------
For added convenience, arbitrary programs can be added to the Application Menu of the Disposable VM. In order to do that create (e.g.) `arbitrary.desktop` file in `/usr/share/applications` in Dom0. That file will point to the desired program. Use the following template for the file:
[Desktop Entry]
Version=1.0
Type=Application
Exec=sh -c 'echo arbitrary | /usr/lib/qubes/qfile-daemon-dvm qubes.VMShell dom0 DEFAULT red
Icon=dispvm-red
Terminal=false
Name=DispVM: Arbitrary Name
GenericName=DispVM: Arbitrary Generic Name
StartupNotify=false
Categories=Network;X-Qubes-VM;
Next, the `/etc/xdg/menus/applications-merged/qubes-dispvm.menu` file has to be modified so that it points to the newly-created .desktop file. (If you use i3 you can skip this step; the shortcut gets added to dmenu automatically.)
Add a `<Filename>arbitrary.desktop</Filename>` line so that your modified file looks like this:
<Include>
<Filename>qubes-dispvm-firefox.desktop</Filename>
<Filename>qubes-dispvm-xterm.desktop</Filename>
<Filename>arbitrary.desktop</Filename>
</Include>
After saving the changes the new shortcut should appear in the Disposable VM Applications menu.

10
customization/fedora-minimal-template-customization.md
View File

@ -139,7 +139,7 @@ Managing GUI theme / appearance is often complex because when you do not want to
For this reason, we need to customize themes for each GUI framework that our application depends on.
This often includes GTK2, GTK3 (which us a different configuration/themes than GTK2), QT.
This often includes GTK2, GTK3 (which us a different configuration/themes than GTK2), Qt.
The apparance of Windows can only be changed in dom0, however, the appearance of all buttons, menus, icons, widgets are specific to each AppVM.
@ -189,7 +189,7 @@ The following programs can be used to see if theme has been correctly applied:
* GTK2 program: scite, thunderbird, firefox
* GTK3 program: lxterminal
* QT program: keepassx
* Qt program: keepassx
*Note*: testing in a TemplateVM will not work as expected because gnome-settings-daemon is not started in TemplateVM.
so test your themes in an AppVM and then update the TemplateVM accordingly.
@ -251,9 +251,9 @@ Edit/Create the following file: /etc/dconf/db/qubes.d/locks/theme.lock:
Finally, regenerate the dconf database
> dconf update
### Uniform look for QT & GTK
### Uniform look for Qt & GTK
Getting an uniform look for QT & GTK is not achieved yet. A good source is on the following link [UNIFORMTHEME]
Getting an uniform look for Qt & GTK is not achieved yet. A good source is on the following link [UNIFORMTHEME]
Two case:
@ -265,7 +265,7 @@ Two case:
You can verify if it is enabled by searching for "style=GTK+" in /etc/xdg/Trolltech.conf.
If style is changed to another name, it will be used instead of your GTK theme.
*Note*: check that ~/.config/Trolltech.conf in your AppVMs is not defining another "style=" because it will take precedence over your global QT theme.
*Note*: check that ~/.config/Trolltech.conf in your AppVMs is not defining another "style=" because it will take precedence over your global Qt theme.
[3GMODEM]: https://www.codeenigma.com/community/blog/installing-3g-usb-modems-linux

31
customization/i3.md
View File

@ -14,12 +14,12 @@ redirect_from:
i3 is part of the testing repository (as of Qubes R3.1) and can be installed from there
using the dom0 update mechanism.
$ qubes-dom0-update --enablerepo=qubes-dom0-current-testing i3
$ sudo qubes-dom0-update --enablerepo=qubes-dom0-current-testing i3
Qubes-specific configuation is available in a separate package and can be installed
optionally. Otherwise you can write your own configuration (see below).
$ qubes-dom0-update --enablerepo=qubes-dom0-current-testing i3-settings-qubes
$ sudo qubes-dom0-update --enablerepo=qubes-dom0-current-testing i3-settings-qubes
That's it. After logging out, you can select i3 in the login manager.
@ -82,33 +82,6 @@ After that you can just install the generated rpm like any other local package
Log out, select i3, then log in again.
### Configuration
**Warning**: Be careful when writing configuration/scripts for the dom0. A script which communicates with the qubes VMs could potentially open a security hole.
Things needed/recommended to be done:
1. Create [a script][xdg_autostart_script] to start all entries in the xdg
autostart directory. This is necessary to bring transient vm's up and
restore state.
2. Change dmenu to i3-dmenu-desktop in the i3 configuration file. This
respects xdg desktop files and gives you a good way of starting programs in
specific domains.
3. Install i3status or use a [different kind of script][i3bar_script] to drive
i3bar.
4. You could install and bind tools to change backlight and volume levels in
i3's config. You could also run kmix and xfce4-power-manager, which are
part of a normal Qubes installation, and bind the keys for you.
5. Qubes does automatic screen locking and so should you. Install `xautolock`
and `i3lock` in dom0 and then add
exec --no-startup-id "xautolock -detectsleep -time 3 -locker 'i3lock -d -c 000000' -notify 30 -notifier \"notify-send -t 2000 'Locking screen in 30 seconds'\""
to your i3 config to enable it.
6. By default `$mod+Return` in i3 will open a new terminal in dom0. If you
prefer to start a new terminal in the domain of the currently active
window, use [a script like this][terminal_start_script].
[xdg_autostart_script]:https://gist.github.com/SietsevanderMolen/7b4cc32ce7b4884513b0a639540e454f
[i3bar_script]: https://gist.github.com/SietsevanderMolen/e7f594f209dfaa3596907e427b657e30
[terminal_start_script]: https://gist.github.com/SietsevanderMolen/7c6f2b5773dbc0c08e1509e49abd1e96

32
customization/kde.md
View File

@ -8,6 +8,38 @@ redirect_from: /en/doc/kde/
Using KDE in dom0
=================
Installation
------------
Prior to R3.2, KDE was the default desktop environment in Qubes. Beginning with
R3.2, however, [XFCE is the new default desktop environment](https://www.qubes-os.org/doc/releases/3.2/release-notes/). Nonetheless, it is
still possible to install KDE by issuing this command in dom0:
$ sudo qubes-dom0-update @kde-desktop-qubes
You can also change your default login manager (lightdm) to the new KDE default: sddm
* first you need to edit the `/etc/sddm.conf` to make sure if the custom X parameter is set according to Qubes needs:
~~~
[XDisplay]
ServerArguments=-nolisten tcp -background none
~~~
* disable the lightdm service:
~~~
$ sudo systemctl disable lightdm
~~~
* enable the sddm service:
~~~
$ sudo systemctl enable sddm
~~~
* reboot
Window Management
-----------------

34
customization/language-localization.md
View File

@ -14,42 +14,28 @@ Language Localization
How to set up pinyin input in Qubes
-----------------------------------
1. Don't try to install anything in Dom0.
1. In the TemplateVM in which the AppVMs you would like to use pinyin input is based, please install `ibus-pinyin` via the package manager or terminal. If the template is Fedora-based, run `sudo dnf install ibus-pinyin`, if the template is Debian-based, run `sudo apt install ibus-pinyin`
2. Choose a TemplateVM in which you will be using pinyin input on AppVM
instances thereof and open a terminal there.
2. Close and shut down the TemplateVM.
3. Issue `sudo yum install ibus-pinyin` (or, for a Debian template,
`sudo apt-get install ibus-pinyin`).
3. Restart an AppVM which based on the template you installed `ibus-pinyin` and open a terminal.
4. Close and shut down the TemplateVM.
4. Run `ibus-setup`
5. Restart an AppVM which inherits from the template and open a terminal.
6. Issue `ibus-setup`.
7. You will likely get the error message telling you to paste
5. You will likely get the error message telling you to paste the following into your bashrc:
export GTK_IM_MODULE=ibus
export XMODIFIERS=@im=ibus
export QT_IM_MODULE=ibus
into your bashrc.
Copy the text, and then issue: `sudo nano ~/.bashrc`
Paste the text into the bottom of the file and press ctrl-x to save and
close.
Copy the text into your `~/.bashrc` file with your favorite text editor.
You will need to do this on any AppVM in which you wish to use pinyin input.
8. Setup ibus input as you like using the graphical menu (add pinyin or
intelligent pinyin to selections). You can bring the menu back by issuing
`ibus-setup` from a terminal.
6. Set up ibus input as you like using the graphical menu (add pinyin or intelligent pinyin to selections). You can bring the menu back by issuing `ibus-setup` from a terminal.
9. Use super-space as you are used to using to switch between pinyin-unicode and
Latin character input.
7. Set up your shortcut for switching between inputs, by default it is super-space.
10. Whenever you restart one of these AppVMs, you will need to open a terminal
and issue `imsettings-switch ibus` to activate ibus.
If ibus-pinyin is not enabled when you restart one of these AppVMs, open a terminal and run `ibus-setup` to activate ibus again.
For further discussion, see [this thread](https://groups.google.com/forum/#!searchin/qubes-users/languge/qubes-users/VcNPlhdgVQM/iF9PqSzayacJ).
For further discussion, see [this qubes-users thread](https://groups.google.com/forum/#!searchin/qubes-users/languge/qubes-users/VcNPlhdgVQM/iF9PqSzayacJ).

22
customization/windows-template-customization.md
View File

@ -26,7 +26,6 @@ Only keep:
*Note*: Windows search is recommended because it is a nightmare to find something in menus if it is not enabled (it removes the search bar from the start menu, from the explorer, and from the control panel).
*Note*: Unselecting windows media, .Net and Internet Explorer will uninstall these components. on a new install it is generally old versions anyway and it will be quicker to install directly the new versions later.
Services
Windows services
---------------------------
@ -48,7 +47,6 @@ Disable the following services that are not required or have no sense in a VM co
* Volume Shadow Copy (see next note in the performance section)
* Windows defender
* Windows Firewall
* Power
*Notes*: IP Helper is required as it is used by Qubes Agent to configure the IP address.
@ -108,20 +106,24 @@ If you remove these tasks they may be recreated automatically by various windows
* SystemRestore: All
* WindowsBackup: All
Disable hibernation
------------------------------
Power options
-------------
and clean hyberfil.sys
First, enable the "Power" Windows service. Then, set all of the following:
1. Ensure that you disabled the Power service (you may need to reboot so that the Power service is effectively stopped).
* Put the computer to sleep: `Never`
* Turn the display off: `Never`
* Turn off hard disk after: Setting (Minutes): `0`
2. Run a cmd.exe as an administrator:
> powercfg -h off
Turn off hibernation. Open a command prompt (`cmd.exe`) as an administrator,
then execute:
C:\hyberfil.sys should now be deleted
powercfg -h off
The hibernation file (`C:\hyberfil.sys`) should now be deleted.
Manual tasks that can/should be started in the template
===================================
-------------------------------------------------------
* Disk defragmentation

12
customization/xfce.md
View File

@ -12,19 +12,15 @@ redirect_from:
XFCE installation in dom0
========================
**Disclaimer: XFCE isn't fully integrated with Qubes environment, it still requires notable amount of manual configuration after install**
**Disclaimer: The article is obsolete for Qubes OS 3.2 and later.**
Requirements (as of 10/24/2012):
Prior to R3.2, KDE was the default desktop environment in Qubes. Beginning with
R3.2 [XFCE is the new default desktop environment](https://www.qubes-os.org/doc/releases/3.2/release-notes/) and does not require manual installation.
- qubes-core-dom0-2.0.37 (not released yet, possible to build from "master" branch of marmarek's repo)
Installation:
qubes-dom0-update --enablerepo=qubes-dom0-unstable @XFCE
Then you need to create /etc/sysconfig/desktop to stay with KDM, as GDM still starts invalid Xorg startup script:
DISPLAYMANAGER=KDE
sudo qubes-dom0-update @xfce-desktop-qubes
Reboot the system. At system startup, select "Xfce session" in login screen (menu on the right bottom corner of the screen).

44
developers/debugging/automated-tests.md → debugging/automated-tests.md
View File

@ -10,28 +10,22 @@ redirect_from:
Automatic tests
===============
Starting with Qubes R3 we use [python unittest][unittest] to perform automatic
tests of Qubes OS. Regardless of the name, we use it for both [unit
tests](https://en.wikipedia.org/wiki/Unit_tests) and [integration
tests](https://en.wikipedia.org/wiki/Integration_tests). The main purpose is of
course to deliver much more stable releases.
Starting with Qubes R3 we use [python unittest][unittest] to perform automatic tests of Qubes OS.
Despite the name, we use it for both [unit tests](https://en.wikipedia.org/wiki/Unit_tests) and [integration tests](https://en.wikipedia.org/wiki/Integration_tests).
The main purpose is, of course, to deliver much more stable releases.
Integration tests are written with assumption to be called on dedicated
hardware. **Do not run those test on machine where you have important data, you
can loose it**. Especially all the VMs with name starting with `test-` are
removed. All the tests are started from dom0, even when testing some VM
component. Those tests will create new VM(s), run the test, then remove the VM(s).
Integration tests are written with the assumption that they will be called on dedicated hardware.
**Do not run these tests on installations with important data, because you might lose it.**
Since these tests were written with this expectation, all the VMs with a name starting with `test-` on the installation are removed during the process, and all the tests are recklessly started from dom0, even when testing VM components.
Most of the tests are stored in [core-admin
repository](https://github.com/QubesOS/qubes-core-admin/tree/master/tests) in
`tests` directory. To start them you can use standard python unittest runner:
Most of the tests are stored in the [core-admin repository](https://github.com/QubesOS/qubes-core-admin/tree/master/tests) in the `tests` directory.
To start them you can use standard python unittest runner:
python -m unittest -v qubes.tests
Or our custom one:
python -m qubes.tests.run -v
Our test runner can be used mostly the same as the standard one, with some nice
additional features like no need to prefix all the tests with "qubes.tests", or
color output. It is also the only way to run only selected template tests.
Our test runner runs mostly the same as the standard one, but it has some nice additional features like color output and not needing the "qubes.test" prefix.
It also has the ability to run lone selected template tests.
You can use `python -m qubes.tests.run -h` to get usage information:
@ -73,7 +67,7 @@ You can use `python -m qubes.tests.run -h` to get usage information:
MODULE+"/"+CLASS+"/"+FUNCTION. MODULE should omit initial "qubes.tests.".
Example: basic/TC_00_Basic/test_000_create
For example to run only tests for fedora-21 template, you can use `-l` option, then filter the list:
For instance, to run only the tests for the fedora-21 template, you can use the `-l` option, then filter the list:
[user@dom0 ~]$ python -m qubes.tests.run -l | grep fedora-21
network/VmNetworking_fedora-21/test_000_simple_networking
@ -103,24 +97,22 @@ Example test run:
![snapshot-tests2.png](/attachment/wiki/developers/snapshot-tests2.png)
## Adding a new test to core-admin
After you added a new unit test to [core-admin/tests](https://github.com/QubesOS/qubes-core-admin/tree/master/tests)
you have to make sure of two things:
After adding a new unit test to [core-admin/tests](https://github.com/QubesOS/qubes-core-admin/tree/master/tests) you'll have to make sure of two things:
1. The test will be added to the RPM file created by [QubesBuilder](/doc/qubes-builder/)
For this you need to edit [core-admin/tests/Makefile](https://github.com/QubesOS/qubes-core-admin/tree/master/tests/Makefile)
2. The test will be loaded by [core-admin/tests/\_\_init\_\_.py](https://github.com/QubesOS/qubes-core-admin/tree/master/tests/__init__.py)
1. That the test will be added to the RPM file created by [QubesBuilder](/doc/qubes-builder/). For this you need to edit the [core-admin/tests/Makefile](https://github.com/QubesOS/qubes-core-admin/tree/master/tests/Makefile)
2. That the test will be loaded by [core-admin/tests/\_\_init\_\_.py](https://github.com/QubesOS/qubes-core-admin/tree/master/tests/__init__.py)
### Editing the Makefile
Add at the bottom of the file the two lines which will copy your test and its
compiled version to the right directory in the RPM file. I.e. adding `example.py`
To add your tests, you must append these two lines to the end of the makefile, which will copy your test and its compiled version to the right directory in the RPM file.
If your test is `example.py`, the appended lines would be:
cp example.py $(DESTDIR)$(PYTHON_TESTSPATH)
cp example.py[co] $(DESTDIR)$(PYTHON_TESTSPATH)
### Editing \_\_init\_\_.py
Add at the bottom of the file in the method `def load_tests` to the variable
`modname` your test. I.e adding `example.py`.
You'll also need to add your test at the bottom of the \_\_init\_\_.py file, in the method `def load_tests`, in the for loop with `modname`.
Again, given the hypothetical `example.py` test:
~~~python
for modname in (

0
developers/debugging/profiling.md → debugging/profiling.md
View File

78
debugging/safe-remote-ttys.md Normal file
View File

@ -0,0 +1,78 @@
---
layout: doc
title: Safe Remote Dom0 Terminals
permalink: /doc/safe-remote-ttys/
redirect_from:
- /en/doc/safe-remote-ttys/
- /doc/safe-remote-ttys/
---
Safe Remote Dom0 Terminals
==========================
If you do not have working graphics in Dom0, then using a terminal can be quite annoying!
This was the case for the author while trying to debug PCI-passthrough of a machine's primary (only) GPU.
Your first thought might be to just allow network access to Dom0, enable ssh, and connect in remotely.
But, this gravely violates the Qubes security model.
Instead, a better solution is to split the input and output paths of using a terminal.
Use your normal keyboard for input, but have the output go to a remote machine in a unidirectional manner.
To do this, we make use of script(1), qvm-run, and optionally your network transport of choice.
To a different VM
-----------------
As an example of forwarding terminal output to another VM on the same machine:
~~~
$ mkfifo /tmp/foo
$ qvm-run -p some-vm 'xterm -e "cat 0<&5" 5<&0' </tmp/foo >/dev/null 2>&1 &
$ script -f /tmp/foo
~~~
To a different machine
----------------------
In this case over SSH (from a network-connected VM):
~~~
$ mkfifo /tmp/foo
$ qvm-run -p some-vm \
'ssh user@host sh -c "DISPLAY=:0 xterm -e \"cat 0<&5\" 5<&0"' \
</tmp/foo >/dev/null 2>&1 &
$ script -f /tmp/foo
~~~
Note that no data received over SSH is ever treated as terminal input in Dom0.
The input path remains only from your trusted local keyboard.
Multiple terminals
------------------
For multiple terminals, you may find it easier to just use tmux than to try to blindly switch to the correct window.
Terminal size
-------------
It is up to you to ensure the sizes of the local and remote terminal are the same, otherwise things may display incorrectly (especially in interactive programs).
Depending on your shell, the size of your local (blind) terminal is likely stored in the `$LINES` and `$COLUMNS` variables.
~~~
$ echo $COLUMNS $LINES
80 24
~~~
A note on serial consoles
-------------------------
If your machine has a serial console, you may with to use that, but note that a similar split-I/O model should be used to ensure Dom0 integrity.
If you use the serial console as normal (via e.g. getty on ttyX, and logging in as normal), then the machine at the end of the serial cable could compromise your machine!
Ideally, you would take input from your trusted keyboard, and only send the output over the serial cable via e.g. disabling getty and using:
~~~
script -f /dev/ttyS0
~~~
You don't even need to connect the TX pin.

0
developers/debugging/test-bench.md → debugging/test-bench.md
View File

208
debugging/vm-interface.md Normal file
View File

@ -0,0 +1,208 @@
---
layout: doc
title: VM Configuration Interface
permalink: /doc/vm-interface/
redirect_from:
- /en/doc/vm-interface/
- /doc/VMInterface/
- /doc/SystemDoc/VMInterface/
- /wiki/SystemDoc/VMInterface/
---
VM Configuration Interface
==========================
Qubes VM have some settings set by dom0 based on VM settings. There are multiple configuration channels, which includes:
- QubesDB
- XenStore (in Qubes 2, data the same as in QubesDB, keys without leading `/`)
- Qubes RPC (called at VM startup, or when configuration changed)
- GUI protocol
QubesDB
--------------------
### Keys exposed by dom0 to VM ###
- `/qubes-vm-type` - VM type, the same as `type` field in `qvm-prefs`. One of `AppVM`, `ProxyVM`, `NetVM`, `TemplateVM`, `HVM`, `TemplateHVM`
- `/qubes-vm-updatable` - flag whether VM is updatable (whether changes in root.img will survive VM restart). One of `True`, `False`
- `/qubes-vm-persistence` - what data do persist between VM restarts:
- `full` - all disks
- `rw-only` - only `/rw` disk
- `none` - none
- `/qubes-timezone - name of timezone based on dom0 timezone. For example `Europe/Warsaw`
- `/qubes-keyboard` - keyboard layout based on dom0 layout. Its syntax is suitable for `xkbcomp` command (after expanding escape sequences like `\n` or `\t`). This is meant only as some default value, VM can ignore this option and choose its own keyboard layout (this is what keyboard setting from Qubes Manager does). This entry is created as part of gui-daemon initialization (so not available when gui-daemon disabled, or not started yet).
- `/qubes-debug-mode` - flag whether VM have debug mode enabled (qvm-prefs setting). One of `1`, `0`
- `/qubes-service/SERVICE_NAME` - subtree for VM services controlled from dom0 (using qvm-service command or Qubes Manager). One of `1`, `0`. Note that not every service will be listed here, if entry is missing, it means "use VM default". List of currently supported services is in [qvm-service man page](/wiki/Dom0Tools/QvmService)
- `/qubes-netmask` - network mask (only when VM has netvm set); currently hardcoded "255.255.255.0"
- `/qubes-ip - IP address for this VM (only when VM has netvm set)
- `/qubes-gateway` - default gateway IP (only when VM has netvm set); VM should add host route to this address directly via eth0 (or whatever default interface name is)
- `/qubes-primary-dns` - primary DNS address (only when VM has netvm set) (in Qubes 3.2 and later, previously `/qubes-gateway` was used for this purpose)
- `/qubes-secondary-dns` - secondary DNS address (only when VM has netvm set)
- `/qubes-netvm-gateway` - same as `qubes-gateway` in connected VMs (only when VM serves as network backend - ProxyVM and NetVM)
- `/qubes-netvm-netmask` - same as `qubes-netmask` in connected VMs (only when VM serves as network backend - ProxyVM and NetVM)
- `/qubes-netvm-network` - network address (only when VM serves as network backend - ProxyVM and NetVM); can be also calculated from qubes-netvm-gateway and qubes-netvm-netmask
- `/qubes-netvm-primary-dns` - same as `qubes-primary-dns` in connected VMs (only when VM serves as network backend - ProxyVM and NetVM); traffic sent to this IP on port 53 should be redirected to primary DNS server (in Qubes 3.2 and later, previously `/qubes-netvm-gateway` was used for this purpose)
- `/qubes-netvm-secondary-dns` - same as `qubes-secondary-dns` in connected VMs (only when VM serves as network backend - ProxyVM and NetVM); traffic sent to this IP on port 53 should be redirected to secondary DNS server
#### Firewall rules in 3.x ####
QubesDB is also used to configure firewall in ProxyVMs. Rules are stored in
separate key for each target VM. Entries:
- `/qubes-iptables` - control entry - dom0 writing `reload` here signal `qubes-firewall` service to reload rules
- `/qubes-iptables-header` - rules not related to any particular VM, should be applied before domains rules
- `/qubes-iptables-domainrules/NNN` - rules for domain `NNN` (arbitrary number)
in `iptables-save` format. Rules are self-contained - fill `FORWARD` iptables
chain and contains all required matches (source IP address etc), as well as
final default action (`DROP`/`ACCEPT`)
VM after applying rules may signal some error, writing a message to
`/qubes-iptables-error` key. This does not exclude any other way of
communicating problem - like a popup.
#### Firewall rules in 4.x ####
QubesDB is also used to configure firewall in ProxyVMs. Each rule is stored as
a separate entry, grouped on target VM:
- `/qubes-firewall/SOURCE_IP` - base tree under which rules are placed. All
rules there should be applied to filter traffic coming from `SOURCE_IP`. This
can be either IPv4 or IPv6 address.
Dom0 will do an empty write to this top level entry after finishing rules
update, so VM can setup a watch here to trigger rules reload.
- `/qubes-firewall/SOURCE_IP/policy` - default action if no rule matches:
`drop` or `accept`.
- `/qubes-firewall/SOURCE_IP/NNNN` - rule number `NNNN` - decimal number,
padded with zeros. Se below for rule format. All the rules should be
applied in order of rules implied by those numbers. Note that QubesDB
itself does not impose any ordering (you need to sort the rules after
retrieving them). The first rule has number `0000`.
Each rule is a single QubesDB entry, consisting of pairs `key=value` separated
by space. Order of those pairs in a single rule is undefined. QubesDB enforces
a limit on a single entry length - 3072 bytes.
Possible options for a single rule:
- `action`, values: `accept`, `drop`; this is present it every rule
- `dst4`, value: destination IPv4 address with a mask; for example: `192.168.0.0/24`
- `dst6`, value: destination IPv6 address with a mask; for example: `2000::/3`
- `dstname`, value: DNS hostname of destination host
- `proto`, values: `tcp`, `udp`, `icmp`
- `specialtarget`, value: One of predefined target, currently defined values:
- `dns` - such option should match DNS traffic to default DNS server (but
not any DNS server), on both TCP and UDP
- `dstports`, value: destination ports range separated with `-`, valid only
together with `proto=tcp` or `proto=udp`; for example `1-1024`, `80-80`
- `icmptype`, value: numeric (decimal) icmp message type, for example `8` for
echo request, valid only together with `proto=icmp`
- `dpi`, value: Deep Packet Inspection protocol (like: HTTP, SSL, SMB, SSH, SMTP) or the default 'NO' as no DPI, only packet filtering
Rule matches only when all predicates matches. Only one of `dst4`, `dst6`,
`dstname`, `specialtarget` can be used in a single rule.
If tool applying firewall encounter any parse error (unknown option, invalid
value etc), it should drop all the traffic coming from that `SOURCE_IP`,
regardless of properly parsed rules.
Example valid rules:
- `action=accept dst4=8.8.8.8 proto=udp dstports=53-53`
- `action=drop dst6=2a00:1450:4000::/37 proto=tcp`
- `specialtarget=dns action=accept`
- `specialtarget=dns action=drop proto=tcp` - drop DNS queries sent using TCP
- `action=drop`
### Keys set by VM for passing info to dom0 ###
- `memory/meminfo` (**xenstore**) - used memory (updated by qubes-meminfo-writer), input information for qmemman;
- Qubes 3.x format: 6 lines (EOL encoded as `\n`), each in format "FIELD: VALUE kB"; fields: `MemTotal`, `MemFree`, `Buffers`, `Cached`, `SwapTotal`, `SwapFree`; meaning the same as in `/proc/meminfo` in Linux.
- Qubes 4.0+ format: used memory size in the VM, in kbytes
- `/qubes-block-devices` - list of block devices exposed by this VM, each device (subdirectory) should be named in a way that VM can attach the device based on it. Each should contain those entries:
- `desc` - device description (ASCII text)
- `size` - device size in bytes
- `mode` - default connection mode; `r` for read-only, `w` for read-write
- `/qubes-usb-devices` - list of USB devices exposed by this VM, each device (subdirectory) should contain:
- `desc` - device description (ASCII text)
- `usb-ver` - USB version (1, 2 or 3)
Qubes RPC
---------
Services called by dom0 to provide some VM configuration:
- `qubes.SetMonitorLayout` - provide list of monitors, one in a line, each line contains four numbers: `width height X Y width_mm height_mm` (physical dimensions - `width_mm` and `height_mm` - are optional)
- `qubes.WaitForSession` - called to wait for full VM startup
- `qubes.GetAppmenus` - receive appmenus from given VM (template); TODO: describe format here
- `qubes.GetImageRGBA` - receive image/application icon. Protocol:
1. Caller sends name of requested icon. This can be one of:
* `xdgicon:NAME` - search for NAME in standard icons theme
* `-` - get icon data from stdin (the caller), can be prefixed with format name, for example `png:-`
* file name
2. The service responds with image dimensions: width and height as
decimal numbers, separated with space and with EOL marker at the and; then
image data in RGBA format (32 bits per pixel)
- `qubes.SetDateTime` - set VM time, called periodically by dom0 (can be
triggered manually from dom0 by calling `qvm-sync-clock`). The service
receives one line at stdin - time in format of `date -u -Iseconds`, for
example `2015-07-31T16:10:43+0000`.
- `qubes.SetGuiMode` - called in HVM to switch between fullscreen and seamless
GUI mode. The service receives a single word on stdin - either `FULLSCREEN`
or `SEAMLESS`
- `qubes.ResizeDisk` - called to inform that underlying disk was resized.
Name of disk image is passed on standard input (`root`, `private`, `volatile`,
or other). This is used starting with Qubes 4.0.
Other Qrexec services installed by default:
- `qubes.Backup` - store Qubes backup. The service receives location chosen by
the user (one line, terminated by '\n'), the backup archive ([description of
backup format](/doc/BackupEmergencyRestoreV2/))
- `qubes.DetachPciDevice` - service called in reaction to `qvm-pci -d` call on
running VM. The service receives one word - BDF of device to detach. When the
service call ends, the device will be detached
- `qubes.Filecopy` - receive some files from other VM. Files sent in [qfile format](/doc/qfilecopy/)
- `qubes.OpenInVM` - open a file in called VM. Service receives a single file on stdin (in
[qfile format](/doc/qfilecopy/). After a file viewer/editor is terminated, if
the file was modified, can be sent back (just raw content, without any
headers); otherwise service should just terminate without sending anything.
This service is used by both `qvm-open-in-vm` and `qvm-open-in-dvm` tools. When
called in DispVM, service termination will trigger DispVM cleanup.
- `qubes.Restore` - retrieve Qubes backup. The service receives backup location
entered by the user (one line, terminated by '\n'), then should output backup
archive in [qfile format](/doc/qfilecopy/) (core-agent-linux component contains
`tar2qfile` utility to do the conversion
- `qubes.SelectDirectory`, `qubes.SelectFile` - services which should show
file/directory selection dialog and return (to stdout) a single line
containing selected path, or nothing in case of cancellation
- `qubes.SuspendPre` - service called in every VM with PCI device attached just
before system suspend
- `qubes.SuspendPost` - service called in every VM with PCI device attached just
after system resume
- `qubes.SyncNtpClock` - service called to trigger network time synchronization.
Service should synchronize local VM time and terminate when done.
- `qubes.WindowIconUpdater` - service called by VM to send icons of individual
windows. The protocol there is simple one direction stream: VM sends window ID
followed by icon in `qubes.GetImageRGBA` format, then next window ID etc. VM
can send icon for the same window multiple times to replace previous one (for
example for animated icons)
- `qubes.VMShell` - call any command in the VM; the command(s) is passed one per line
Currently Qubes still calls few tools in VM directly, not using service
abstraction. This will change in the future. Those tools are:
- `/usr/lib/qubes/qubes-download-dom0-updates.sh` - script to download updates (or new packages to be installed) for dom0 (`qubes-dom0-update` tool)
- `date -u -Iseconds` - called directly to retrieve time after calling `qubes.SyncNtpClock` service (`qvm-sync-clock` tool)
- `nm-online -x` - called before `qubes.SyncNtpClock` service call by `qvm-sync-clock` tool
- `resize2fs` - called to resize filesystem on /rw partition by `qvm-grow-private` tool
- `gpk-update-viewer` - called by Qubes Manager to display available updates in a TemplateVM
- `systemctl start qubes-update-check.timer` (and similarly stop) - called when enabling/disabling updates checking in given VM (`qubes-update-check` [qvm-service](/doc/qubes-service/))
Additionally automatic tests extensively calls various commands directly in VMs. We do not plan to change that.
GUI protocol
------------
GUI initialization includes passing the whole screen dimensions from dom0 to VM. This will most likely be overwritten by qubes.SetMonitorLayout Qubes RPC call.

2
developers/debugging/windows-debugging.md → debugging/windows-debugging.md
View File

@ -15,7 +15,7 @@ Debugging Windows code can be tricky in a virtualized environment. The guide bel
User-mode debugging is usually straightforward if it can be done on one machine. Just duplicate your normal debugging environment in the VM.
Things get complicated if you need to perform kernel debugging or troubleshoot problems that only manifest on system boot, user logoff or similar. For that you need two Windows VMs: the *host* and the *target*. The *host* will contain [WinDbg](http://msdn.microsoft.com/en-us/library/windows/hardware/ff551063(v=vs.85).aspx) installation, your source code and private symbols. The *target* will run the code being debugged. Both will be linked by virtual serial ports.
Things get complicated if you need to perform kernel debugging or troubleshoot problems that only manifest on system boot, user logoff or similar. For that you need two Windows VMs: the *host* and the *target*. The *host* will contain [WinDbg](https://msdn.microsoft.com/en-us/library/windows/hardware/ff551063(v=vs.85).aspx) installation, your source code and private symbols. The *target* will run the code being debugged. Both will be linked by virtual serial ports.
- First, you need to prepare separate copies of both *target* and *host* VM configuration files with some changes. Copy the files from **/var/lib/qubes/appvms/vmname/vmname.conf** to some convenient location, let's call them **host.conf** and **target.conf**.
- In both copied files add the following line at the end: `serial = 'pty'`. This will make Xen connect VM's serial ports to dom0's ptys.

241
developers/building/building-archlinux-template.md
View File

@ -1,241 +0,0 @@
---
layout: doc
title: Building Archlinux Template
permalink: /doc/building-archlinux-template/
redirect_from:
- /en/doc/building-archlinux-template/
- /doc/BuildingArchlinuxTemplate/
- /wiki/BuildingArchlinuxTemplate/
---
Template building
=================
The archlinux VM is now almost working as a NetVM. Based on qubes-builder code, you could find below how to build it and problem that could arise from template building to using archlinux as a netvm:
Download qubes-builder git code
-------------------------------
Prefer the [marmarek git repository](https://github.com/marmarek/qubes-builder) as it is the most recent one.
~~~
git clone https://github.com/marmarek/qubes-builder.git
~~~
Change your builder.conf
------------------------
Change the following variables / add the following lines (as appropriate):
~~~
BUILDER_PLUGINS += builder-archlinux
GIT_PREFIX := marmarek/qubes-
DISTS_VM += archlinux
~~~
If you don't already have a `builder.conf` in the root of your qubes-builder
directory, a basic Archlinux template build may be achieved by copying
`example-configs/debian.conf` and making the above changes (don't forget to
also comment out any Debian-related `DISTS_VM += ` lines).
Get all required sources
------------------------
~~~
make get-sources
~~~
Note that make get-sources sometimes fails because it didn't download packages that are not used by archlinux such as xfce or kde packages.
You can ignore the repositories that are failing by adding the following line to your builder.conf:
~~~
COMPONENTS:=$(filter-out desktop-linux-kde desktop-linux-xfce,$(COMPONENTS))
~~~
Just don't forget that you need to comment this line again if you want to build the whole Qubes-OS install CD.
Make all required Qubes components
----------------------------------
The first use of the builder can take several hours depending on your bandwidth as it will install an archlinux chroot:
~~~
make qubes-vm
~~~
Now build the template itself
-----------------------------
This can take again several hours, especially the first time you built and archlinux template:
~~~
make linux-template-builder
~~~
Retrieve your template
----------------------
You can now find your template in qubes-src/linux-template-builder/rpm/noarch. Install it in dom0 (just take care as it will replace your current archlinux-x64 template)
* * * * *
Known problems during building or when running the VM
=====================================================
Build fails when fetching qubes-mgmt-salt
-----------------------------------------
The `qubes-mgmt-salt` repo is not currently forked under the marmarek user on
GitHub, to whom the above instructions set the `GIT_PREFIX`. As Archlinux is
not yet supported by mgmt-salt, simply leave it out of the build (when building
the Archlinux template on it's own) by appending the following to your
`builder.conf`:
~~~
BUILDER_PLUGINS := $(filter-out mgmt-salt,$(BUILDER_PLUGINS))
~~~
The nm-applet (network manager icon) fails to start when archlinux is defined as a template-vm:
-----------------------------------------------------------------------------------------------
In fact /etc/dbus-1/system.d/org.freedesktop.NetworkManager.conf does not allow a standard user to run network manager clients. To allow this, one need to change inside \<policy context="default"\>:
~~~
<deny send_destination="org.freedesktop.NetworkManager"/>
~~~
to
~~~
<allow send_destination="org.freedesktop.NetworkManager"/>
~~~
DispVM, Yum proxy and most Qubes addons (thunderbird ...) have not been tested at all.
--------------------------------------------------------------------------------------
The sound does not work in AppVMs and there are messages related to pulse segfault in glibc when running dmesg (FIXED)
----------------------------------------------------------------------------------------------------------------------
This is apparently a bug in Archlinux between glibc and pulseaudio package 4.0-6. The packages pulseaudio-4.0-2 and libpulse-4.0-2 are known to work and can be downloaded and reinstalled manually.
Error when building the gui-agent-linux with pulsecore error
------------------------------------------------------------
~~~
module-vchan-sink.c:62:34: fatal error: pulsecore/core-error.h: No such file or directory
#include <pulsecore/core-error.h>
~~~
This error is because Archlinux update package too quickly. Probably, a new version of pulseaudio has been released, but the qubes team has not imported the new development headers yet.
You can create fake new headers just by copying the old headers:
~~~
cd qubes-builder/qubes-src/gui-agent-linux/pulse
ls
cp -r pulsecore-#lastversion pulsecore-#archlinuxversion
~~~
You can check the current archlinux pulseaudio version like this:
~~~
sudo chroot chroot-archlinux/ pacman -Qi pulseaudio
~~~
chroot-archlinux/dev/pts has not been unmounted
-----------------------------------------------
This is a known problem when there are errors during building. Check what is mounted using the command mount (with no parameters). Just unmount what you can (or reboot your vm if you are too lazy :) )
Known problems in Qubes R2-B2
=============================
xen-vmm-vm fail to build with a PARSETUPLE related error (FIXED):
-----------------------------------------------------------------
Commenting out "\#define HAVE\_ATTRIBUTE\_FORMAT\_PARSETUPLE" from chroot\_archlinux/usr/include/python2.7/pyconfig.h fixes the problem, but it isn't the right solution [1]...
A better fix is planned for the next python release (the bug is considered release blocking), and will be updated in archlinux chroot as soon as available.
[1] [http://bugs.python.org/issue17547](http://bugs.python.org/issue17547)
The boot process fails without visible errors in the logs, but spawn a recovery shell
-------------------------------------------------------------------------------------
The problem is a new conflict between systemd and the old sysvinit style. To fix this, you can change the master xen template in dom0 to remove sysvinit remains: Edit **INSIDE DOM0** /usr/share/qubes/vm-template.conf, and change the variable 'extra' that contains the kernel variables: from:
~~~
extra="ro nomodeset 3 console=hvc0 rd_NO_PLYMOUTH {kernelopts}"
~~~
to:
~~~
extra="ro nomodeset console=hvc0 rd_NO_PLYMOUTH {kernelopts}"
~~~
Qubes-OS is now using different xenstore variable names, which makes to archlinux VM failing to boot
----------------------------------------------------------------------------------------------------
Apply the following fix in the template to revert the variable name to the old Qubes version.
You can edit the template the following way:
~~~
sudo mkdir /mnt/vm
sudo mount /var/lib/qubes/vm-templates/archlinux-x64/root.img /mnt/vm
sudo chroot /mnt/vm
~~~
Then apply the fix:
~~~
sudo sed 's:qubes-keyboard:qubes_keyboard:g' -i /etc/X11/xinit/xinitrc.d/qubes-keymap.sh
sudo sed 's:qubes-netvm-domid:qubes_netvm_domid:g' -i /etc/NetworkManager/dispatcher.d/30-qubes-external-ip
sudo sed 's:qubes-netvm-external-ip:qubes_netvm_external_ip:g' -i /etc/NetworkManager/dispatcher.d/30-qubes-external-ip
sudo sed 's:qubes-netvm-network:qubes_netvm_network:g' -i /usr/lib/qubes/init/network-proxy-setup.sh
sudo sed 's:qubes-netvm-gateway:qubes_netvm_gateway:g' -i /usr/lib/qubes/init/network-proxy-setup.sh
sudo sed 's:qubes-netvm-netmask:qubes_netvm_netmask:g' -i /usr/lib/qubes/init/network-proxy-setup.sh
sudo sed 's:qubes-netvm-secondary-dns:qubes_netvm_secondary_dns:g' -i /usr/lib/qubes/init/network-proxy-setup.sh
sudo sed 's:qubes-vm-type:qubes_vm_type:g' -i /usr/lib/qubes/init/qubes-sysinit.sh
sudo sed 's:qubes-ip:qubes_ip:g' -i /usr/lib/qubes/setup-ip
sudo sed 's:qubes-netmask:qubes_netmask:g' -i /usr/lib/qubes/setup-ip
sudo sed 's:qubes-gateway:qubes_gateway:g' -i /usr/lib/qubes/setup-ip
sudo sed 's:qubes-secondary-dns:qubes_secondary_dns:g' -i /usr/lib/qubes/setup-ip
sudo sed 's:qubes-netvm-network:qubes_netvm_network:g' -i /usr/lib/qubes/setup-ip
sudo sed 's:qubes-netvm-gateway:qubes_netvm_gateway:g' -i /usr/lib/qubes/setup-ip
sudo sed 's:qubes-netvm-netmask:qubes_netvm_netmask:g' -i /usr/lib/qubes/setup-ip
sudo sed 's:qubes-netvm-secondary-dns:qubes_netvm_secondary_dns:g' -i /usr/lib/qubes/setup-ip
sudo sed 's:qubes-iptables-domainrules:qubes_iptables_domainrules:g' -i /usr/bin/qubes-firewall
sudo sed 's:qubes-iptables-header:qubes_iptables_header:g' -i /usr/bin/qubes-firewall
sudo sed 's:qubes-iptables-error:qubes_iptables_error:g' -i /usr/bin/qubes-firewall
sudo sed 's:qubes-iptables:qubes_iptables:g' -i /usr/bin/qubes-firewall
sudo sed 's:qubes-netvm-domid:qubes_netvm_domid:g' -i /usr/bin/qubes-netwatcher
sudo sed 's:qubes-netvm-external-ip:qubes_netvm_external_ip:g' -i /usr/bin/qubes-netwatcher
sudo sed 's:qubes-vm-updateable:qubes_vm_updateable:g' -i /usr/lib/qubes/qubes_trigger_sync_appmenus.sh
sudo sed 's:qubes-vm-type:qubes_vm_type:g' -i /usr/bin/qubes-session
sudo sed 's:qubes-vm-updateable:qubes_vm_updateable:g' -i /usr/bin/qubes-session
~~~
Do not forgot to:
~~~
umount /mnt/vm
~~~
Installing the template in dom0 fails because of a missing dependency (qubes-core-dom0-linux)
---------------------------------------------------------------------------------------------
Again you built a template based on a recent Qubes API which has not been released yet. So skip the dependency for now:
~~~
sudo rpm -U --nodeps yourpackage.rpm
~~~

57
developers/building/kde-dom0.md
View File

@ -1,57 +0,0 @@
---
layout: doc
title: KDE dom0
permalink: /doc/kde-dom0/
redirect_from:
- /en/doc/kde-dom0/
- /doc/KdeDom0/
- /wiki/KdeDom0/
---
Qubes-customized KDE packages for Dom0
======================================
The Qubes kde-dom0 project (see [Source Code](/doc/source-code/)) contains the source code needed for building the customized KDE packages for use in Qubes Dom0 (the user desktop). The packages are based on Fedora 12 KDE packages, but are heavily slimmed down (Qubes doesn't need lots of KDE functionality in Dom0, such as most of the KDE apps). In the near future those KDE packages will also get some Qubes specific extensions, such as coloured titlebars/frames nicely integrated into the KDE Window Manager. And, of course, custom themes, e.g. for KDM :)
Getting the sources
-------------------
~~~
git clone git://qubes-os.org/mainstream/kde-dom0.git kde-dom0
~~~
Building the packages
---------------------
It's best to use Fedora 12 or 13 as a development system.
First, you should download and verify the original KDE sources (not part of the kde-dom0 repository):
~~~
make get-sources verify-sources
~~~
Now, check if you have all the required build dependencies:
~~~
make prep
~~~
Install any required packages that `make` might have complained about. Then you're ready to build the rpms (you might want to adjust the release of each rpm package by editing the `rel` variable at the beginning of each `.spec` file):
~~~
make rpms
~~~
**Note:** The `kdebase-*` packages build process requires corresponding `kdelibs-devel` package to be installed first. If your build system is based on Fedora 12/13, and if the `kdelibs-devel` package exist in Fedora repo that is based the same KDE software version (e.g. 4.4.3) as the KDE packages you're building (see the `version` file), than you should be able to use the Fedora package:
~~~
yum install kdelibs-devel-{version}
~~~
If not, then you should build your `kdelibs-devel` first (`cd kdelibs-devel && make rpms`), then install it on your build system, and then you can build all the rest (`make rpms`).
Installing KDE packages from Qubes repository
---------------------------------------------
TODO

34
developers/building/pvusb.md
View File

@ -1,34 +0,0 @@
---
layout: doc
title: PVUSB
permalink: /doc/pvusb/
---
USB Pass through: USBVM
-----------------------
**WARNING:** This is experimental and very broken.
Source: [https://groups.google.com/d/msg/qubes-devel/4AKulABh2Jc/\_R7SRSC4peYJ](https://groups.google.com/d/msg/qubes-devel/4AKulABh2Jc/_R7SRSC4peYJ)
You'll need the patch tagged abb\_e58b432 from [git://github.com/grwl/qubes-core.git](git://github.com/grwl/qubes-core.git).
The rest is in RPMs, yes. I roughly follow this procedure to have pvusb on Qubes 1.0:
- rebuild kernel, core, and xen from marmarek's repo (devel-3.4 branch for kernel),
- make dedicated usbvm domain, passthrough USB controller PCI devices there
- in usbvm: "rpm -Uhv qubes-core-vm-2.1.1-1.fc17.x86\_64.rpm xen-libs-2000:4.1.3-18.fc17.x86\_64.rpm xen-qubes-vm-essentials-2000:4.1.3-18.fc17.x86\_64.rpm"
- in appvm where you want to attach the device to: "rpm -Uhv qubes-core-vm-2.1.1-1.fc17.x86\_64.rpm"
- in dom0 I think the following packages need to be updated, don't have exact list now.qubes-core-dom0 is actually important, the rest are dependencies:
> kernel-qubes-vm-3.4.18-1.pvops.qubes.x86\_64.rpm
> qubes-core-dom0-2.1.1-1.fc13.x86\_64.rpm
> xen-4.1.3-18.fc13.x86\_64.rpm
> xen-hvm-4.1.3gui2.0.9-18.fc13.x86\_64.rpm
> xen-hypervisor-4.1.3-18.fc13.x86\_64.rpm
> xen-libs-4.1.3-18.fc13.x86\_64.rpm
> xen-licenses-4.1.3-18.fc13.x86\_64.rpm
> xen-runtime-4.1.3-18.fc13.x86\_64.rpm
- plug or replug some USB device -- it will be picked up by usbvm, and in dom0 it will appear in the output of qvm-usb

34
developers/contributing.md
View File

@ -1,34 +0,0 @@
---
layout: doc
title: Contributing
permalink: /doc/contributing/
redirect_from:
- /en/doc/contributing/
- /doc/ContributingHowto/
- /wiki/ContributingHowto/
---
How can I contribute to the Qubes Project?
==========================================
Ok, so you think Qubes Project is cool and you would like to contribute? You are very welcome!
First you should decide what you are interested in (and good in). The Qubes project would welcome contributions in various areas:
- Testing and [bug reporting](/doc/reporting-bugs/)
- Code audit (e.g. gui-daemon)
- New features
- Artwork (plymouth themes, KDM themes, installer themes, wallpapers, etc)
- [Documentation](/doc/doc-guidelines)
Perhaps the best starting point is to have a look at the [issues](https://github.com/QubesOS/qubes-issues/issues) to see what are the most urgent tasks to do.
Before you engage in some longer activity, e.g. implementing a new feature, it's always good to contact us first (preferably via the [qubes-devel](/doc/mailing-lists/) list), to avoid a situation when two or more independent people would work on the same feature at the same time, doubling each other's work. When you contact us and devote to a particular task, we will create a ticket for this task with info who is working on this feature and what is the expected date of some early code to be posted.
When you are ready to start some work, read how to [access Qubes sources and send patches](/doc/source-code/).
You can also contribute in other areas than coding and testing, e.g. by providing mirrors for Qubes rpm repositories, providing feedback about what features you would like to have in Qubes, or perhaps even preparing some cool You Tube videos that would demonstrate some Qubes' features. You are always encouraged to discuss your ideas on qubes-devel.
You should be aware, however, that we will not blindly accept all the contributions! We will accept only the quality ones. Open source doesn't mean lack of quality control! If we reject your patch, please do not get discouraged, try fixing it so that it adheres to the required standards. We will only reject contributions in the good faith, to make Qubes a better OS.
Thanks, [The Qubes Project team](/team).

129
developers/debugging/vm-interface.md
View File

@ -1,129 +0,0 @@
---
layout: doc
title: VM Configuration Interface
permalink: /doc/vm-interface/
redirect_from:
- /en/doc/vm-interface/
- /doc/VMInterface/
- /doc/SystemDoc/VMInterface/
- /wiki/SystemDoc/VMInterface/
---
VM Configuration Interface
==========================
Qubes VM have some settings set by dom0 based on VM settings. There are multiple configuration channels, which includes:
- XenStore
- QubesDB - replacing most of xenstore (in R3 only)
- Qubes RPC (called at VM startup, or when configuration changed)
- GUI protocol
xenstore
--------
Keys exposed by dom0 to VM (only Qubes specific included):
- `qubes-vm-type` - VM type, the same as `type` field in `qvm-prefs`. One of `AppVM`, `ProxyVM`, `NetVM`, `TemplateVM`, `HVM`, `TemplateHVM`
- `qubes-vm-updatable` - flag whether VM is updatable (whether changes in root.img will survive VM restart). One of `True`, `False`
- `qubes-timezone - name of timezone based on dom0 timezone. For example `Europe/Warsaw`
- `qubes-keyboard` - keyboard layout based on dom0 layout. Its syntax is suitable for `xkbcomp` command (after expanding escape sequences like `\n` or `\t`). This is meant only as some default value, VM can ignore this option and choose its own keyboard layout (this is what keyboard setting from Qubes Manager does). This entry is created as part of gui-daemon initialization (so not available when gui-daemon disabled, or not started yet).
- `qubes-debug-mode` - flag whether VM have debug mode enabled (qvm-prefs setting). One of `1`, `0`
- `qubes-service/SERVICE_NAME` - subtree for VM services controlled from dom0 (using qvm-service command or Qubes Manager). One of `1`, `0`. Note that not every service will be listed here, if entry is missing, it means "use VM default". List of currently supported services is in [qvm-service man page](/wiki/Dom0Tools/QvmService)
- `qubes-netmask` - network mask (only when VM has netvm set); currently hardcoded "255.255.255.0"
- \`qubes-ip - IP address for this VM (only when VM has netvm set)
- `qubes-gateway` - default gateway IP and primary DNS address (only when VM has netvm set); VM should add host route to this address directly via eth0 (or whatever default interface name is)
- `qubes-secondary-dns` - secondary DNS address (only when VM has netvm set)
- `qubes-netvm-gateway` - same as `qubes-gateway` in connected VMs (only when VM serves as network backend - ProxyVM and NetVM); because this is also set as primary DNS in connected VMs, traffic sent to this IP on port 53 should be redirected to DNS server
- `qubes-netvm-netmask` - same as `qubes-netmask` in connected VMs (only when VM serves as network backend - ProxyVM and NetVM)
- `qubes-netvm-network` - network address (only when VM serves as network backend - ProxyVM and NetVM); can be also calculated from qubes-netvm-gateway and qubes-netvm-netmask
- `qubes-netvm-secondary-dns` - same as `qubes-secondary-dns` in connected VMs (only when VM serves as network backend - ProxyVM and NetVM); traffic sent to this IP on port 53 should be redirected to secondary DNS server
Keys set by VM for passing info to dom0:
- `memory/meminfo` - used memory (updated by qubes-meminfo-writer), input information for qmemman; Format: 6 lines (EOL encoded as `\n`), each in format "FIELD: VALUE kB"; fields: `MemTotal`, `MemFree`, `Buffers`, `Cached`, `SwapTotal`, `SwapFree`; meaning the same as in `/proc/meminfo` in Linux
- `qubes-block-devices` - list of block devices exposed by this VM, each device (subdirectory) should be named in a way that VM can attach the device based on it. Each should contain those entries:
- `desc` - device description (ASCII text)
- `size` - device size in bytes
- `mode` - default connection mode; `r` for read-only, `w` for read-write
- `qubes-usb-devices` - list of USB devices exposed by this VM, each device (subdirectory) should contain:
- `desc` - device description (ASCII text)
- `usb-ver` - USB version (1, 2 or 3)
Qubes RPC
---------
Services called by dom0 to provide some VM configuration:
- `qubes.SetMonitorLayout` - provide list of monitors, one in a line, each line contains four numbers: `width height X Y`
- `qubes.WaitForSession` - called to wait for full VM startup
- `qubes.GetAppmenus` - receive appmenus from given VM (template); TODO: describe format here
- `qubes.GetImageRGBA` - receive image/application icon. Protocol:
1. Caller sends name of requested icon. This can be one of:
* `xdgicon:NAME` - search for NAME in standard icons theme
* `-` - get icon data from stdin (the caller), can be prefixed with format name, for example `png:-`
* file name
2. The service responds with image dimensions: width and height as
decimal numbers, separated with space and with EOL marker at the and; then
image data in RGBA format (32 bits per pixel)
- `qubes.SetDateTime` - set VM time, called periodically by dom0 (can be
triggered manually from dom0 by calling `qvm-sync-clock`). The service
receives one line at stdin - time in format of `date -u -Iseconds`, for
example `2015-07-31T16:10:43+0000`.
- `qubes.SetGuiMode` - called in HVM to switch between fullscreen and seamless
GUI mode. The service receives a single word on stdin - either `FULLSCREEN`
or `SEAMLESS`
Other Qrexec services installed by default:
- `qubes.Backup` - store Qubes backup. The service receives location chosen by
the user (one line, terminated by '\n'), the backup archive ([description of
backup format](/doc/BackupEmergencyRestoreV2/))
- `qubes.DetachPciDevice` - service called in reaction to `qvm-pci -d` call on
running VM. The service receives one word - BDF of device to detach. When the
service call ends, the device will be detached
- `qubes.Filecopy` - receive some files from other VM. Files sent in [qfile format](/doc/qfilecopy/)
- `qubes.OpenInVM` - open a file in called VM. Service receives a single file on stdin (in
[qfile format](/doc/qfilecopy/). After a file viewer/editor is terminated, if
the file was modified, can be sent back (just raw content, without any
headers); otherwise service should just terminate without sending anything.
This service is used by both `qvm-open-in-vm` and `qvm-open-in-dvm` tools. When
called in DispVM, service termination will trigger DispVM cleanup.
- `qubes.Restore` - retrieve Qubes backup. The service receives backup location
entered by the user (one line, terminated by '\n'), then should output backup
archive in [qfile format](/doc/qfilecopy/) (core-agent-linux component contains
`tar2qfile` utility to do the conversion
- `qubes.SelectDirectory`, `qubes.SelectFile` - services which should show
file/directory selection dialog and return (to stdout) a single line
containing selected path, or nothing in case of cancellation
- `qubes.SuspendPre` - service called in every VM with PCI device attached just
before system suspend
- `qubes.SuspendPost` - service called in every VM with PCI device attached just
after system resume
- `qubes.SyncNtpClock` - service called to trigger network time synchronization.
Service should synchronize local VM time and terminate when done.
- `qubes.WindowIconUpdater` - service called by VM to send icons of individual
windows. The protocol there is simple one direction stream: VM sends window ID
followed by icon in `qubes.GetImageRGBA` format, then next window ID etc. VM
can send icon for the same window multiple times to replace previous one (for
example for animated icons)
- `qubes.VMShell` - call any command in the VM; the command(s) is passed one per line
Currently Qubes still calls few tools in VM directly, not using service
abstraction. This will change in the future. Those tools are:
- `/usr/lib/qubes/qubes-download-dom0-updates.sh` - script to download updates (or new packages to be installed) for dom0 (`qubes-dom0-update` tool)
- `date -u -Iseconds` - called directly to retrieve time after calling `qubes.SyncNtpClock` service (`qvm-sync-clock` tool)
- `nm-online -x` - called before `qubes.SyncNtpClock` service call by `qvm-sync-clock` tool
- `resize2fs` - called to resize filesystem on /rw partition by `qvm-grow-private` tool
- `gpk-update-viewer` - called by Qubes Manager to display available updates in a TemplateVM
- `systemctl start qubes-update-check.timer` (and similarly stop) - called when enabling/disabling updates checking in given VM (`qubes-update-check` [qvm-service](/doc/qubes-service/))
Additionally automatic tests extensively calls various commands directly in VMs. We do not plan to change that.
GUI protocol
------------
GUI initialization includes passing the whole screen dimensions from dom0 to VM. This will most likely be overwritten by qubes.SetMonitorLayout Qubes RPC call.

29
developers/devel-books.md
View File

@ -1,29 +0,0 @@
---
layout: doc
title: Developer Books
permalink: /doc/devel-books/
redirect_from:
- /en/doc/devel-books/
- /doc/DevelBooks/
- /wiki/DevelBooks/
---
Below is a list of various books that might be useful in learning some basics needed for Qubes development.
- A must-read about Xen internals:
- [http://www.amazon.com/Definitive-Guide-Xen-Hypervisor/dp/013234971X](http://www.amazon.com/Definitive-Guide-Xen-Hypervisor/dp/013234971X)
- Some good books about Linux kernel:
- [http://www.amazon.com/Linux-Kernel-Development-Robert-Love/dp/0672327201](http://www.amazon.com/Linux-Kernel-Development-Robert-Love/dp/0672327201)
- [http://www.amazon.com/Linux-Device-Drivers-Jonathan-Corbet/dp/0596005903](http://www.amazon.com/Linux-Device-Drivers-Jonathan-Corbet/dp/0596005903)
- Solid intro into Trusted Computing by David Grawrock (original Intel architect for TXT):
- [http://www.amazon.com/Dynamics-Trusted-Platform-Buildin-Grawrock/dp/1934053082](http://www.amazon.com/Dynamics-Trusted-Platform-Buildin-Grawrock/dp/1934053082)
- Good book about GIT:
- [http://progit.org/book/](http://progit.org/book/)
- Useful books about Python:
- [http://www.qtrac.eu/py3book.html](http://www.qtrac.eu/py3book.html) (Note that Qubes management tools are written in Python 2.6, but this book is still a very good choice)
- [http://www.qtrac.eu/pyqtbook.html](http://www.qtrac.eu/pyqtbook.html)

47
developers/devel-faq.md
View File

@ -1,47 +0,0 @@
---
layout: doc
title: Developers' FAQ
permalink: /doc/devel-faq/
redirect_from:
- /en/doc/devel-faq/
- /doc/DevelFaq/
- /wiki/DevelFaq/
---
Qubes Developers' FAQ
=====================
Q: Why does dom0 need to be 64-bit?
-----------------------------------
Since 2013 [Xen has not supported 32-bit x86 architecture](http://wiki.xenproject.org/wiki/Xen_Project_Release_Features) and Intel VT-d, which Qubes uses to isolate devices and drivers, is available on Intel 64-bit processors only.
In addition, often it is more difficult to exploit a bug on the x64 Linux than it is on x86 Linux (e.g. ASLR is sometimes harder to get around). While we designed Qubes with the emphasis on limiting any potential attack vectors in the first place, still we realize that some of the code running in Dom0, e.g. our GUI daemon or xen-store daemon, even though it is very simple code, might contain some bugs. Plus currently we haven't implemented a separate storage domain, so also the disk backends are in Dom0 and are "reachable" from the VMs, which adds up to the potential attack surface. So, having faced a choice between 32-bit and 64-bit OS for Dom0, it was almost a no-brainer, as the 64-bit option provides some (little perhaps, but still) more protection against some classes of attacks, and at the same time does not have any disadvantages (except that it requires a 64-bit processor, but all systems on which it makes sense to run Qubes, e.g. that have at least 3-4GB memory, they do have 64-bit CPUs anyway).
Q: Why do you use KDE in Dom0? What is the roadmap for Gnome support?
---------------------------------------------------------------------
There are a few things that are KDE-specific, but generally it should not be a big problem to also add Gnome support to Qubes (in Dom0 of course). Those KDE-specific things are:
- Qubes requires KDM (KDE Login Manager), rather than GDM, for the very simple reason that GDM doesn't obey standards and start `/usr/bin/Xorg` instead of `/usr/bin/X`. This is important for Qubes, because we need to load a special "X wrapper" (to make it possible to use Linux usermode shared memory to access Xen shared memory pages in our App Viewers -- see the sources [here](https://github.com/QubesOS/qubes-gui-daemon/tree/master/shmoverride)). So, Qubes makes the `/usr/bin/X` to be a symlink to the Qubes X Wrapper, which, in turn, executes the `/usr/bin/Xorg`. This works well with KDM (and would probably also work with other X login managers), but not with GDM. If somebody succeeded in makeing GDM to execute `/usr/bin/X` instead of `/usr/bin/Xorg`, we would love to hear about it!
- We maintain a special [repository](/doc/kde-dom0/) for building packages specifically for Qubes Dom0.
- We've patched the KDE's Window Manager (specifically [one of the decoration plugins](https://github.com/QubesOS/qubes-desktop-linux-kde/tree/master/plastik-for-qubes)) to draw window decorations in the color of the specific AppVM's label.
If you're interested in porting GNOME for Qubes Dom0 use, let us know -- we will most likely welcome patches in this area.
Q: What is the recommended build environment?
---------------------------------------------
Any rpm-based, 64-bit. Preferred Fedora.
Q: How to build Qubes from sources?
-----------------------------------
See [the instruction](/doc/qubes-builder/)
Q: How do I submit a patch?
---------------------------
See [Qubes Source Code Repositories](/doc/source-code/).

59
developers/fundamentals/networking.md
View File

@ -1,59 +0,0 @@
---
layout: doc
title: Networking
permalink: /doc/networking/
redirect_from:
- /doc/qubes-net/
- /en/doc/qubes-net/
- /doc/QubesNet/
- /wiki/QubesNet/
---
VM network in Qubes
===================
Overall description
-------------------
In Qubes, the standard Xen networking is used, based on backend driver in the driver domain and frontend drivers in VMs. In order to eliminate layer 2 attacks originating from a compromised VM, routed networking is used instead of the default bridging of `vif` devices. The default *vif-route* script had some deficiencies (requires `eth0` device to be up, and sets some redundant iptables rules), therefore the custom *vif-route-qubes* script is used.
The IP address of `eth0` interface in AppVM, as well as two IP addresses to be used as nameservers (`DNS1` and `DNS2`), are passed via xenstore to AppVM during its boot (thus, there is no need for DHCP daemon in the network driver domain). `DNS1` and `DNS2` are private addresses; whenever an interface is brought up in the network driver domain, the */usr/lib/qubes/qubes\_setup\_dnat\_to\_ns* script sets up the DNAT iptables rules translating `DNS1` and `DNS2` to the newly learned real dns servers. This way AppVM networking configuration does not need to be changed when configuration in the network driver domain changes (e.g. user switches to a different WLAN). Moreover, in the network driver domain, there is no DNS server either, and consequently there are no ports open to the VMs.
Routing tables examples
-----------------------
VM routing table is simple:
||
|Destination|Gateway|Genmask|Flags|Metric|Ref|Use|Iface|
|0.0.0.0|0.0.0.0|0.0.0.0|U|0|0|0|eth0|
Network driver domain routing table is a bit longer:
||
|Destination|Gateway|Genmask|Flags|Metric|Ref|Use|Iface|
|10.2.0.16|0.0.0.0|255.255.255.255|UH|0|0|0|vif4.0|
|10.2.0.7|0.0.0.0|255.255.255.255|UH|0|0|0|vif10.0|
|10.2.0.9|0.0.0.0|255.255.255.255|UH|0|0|0|vif9.0|
|10.2.0.8|0.0.0.0|255.255.255.255|UH|0|0|0|vif8.0|
|10.2.0.12|0.0.0.0|255.255.255.255|UH|0|0|0|vif3.0|
|192.168.0.0|0.0.0.0|255.255.255.0|U|1|0|0|eth0|
|0.0.0.0|192.168.0.1|0.0.0.0|UG|0|0|0|eth0|
Location of the network driver domain
-------------------------------------
Traditionally, the network driver domain is dom0. This design means that a lot of code (networking stack, drivers) running in the all-powerful domain is exposed to potential attack. Although it is supported (one can execute *qvm-set-default-netvm dom0*), it is strongly discouraged.
Instead, a dedicated domain called `netvm` should be used. In order to activate it, one needs to install the `qubes-servicevm-netvm` rpm package, and enable it via command *qvm-set-default-netvm netvm*. This domain will be assigned all PCI devices that are network cards. One can interact with the *Networkmanager* daemon running in `netvm` in the same way as with any other VM GUI application (with one detail that *nm-applet* requires a system tray, thus one needs to start it via "KDEMenu-\>Applications-\>Netvm-\>Show Tray").
Note that in order to isolate `netvm` properly, the platform must support VTd and it must be activated. Otherwise, compromised `netvm` can use DMA to get control over dom0 and even the hypervisor.
When using `netvm`, there is no network connectivity in dom0. This is the desired configuration - it eliminates all network-bourne attacks. Observe that dom0 is meant to be used for administrative tasks only, and (with one exception) they do not need network. Anything not related to system administration should be done in one of AppVMs.
The above-mentioned exception is the system packages upgrade. Again, one must not install random applications in dom0, but there is a need to e.g. upgrade existing packages. While one may argue that the new packages could be downloaded on a separate machine and copied to dom0 via a pendrive, this solution has its own problems. Therefore, the advised method to temporarily grant network connectivity to dom0 is to use *qvm-dom0-network-via-netvm up* command. It will pause all running VMs (so that they can do no harm to dom0) and connect dom0 to netvm network just like another AppVM. Having completed package upgrade, execute *qvm-dom0-network-via-netvm down* to revert to the normal state.
Firewall and Proxy VMs
----------------------
TODO

21
developers/license.md
View File

@ -1,21 +0,0 @@
---
layout: doc
title: License
permalink: /doc/license/
redirect_from:
- /en/doc/license/
- /doc/QubesLicensing/
- /wiki/QubesLicensing/
---
Qubes OS License
================
Qubes is a compilation of software packages, each under its own license. The compilation is made available under the GNU General Public License version 2.
The full text of the GPL v2 license can be found [here](http://www.gnu.org/licenses/gpl-2.0.html).
Note on rights to double-licensing of the Qubes code
----------------------------------------------------
Invisible Things Lab (ITL), who has funded and run the Qubes project since the beginning, and who has contributed majority of Qubes-specific code (specifically: `core-*`, `gui-*`, and `qubes-*` repositories) would like to have a right to redistribute parts of this code under proprietary licenses. This is especially important for Qubes R3 and later, where the new architecture allows the creation of many editions of Qubes, using different hypervisors, some of which might not be open source. That's why we ask every developer who contributes code to Qubes project to grant ITL permission to reuse the code under a different license, and to express this consent by including the [standard signed-off line](http://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/Documentation/SubmittingPatches?id=HEAD#n358) in the commit.

81
developers/reporting-bugs.md
View File

@ -1,81 +0,0 @@
---
layout: doc
title: Reporting Bugs
permalink: /doc/reporting-bugs/
redirect_from:
- /en/doc/reporting-bugs/
- /doc/BugReportingGuide/
- /wiki/BugReportingGuide/
---
Bug Reporting Guide
===================
One of the most important contribution task is reporting the bugs you have found.
Asking a Question
-----------------
Before you ask, do some searching and reading. Check [the
docs](https://www.qubes-os.org/doc/), Google, GitHub, and StackOverflow. If
your question is something that has been answered many times before, the
project maintainers might be tired of repeating themselves.
Whenever possible, ask your question on the Qubes mailing list which is
located [here](https://groups.google.com/forum/#!forum/qubes-users). This
allows anyone to answer and makes the answer available for the next person
with the same question.
Submitting a Bug Report (or "Issue")
------------------------------------
On GitHub, "Bug Reports" are called "Issues."
Issues can be submitted to the Qubes project located at
[https://github.com/QubesOS/qubes-issues](https://github.com/QubesOS/qubes-issues).
### Has This Been Asked Before?
Before you submit a bug report, you should search existing issues. Be sure
to check both currently open issues, as well as issues that are already
closed. 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. 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.
### Nope, Hasn't Been Asked Before
If you can't find anything in the existing issues, don't be shy about
filing a new one.
You should be sure to include the version the project, as well as versions
of related software. For example, be sure to include the Qubes release
version (R2, R3) and specific version numbers of package causing problems
(if known).
If your issue is related to hardware, provide as many details as possible
about the hardware, which could include using commandline tools such as
`lspci`.
Project maintainers really appreciate thorough explanations. It usually
helps them address the problem more quickly, so everyone wins!
Improving the Code
------------------
The best way is to "Fork" the repo on GitHub. This will create a copy of
the repo on your GitHub account.
Before you set out to improve the code, you should have a focused idea in
mind of what you want to do.
Each commit should do one thing, and each PR should be one specific
improvement. Each PR needs to be signed.
* [How can I contribute to the Qubes Project?](https://www.qubes-os.org/doc/ContributingHowto/)
* [Developer Documentation](https://www.qubes-os.org/doc/)
* [Package Release Workflow](https://github.com/QubesOS/qubes-builder/blob/master/doc/ReleaseManagerWorkflow.md)

52
developers/system-doc.md
View File

@ -1,52 +0,0 @@
---
layout: doc
title: System Documentation
permalink: /doc/system-doc/
redirect_from:
- /en/doc/system-doc/
- /doc/SystemDoc/
- /wiki/SystemDoc/
---
System Documentation for Developers
===================================
Fundamentals
------------
* [Qubes OS Architecture Overview](/doc/architecture/)
* [Qubes OS Architecture Spec v0.3 [PDF]](/attachment/wiki/QubesArchitecture/arch-spec-0.3.pdf)
(The original 2009 document that started this all...)
* [Security-critical elements of Qubes OS](/doc/security-critical-code/)
* [Qrexec: command execution in VMs](/doc/qrexec3/)
* [Qubes GUI virtualization protocol](/doc/gui/)
* [Networking in Qubes](/doc/networking/)
* [Implementation of template sharing and updating](/doc/template-implementation/)
Services
--------
* [Inter-domain file copying](/doc/qfilecopy/) (deprecates [`qfileexchgd`](/doc/qfileexchgd/))
* [Dynamic memory management in Qubes](/doc/qmemman/)
* [Implementation of DisposableVMs](/doc/dvm-impl/)
* [Article about disposable VMs](http://theinvisiblethings.blogspot.com/2010/06/disposable-vms.html)
* [Dom0 secure update mechanism](/doc/dom0-secure-updates/)
* VM secure update mechanism (forthcoming)
Debugging
---------
* [Profiling python code](/doc/profiling/)
* [Test environment in separate machine for automatic tests](/doc/test-bench/)
* [Automated tests](/doc/automated-tests/)
* [VM-dom0 internal configuration interface](/doc/vm-interface/)
* [Debugging Windows VMs](/doc/windows-debugging/)
Building
--------
* [Building Qubes](/doc/qubes-builder/) (["API" Details](/doc/qubes-builder-details/))
* [Development Workflow](/doc/development-workflow/)
* [KDE Dom0 packages for Qubes](/doc/kde-dom0/)
* [Building Qubes OS 3.0 ISO](/doc/qubes-r3-building/)
* [Building USB passthrough support (experimental)](/doc/pvusb/)
* [Building a TemplateVM based on a new OS (ArchLinux example)](/doc/building-non-fedora-template/)
* [Building the Archlinux Template](/doc/building-archlinux-template/)

178
doc.md
View File

@ -1,5 +1,5 @@
---
layout: default
layout: doc-index
title: Documentation
permalink: /doc/
redirect_from:
@ -8,42 +8,59 @@ redirect_from:
- /wiki/UserDoc/
- /doc/QubesDocs/
- /wiki/QubesDocs/
- /help/
- /en/help/
- /en/community/
- /community/
---
User Documentation
==================
The Basics
----------
* [A Tour of Qubes OS](/tour/)
* [What is Qubes OS?](/intro/)
* [Video Tours](/video-tours/)
* [Screenshots](/screenshots/)
* [Getting Started](/getting-started/)
* [User FAQ](/doc/user-faq/)
* [Mailing Lists](/mailing-lists/)
* [How to Contribute](/doc/contributing/)
Security Information
--------------------
* [Security Center](/security/)
* [Security Pack](/security/pack/)
* [Security Bulletins](/security/bulletins/)
* [Canaries](/security/canaries/)
* [Xen Security Advisory (XSA) Tracker](/security/xsa/)
* [Why and How to Verify Signatures](/security/verifying-signatures/)
* [Qubes PGP Keys](https://keys.qubes-os.org/keys/)
Choosing Your Hardware
----------------------
* [System Requirements](/doc/system-requirements/)
* [Certified Hardware](/doc/certified-hardware/)
* [Hardware Compatibility List (HCL)](/hcl/)
* [Qubes-Certified Laptops](/doc/certified-laptops/)
Installing & Upgrading Qubes
----------------------------
* [Qubes Downloads](/downloads/)
* [Installation Guide](/doc/installation-guide/)
* [Upgrade Guides](/doc/upgrade/)
* [Why and How to Verify Signatures](/doc/verifying-signatures/)
* [Why and How to Verify Signatures](/security/verifying-signatures/)
* [Security Considerations when Installing](/doc/install-security/)
* [Try Qubes without installing: Qubes Live USB (alpha)](/doc/live-usb/)
* [Supported Versions](/doc/supported-versions/)
* [Version Scheme](/doc/version-scheme/)
* [Custom Installation](/doc/custom-install/)
* [Testing new releases and updates](/doc/testing/)
Common Tasks
------------
* [Copying and Pasting Text Between Domains](/doc/copy-paste/)
* [Copying and Moving Files Between Domains](/doc/copying-files/)
* [Copying Files to and from dom0](/doc/copy-to-dom0/)
* [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/)
@ -52,61 +69,66 @@ Common Tasks
* [Recording Optical Discs](/doc/recording-optical-discs/)
* [Managing Application Shortcuts](/doc/managing-appvm-shortcuts/)
* [Enabling Fullscreen Mode](/doc/full-screen-mode/)
* [Tips and Tricks](/doc/tips-and-tricks/)
Managing Operating Systems within Qubes
---------------------------------------
* [TemplateVMs](/doc/templates/)
* [Templates: Fedora - minimal](/doc/templates/fedora-minimal/)
* [Templates: Fedora](/doc/templates/fedora/)
* [Templates: Fedora Minimal](/doc/templates/fedora-minimal/)
* [Templates: Debian](/doc/templates/debian/)
* [Templates: Archlinux](/doc/templates/archlinux/)
* [Templates: Ubuntu](/doc/templates/ubuntu/)
* [Templates: Whonix](/doc/whonix/)
* [Installing and Using Windows-based AppVMs (Qubes R2 Beta 3 and later)](/doc/windows-appvms/)
* [Creating and Using HVM and Windows Domains (Qubes R2+)](/doc/hvm/)
* [Advanced options and troubleshooting of Qubes Tools for Windows (R3)](/doc/windows-tools-3/)
* [Advanced options and troubleshooting of Qubes Tools for Windows (R2)](/doc/windows-tools-2/)
* [Uninstalling Qubes Tools for Windows 2.x](/doc/uninstalling-windows-tools-2/)
* [Upgrading the Fedora 21 Template](/doc/fedora-template-upgrade-21/)
* [Upgrading the Fedora 20 Template](/doc/fedora-template-upgrade-20/)
* [Upgrading the Fedora 18 Template](/doc/fedora-template-upgrade-18/)
* [Upgrading the Debian 8 Template](/doc/debian-template-upgrade-8/)
* [Pentesting](/doc/pentesting/)
* [Pentesting: BlackArch](/doc/pentesting/blackarch/)
* [Pentesting: Kali](/doc/pentesting/kali/)
* [Pentesting: PTF](/doc/pentesting/ptf/)
* [Windows: Installing and Using Windows-based AppVMs (Qubes R2 Beta 3 and later)](/doc/windows-appvms/)
* [Windows: Creating and Using HVM and Windows Domains (Qubes R2+)](/doc/hvm/)
* [Windows: Advanced options and troubleshooting of Qubes Tools for Windows (R3)](/doc/windows-tools-3/)
* [Windows: Advanced options and troubleshooting of Qubes Tools for Windows (R2)](/doc/windows-tools-2/)
* [Windows: Uninstalling Qubes Tools for Windows 2.x](/doc/uninstalling-windows-tools-2/)
* [Fedora: Upgrading the Fedora 23 Template to Fedora 24](/doc/template/fedora/upgrade-23-to-24/)
* [Fedora: Upgrading the Fedora 21 Template to Fedora 23](/doc/template/fedora/upgrade-21-to-23/)
* [Fedora: Upgrading the Fedora 20 Template to Fedora 21](/doc/template/fedora/upgrade-20-to-21/)
* [Fedora: Upgrading the Fedora 18 Template to Fedora 20](/doc/template/fedora/upgrade-18-to-20/)
* [Debian: Upgrading the Debian 8 Template to Debian 9](/doc/template/debian/upgrade-8-to-9/)
* [How to Reinstall a TemplateVM](/doc/reinstall-template)
* [Tips for Using Linux in an HVM](/doc/linux-hvm-tips/)
* [Creating a NetBSD VM](/doc/netbsd/)
Security Guides
---------------
* [Qubes OS Project Security Information](/security/)
* [Security Guidelines](/doc/security-guidelines/)
* [Understanding Qubes Firewall](/doc/qubes-firewall/)
* [Understanding Qubes Firewall](/doc/firewall/)
* [Understanding and Preventing Data Leaks](/doc/data-leaks/)
* [Installing Anti Evil Maid](/doc/anti-evil-maid/)
* [Using Multi-factor Authentication with Qubes](/doc/multifactor-authentication/)
* [Using GPG more securely in Qubes: Split GPG](/doc/split-gpg/)
* [How to Set Up a Split Bitcoin Wallet in Qubes](/doc/split-bitcoin/)
* [[Unofficial] Split dm-crypt](https://github.com/rustybird/qubes-split-dm-crypt)
* [Configuring YubiKey for user authentication](/doc/yubi-key/)
* [Note regarding password-less root access in VM](/doc/vm-sudo/)
Privacy Guides
--------------
* [Whonix for Privacy & Anonymity](/doc/whonix/)
* [Running Tails in Qubes](/doc/tails/)
* [Anonymizing your MAC Address](/doc/anonymizing-your-mac-address/)
* [TorVM](/doc/torvm/)
* [Martus](/doc/martus/)
* [Signal](/doc/signal/)
Configuration Guides
--------------------
* [Configuration Files](/doc/config-files/)
* [How to set up a ProxyVM as a VPN Gateway](/doc/vpn/)
* [Storing AppVMs on Secondary Drives](/doc/secondary-storage/)
* [Where are my external storage devices mounted?](/doc/external-device-mount-point/)
* [Multibooting](/doc/multiboot/)
* [Resizing AppVM and HVM Disk Images](/doc/resize-disk-image/)
* [Extending `root.img` Size](/doc/resize-root-disk-image/)
@ -114,7 +136,7 @@ Configuration Guides
* [Mutt Guide](/doc/mutt/)
* [Postfix Guide](/doc/postfix/)
* [Fetchmail Guide](/doc/fetchmail/)
* [Creating Custom NetVMs and ProxyVMs](http://theinvisiblethings.blogspot.com/2011/09/playing-with-qubes-networking-for-fun.html)
* [Creating Custom NetVMs and ProxyVMs](https://theinvisiblethings.blogspot.com/2011/09/playing-with-qubes-networking-for-fun.html)
* [How to make proxy for individual tcp connection from networkless VM](https://groups.google.com/group/qubes-devel/msg/4ca950ab6d7cd11a)
* [Make an HTTP Filtering Proxy in a FirewallVM](/doc/config/http-filtering-proxy)
* [Adding Bridge Support to the NetVM (EXPERIMENTAL)](/doc/network-bridge-support/)
@ -131,7 +153,6 @@ Configuration Guides
Customization Guides
--------------------
* [DispVM Customization](/doc/dispvm-customization/)
* [Customizing Fedora minimal templates](/doc/fedora-minimal-template-customization)
* [Customizing Windows 7 templates](/doc/windows-template-customization)
@ -139,24 +160,26 @@ Customization Guides
* [Installing XFCE in dom0](/doc/xfce/)
* [Installing i3 in dom0](/doc/i3/)
* [Language Localization](/doc/language-localization/)
* [Dark Theme in Dom0 and DomU](/doc/dark-theme/)
* [How to make any file in a TemplateBasedVM persistent using bind-dirs](/doc/bind-dirs/)
Troubleshooting
---------------
* [Home directory is out of disk space error](/doc/out-of-memory/)
* [Installing on system with new AMD GPU (missing firmware problem)](https://groups.google.com/group/qubes-devel/browse_thread/thread/e27a57b0eda62f76)
* [How to install an Nvidia driver in dom0](/doc/install-nvidia-driver/)
* [Solving problems with Macbook Air 2012](https://groups.google.com/group/qubes-devel/browse_thread/thread/b8b0d819d2a4fc39/d50a72449107ab21#8a9268c09d105e69)
* [Nvidia troubleshooting guide](/doc/nvidia-troubleshooting/)
* [Lenovo ThinkPad Troubleshooting](/doc/thinkpad-troubleshooting/)
* [Apple MacBook Troubleshooting](/doc/macbook-troubleshooting/)
* [Getting Sony Vaio Z laptop to work with Qubes](/doc/sony-vaio-tinkering/)
* [Getting Lenovo 450 to work with Qubes](/doc/lenovo450-tinkering/)
* [Getting Lenovo Thinkpad X201 to work with Qubes](/doc/thinkpad_x201/)
* [Troubleshooting UEFI related problems](/doc/uefi-troubleshooting/)
* [Fixing wireless on suspend & resume](/doc/wireless-troubleshooting/)
* [How to remove VMs manually](/doc/remove-vm-manually/)
Reference Pages
---------------
* [Dom0 Command-Line Tools](/doc/dom0-tools/)
* [DomU Command-Line Tools](/doc/vm-tools/)
* [Glossary of Qubes Terminology](/doc/glossary/)
@ -168,22 +191,91 @@ Presentation Slides
-------------------
* [[PDF] LinuxCon 2014 -- Qubes OS R2 Tutorial](/attachment/wiki/slides/LinuxCon_2014_Qubes_Tutorial.pdf)
* [[PDF] LinuxCon 2014 -- Qubes OS Keynote](/attachment/wiki/slides/LinuxCon_2014_Qubes_Keynote.pdf)
* [[PDF] RMLL 2016 -- Improving client systems security with Qubes OS](/attachment/wiki/slides/RMLL_2016_Improving-client-systems-security.pdf)
Developer Documentation
=======================
For Developers
--------------
* [System Documentation](/doc/system-doc/)
* [Developers' FAQ](/doc/devel-faq/)
* [Reporting Security Issues](/security/)
* [Reporting Bugs](/doc/reporting-bugs/)
The Basics
----------
* [Developer FAQ](/doc/devel-faq/)
* [Report a Security Issue](/security/)
* [Report a Bug](/doc/reporting-bugs/)
* [How to Contribute](/doc/contributing/)
* [Testing new releases and updates](/doc/testing/)
* [Source Code](/doc/source-code/)
* [How to Contribute to the Qubes OS Project](/doc/contributing/)
* [Qubes OS License](/doc/license/)
* [Coding Guidelines](/doc/coding-style/)
* [Documentation Guidelines](/doc/doc-guidelines/)
* [Code Signing](/doc/code-signing/)
* [Community-Developed Feature Tracker](/qubes-issues/)
* [Books for Developers](/doc/devel-books/)
* [Qubes OS License](/doc/license/)
* [Style Guide](/doc/style-guide/)
* [Usability & UX](/doc/usability-ux/)
Security Information
--------------------
* [Security Center](/security/)
* [Security Pack](/security/pack/)
* [Security Bulletins](/security/bulletins/)
* [Security Bulletin Checklist](/security/bulletins/checklist/)
* [Security Bulletin Template](/security/bulletins/template/)
* [Canaries](/security/canaries/)
* [Canary Template](/security/canaries/template/)
* [Xen Security Advisory (XSA) Tracker](/security/xsa/)
* [Why and How to Verify Signatures](/security/verifying-signatures/)
* [Qubes PGP Keys](http://keys.qubes-os.org/keys/)
System
------
* [Qubes OS Architecture Overview](/doc/architecture/)
* [Qubes OS Architecture Spec v0.3 [PDF]](/attachment/wiki/QubesArchitecture/arch-spec-0.3.pdf)
* [Security-critical elements of Qubes OS](/doc/security-critical-code/)
* [Qubes Core Admin](https://dev.qubes-os.org/projects/core-admin/en/latest/)
* [Qubes Core Admin Client](https://dev.qubes-os.org/projects/core-admin-client/en/latest/)
* [Qrexec: command execution in VMs](/doc/qrexec3/)
* [Qubes GUI virtualization protocol](/doc/gui/)
* [Networking in Qubes](/doc/networking/)
* [Implementation of template sharing and updating](/doc/template-implementation/)
* [Storage Pools](/doc/storage-pools/)
Services
--------
* [Inter-domain file copying](/doc/qfilecopy/) (deprecates [`qfileexchgd`](/doc/qfileexchgd/))
* [Dynamic memory management in Qubes](/doc/qmemman/)
* [Implementation of DisposableVMs](/doc/dvm-impl/)
* [Article about disposable VMs](http://theinvisiblethings.blogspot.com/2010/06/disposable-vms.html)
* [Dom0 secure update mechanism](/doc/dom0-secure-updates/)
* VM secure update mechanism (forthcoming)
Debugging
---------
* [Profiling python code](/doc/profiling/)
* [Test environment in separate machine for automatic tests](/doc/test-bench/)
* [Automated tests](/doc/automated-tests/)
* [VM-dom0 internal configuration interface](/doc/vm-interface/)
* [Debugging Windows VMs](/doc/windows-debugging/)
* [Safe Remote Dom0 Terminals](/doc/safe-remote-ttys/)
Building
--------
* [Building Qubes](/doc/qubes-builder/) (["API" Details](/doc/qubes-builder-details/))
* [Development Workflow](/doc/development-workflow/)
* [Building Qubes OS 3.0 ISO](/doc/qubes-r3-building/)
* [Building Qubes Templates](https://github.com/QubesOS/qubes-template-configs)
* [Building a TemplateVM based on a new OS (ArchLinux example)](/doc/building-non-fedora-template/)
* [Building the Archlinux Template](/doc/building-archlinux-template/)
* [How to compile kernels for dom0](https://groups.google.com/d/topic/qubes-users/yBeUJPwKwHM/discussion)
Releases
--------
* [Release checklist](/doc/releases/todo/)
* [Qubes R1.0 release notes](/doc/releases/1.0/release-notes/)
* [Qubes R2.0 release notes](/doc/releases/2.0/release-notes/)
* [Qubes R3.0 release notes](/doc/releases/3.0/release-notes/)
* [Qubes R3.0 release schedule](/doc/releases/3.0/schedule/)
* [Qubes R3.1 release notes](/doc/releases/3.1/release-notes/)
* [Qubes R3.1 release schedule](/doc/releases/3.1/schedule/)
* [Qubes R3.2 release notes](/doc/releases/3.2/release-notes/)
* [Qubes R3.2 release schedule](/doc/releases/3.2/schedule/)

70
hardware/certified-hardware.md Normal file
View File

@ -0,0 +1,70 @@
---
layout: doc
title: Certified Hardware
permalink: /doc/certified-hardware/
redirect_from:
- /doc/hardware/
- /doc/certified-laptops/
- /hardware-certification/
---
# Certified Hardware #
## Important Information ##
There is currently **no** specific hardware (e.g., specific laptop model) that the Qubes team recommends for individual users.
However, we're working hard to make a "reasonably secure laptop" a reality, and we look forward to sharing more information about this when the time is right.
(Note that this will be distinct from a [stateless laptop], which no one has implemented yet.)
In the meantime, users are encouraged to make use of the [Hardware Compatibility List] and [System Requirements] as sources of information in making hardware selection decisions.
Serious prospective business customers should [contact us] for more information.
## Hardware Certification ##
### Become Hardware Certified ###
If you are a hardware vendor, you can have your hardware certified as compatible with Qubes OS.
The benefits of hardware certification include:
* Your customers can purchase with confidence, knowing that they can take full advantage of Qubes OS on your hardware.
* Your hardware will continue to be compatible with Qubes OS as it further develops.
* You can support the development of Qubes OS.
### Hardware Certification Requirements ###
Please see the [updated requirements] for Qubes 4.x certification.
(Please note that these are the requirements for hardware *certification*, *not* the requirements for *running* Qubes 4.x.
For the latter, please see the [system requirements for Qubes 4.x].)
### Hardware Certification Process ###
To have hardware certified, the vendor must:
1. Send the Qubes team two (2) units for testing (non-returnable) for each configuration the vendor wishes to be offering.
2. Offer to customers the very same configuration (same motherboard, same screen, same BIOS version, same Wi-Fi module, etc.) for at least one year.
3. Pay the Qubes team a flat monthly rate, to be agreed upon between the hardware vendor and the Qubes team.
It is the vendor's responsibility to ensure the hardware they wish to have certified can run Qubes OS, at the very least the latest stable version.
This could be done by consulting the [Hardware Compatibility List] or trying to install it themselves before shipping any units to us.
While we are willing to troubleshoot simple issues, we will need to charge a consulting fee for more in-depth work.
If you are interested in having your hardware certified, please [contact us].
## Qubes-certified Laptops ##
Qubes-certified laptops are regularly tested by the Qubes developers to ensure compatibility with all of Qubes' features.
The developers test all new major versions and updates to ensure that no regressions are introduced.
Unfortunately, there are currently no certified laptops for Qubes R3.x or R4.x.
This page will be updated once certified laptops are available.
For more general information about choosing hardware for Qubes, please see the [System Requirements] and the [Hardware Compatibility List].
We aim to partner with a select few computer vendors to ensure that Qubes users have reliable hardware purchasing options.
We aim for these vendors to be as diverse as possible in terms of geography, cost, and availability.
Note, however, that we certify only that a particular hardware *configuration* is *supported* by Qubes.
We take no responsibility for our partners' manufacturing or shipping processes, nor can we control whether physical hardware is modified (whether maliciously or otherwise) *en route* to the user.
To learn more about the certification process, or if you're interested in having your company's hardware certified, please see the [Hardware Certification] section.
[stateless laptop]: https://blog.invisiblethings.org/2015/12/23/state_harmful.html
[System Requirements]: /doc/system-requirements/
[Hardware Compatibility List]: /hcl/
[Hardware Certification]: #hardware-certification
[updated requirements]: /news/2016/07/21/new-hw-certification-for-q4/
[system requirements for Qubes 4.x]: /doc/system-requirements/#qubes-release-4x
[contact us]: mailto:business@qubes-os.org

57
hardware/certified-laptops.md
View File

@ -1,57 +0,0 @@
---
layout: doc
title: Qubes-Certified Laptops
permalink: /doc/certified-laptops/
---
Qubes-certified Laptops
=======================
Qubes-certified laptops are laptops that are regularly tested by the Qubes
developers to ensure compatibility with all of Qubes' features. The developers
test all new major versions and updates to ensure no regressions are introduced.
To learn more about the certification process, or if you're interested in
getting your company's hardware Qubes-certified, please see the [Hardware
Certification] page.
We aim to partner with a few select computer makers to ensure that Qubes is
compatible with them, so that new users have clear path towards getting started
with Qubes if they desire. We aim for these makers to be as diverse as possible
in terms of geography, cost, and availability.
Note that we certify only that a particular configuration is supported by Qubes.
We take no responsibility for our partners' shipping process -- including that
the hardware will not being modified in any way (malicious or not).
For more general information about choosing hardware for Qubes, please see the
[System Requirements] and the [Hardware Compatibility List].
Purism Librem 13
----------------
[![image of Librem 13](/attachment/site/qubes-plus-purism.png)](https://puri.sm/librem-13/)
For users now who seek to buy a Librem 13, there is an option to have Qubes
pre-installed on their Librem 13. This will include all the necessary tweaks for
maximum compatibility with Qubes.
In addition, the Qubes team will receive a small portion of the revenue from any
Librem 13 sale that comes with Qubes pre-installed.
For existing Librem 13 users, please follow the instructions to ensure maximum
compatibility with Qubes:
1. In `dom0`, open a terminal and type:
sudo qubes-dom0-update --releasever=3.1 xorg-x11-drivers xorg-x11-drv-intel
2. (optional) Enable newer kernel:
sudo qubes-dom0-update --enablerepo=qubes-dom0-unstable kernel
[System Requirements]: /doc/system-requirements/
[Hardware Compatibility List]: /hcl/
[Hardware Certification]: /hardware-certification/

22
hardware/hcl.md
View File

@ -13,18 +13,18 @@ redirect_from:
Hardware Compatibility List (HCL) for All Qubes OS Releases
===========================================================
The [HCL](/hcl) is a compilation of reports generated and submitted by users across various Qubes versions.
The [HCL](/hcl) is a compilation of reports generated and submitted by users across various Qubes versions about their hardware's compatibility with Qubes.
**Note:**
Except in the case of developer-reported entries, the Qubes team has not independently verified the accuracy of these reports.
Please first consult the data sheets (CPU, chipset, motherboard) prior to buying new hardware for Qubes.
Meet the [System Requirements](/doc/system-requirements/) and search particular for support of:
Make sure it meets the [System Requirements](/doc/system-requirements/) and search in particular for support of:
- HVM ("AMD virtualization (AMD-V)", "Intel virtualization (VT-x)", "VIA virtualization (VIA VT)")
- IOMMU ("AMD I/O Virtualization Technology (AMD-Vi)", "Intel Virtualization Technology for Directed I/O (VT-d)")
- TPM ("Trusted Platform Module (TPM)" connected to a "20-pin TPM header" on motherboards.)
Test the hardware yourself, if possible.
If using the list to make a purchasing decision, we recommend that you choose hardware with:
If using the list to make a purchasing decision, we recommend that you choose hardware with:
- the best achievable Qubes security level (green columns in HVM, IOMMU, TPM)
- and general machine compatibility (green columns in Qubes version, dom0 kernel, remarks).
@ -32,15 +32,15 @@ Test the hardware yourself, if possible.
Generating and Submitting New Reports
-------------------------------------
In order to generate a HCL report in Qubes, simply open a terminal in dom0 (KDE: start-menu -\> System Tools -\> Konsole or Terminal Emulator)
and run `qubes-hcl-report <vm-name>`, where `<vm-name>` is the name of the VM to which the generated HCL files will be saved.
(Note: If you are working with a new Qubes installation, you may need to update your system in order to download this script.)
In order to generate an HCL report in Qubes, simply open a terminal in dom0 (KDE: start-menu -\> System Tools -\> Konsole or Terminal Emulator)
and run `qubes-hcl-report <vm-name>`, where `<vm-name>` is the name of the VM to which the generated HCL files will be saved.
(Note: If you are working with a new Qubes installation, you may need to update your system in order to download this script.)
You are encouraged to submit your HCL report for the benefit of further Qubes development and other users.
If you would like to submit your HCL report, please send the **HCL Info** `.yml` file to [\`qubes-users@googlegroups.com\`](/doc/mailing-lists/) with the subject `HCL - <your machine model name>`.
Please include any useful information about any Qubes features you may have tested (see the legend below), as well as general machine compatibility (video, networking, sleep, etc.).
If you have problems with your hardware try a different kernel in the [Troubleshooting menu](/doc/InstallationGuideR2rc1/#troubleshooting-problems-with-the-installer).
Please consider sending the **HCL Support Files** `.cpio.gz` file as well. To generate these add the `-s` or `--support` command line option.
When submitting reports, test the hardware yourself, if possible.
If you would like to submit your HCL report, please send the **HCL Info** `.yml` file to [\`qubes-users@googlegroups.com\`](/doc/mailing-lists/) with the subject `HCL - <your machine model name>`.
Please include any useful information about any Qubes features you may have tested (see the legend below), as well as general machine compatibility (video, networking, sleep, etc.).
Please consider sending the **HCL Support Files** `.cpio.gz` file as well. To generate these add the `-s` or `--support` command line option.
**Please note:**
The **HCL Support Files** may contain numerous hardware details, including serial numbers. If, for privacy or security reasons, you do not wish to make this information public, please **do not** send the `.cpio.gz` file to the public mailing list.

102
hardware/system-requirements.md
View File

@ -8,81 +8,85 @@ redirect_from:
- /wiki/SystemRequirements/
---
System Requirements
===================
# System Requirements #
Minimum
-------
## Qubes Release 3.x ##
### Minimum ###
* 64-bit Intel or AMD processor (x86\_64 aka x64 aka AMD64)
* 4 GB RAM
* 32 GB disk space
* Legacy boot mode ([UEFI is not supported yet][UEFI])
* Legacy boot mode (required for R3.0 and earlier; UEFI is supported beginning with R3.1)
Recommended
-----------
### Recommended ###
* Fast SSD (strongly recommended)
* Intel GPU (strongly preferred)
* Intel IGP (strongly preferred)
* Nvidia GPUs may require significant [troubleshooting][nvidia].
* ATI GPUs have not been formally tested (but see the [Hardware Compatibility
List]).
* Intel VT-x or AMD-v technology (required for running HVM domains, such as
Windows-based AppVMs)
* Intel VT-d or AMD IOMMU technology (required for effective isolation of
network VMs)
* ATI GPUs have not been formally tested (but see the [Hardware Compatibility List]).
* [Intel VT-x] or [AMD-V] (required for running HVM domains, such as Windows-based AppVMs)
* [Intel VT-d] or [AMD-Vi (aka AMD IOMMU)] (required for effective isolation of network VMs)
* TPM with proper BIOS support (required for [Anti Evil Maid])
## Qubes Release 4.x ##
Choosing Hardware
-----------------
### Minimum ###
* Please see the [Hardware Compatibility List] for a compilation of
hardware reports generated and submitted by users across various Qubes
versions. (For more information about the HCL itself, see [here][hcl-doc]).
* For more certain hardware compatibility, you may wish to consider a
[Qubes-certified laptop].
* 64-bit Intel or AMD processor (x86\_64 aka x64 aka AMD64)
* [Intel VT-x] with [EPT] or [AMD-V] with [RVI]
* [Intel VT-d] or [AMD-Vi (aka AMD IOMMU)]
* 4 GB RAM
* 32 GB disk space
### Recommended ###
Important Notes
---------------
* Fast SSD (strongly recommended)
* Intel IGP (strongly preferred)
* Nvidia GPUs may require significant [troubleshooting][nvidia].
* ATI GPUs have not been formally tested (but see the [Hardware Compatibility List]).
* TPM with proper BIOS support (required for [Anti Evil Maid])
* A non-USB keyboard or multiple USB controllers
* Also consider the [hardware certification requirements for Qubes 4.x].
* Qubes **can** be installed on systems which do not meet the recommended
requirements. Such systems will still offer significant security
improvements over traditional operating systems, since things like GUI
isolation and kernel protection do not require special hardware.
* Qubes **can** be installed on a USB flash drive or external disk, and testing
has shown that this works very well. A fast USB 3.0 flash drive is
recommended for this. (As a reminder, its capacity must be at least 32 GB.)
Simply plug the flash drive into the computer before booting into the Qubes
installer from a separate installation medium, choose the flash drive as the
target installation disk, and proceed with the installation normally. After
Qubes has been installed on the flash drive, it can then be plugged into
other computers in order to boot into Qubes. In addition to the convenience
of having a portable copy of Qubes, this allows users to test for hardware
compatibility on multiple machines (e.g., at a brick-and-mortar computer
store) before deciding on which computer to purchase. (See [hcl-report] for
advice on hardware compatibility testing.) Keep in mind to also change
assigned devices for your netvm and usbvm, if you move between different
machines.
* There is also a [live USB] option available, which may be even easier for
testing.
* Installing Qubes in a virtual machine is not recommended, as it uses its own
bare-metal hypervisor (Xen).
## Choosing Hardware ##
* Please see the [Hardware Compatibility List] for a compilation of hardware reports generated and submitted by users across various Qubes versions.
(For more information about the HCL itself, see [here][hcl-doc].)
* See the [Certified Hardware] page.
## Important Notes ##
* Qubes **can** be installed on systems which do not meet the recommended requirements.
Such systems will still offer significant security improvements over traditional operating systems, since things like GUI isolation and kernel protection do not require special hardware.
* Qubes **can** be installed on a USB flash drive or external disk, and testing has shown that this works very well. A fast USB 3.0 flash drive is recommended for this.
(As a reminder, its capacity must be at least 32 GB.)
Simply plug the flash drive into the computer before booting into the Qubes installer from a separate installation medium, choose the flash drive as the target installation disk, and proceed with the installation normally.
After Qubes has been installed on the flash drive, it can then be plugged into other computers in order to boot into Qubes.
In addition to the convenience of having a portable copy of Qubes, this allows users to test for hardware compatibility on multiple machines (e.g., at a brick-and-mortar computer
store) before deciding on which computer to purchase.
(See [hcl-report] for advice on hardware compatibility testing.)
Remember to change the devices assigned to your NetVM and USBVM if you move between different machines.
* Installing Qubes in a virtual machine is not recommended, as it uses its own bare-metal hypervisor (Xen).
* Macintosh PCs are not currently supported due to keyboard and mouse problems.
(See [#230] for details. Patches welcome!)
* [Advice on finding a VT-d capable notebook][vt-d-notebook].
[UEFI]: https://github.com/QubesOS/qubes-issues/issues/794
[nvidia]: /doc/install-nvidia-driver/
[hardware certification requirements for Qubes 4.x]: /news/2016/07/21/new-hw-certification-for-q4/
[Certified Hardware]: /doc/certified-hardware/
[Hardware Compatibility List]: /hcl/
[hcl-doc]: /doc/hcl/
[hcl-report]: /doc/HCL/#generating-and-submitting-new-reports
[hcl-report]: /doc/hcl/#generating-and-submitting-new-reports
[Anti Evil Maid]: /doc/anti-evil-maid/
[Qubes-certified laptop]: /doc/certified-laptops/
[live USB]: /doc/live-usb/
[#230]: https://github.com/QubesOS/qubes-issues/issues/230
[vt-d-notebook]: https://groups.google.com/d/msg/qubes-users/Sz0Nuhi4N0o/ZtpJdoc0OY8J
[Intel VT-x]: https://en.wikipedia.org/wiki/X86_virtualization#Intel_virtualization_.28VT-x.29
[AMD-V]: https://en.wikipedia.org/wiki/X86_virtualization#AMD_virtualization_.28AMD-V.29
[Intel VT-d]: https://en.wikipedia.org/wiki/X86_virtualization#Intel-VT-d
[AMD-Vi (aka AMD IOMMU)]: https://en.wikipedia.org/wiki/X86_virtualization#I.2FO_MMU_virtualization_.28AMD-Vi_and_Intel_VT-d.29
[EPT]: https://en.wikipedia.org/wiki/Second_Level_Address_Translation#Extended_Page_Tables
[RVI]: https://en.wikipedia.org/wiki/Second_Level_Address_Translation#Rapid_Virtualization_Indexing

193
installing/custom-install.md Normal file
View File

@ -0,0 +1,193 @@
---
layout: doc
title: Custom Installation
permalink: /doc/custom-install/
redirect_from:
- /doc/encryption-config/
---
Custom Installation
===================
In the present context, "custom installation" refers to things like manual
partitioning, setting up LVM and RAID, and manual LUKS encryption configuration.
Installer Defaults (R3.2)
-------------------------
For reference, these are the defaults for a single disk:
~~~
Mount Point: `/`
Desired Capacity: (your choice)
Device Type: `LVM`
Volume Group: `qubes_dom0`
File System: `ext4`
Name: `root`
Mount Point: `/boot`
Desired Capacity: 500 MiB (recommended)
Device Type: Standard Partition
File System: `ext4`
Mount Point: (none)
Desired Capacity: 9.44 GiB (recommended)
Device Type: LVM
Volume Group: qubes_dom0
File System: `swap`
Name: `swap`
~~~
Typical Partition Schemes
-------------------------
If you want your partition/LVM scheme to look like the Qubes default but
with a few tweaks, follow these examples. With a single disk, the result
should look something like this:
~~~
NAME TYPE MOUNTPOINT
sda disk
├──sda1 part /boot
└──sda2 part
└──luks-<UUID> crypt
├──qubes_dom0-root lvm /
└──qubes_dom0-swap lvm [SWAP]
~~~
If you're using `mdadm` software RAID, it should look something like this:
~~~
NAME TYPE MOUNTPOINT
sda disk
├──sda1 part
│ └──md0 raid1 /boot
└──sda2 part
└──md1 raid1
└──luks-<UUID> crypt
├──qubes_dom0-root lvm /
└──qubes_dom0-swap lvm [SWAP]
sdb disk
├──sdb1 part
│ └──md0 raid1 /boot
└──sdb2 part
└──md1 raid1
└──luks-<UUID> crypt
├──qubes_dom0-root lvm /
└──qubes_dom0-swap lvm [SWAP]
~~~
Example: LVM on LUKS on RAID (R3.2)
-----------------------------------
Boot into the Qubes installer, then press `ctrl`+`alt`+`F2` to get a virtual
console.
1. (Optional) Wipe both disks:
# hdparm --user-master u --security-set-pass pass /dev/sda
# time hdparm --user-master u --security-erase-enhanced pass /dev/sda
# hdparm --user-master u --security-set-pass pass /dev/sdb
# time hdparm --user-master u --security-erase-enhanced pass /dev/sdb
2. Create desired partitions:
# fdisk /dev/sda
<create partitions>
# fdisk /dev/sdb
<create partitions>
3. Create RAID devices:
# mdadm --create --verbose /dev/md0 --level=mirror --raid-devices=2 /dev/sda1 /dev/sdb1
# mdadm --create --verbose /dev/md1 --level=mirror --raid-devices=2 /dev/sda2 /dev/sdb2
4. Create LUKS encrypted volume:
# cryptsetup -v --hash sha512 --cipher aes-xts-plain64 --key-size 512 --use-random --iter-time 5000 --verify-passphrase luksFormat /dev/md1
5. Open encrypted volume:
# cryptsetup open /dev/md1 luks
6. Create LVM volumes:
# pvcreate /dev/mapper/luks
# vgcreate qubes_dom0 /dev/mapper/luks
# lvcreate -n swap -L 10G qubes_dom0
# lvcreate -n root -l +100%FREE qubes_dom0
7. Proceed with installer. At the disk selection screen, select:
[x] I will configure partitioning.
[ ] Encrypt my data.
Continue normally from here.
Manual Encryption Configuration (R3.1)
--------------------------------------
Qubes OS uses full disk encryption (FDE) by default. If you are an advanced
user who wishes to customize your encryption parameters during installation,
this page can help.
The Qubes installer uses `cryptsetup` (LUKS/dm-crypt) under the hood. You can
configure the encryption options while installing Qubes as follows:
01. Boot into the installer. Wait for first GUI screen to appear where it asks
about language/localization .
02. Press `Ctrl+Alt+F2` on your keyboard to escape to a shell session. (If you
are on a laptop, and your laptop keyboard does not work properly, you may have
to plug in a USB keyboard.)
03. Check and adjust the partitioning on the drive you plan to install to with
`parted`. For example, you can leave the partition table as `msdos/MBR` type,
then create a 500 MB ext4 boot partition, a 10 GB swap partition, and use the
rest of the drive (minus overprovisioning space for SSDs) for the root
partition.
04. Run to set the LUKS options as you like and set the passphrase:
# cryptsetup <options> luksFormat <partition>
For example:
# cryptsetup -v --hash sha512 --cipher aes-xts-plain64 --key-size 512 --use-random --iter-time 5000 --verify-passphrase luksFormat /dev/sda2
05. (Optional) Make sure the new container works:
# cryptsetup open /dev/sda2 test
# mkfs.ext4 /dev/mapper/test
# mount /dev/mapper/test /mnt/test
# umount /dev/mapper/test
# cryptsetup close test
06. Everything should be set with the preparation, so press `Ctrl+Alt+F7` to go
back to the GUI installer.
07. Continue installing as usual. When you get to the disk
partitioning/allocation part, pay attention.
08. When you select the disk, it may complain about only having a few MB of
space. Uncheck the "Encrypt and ask me about the passphrase later" box and
press the "Custom" button.
09. In this menu, you should see the unencrypted boot partition and the encrypted
LUKS partitions you created earlier. You must unlock the LUKS partition here,
i.e. enter passphrases.
10. Set the mount points on these partitions once they are decrypted. (This part
may be a bit glitchy, but you should be able to get it working after a
reboot.) For example, set the mount point for the primary LUKS partition as
`/`. Make sure the "Encrypted" box stays checked and that you check the
"Format" box (required for the root partition). Similarly, set `/boot` as
the mount point for the unencrypted boot partition and `swap` as the mount
point for the swap partition.
11. Now the install should complete without any other issues. When it's
finished, you'll have LUKS-encrypted partitions with the options you chose
above. You can verify this command in dom0:
# cryptsetup luksDump <partition>
For example:
# cryptsetup luksDump /dev/sda2

6
installing/install-security.md
View File

@ -76,9 +76,9 @@ Cons:
other two options.)
[verify]: /doc/verifying-signatures/
[classic problem]: http://www.acm.org/classics/sep95/
[solutions]: http://www.dwheeler.com/trusting-trust/
[verify]: /security/verifying-signatures/
[classic problem]: https://www.ece.cmu.edu/~ganger/712.fall02/papers/p761-thompson.pdf
[solutions]: https://www.dwheeler.com/trusting-trust/
[USB qube]: /doc/usb/#creating-and-using-a-usb-qube
[BadUSB]: https://srlabs.de/badusb/

41
installing/installation-guide.md
View File

@ -19,6 +19,15 @@ redirect_from:
Installation Guide
==================
Warning
-------
There is a set of known upstream bugs in the Fedora installer that affect Qubes OS ([Bug 1170803], [Bug 1374983], and [Bug 1268700]; tracked in Qubes issue [#2835]).
Because of these bugs, the installer will try to access all existing disk partitions, run fsck on them, and mount them.
Therefore, we *strongly* recommended that, prior to starting the Qubes installer, you physically disconnect all disks that you do not want to be modified.
Furthermore, if you are installing Qubes on a potentially compromised system, we *strongly* recommended that you wipe your target installation disk before starting the installer.
Hardware Requirements
---------------------
@ -55,12 +64,13 @@ an installation medium.)
If you prefer to use a USB drive, then you just need to copy the ISO onto the
USB device, e.g. using `dd`:
dd if=Qubes-R3-x86_64.iso of=/dev/sda
dd if=Qubes-R3-x86_64.iso of=/dev/sdX
Change `Qubes-R3-x86_64.iso` to the filename of the version you're installing,
and change `/dev/sda` to the correct target device. **Warning:** Choosing the
wrong device could result in data loss. Make sure to write to the entire device
(e.g., `/dev/sda`) rather than just a single partition (e.g., `/dev/sda1`).
and change `/dev/sdX` to the correct target device (e.g., `/dev/sda`).
**Warning:** Choosing the wrong device could result in data loss. Make sure to
write to the entire device (e.g., `/dev/sda`) rather than just a single
partition (e.g., `/dev/sda1`).
On Windows, you can use the [Rufus] tool. Be sure to select "DD image" mode (you
need to do that **after** selecting the Qubes ISO):
@ -77,6 +87,21 @@ The installer loads Xen right at the beginning, so chances are high that if you
can see the installer's graphical screen, Qubes will work on your system. :)
Installing to a USB drive
-------------------------
Installing an operating system onto a USB drive can be a convenient and secure
method of ensuring that your data is protected. Be advised that a minimum
storage of 32 GB is required on the USB drive. This installation process may
take longer than an installation on a standard hard disk. The installation
process is identical to using a hard disk in conjunction with two exceptions:
* Select the USB as the storage location for the OS.
* Leave the option checked to “Automatically configure my Qubes installation to
the disk(s) I selected and return me to the main menu”.
Upgrading
---------
@ -101,13 +126,17 @@ Getting Help
questions to the appropriate mailing list.
[Bug 1170803]: https://bugzilla.redhat.com/show_bug.cgi?id=1170803
[Bug 1374983]: https://bugzilla.redhat.com/show_bug.cgi?id=1374983
[Bug 1268700]: https://bugzilla.redhat.com/show_bug.cgi?id=1268700
[#2835]: https://github.com/QubesOS/qubes-issues/issues/2835
[system requirements]: /doc/system-requirements/
[Hardware Compatibility List]: /hcl/
[live USB]: /doc/live-usb/
[downloads]: /downloads/
[verifying signatures]: /doc/verifying-signatures/
[verifying signatures]: /security/verifying-signatures/
[security considerations]: /doc/install-security/
[Rufus]: http://rufus.akeo.ie/
[Rufus]: https://rufus.akeo.ie/
[documentation]: /doc/
[improving]: /doc/doc-guidelines/
[mailing lists]: /doc/mailing-lists/

31
installing/live-usb.md
View File

@ -10,14 +10,18 @@ Qubes Live USB (alpha)
Qubes Live USB allows you to run and try Qubes OS without having to install it
anywhere. Qubes Live USB is currently in alpha. If you use it, please consider
running the [HCL reporting tool](/hcl/) and sending us the results so that we
can continue to improve it.
can continue to improve it. If would like to contribute to the Qubes OS
Project by improving Qubes Live USB and integrating it with the installer,
please consider applying for a [Google Summer of Code][gsoc-page] scholarship
(if you are eligible) and choosing the QubesOS Project as a mentor
organization. You can find our list of project ideas [here][project-page].
Introduction
------------
We have faced several challenges when making this Live USB edition of Qubes OS,
which traditional Linux distros don't have to bother with:
When making this Live USB edition of Qubes OS, we faced several challenges which
traditional Linux distros don't have to bother with:
1. We needed to ensure Xen is properly started when booting the stick. In fact
we still don't support UEFI boot for the stick for this reason, even though
@ -39,20 +43,20 @@ few tens of MBs per VM, sometimes even more. Also, each VM's private
image, which essentially holds just the user home directory, typically starts
with a few tens of MBs for an "empty VM". Now, while these represent rather
insignificant numbers on a disk-basked system, in the case of a live USB all
these files must be stored in RAM, which is a scare resource on any OS, but
these files must be stored in RAM, which is a scarce resource on any OS, but
especially on Qubes.
We have implemented some quick optimizations in order to minimize the above
problem, but this is still far from a proper solution. We're planning to work
more on this next.
Now, there are three directions in how we want to work further on this Qubes
There are three directions in which we want to do further work on this Qubes
Live USB variant:
1. Introduce an easy, clickable "install to disk" option, merging this with the
Qubes installation ISO. So, e.g. make it possible to first see if the given
hardware is compatible with Qubes (run the HCL reporting tool) and only then
install on the main disk. Also, ensure UEFI boot works well.
hardware is compatible with Qubes (by running the HCL reporting tool) and
only then install on the main disk. Also, ensure UEFI boot works well.
2. Introduce options for persistence while still running this out of a USB
stick. This would be achieved by allowing (select) VMs' private images to be
@ -90,17 +94,17 @@ expectations accordingly.)
from a large Qubes backup blob.
5. It's easy to generate Out Of Memory (OOM) in Dom0 by creating lots of VMs
which are writing a lot into the VMs filesystem.
6. There is no DispVM savefile, so if one starts one the savefile must be
regenerated which takes about 1-2 minutes.
7. UEFI boot doesn't work, and if you try booting it via UEFI Xen will not be
started, rendering the whole experiment unusable.
6. There is no DispVM savefile, so if you start a DispVM the savefile must be
regenerated, which takes about 1-2 minutes.
7. UEFI boot doesn't work, and if you try booting Qubes Live USB via UEFI, Xen
will not be started, rendering the whole experiment unusable.
Downloading and burning
-----------------------
1. Download the ISO (and its signature for verification) from the
[downloads page](/downloads/#qubes-live-usb-alpha/).
[downloads page](/downloads/#qubes-live-usb-alpha).
2. "Burn" (copy) the ISO onto a USB drive (replace `/dev/sdX` with your USB
drive device):
@ -112,3 +116,6 @@ Downloading and burning
**Caution:** It is very easy to misuse the `dd` command. If you mix up `if`
and `of` or specify an incorrect device, you could accidentally overwrite
your primary system drive. Please be careful!
[project-page]: https://www.qubes-os.org/gsoc/
[gsoc-page]: https://summerofcode.withgoogle.com/organizations/6239659689508864/

10
installing/models/lenovo-w540.md
View File

@ -1,10 +0,0 @@
---
layout: doc
title: Lenovo W540 Installation Guide
permalink: /doc/installation-guide/lenovo-w540/
---
Lenovo W540 Installation Guide
==============================
(**Note:** This page is currently under construction.)

60
installing/supported-versions.md
View File

@ -4,37 +4,51 @@ title: Supported Versions
permalink: /doc/supported-versions/
---
<style>
article td, article th {
border-width: 2px;
border-style: double;
padding: 5px;
}
</style>
Supported Versions
==================
Qubes OS
--------
Qubes OS releases are supported for **six months** after each subsequent major
or minor release. The version scheme is explained [here](/doc/version-scheme/).
All available current and past downloads can be found [here](/downloads/).
or minor release (see [Version Scheme]). The current release and past major
releases are always available on the [Downloads] page, while all ISOs, including
past minor releases, are available from our [download mirrors].
| Qubes OS Version | Start Date | End Date | Status |
| ---------------- | ---------- | ---------- | --------------------------- |
| ---------------- | ---------- | ---------- | ------------------------------- |
| Release 1 | 2012-09-03 | 2015-03-26 | Old, unsupported |
| Release 2 | 2014-09-26 | 2016-04-01 | Old, unsupported |
| Release 3.0 | 2015-10-01 | 2016-09-09 | Old, supported |
| Release 3.1 | 2016-03-09 | TBA | Current, supported |
| Release 3.0 | 2015-10-01 | 2016-09-09 | Old, unsupported |
| Release 3.1 | 2016-03-09 | 2017-03-29 | Old, unsupported |
| Release 3.2 | 2016-09-29 | TBA | Current, [extended support] |
| Release 4.0 | TBA | TBA | In development |
Templates
---------
The table below shows the [template](/doc/templates/) versions supported by each
Qubes OS release. Currently, only Fedora and Debian templates are officially
supported.
Dom0
----
The table below shows the OS used for dom0 in each Qubes OS release.
| Qubes OS Version | Dom0 OS |
| ---------------- | --------- |
| Release 1 | Fedora 13 |
| Release 2 | Fedora 18 |
| Release 3.0 | Fedora 20 |
| Release 3.1 | Fedora 20 |
| Release 3.2 | Fedora 23 |
| Release 4.0 | TBA |
**Note:** Dom0 is isolated from domUs. DomUs can access only a few interfaces,
such as Xen, device backends (in the dom0 kernel and in other VMs, such as the
NetVM), and Qubes tools (gui-daemon, qrexec-daemon, etc.). These components are
[security-critical], and we provide updates for all of them (when necessary),
regardless of the support status of the base distribution. For this reason, we
consider it safe to continue using a given base distribution in dom0 even after
it has reached end-of-life.
TemplateVMs
-----------
The table below shows the [TemplateVM] versions supported by each Qubes OS
release. Currently, only Fedora and Debian TemplateVMs are officially supported.
| Qubes OS Version | Fedora Versions | Debian Versions |
| ---------------- | --------------- | --------------------------------------------- |
@ -42,9 +56,17 @@ supported.
| Release 2 | 21 | None |
| Release 3.0 | 21, 22\*, 23 | 7 ("wheezy")\*, 8 ("jessie") |
| Release 3.1 | 21, 22\*, 23 | 7 ("wheezy")\*, 8 ("jessie"), 9 ("stretch")\* |
| Release 3.2 | TBA | TBA |
| Release 3.2 | 23, 24\* | 8 ("jessie"), 9 ("stretch")\* |
| Release 4.0 | TBA | TBA |
\* Denotes versions for which we have published the packages but have not done
extensive testing.
[Version Scheme]: /doc/version-scheme/
[Downloads]: /downloads/
[download mirrors]: /downloads/#mirrors
[security-critical]: /doc/security-critical-code/
[TemplateVM]: /doc/templates/
[extended support]: /news/2016/09/02/4-0-minimum-requirements-3-2-extended-support/

2
installing/upgrade/upgrade-to-r2.md
View File

@ -19,7 +19,7 @@ Current Qubes R2 Beta 3 (R2B3) systems can be upgraded in-place to the latest R2
Upgrade Template and Standalone VM(s)
-------------------------------------
- Qubes R2 comes with new template based on Fedora 20. You can upgrade existing template according to procedure described [here](/doc/FedoraTemplateUpgrade/).
- Qubes R2 comes with new template based on Fedora 20. You can upgrade existing template according to procedure described [here](/doc/fedora-template-upgrade-20/).
- **It also possible to download a new Fedora 20-based template from our repositories**. To do this please first upgrade the Dom0 distro as described in the section below.

2
installing/upgrade/upgrade-to-r2b2.md
View File

@ -64,7 +64,7 @@ $ sudo -s
# umount /mnt/cdrom
~~~
If you already have fedora-17-x64, you can also upgrade it to fedora-18-x64 following [standard Fedora upgrade procedure](http://fedoraproject.org/wiki/Upgrading_Fedora_using_yum) (only "yum" method will work in Qubes VM).
If you already have fedora-17-x64, you can also upgrade it to fedora-18-x64 following [standard Fedora upgrade procedure](https://fedoraproject.org/wiki/Upgrading_Fedora_using_yum) (only "yum" method will work in Qubes VM).
Upgrade Dom0
------------

1
installing/upgrade/upgrade-to-r3.0.md
View File

@ -103,6 +103,7 @@ Upgrading template on already upgraded dom0
When for some reason you did not upgraded all the templates and standalone VMs before upgrading dom0, you can still do this, but it will be somehow more complicated. This can be a case when you restore backup done on Qubes R2.
When you start R2 template/standalone VM on R3.0, there will be some limitations:
1. qrexec will not connect (you will see an error message during VM startup)
2. GUI will not connect - you will not see any VM window
3. VM will not be configured - especially it will not have network access

5
installing/upgrade/upgrade-to-r3.1.md
View File

@ -105,6 +105,11 @@ will have changed. Once the system boots up again, you can reseal your Anti Evil
Maid passphrase to the new configuration. Please consult the Anti Evil Maid
[documentation](/doc/anti-evil-maid) for instructions on how to do that.
If you use USB VM, you may encounter problem with starting it on updated Xen
version (because of strict default settings). Take a look at
[User FAQ](/doc/user-faq/#i-created-a-usbvm-and-assigned-usb-controllers-to-it-now-the-usbvm-wont-boot)
for details.
Once you have upgraded dom0, you can install new templates from Qubes R3.1
repositories, in particular the new default Fedora 23 template:

167
installing/upgrade/upgrade-to-r3.2.md Normal file
View File

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

1
installing/upgrade/upgrade.md
View File

@ -13,4 +13,5 @@ Qubes OS Upgrade Guides
* [Upgrading from R2 Beta 3 to R2](/doc/upgrade-to-r2/)
* [Upgrading from R2 to R3.0](/doc/upgrade-to-r3.0/)
* [Upgrading from R3.0 to R3.1](/doc/upgrade-to-r3.1/)
* [Upgrading from R3.1 to R3.2](/doc/upgrade-to-r3.2/)

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