diff --git a/.travis.yml b/.travis.yml new file mode 100644 index 00000000..9153aed5 --- /dev/null +++ b/.travis.yml @@ -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 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e5ab919a..f73117d0 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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/ diff --git a/_dev/Makefile b/_dev/Makefile new file mode 100644 index 00000000..8177cd00 --- /dev/null +++ b/_dev/Makefile @@ -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 ' where 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." diff --git a/_dev/_build/.gitignore b/_dev/_build/.gitignore new file mode 100644 index 00000000..e69de29b diff --git a/_dev/_static/.gitignore b/_dev/_static/.gitignore new file mode 100644 index 00000000..e69de29b diff --git a/_dev/_templates/.gitignore b/_dev/_templates/.gitignore new file mode 100644 index 00000000..e69de29b diff --git a/_dev/conf.py b/_dev/conf.py new file mode 100644 index 00000000..9f311f45 --- /dev/null +++ b/_dev/conf.py @@ -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 +# " v 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 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 diff --git a/_dev/index.rst b/_dev/index.rst new file mode 100644 index 00000000..2e09dc47 --- /dev/null +++ b/_dev/index.rst @@ -0,0 +1,15 @@ +Welcome to Qubes OS developer's documentation! +============================================== + +Contents: + +.. toctree:: + :maxdepth: 2 + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` + diff --git a/basics/user-faq.md b/basics/user-faq.md deleted file mode 100644 index 49df1290..00000000 --- a/basics/user-faq.md +++ /dev/null @@ -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 WorksTM :) - -### 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 `` with your device, for example `00:1c.2`: - - echo 0000: > /sys/bus/pci/drivers/pciback/unbind - MODALIAS=`cat /sys/bus/pci/devices/0000:/modalias` - MOD=`modprobe -R $MODALIAS | head -n 1` - echo 0000: > /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. diff --git a/developers/code-signing.md b/basics_dev/code-signing.md similarity index 90% rename from developers/code-signing.md rename to basics_dev/code-signing.md index eb656ead..059e3a5d 100644 --- a/developers/code-signing.md +++ b/basics_dev/code-signing.md @@ -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/ diff --git a/developers/coding-style.md b/basics_dev/coding-style.md similarity index 66% rename from developers/coding-style.md rename to basics_dev/coding-style.md index 4110eb40..c7a18b80 100644 --- a/developers/coding-style.md +++ b/basics_dev/coding-style.md @@ -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 -------------------------- diff --git a/basics_dev/devel-books.md b/basics_dev/devel-books.md new file mode 100644 index 00000000..4284b893 --- /dev/null +++ b/basics_dev/devel-books.md @@ -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.) diff --git a/basics_dev/devel-faq.md b/basics_dev/devel-faq.md new file mode 100644 index 00000000..ba62c832 --- /dev/null +++ b/basics_dev/devel-faq.md @@ -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). diff --git a/basics_dev/license.md b/basics_dev/license.md new file mode 100644 index 00000000..1a7879a2 --- /dev/null +++ b/basics_dev/license.md @@ -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. diff --git a/basics_dev/package-contributions.md b/basics_dev/package-contributions.md new file mode 100644 index 00000000..56731da6 --- /dev/null +++ b/basics_dev/package-contributions.md @@ -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/ + diff --git a/developers/source-code.md b/basics_dev/source-code.md similarity index 82% rename from developers/source-code.md rename to basics_dev/source-code.md index d56b12b6..f39a2460 100644 --- a/developers/source-code.md +++ b/basics_dev/source-code.md @@ -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 diff --git a/developers/style-guide.md b/basics_dev/style-guide.md similarity index 91% rename from developers/style-guide.md rename to basics_dev/style-guide.md index 81e7a40c..160e8666 100644 --- a/developers/style-guide.md +++ b/basics_dev/style-guide.md @@ -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.
{% 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.
{% for color in site.data.styleguide.colors %} @@ -42,7 +42,7 @@ The following **grayscale** colors are currently used on the Qubes website, docu {% endfor %}
-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!
{% for color in site.data.styleguide.colors %} diff --git a/basics_dev/system-doc.md b/basics_dev/system-doc.md new file mode 100644 index 00000000..110e7fb7 --- /dev/null +++ b/basics_dev/system-doc.md @@ -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 +--- + diff --git a/developers/usability-ux.md b/basics_dev/usability-ux.md similarity index 50% rename from developers/usability-ux.md rename to basics_dev/usability-ux.md index 6d32472e..b8762d0e 100644 --- a/developers/usability-ux.md +++ b/basics_dev/usability-ux.md @@ -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.
Interfaces Should Not
-- 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.
Interfaces Should @@ -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!
Avoid Acronyms
-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. +
Use Simple Words
-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. - ---
@@ -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.
Use Common Concepts @@ -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 Avoid Duplicate Words
-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.
Create Groups & Categories
-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.
- Don't Leave Users Stranded + Don't Leave Users Stranded
-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: +
- Offer Actionable Solutions + Offer Actionable Solutions
-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. ---
- Avoid Repetitive Tasks + Minimize Repetitive Steps
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. - -
- Minimize Repetitive Steps -
+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 diff --git a/basics_user/contributing.md b/basics_user/contributing.md new file mode 100644 index 00000000..d0915fc3 --- /dev/null +++ b/basics_user/contributing.md @@ -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/ + diff --git a/developers/doc-guidelines.md b/basics_user/doc-guidelines.md similarity index 75% rename from developers/doc-guidelines.md rename to basics_user/doc-guidelines.md index 53d42246..c9d91852 100644 --- a/developers/doc-guidelines.md +++ b/basics_user/doc-guidelines.md @@ -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 diff --git a/basics_user/reporting-bugs.md b/basics_user/reporting-bugs.md new file mode 100644 index 00000000..7cd31084 --- /dev/null +++ b/basics_user/reporting-bugs.md @@ -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 + diff --git a/basics_user/testing.md b/basics_user/testing.md new file mode 100644 index 00000000..2ac14ca2 --- /dev/null +++ b/basics_user/testing.md @@ -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 or 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/ + diff --git a/basics_user/user-faq.md b/basics_user/user-faq.md new file mode 100644 index 00000000..350416e9 --- /dev/null +++ b/basics_user/user-faq.md @@ -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 WorksTM :) + +### 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 `` with your device, for example `00:1c.2`: + + echo 0000: > /sys/bus/pci/drivers/pciback/unbind + MODALIAS=`cat /sys/bus/pci/devices/0000:/modalias` + MOD=`modprobe -R $MODALIAS | head -n 1` + echo 0000: > /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. diff --git a/building/building-archlinux-template.md b/building/building-archlinux-template.md new file mode 100644 index 00000000..a13d6378 --- /dev/null +++ b/building/building-archlinux-template.md @@ -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. +
+
+![arch-template-01](/attachment/wiki/ArchlinuxTemplate/arch-template-01.png) +
+
+* Ensure there is at least 25GB preferably 30GB of free space in the private storage. I made the private storage 30GB to be safe. +
+
+![arch-template-02](/attachment/wiki/ArchlinuxTemplate/arch-template-02.png) +
+
+ +*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 +
+
+![arch-template-03](/attachment/wiki/ArchlinuxTemplate/arch-template-03.png) +
+
+ +## 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** +
+
+![arch-template-04](/attachment/wiki/ArchlinuxTemplate/arch-template-04.png) +
+
+ +## 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…. +
+
+![arch-template-06](/attachment/wiki/ArchlinuxTemplate/arch-template-06.png) +
+
+ * 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. +
+
+![arch-template-07](/attachment/wiki/ArchlinuxTemplate/arch-template-07.png) +
+
+
+ +## 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** +
+
+![arch-template-08](/attachment/wiki/ArchlinuxTemplate/arch-template-08.png) +
+
+ * 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**' +
+
+![arch-template-09](/attachment/wiki/ArchlinuxTemplate/arch-template-09.png) +
+
+ + * 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**' +
+
+![arch-template-10](/attachment/wiki/ArchlinuxTemplate/arch-template-10.png) +
+
+ + * 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**' +
+
+![arch-template-11](/attachment/wiki/ArchlinuxTemplate/arch-template-11.png) +
+
+ + * Screen "**Choose Repos To Use To Build Packages**" + + * Select 'QubesOS/qubes- Stable - Default Repo' + * Select '**OK**' Press '**Enter**' +
+
+![arch-template-12](/attachment/wiki/ArchlinuxTemplate/arch-template-12.png) +
+
+ + * Screen "**Build Template Only?**" + + * Select '**Yes**' Press '**Enter**' +
+
+![arch-template-12](/attachment/wiki/ArchlinuxTemplate/arch-template-12a.png) +
+
+ + * 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** +
+
+![arch-template-13](/attachment/wiki/ArchlinuxTemplate/arch-template-13.png) +
+
+ + * Screen '**Get sources**' wants to download additional packages needed for the choosen plugin/s. + + * Select '**Yes**' Press '**Enter**' +
+
+![arch-template-14](/attachment/wiki/ArchlinuxTemplate/arch-template-14.png) +
+
+ + * Then wait for download to finish and press '**OK**' +
+
+![arch-template-14](/attachment/wiki/ArchlinuxTemplate/arch-template-15.png) +
+
+ + * 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**' +
+
+![arch-template-16](/attachment/wiki/ArchlinuxTemplate/arch-template-16.png) +
+
+ + *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* +
+
+![arch-template-17](/attachment/wiki/ArchlinuxTemplate/arch-template-17.png) +
+
+ +## 7: Install all the dependencies + +*Note: make sure you are in the “qubes-builder” directory to run the following cmds* + +* **$ make install-deps** +
+
+![arch-template-18](/attachment/wiki/ArchlinuxTemplate/arch-template-18.png) +
+
+ +## 8: Get all the require sources for the build: (Note: this may take some time) + +* **$ make get-sources** +
+
+![arch-template-19](/attachment/wiki/ArchlinuxTemplate/arch-template-19.png) +
+
+
+ +## 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** +
+
+![arch-template-20](/attachment/wiki/ArchlinuxTemplate/arch-template-20.png) +
+
+ + + * 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** +
+
+ + +## 10: Make the actual Archlinux template + +* **$ make template** +
+
+![arch-template-21](/attachment/wiki/ArchlinuxTemplate/arch-template-21.png) +
+
+ +## 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) +
+
+![arch-template-22](/attachment/wiki/ArchlinuxTemplate/arch-template-22.png) +
+
+ +* **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 '**.**' '**Templates** (correct) vs **templates** (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** + +
+
+![arch-template-23](/attachment/wiki/ArchlinuxTemplate/arch-template-23.png) +
+
+![arch-template-24](/attachment/wiki/ArchlinuxTemplate/arch-template-24.png) +
+
+ +* 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 \: + +`` + +to + +`` + +## 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 +``` + +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) + +
diff --git a/developers/building/building-non-fedora-template.md b/building/building-non-fedora-template.md similarity index 90% rename from developers/building/building-non-fedora-template.md rename to building/building-non-fedora-template.md index 5fd85d46..7dea47dc 100644 --- a/developers/building/building-non-fedora-template.md +++ b/building/building-non-fedora-template.md @@ -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...) diff --git a/developers/building/development-workflow.md b/building/development-workflow.md similarity index 99% rename from developers/building/development-workflow.md rename to building/development-workflow.md index f9e8cea9..4ddce81f 100644 --- a/developers/building/development-workflow.md +++ b/building/development-workflow.md @@ -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 diff --git a/developers/building/qubes-builder-details.md b/building/qubes-builder-details.md similarity index 100% rename from developers/building/qubes-builder-details.md rename to building/qubes-builder-details.md diff --git a/developers/building/qubes-builder.md b/building/qubes-builder.md similarity index 79% rename from developers/building/qubes-builder.md rename to building/qubes-builder.md index 545ae968..3fd1815f 100644 --- a/developers/building/qubes-builder.md +++ b/building/qubes-builder.md @@ -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: diff --git a/developers/building/qubes-r3-building.md b/building/qubes-r3-building.md similarity index 100% rename from developers/building/qubes-r3-building.md rename to building/qubes-r3-building.md diff --git a/common-tasks/backup-emergency-restore-v4.md b/common-tasks/backup-emergency-restore-v4.md new file mode 100644 index 00000000..3b94a75a --- /dev/null +++ b/common-tasks/backup-emergency-restore-v4.md @@ -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 + diff --git a/common-tasks/backup-restore.md b/common-tasks/backup-restore.md index fa48ffec..0b2ecaa7 100644 --- a/common-tasks/backup-restore.md +++ b/common-tasks/backup-restore.md @@ -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 ----- diff --git a/common-tasks/copy-from-dom0.md b/common-tasks/copy-from-dom0.md index fd263cc5..524b553a 100644 --- a/common-tasks/copy-from-dom0.md +++ b/common-tasks/copy-from-dom0.md @@ -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 diff --git a/common-tasks/copy-paste.md b/common-tasks/copy-paste.md index 25a527e3..f191b9ef 100644 --- a/common-tasks/copy-paste.md +++ b/common-tasks/copy-paste.md @@ -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 -------------------------------------- diff --git a/common-tasks/copying-files.md b/common-tasks/copying-files.md index 2fcb9980..392310a6 100644 --- a/common-tasks/copying-files.md +++ b/common-tasks/copying-files.md @@ -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) diff --git a/common-tasks/dispvm.md b/common-tasks/dispvm.md index 1f5af78c..18560ff8 100644 --- a/common-tasks/dispvm.md +++ b/common-tasks/dispvm.md @@ -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) ------------------------------------------- diff --git a/common-tasks/full-screen-mode.md b/common-tasks/full-screen-mode.md index 924d0715..b0fef0cc 100644 --- a/common-tasks/full-screen-mode.md +++ b/common-tasks/full-screen-mode.md @@ -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)) diff --git a/common-tasks/managing-appvm-shortcuts.md b/common-tasks/managing-appvm-shortcuts.md index 8f75dd85..e289ae79 100644 --- a/common-tasks/managing-appvm-shortcuts.md +++ b/common-tasks/managing-appvm-shortcuts.md @@ -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. diff --git a/common-tasks/software-update-dom0.md b/common-tasks/software-update-dom0.md index c9bd1dcb..74d14336 100644 --- a/common-tasks/software-update-dom0.md +++ b/common-tasks/software-update-dom0.md @@ -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 - ~~~ -### Kernel Upgrade ### +### Testing repositories -Install newer kernel. The following example installs kernel 3.19 and was tested on Qubes R3 RC1. +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=` +option. Example commands: ~~~ -sudo qubes-dom0-update kernel-3.19* +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 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 --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/). diff --git a/common-tasks/software-update-vm.md b/common-tasks/software-update-vm.md index 7811c416..b205980a 100644 --- a/common-tasks/software-update-vm.md +++ b/common-tasks/software-update-vm.md @@ -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=` +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 OverTM. 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 OverTM. 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 -------------- diff --git a/common-tasks/tips-and-tricks.md b/common-tasks/tips-and-tricks.md new file mode 100644 index 00000000..64673eee --- /dev/null +++ b/common-tasks/tips-and-tricks.md @@ -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) diff --git a/common-tasks/usb.md b/common-tasks/usb.md index d6e7ec4c..dfddc3ed 100644 --- a/common-tasks/usb.md +++ b/common-tasks/usb.md @@ -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 @@ -44,7 +216,7 @@ follows: 1. Insert your USB drive. 2. In a dom0 console (running as a normal user), list all available block - devices: + devices: qvm-block -l @@ -64,9 +236,9 @@ 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 + qvm-block -a personal dom0:sdb This will attach the device to the qube as `/dev/xvdi` if that name is not already taken by another attached device, or `/dev/xvdj`, etc. @@ -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 + qvm-block -d + + or + + qvm-block -d 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 diff --git a/configuration/assigning-devices.md b/configuration/assigning-devices.md index 83cfd540..6aa8278a 100644 --- a/configuration/assigning-devices.md +++ b/configuration/assigning-devices.md @@ -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 diff --git a/configuration/config-files.md b/configuration/config-files.md index faa5695b..d83c2a19 100644 --- a/configuration/config-files.md +++ b/configuration/config-files.md @@ -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. diff --git a/configuration/disk-trim.md b/configuration/disk-trim.md index 932c316d..cbb67259 100644 --- a/configuration/disk-trim.md +++ b/configuration/disk-trim.md @@ -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: diff --git a/configuration/external-device-mount-point.md b/configuration/external-device-mount-point.md deleted file mode 100644 index e37e64b3..00000000 --- a/configuration/external-device-mount-point.md +++ /dev/null @@ -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. diff --git a/configuration/fetchmail.md b/configuration/fetchmail.md index 9d4d8206..0bdd128e 100644 --- a/configuration/fetchmail.md +++ b/configuration/fetchmail.md @@ -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 ~~~ diff --git a/configuration/http-filtering-proxy.md b/configuration/http-filtering-proxy.md index cd6de109..8bb5f10c 100644 --- a/configuration/http-filtering-proxy.md +++ b/configuration/http-filtering-proxy.md @@ -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 diff --git a/configuration/managing-vm-kernel.md b/configuration/managing-vm-kernel.md index 61a27be5..6748228f 100644 --- a/configuration/managing-vm-kernel.md +++ b/configuration/managing-vm-kernel.md @@ -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 # replace this 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 @@ -298,7 +320,9 @@ 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. +start kernel configured within VM. + +When starting the VM you can safely ignore any warnings about a missing module 'dummy-hcd' ### Troubleshooting diff --git a/configuration/multiboot.md b/configuration/multiboot.md index 01a77d18..3cba4ec7 100644 --- a/configuration/multiboot.md +++ b/configuration/multiboot.md @@ -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 diff --git a/configuration/mutt.md b/configuration/mutt.md index 879e9753..eae19b32 100644 --- a/configuration/mutt.md +++ b/configuration/mutt.md @@ -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 diff --git a/configuration/postfix.md b/configuration/postfix.md index d4565edf..0bde2398 100644 --- a/configuration/postfix.md +++ b/configuration/postfix.md @@ -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. diff --git a/configuration/resize-disk-image.md b/configuration/resize-disk-image.md index 9b7d0443..6458b7f3 100644 --- a/configuration/resize-disk-image.md +++ b/configuration/resize-disk-image.md @@ -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. diff --git a/configuration/rxvt.md b/configuration/rxvt.md index b9248654..2031dd4d 100644 --- a/configuration/rxvt.md +++ b/configuration/rxvt.md @@ -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' diff --git a/configuration/salt.md b/configuration/salt.md index d1da491e..497c1929 100644 --- a/configuration/salt.md +++ b/configuration/salt.md @@ -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 diff --git a/configuration/secondary-storage.md b/configuration/secondary-storage.md index a4314bbe..f04b6665 100644 --- a/configuration/secondary-storage.md +++ b/configuration/secondary-storage.md @@ -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 diff --git a/configuration/vpn.md b/configuration/vpn.md index 94ae2060..41bd81d9 100644 --- a/configuration/vpn.md +++ b/configuration/vpn.md @@ -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`. - - 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`). - - It also contains a line `remote X.X.X.X 1194`, where `X.X.X.X` is the ip of your openvpn server. - - 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). - - 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. - - 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. - - -3. Setup iptables: - Edit `/rw/config/qubes-firewall-user-script` and add: - - `iptables -P OUTPUT DROP` - This blocks all outgoing traffic, if not specified otherwise. - `iptables -I OUTPUT -o $DEV -j ACCEPT` - This allows the local system to connect through the vpn (you dont need this). + 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. - `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. + 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`. - `iptables -I OUTPUT -o lo -j ACCEPT` - This allows connections from the system to the system. + You may also wish to install `nano` or another simple text editor for entering the scripts below. - `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). +2. Set up and test the VPN client. - `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) + Make sure the VPN VM and its template VM are not running. + + 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/...'. - Now save `/rw/config/qubes-firewall-user-script` and make it executable: + 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 ` is recommended. + + __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 + ``` + + 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. + + Proceed to the next step when you're sure the basic VPN connection is working. + +3. Create the DNS-handling script. + Use `sudo nano /rw/config/vpn/qubes-vpn-handler.sh` to edit and add: + + ~~~ + #!/bin/bash + set -e + export PATH="$PATH:/usr/sbin:/sbin" + + case "$1" in + + 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 + + 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` + +5. Set up the VPN's autostart. + + Use `sudo nano /rw/config/rc.local` to clear out the existing lines and add: + + ~~~ + #!/bin/bash + VPN_CLIENT='openvpn' + VPN_OPTIONS='--cd /rw/config/vpn/ --config openvpn-client.ovpn --daemon' -4. Setup the vpn's autostart: - Edit to `/rw/config/rc.local`, make it executable (`sudo chmod +x /rw/config/rc.local`) and add: + su - -c 'notify-send "$(hostname): Starting $VPN_CLIENT..." --icon=network-idle' user + groupadd -rf qvpn ; sleep 2s + sg qvpn -c "$VPN_CLIENT $VPN_OPTIONS" + ~~~ + + Change the `VPN_CLIENT` and `VPN_OPTIONS` variables to match your VPN software. - ln -s /home/user/vpn.cfg /etc/openvpn/vpn.conf; - systemctl --no-block start openvpn@vpn.service; + 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. -5. Configure your AppVMs to use the new VM as a NetVM. +Usage +----- - ![Settings-NetVM.png](/attachment/wiki/VPN/Settings-NetVM.png) +Configure your AppVMs to use the VPN VM as a NetVM... -6. Optionally, you can install some [custom icons](https://github.com/Zrubi/qubes-artwork-proxy-vpn) for your VPN +![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 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. diff --git a/customization/bind-dirs.md b/customization/bind-dirs.md new file mode 100644 index 00000000..8ce2c986 --- /dev/null +++ b/customization/bind-dirs.md @@ -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) + diff --git a/customization/dark-theme.md b/customization/dark-theme.md new file mode 100644 index 00000000..5599a848 --- /dev/null +++ b/customization/dark-theme.md @@ -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` diff --git a/customization/dispvm-customization.md b/customization/dispvm-customization.md index b5498295..9c3be657 100644 --- a/customization/dispvm-customization.md +++ b/customization/dispvm-customization.md @@ -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 + [user@dom0 ~]$ qvm-create-default-dvm 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 **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 `arbitrary.desktop` line so that your modified file looks like this: + + + qubes-dispvm-firefox.desktop + qubes-dispvm-xterm.desktop + arbitrary.desktop + + +After saving the changes the new shortcut should appear in the Disposable VM Applications menu. diff --git a/customization/fedora-minimal-template-customization.md b/customization/fedora-minimal-template-customization.md index b4c3da80..0a186f67 100644 --- a/customization/fedora-minimal-template-customization.md +++ b/customization/fedora-minimal-template-customization.md @@ -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 diff --git a/customization/i3.md b/customization/i3.md index 00d17801..9178fccf 100644 --- a/customization/i3.md +++ b/customization/i3.md @@ -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 diff --git a/customization/kde.md b/customization/kde.md index bbba0dcf..cee094a6 100644 --- a/customization/kde.md +++ b/customization/kde.md @@ -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 ----------------- diff --git a/customization/language-localization.md b/customization/language-localization.md index 65287741..81f327fb 100644 --- a/customization/language-localization.md +++ b/customization/language-localization.md @@ -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`). - -4. Close and shut down the TemplateVM. - -5. Restart an AppVM which inherits from the template and open a terminal. +3. Restart an AppVM which based on the template you installed `ibus-pinyin` and open a terminal. -6. Issue `ibus-setup`. +4. Run `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). diff --git a/customization/windows-template-customization.md b/customization/windows-template-customization.md index 3c4a773f..78387a09 100644 --- a/customization/windows-template-customization.md +++ b/customization/windows-template-customization.md @@ -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 diff --git a/customization/xfce.md b/customization/xfce.md index 60370e65..64eb5c53 100644 --- a/customization/xfce.md +++ b/customization/xfce.md @@ -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). diff --git a/developers/debugging/automated-tests.md b/debugging/automated-tests.md similarity index 67% rename from developers/debugging/automated-tests.md rename to debugging/automated-tests.md index 1013dd6d..246410d6 100644 --- a/developers/debugging/automated-tests.md +++ b/debugging/automated-tests.md @@ -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` +### Editing the Makefile +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 ( diff --git a/developers/debugging/profiling.md b/debugging/profiling.md similarity index 100% rename from developers/debugging/profiling.md rename to debugging/profiling.md diff --git a/debugging/safe-remote-ttys.md b/debugging/safe-remote-ttys.md new file mode 100644 index 00000000..0568df6d --- /dev/null +++ b/debugging/safe-remote-ttys.md @@ -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' /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"' \ + /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. diff --git a/developers/debugging/test-bench.md b/debugging/test-bench.md similarity index 100% rename from developers/debugging/test-bench.md rename to debugging/test-bench.md diff --git a/debugging/vm-interface.md b/debugging/vm-interface.md new file mode 100644 index 00000000..4b643bfe --- /dev/null +++ b/debugging/vm-interface.md @@ -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. diff --git a/developers/debugging/windows-debugging.md b/debugging/windows-debugging.md similarity index 96% rename from developers/debugging/windows-debugging.md rename to debugging/windows-debugging.md index 141a643d..bcd052a5 100644 --- a/developers/debugging/windows-debugging.md +++ b/debugging/windows-debugging.md @@ -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. diff --git a/developers/building/building-archlinux-template.md b/developers/building/building-archlinux-template.md deleted file mode 100644 index afb574dc..00000000 --- a/developers/building/building-archlinux-template.md +++ /dev/null @@ -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 \: - -~~~ - -~~~ - -to - -~~~ - -~~~ - -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 -~~~ - -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 -~~~ diff --git a/developers/building/kde-dom0.md b/developers/building/kde-dom0.md deleted file mode 100644 index 5e0a9bbc..00000000 --- a/developers/building/kde-dom0.md +++ /dev/null @@ -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 diff --git a/developers/building/pvusb.md b/developers/building/pvusb.md deleted file mode 100644 index 790decd4..00000000 --- a/developers/building/pvusb.md +++ /dev/null @@ -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 - diff --git a/developers/contributing.md b/developers/contributing.md deleted file mode 100644 index e3cf2d38..00000000 --- a/developers/contributing.md +++ /dev/null @@ -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). diff --git a/developers/debugging/vm-interface.md b/developers/debugging/vm-interface.md deleted file mode 100644 index 7f801102..00000000 --- a/developers/debugging/vm-interface.md +++ /dev/null @@ -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. diff --git a/developers/devel-books.md b/developers/devel-books.md deleted file mode 100644 index 8f738a5f..00000000 --- a/developers/devel-books.md +++ /dev/null @@ -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) - diff --git a/developers/devel-faq.md b/developers/devel-faq.md deleted file mode 100644 index 76be513b..00000000 --- a/developers/devel-faq.md +++ /dev/null @@ -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/). diff --git a/developers/fundamentals/networking.md b/developers/fundamentals/networking.md deleted file mode 100644 index d11bc5b8..00000000 --- a/developers/fundamentals/networking.md +++ /dev/null @@ -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 diff --git a/developers/license.md b/developers/license.md deleted file mode 100644 index 1b0c8bf0..00000000 --- a/developers/license.md +++ /dev/null @@ -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. diff --git a/developers/reporting-bugs.md b/developers/reporting-bugs.md deleted file mode 100644 index 98f8c0b1..00000000 --- a/developers/reporting-bugs.md +++ /dev/null @@ -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) diff --git a/developers/system-doc.md b/developers/system-doc.md deleted file mode 100644 index 5f4cb4a3..00000000 --- a/developers/system-doc.md +++ /dev/null @@ -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/) - - diff --git a/doc.md b/doc.md index 4d77fd14..8fb3241c 100644 --- a/doc.md +++ b/doc.md @@ -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/) + diff --git a/hardware/certified-hardware.md b/hardware/certified-hardware.md new file mode 100644 index 00000000..4049810f --- /dev/null +++ b/hardware/certified-hardware.md @@ -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 + diff --git a/hardware/certified-laptops.md b/hardware/certified-laptops.md deleted file mode 100644 index 4bd061b6..00000000 --- a/hardware/certified-laptops.md +++ /dev/null @@ -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/ - - diff --git a/hardware/hcl.md b/hardware/hcl.md index a696cf8d..b48b9f94 100644 --- a/hardware/hcl.md +++ b/hardware/hcl.md @@ -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 `, where `` 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 `, where `` 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 - `. - 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 - `. +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. diff --git a/hardware/system-requirements.md b/hardware/system-requirements.md index 911e0014..c7b89e46 100644 --- a/hardware/system-requirements.md +++ b/hardware/system-requirements.md @@ -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 diff --git a/installing/custom-install.md b/installing/custom-install.md new file mode 100644 index 00000000..56c540c3 --- /dev/null +++ b/installing/custom-install.md @@ -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- 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- crypt + ├──qubes_dom0-root lvm / + └──qubes_dom0-swap lvm [SWAP] + sdb disk + ├──sdb1 part + │ └──md0 raid1 /boot + └──sdb2 part + └──md1 raid1 + └──luks- 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 + + # fdisk /dev/sdb + + +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 luksFormat + + 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 + + For example: + + # cryptsetup luksDump /dev/sda2 + diff --git a/installing/install-security.md b/installing/install-security.md index d41c60f7..e82d65b3 100644 --- a/installing/install-security.md +++ b/installing/install-security.md @@ -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/ diff --git a/installing/installation-guide.md b/installing/installation-guide.md index 761b5cb0..bb7b4a80 100644 --- a/installing/installation-guide.md +++ b/installing/installation-guide.md @@ -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/ diff --git a/installing/live-usb.md b/installing/live-usb.md index ad630bfb..6e629962 100644 --- a/installing/live-usb.md +++ b/installing/live-usb.md @@ -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 @@ -74,7 +78,7 @@ Live USB variant: Current limitations ------------------- -(Remember that Qubes Live USB is currently in alpha, so please meter your +(Remember that Qubes Live USB is currently in alpha, so please meter your expectations accordingly.) 1. Currently just the 3 example VMs (untrusted, personal, work), plus the @@ -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/ diff --git a/installing/models/lenovo-w540.md b/installing/models/lenovo-w540.md deleted file mode 100644 index fed5958c..00000000 --- a/installing/models/lenovo-w540.md +++ /dev/null @@ -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.) diff --git a/installing/supported-versions.md b/installing/supported-versions.md index a68399c0..ab6a65f0 100644 --- a/installing/supported-versions.md +++ b/installing/supported-versions.md @@ -4,37 +4,51 @@ title: Supported Versions permalink: /doc/supported-versions/ --- - - Supported Versions ================== Qubes OS -------- Qubes OS releases are supported for **six months** after each subsequent major -or minor release. 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 4.0 | TBA | TBA | In development | +| 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, 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/ + diff --git a/installing/upgrade/upgrade-to-r2.md b/installing/upgrade/upgrade-to-r2.md index 613dbfc7..a572d1eb 100644 --- a/installing/upgrade/upgrade-to-r2.md +++ b/installing/upgrade/upgrade-to-r2.md @@ -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. diff --git a/installing/upgrade/upgrade-to-r2b2.md b/installing/upgrade/upgrade-to-r2b2.md index a6bfc8b0..a3d37ee9 100644 --- a/installing/upgrade/upgrade-to-r2b2.md +++ b/installing/upgrade/upgrade-to-r2b2.md @@ -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 ------------ diff --git a/installing/upgrade/upgrade-to-r3.0.md b/installing/upgrade/upgrade-to-r3.0.md index fa922053..35c6c8fd 100644 --- a/installing/upgrade/upgrade-to-r3.0.md +++ b/installing/upgrade/upgrade-to-r3.0.md @@ -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 diff --git a/installing/upgrade/upgrade-to-r3.1.md b/installing/upgrade/upgrade-to-r3.1.md index 46917339..b69852f8 100644 --- a/installing/upgrade/upgrade-to-r3.1.md +++ b/installing/upgrade/upgrade-to-r3.1.md @@ -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: diff --git a/installing/upgrade/upgrade-to-r3.2.md b/installing/upgrade/upgrade-to-r3.2.md new file mode 100644 index 00000000..fa2db98a --- /dev/null +++ b/installing/upgrade/upgrade-to-r3.2.md @@ -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. + + diff --git a/installing/upgrade/upgrade.md b/installing/upgrade/upgrade.md index 48ba3f50..b3297a19 100644 --- a/installing/upgrade/upgrade.md +++ b/installing/upgrade/upgrade.md @@ -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/) diff --git a/installing/verifying-signatures.md b/installing/verifying-signatures.md deleted file mode 100644 index cc2dc875..00000000 --- a/installing/verifying-signatures.md +++ /dev/null @@ -1,201 +0,0 @@ ---- -layout: doc -title: Verifying Signatures -permalink: /doc/verifying-signatures/ -redirect_from: -- /en/doc/verifying-signatures/ -- /doc/VerifyingSignatures/ -- /wiki/VerifyingSignatures/ ---- - -On Digital Signatures and Key Verification -========================================== - -What Digital Signatures Can and Cannot Prove --------------------------------------------- - -Most people – even programmers – are confused about the basic concepts underlying digital signatures. Therefore, most people should read this section, even if it looks trivial at first sight. - -Digital signatures can prove both **authenticity** and **integrity** to a reasonable degree of certainty. **Authenticity** ensures that a given file was indeed created by the person who signed it (i.e., that it was not forged by a third party). **Integrity** ensures that the contents of the file have not been tampered with (i.e., that a third party has not undetectably altered its contents *en route*). - -Digital signatures **cannot** prove any other property, e.g., that the signed file is not malicious. In fact, there is nothing that could stop someone from signing a malicious program (and it happens from time to time in reality). - -The point is, of course, that people must choose who they will trust (e.g., Linus Torvalds, Microsoft, the Qubes Project, etc.) and assume that if a given file was signed by a trusted party, then it should not be malicious or buggy in some horrible way. But the decision of whether to trust any given party is beyond the scope of digital signatures. It's more of a sociological and political decision. - -Once we make the decision to trust certain parties, digital signatures are useful, because they make it possible for us to limit our trust only to those few parties we choose and not to worry about all the "Bad Things That Can Happen In The Middle" between us and them, e.g., server compromises (qubes-os.org will surely be compromised one day), dishonest IT staff at the hosting company, dishonest staff at the ISPs, Wi-Fi attacks, etc. - -By verifying all the files we download which purport to be authored by a party we've chosen to trust, we eliminate concerns about the bad things discussed above, since we can easily detect whether any files have been tampered with (and subsequently choose to refrain from executing, installing, or opening them). - -However, for digital signatures to make any sense, we must ensure that the public keys we use for signature verification are indeed the original ones. Anybody can generate a GPG key pair that purports to belong to "The Qubes Project," but of course only the key pair that we (i.e., the Qubes developers) generated is the legitimate one. The next section explains how to verify the validity of the Qubes signing keys. - -Importing Qubes Signing Keys ----------------------------- - -Every file published by the Qubes Project (ISO, RPM, TGZ files and git repositories) is digitally signed by one of the developer or release signing keys. Each such key is signed by the Qubes Master Signing Key ([`0x36879494`](https://keys.qubes-os.org/keys/qubes-master-signing-key.asc)). - -The public portion of the Qubes Master Signing Key can be imported directly from a [ keyserver](https://en.wikipedia.org/wiki/Key_server_%28cryptographic%29#Keyserver_examples) (specified on first use with --keyserver URI, keyserver saved in `~/.gnupg/gpg.conf`), e.g., - - gpg --keyserver pool.sks-keyservers.net --recv-keys 0x427F11FD0FAA4B080123F01CDDFA1A3E36879494 - -or downloaded [here](https://keys.qubes-os.org/keys/qubes-master-signing-key.asc) and imported with gpg, - - $ gpg --import ./qubes-master-signing-key.asc - -or fetched directly with gpg. - - $ gpg --fetch-keys https://keys.qubes-os.org/keys/qubes-master-signing-key.asc - -For additional security we also publish the fingerprint of the Qubes Master Signing Key ([`0x36879494`](https://keys.qubes-os.org/keys/qubes-master-signing-key.asc)) here in this document: - - pub 4096R/36879494 2010-04-01 - Key fingerprint = 427F 11FD 0FAA 4B08 0123 F01C DDFA 1A3E 3687 9494 - uid Qubes Master Signing Key - -There should also be a copy of this key at the project's main website, in the [Qubes Security Pack](/doc/security-pack/), and in the archives of the project's [developer](https://groups.google.com/forum/#!msg/qubes-devel/RqR9WPxICwg/kaQwknZPDHkJ) and [user](https://groups.google.com/d/msg/qubes-users/CLnB5uFu_YQ/ZjObBpz0S9UJ) mailing lists. - -Once you have obtained the Qubes Master Signing Key ([`0x36879494`](https://keys.qubes-os.org/keys/qubes-master-signing-key.asc)), you should verify the fingerprint of this key very carefully by obtaining copies of the fingerprint from trustworthy independent sources and comparing them to the downloaded key's fingerprint to ensure they match. Then set its trust level to "ultimate" (oh, well), so that it can be used to automatically verify all the keys signed by the Qubes Master Signing Key: - - - $ gpg --edit-key 0x36879494 - gpg (GnuPG) 1.4.18; Copyright (C) 2014 Free Software Foundation, Inc. - This is free software: you are free to change and redistribute it. - There is NO WARRANTY, to the extent permitted by law. - - - pub 4096R/36879494 created: 2010-04-01 expires: never usage: SC - trust: unknown validity: unknown - [ unknown] (1). Qubes Master Signing Key - - gpg> fpr - pub 4096R/36879494 2010-04-01 Qubes Master Signing Key - Primary key fingerprint: 427F 11FD 0FAA 4B08 0123 F01C DDFA 1A3E 3687 9494 - - gpg> trust - pub 4096R/36879494 created: 2010-04-01 expires: never usage: SC - trust: unknown validity: unknown - [ unknown] (1). Qubes Master Signing Key - - Please decide how far you trust this user to correctly verify other users' keys - (by looking at passports, checking fingerprints from different sources, etc.) - - 1 = I don't know or won't say - 2 = I do NOT trust - 3 = I trust marginally - 4 = I trust fully - 5 = I trust ultimately - m = back to the main menu - - Your decision? 5 - Do you really want to set this key to ultimate trust? (y/N) y - - pub 4096R/36879494 created: 2010-04-01 expires: never usage: SC - trust: ultimate validity: unknown - [ unknown] (1). Qubes Master Signing Key - Please note that the shown key validity is not necessarily correct - unless you restart the program. - - gpg> q - -Now you can easily download any of the developer or release signing keys that happen to be used to sign particular ISO, RPM, TGZ files or git tags. - -For example: Qubes OS Release 2 Signing Key ([`0x0A40E458`](https://keys.qubes-os.org/keys/qubes-release-2-signing-key.asc)) is used for all Release 2 ISO images. - - $ gpg --recv-keys 0x3F01DEF49719158EF86266F80C73B9D40A40E458 - gpg: requesting key 0A40E458 from hkp server keys.gnupg.net - gpg: key 0A40E458: public key "Qubes OS Release 2 Signing Key" imported - gpg: 3 marginal(s) needed, 1 complete(s) needed, PGP trust model - gpg: depth: 0 valid: 1 signed: 1 trust: 0-, 0q, 0n, 0m, 0f, 1u - gpg: depth: 1 valid: 1 signed: 0 trust: 1-, 0q, 0n, 0m, 0f, 0u - gpg: Total number processed: 1 - gpg: imported: 1 (RSA: 1) - -You can also download all the currently used developers' signing keys and current and older release signing keys (and also a copy of the Qubes Master Signing Key) from the [keys directory on our server](https://keys.qubes-os.org/keys/) and from the [Qubes Security Pack](/doc/security-pack/). - -The developer signing keys are set to be valid for 1 year only, while the Qubes Master Signing Key ([`0x36879494`](https://keys.qubes-os.org/keys/qubes-master-signing-key.asc)) has no expiration date. This latter key was generated and is kept only within a dedicated, air-gapped "vault" machine, and the private portion will (hopefully) never leave this isolated machine. - -You can now verify the ISO image (`Qubes-R2-x86_64-DVD.iso`) matches its signature (`Qubes-R2-x86_64-DVD.iso.asc`): - - $ gpg -v --verify Qubes-R2-x86_64-DVD.iso.asc Qubes-R2-x86_64-DVD.iso - gpg: armor header: Version: GnuPG v1 - gpg: assuming signed data in `Qubes-R2-x86_64-DVD.iso' - gpg: Signature made Tue Sep 23 08:38:40 2014 UTC using RSA key ID 0A40E458 - gpg: using PGP trust model - gpg: Good signature from "Qubes OS Release 2 Signing Key" - gpg: binary signature, digest algorithm SHA1 - -The Release 2 Signing Key ([`0x0A40E458`](https://keys.qubes-os.org/keys/qubes-release-2-signing-key.asc)) used to sign this ISO image should be signed by the Qubes Master Signing Key ([`0x36879494`](https://keys.qubes-os.org/keys/qubes-master-signing-key.asc)): - - $ gpg --list-sig 0A40E458 - pub 4096R/0A40E458 2012-11-15 - uid Qubes OS Release 2 Signing Key - sig 36879494 2012-11-15 Qubes Master Signing Key - sig 3 0A40E458 2012-11-15 Qubes OS Release 2 Signing Key - -Having problems verifying the ISO images? Make sure you have the corresponding release signing key and see this thread: - -[https://groups.google.com/group/qubes-devel/browse\_thread/thread/4bdec1cd19509b38/9f8e219c41e1b232](https://groups.google.com/group/qubes-devel/browse_thread/thread/4bdec1cd19509b38/9f8e219c41e1b232) - -Verifying Digests ------------------ - -Each ISO is accompanied by a plain text file ending in `.DIGESTS`. This file contains the output of running several different crytographic hash functions on the ISO in order to obtain alphanumeric outputs known as "digests." For example, `Qubes-R2-x86_64-DVD.iso` is accompanied by `Qubes-R2-x86_64-DVD.iso.DIGESTS` which has the following content: - - -----BEGIN PGP SIGNED MESSAGE----- - Hash: SHA256 - - 6f6ff24f2edec3a7607671001e694d8e *Qubes-R2-x86_64-DVD.iso - 0344e04a98b741c311936f3e2bb67fcebfc2be08 *Qubes-R2-x86_64-DVD.iso - 1fa056b73d8e2e93acdf3dcaface2515d61335e723d1d7d338241209119c10a3 *Qubes-R2-x86_64-DVD.iso - a49ff19c1ad8c51a50198ac51670cf7c71972b437fa59f2e9fc9432cce76f4529f10de1d576ac777cdd49b9325eb2f32347fd13e0f9b04f823a73e84c6ddd772 *Qubes-R2-x86_64-DVD.iso - -----BEGIN PGP SIGNATURE----- - Version: GnuPG v1 - - iQIcBAEBCAAGBQJVvUfGAAoJEAxzudQKQORYhj0P/1TTtDn0WtlfwvSOQ5m3ybeT - CiEv/wWZmZR2hfTOs1chlwt5PZFUCkAk6hbr7+AbJU3HurnmyK97ORtak0WcuBiO - 3MWKGiDaBGjKfYcv7YZWDcMRCjN69I4gq7lhXB2JC5pSnOkciD8xzSMAnyFz8Dnh - sHSGJIrOIeLhj0Jt90NGm2CKeQgKrbCGQWWqn/BRf40GXjkyGDSAj+Bsbnpn3LjE - kWOblX631PRi8eclD27/b5hsK/ur7RlpA0KKn7dJoTO2PikEZRoT7QgcIMxYWOja - GZhDi/5gWyttVmF1EszkwaYLAH3uqkZbgKHIsLwweTwXYxMqjobQ5dFkm0RCaXXg - wf/ayfyAIHCWYK0GvyHyAe7hs30UQ4Ssw0LDnnTsOwJYzxZpZqWhcg89EBMGdNgu - 5sghcj97VHjDI/zpRyTOAi1+8ZoG1FMsvmnlpghojXPcFGM1nldKs2k1XfGHdVrH - ucJfhQilhsGo65EiN+v9VS6tz5dDtX5+NnkkpR5mOx1+xwUf4n+F6cWyIiLKY6Se - byIN0dPtErZpq47w6bhLZ3Dd/frReG8Egmr7yLAqGHKmuwvmEUA6w6a2VzWQy5G4 - Smcj5kPHKWJ9SvAQHc7SoUmYqt2GEAKBi6CYb5Oeknf3vc4QUSPxF8KRiebUhTxc - ruycSbLkLklsDjfH0caD - =NVWj - -----END PGP SIGNATURE----- - -Four digests have been computed for this ISO. The hash functions used, in order from top to bottom, are MD5, SHA1, SHA256, and SHA512. One way to verify that the ISO you downloaded matches any of these is by using `openssl` from the command line: - - $ openssl dgst -md5 Qubes-R2-x86_64-DVD.iso - MD5(Qubes-R2-x86_64-DVD.iso)= 6f6ff24f2edec3a7607671001e694d8e - $ openssl dgst -sha1 Qubes-R2-x86_64-DVD.iso - SHA1(Qubes-R2-x86_64-DVD.iso)= 0344e04a98b741c311936f3e2bb67fcebfc2be08 - $ openssl dgst -sha256 Qubes-R2-x86_64-DVD.iso - SHA256(Qubes-R2-x86_64-DVD.iso)= 1fa056b73d8e2e93acdf3dcaface2515d61335e723d1d7d338241209119c10a3 - $ openssl dgst -sha512 Qubes-R2-x86_64-DVD.iso - SHA512(Qubes-R2-x86_64-DVD.iso)= a49ff19c1ad8c51a50198ac51670cf7c71972b437fa59f2e9fc9432cce76f4529f10de1d576ac777cdd49b9325eb2f32347fd13e0f9b04f823a73e84c6ddd772 - -(Notice that the outputs match the values from the `.DIGESTS` file.) - -However, it is possible that an attacker replaced `Qubes-R2-x86_64-DVD.iso` with a malicious ISO, computed the hash values for that ISO, and replaced the values in `Qubes-R2-x86_64-DVD.iso.DIGESTS` with his own set of values. Therefore, ideally, we should also verify the authenticity of the listed hash values. Since `Qubes-R2-x86_64-DVD.iso.DIGESTS` is a clearsigned PGP file, we can use `gpg` to verify it from the command line: - - $ gpg -v --verify Qubes-R2-x86_64-DVD.iso.DIGESTS - gpg: armor header: Hash: SHA256 - gpg: armor header: Version: GnuPG v1 - gpg: original file name='' - gpg: Signature made 2015-08-01T22:27:18 UTC using RSA key ID 0A40E458 - gpg: using PGP trust model - gpg: Good signature from "Qubes OS Release 2 Signing Key" - gpg: textmode signature, digest algorithm SHA256 - -The signature is good. Assuming our copy of the `Qubes OS Release 2 Signing Key` is also authentic (see above), we can be confident that these hash values came from the Qubes devs. - -Verifying Qubes Code --------------------- - -Developers who fetch code from our Git server should always verify tags on the latest commit. Any commits that are not followed by a signed tag should not be trusted! - -To verify a signature on a git tag, you can use: - - $ git tag -v diff --git a/managing-os/hvm.md b/managing-os/hvm.md index 2f2fc478..f1724823 100644 --- a/managing-os/hvm.md +++ b/managing-os/hvm.md @@ -15,20 +15,20 @@ Creating and using HVM (fully virtualized) domains What are HVM domains? --------------------- -HVM domains (Hardware VM), in contrast to PV domains (Paravirtualized domains), allow to create domains based on any OS, if one only has its installation ISO. E.g. this allows to have Windows-based VMs in Qubes. +HVM domains (Hardware VM), in contrast to PV domains (Paravirtualized domains), allow one to create domains based on any OS for which one has an installation ISO. For example, this allows one to have Windows-based VMs in Qubes. -Interested readers might want to check [this article](http://theinvisiblethings.blogspot.com/2012/03/windows-support-coming-to-qubes.html) to learn why it took so long for Qubes OS to support HVM domains (Qubes 1 only supported Linuxed-based PV domains). +Interested readers might want to check [this article](https://blog.invisiblethings.org/2012/03/03/windows-support-coming-to-qubes.html) to learn why it took so long for Qubes OS to support HVM domains (Qubes 1 only supported Linux based PV domains). Creating an HVM domain ---------------------- -First, lets create a new HVM domain (use the --hvm switch to qvm-create, or choose HVM type in the Qubes Manager VM creation dialog box): +First, lets create a new HVM domain. Use the --hvm switch to qvm-create, or choose HVM type in the Qubes Manager VM creation dialog box: ~~~ qvm-create win7 --hvm --label green ~~~ -(Of course, the name of the domain ("win7"), as well as it's label ("green"), are just exemplary). +(The name of the domain ("win7") as well as it's label ("green") are just exemplary of course). If you receive an error like this one, then you must first enable VT-x in your BIOS: @@ -36,72 +36,141 @@ If you receive an error like this one, then you must first enable VT-x in your B libvirt.libvirtError: invalid argument: could not find capabilities for arch=x86_64 ~~~ -Now, we need to install an OS inside this VM, this can done by attaching an installation ISO upon starting the VM (this currently can be done only from command line, but in the future we surely will added an option to do this also from the manager): +Now we need to install an OS inside this VM. This can done by attaching an installation ISO to and starting the VM (this can currently only be done from command line, but in the future we will surely add an option to do this also from the manager): ~~~ qvm-start win7 --cdrom=/usr/local/iso/win7_en.iso ~~~ -The command above assumes the installation ISO was somehow transferred to Dom0, e.g. copied using `dd` command from an installation CDROM. If one wishes to use the actual physical media without copying it first to a file, then one can just pass `/dev/cdrom` as an argument to `--cdrom`: +The above command assumes the installation ISO was transferred to Dom0 (copied using `dd` command from an installation CDROM for example). If one wishes to use the actual physical media without copying it first to a file, then one can just pass `/dev/cdrom` as an argument to `--cdrom`: ~~~ qvm-start win7 --cdrom=/dev/cdrom ~~~ -Now, the VM will start booting from the attached CDROM device, which in the example above just happens to be the Windows 7 installation disk. Depending on the OS that is being installed in the VM, one might be required to start the VM several times (as is the case e.g. with Windows 7 installation), because whenever the installer wants to "reboot the system", it actually shutdowns the VM (and Qubes won't automatically start it), so several invocations of qvm-start command (as shown above) might be needed. +Next the VM will start booting from the attached CDROM device (which in the example above just happens to be a Windows 7 installation disk). Depending on the OS that is being installed in the VM one might be required to start the VM several times (as is the case with Windows 7 installations), because whenever the installer wants to "reboot the system" it actually shutdowns the VM and Qubes won't automatically start it. Several invocations of qvm-start command (as shown above) might be needed. [![r2b1-win7-installing.png](/attachment/wiki/HvmCreate/r2b1-win7-installing.png)](/attachment/wiki/HvmCreate/r2b1-win7-installing.png) Using Installation ISOs located in other VMs -------------------------------------------- -Sometimes one wants to download the installation ISO from the Web and use it for HVM creation. However, for security reasons, networking is disabled for Qubes Dom0, which makes it not possible to download an ISO within Dom0. Also Qubes do not provide any (easy to use) mechanisms for copying files between AppVMs and Dom0, and generally tries to discourage such actions. So, it would be inconvenient to require that the installation ISO for an HVM domain be always located in Dom0. And the good news is that this is indeed not required -- one can use the following syntax when specifying the location of /usr/local/iso/win7\_en.iso the installation ISO: +Sometimes one wants to download the installation ISO from the Web and use it for HVM creation. For security reasons, networking is disabled for Qubes Dom0, which makes it impossible to download an ISO within Dom0. Qubes also does not provide any easy to use mechanisms for copying files between AppVMs and Dom0 and generally tries to discourage such actions. Due to these factors it would be inconvenient to require that the installation ISO for an HVM domain be always located in Dom0. The good news, however, is that this is indeed not required. One can use the following syntax when specifying the location of an installation ISO (such as the Windows 7 installation ISO): ~~~ --cdrom=[appvm]:[/path/to/iso/within/appvm] ~~~ -Assuming e.g. the an installation ISO named `ubuntu-12.10-desktop-i386.iso` has been downloaded in `work-web` AppVM, and located within `/home/user/Downloads` directory within this AppVM, one can immediately create a new HVM and use this ISO as an installation media with the following command (issued in Dom0, of course): +Assuming that an installation ISO named `ubuntu-12.10-desktop-i386.iso` has been downloaded in `work-web` AppVM and is located within the `/home/user/Downloads` directory within this AppVM, one can immediately create a new HVM using this ISO as an installation media with the following command issued in Dom0: ~~~ qvm-create --hvm ubuntu --label red qvm-start ubuntu --cdrom=work-web:/home/user/Downloads/ubuntu-12.10-desktop-i386.iso ~~~ -Of course the AppVM where the ISO is kept must also be running for this to work (this VM is now serving the ISO and acting as a disk backend). +The AppVM where the ISO is kept must be running for this to work as this VM is now serving the ISO and acting as a disk backend. ![r2b1-installing-ubuntu-1.png](/attachment/wiki/HvmCreate/r2b1-installing-ubuntu-1.png) +Converting VirtualBox VM to HVM +------------------------------- + +Microsoft provides [free 90 day evaluation VirtualBox VMs for browser testing](https://developer.microsoft.com/en-us/microsoft-edge/tools/vms/). + +About 60 GB of disk space is required for conversion, use external harddrive if needed. Final root.img size is 40 GB. + +In Debian AppVM, install qemu-utils and unzip: + +~~~ +sudo apt install qemu-utils unzip +~~~ + +Unzip VirtualBox zip file: + +~~~ +unzip *.zip +~~~ + +Extract OVA tar archive: + +~~~ +tar -xvf *.ova +~~~ + +Convert vmdk to raw: + +~~~ +qemu-img convert -O raw *.vmdk win10.raw +~~~ + +Create new HVM in Dom0, with amount of RAM in MB you wish: + +~~~ +qvm-create --hvm win10 --label red --mem=4096 +~~~ + +Copy file to Dom0: + +~~~ +qvm-run --pass-io untrusted 'cat "/media/user/externalhd/win10.raw"' > /var/lib/qubes/appvms/win10/root.img +~~~ + +Start win10 VM: + +~~~ +qvm-start win10 +~~~ + +**Optional ways to get more information** + +Filetype of OVA file: + +~~~ +file *.ova +~~~ + +List files of OVA tar archive: + +~~~ +tar -tf *.ova +~~~ + +List filetypes supported by qemu-img: + +~~~ +qemu-img -h | tail -n1 +~~~ + Setting up networking for HVM domains ------------------------------------- -Just like standard (paravirtualized) AppVMs, the HVM domains got fixed IP addresses centrally assigned by Qubes. Normally Qubes agent scripts, running within each AppVM, are responsible for setting up networking within the VM according the configuration created by Qubes. Such centrally managed networking infrastructure allows for [advanced networking configuration](http://theinvisiblethings.blogspot.com/2011/09/playing-with-qubes-networking-for-fun.html). +Just like standard paravirtualized AppVMs, the HVM domains get fixed IP addresses centrally assigned by Qubes. Normally Qubes agent scripts running within each AppVM are responsible for setting up networking within the VM according the configuration created by Qubes. Such centrally managed networking infrastructure allows for [advanced networking configuration](https://blog.invisiblethings.org/2011/09/28/playing-with-qubes-networking-for-fun.html). -However, a generic HVM domain, e.g. a standard Windows or Ubuntu installation, has (at least initially) no Qubes agent scripts running inside it, and thus requires manual networking configuration, so that it match the values assigned by Qubes for this domain. +A generic HVM domain such as a standard Windows or Ubuntu installation, however, has no Qubes agent scripts running inside it initially and thus requires manual networking configuration so that it match the values assigned by Qubes for this domain. -Even though we do have a small DHCP server (that runs inside HVM untrusted stub domain) to make the manual network configuration not necessary for many VMs, this won't work for most modern Linux distributions which contain Xen networking PV drivers built in (but not Qubes tools) and which bypass the stub-domain networking (their net frontends connect directly to the net backend in the netvm), and so our DHCP server is not useful. +Even though we do have a small DHCP server that runs inside HVM untrusted stub domain to make the manual network configuration not necessary for many VMs, this won't work for most modern Linux distributions which contain Xen networking PV drivers (but not Qubes tools) built in which bypass the stub-domain networking (their net frontends connect directly to the net backend in the netvm). In this instance our DHCP server is not useful. In order to manually configure networking in a VM, one should first find out the IP/netmask/gateway assigned to the particular VM by Qubes. This can be seen e.g. in the Qubes Manager in the VM's properties: ![r2b1-manager-networking-config.png](/attachment/wiki/HvmCreate/r2b1-manager-networking-config.png) -Alternatively, one can use `qvm-ls -n` command to obtain the same information. +Alternatively, one can use `qvm-ls -n` command to obtain the same information. One should configure the networking within the HVM according to those settings (IP/netmask/gateway). One should set DNS addresses to the same IP as gateway. -Now, one should configure the networking within the HVM according to those settings (IP/netmask/gateway). Only IPv4 networking is currently supported in Qubes. Set DNS address to the same IP as gateway. +Only IPv4 networking is currently supported in Qubes. **Note:** If one plans on installing Qubes Tools for Windows guests (see below) it is 'not' necessary to configure networking manually as described in this section, because the tools will take care of setting the networking automatically for such Windows domains. Using Template-based HVM domains -------------------------------- -TODO (Coming in Qubes R2 beta 3). +Please see our dedicated page on [installing and using Windows-based AppVMs](/doc/windows-appvms/). Cloning HVM domains ------------------- -Just like normal AppVMs, the HVM domains can also be cloned, either using a command-line `qvm-clone` command, or via manager's 'Clone VM' option in the right-click menu. +Just like normal AppVMs, the HVM domains can also be cloned either using a command-line `qvm-clone` command or via manager's 'Clone VM' option in the right-click menu. -The cloned VM will get identical root and private image, and essentially will be identical to the original VM, except that it will get a different MAC address for the networking interface: +The cloned VM will get identical root and private image and will essentially be an identical of the original VM except that it will get a different MAC address for the networking interface: ~~~ [joanna@dom0 ~]$ qvm-prefs win7 @@ -157,7 +226,7 @@ drive : None timezone : localtime ~~~ -Note how the MAC addresses differ between those two, otherwise identical VMs. Of course, the IP addresses, assigned by Qubes, will also be different, to allow networking to function properly: +Note how the MAC addresses differ between those two otherwise identical VMs. The IP addresses assigned by Qubes will also be different of course to allow networking to function properly: ~~~ [joanna@dom0 ~]$ qvm-ls -n @@ -167,7 +236,7 @@ Note how the MAC addresses differ between those two, otherwise identical VMs. Of /.../ ~~~ -If, for any reason, one would like to make sure that the two VMs have the same MAC address, one can use qvm-prefs to set a fixed MAC address for the VM: +If for any reason one would like to make sure that the two VMs have the same MAC address, one can use qvm-prefs to set a fixed MAC address for the VM: ~~~ [joanna@dom0 ~]$ qvm-prefs win7-copy -s mac 00:16:3E:5E:6C:05 @@ -196,10 +265,6 @@ drive : None timezone : localtime ~~~ -Please note that as of now Qubes does not support shared templates for HVM domains. This means that HVM domains cloned this way will have two separate copies of the whole filesystems. This has consequences in taking much more disk space compared to standard AppVMs that share the root fs with the Template VM. Another consequence is that it's probably not legal to clone a proprietary OS, such as Windows this way, unless your license specifically allows for that (even though Windows Activation won't complain when one sets identical MAC address for the cloned VMs, it's doubtful practice at best). - -In the near future we plan on introducing shared template also for HVM domains, hopefully solving the problems described above. - Installing Qubes support tools in Windows 7 VMs ----------------------------------------------- @@ -210,7 +275,7 @@ Assigning PCI devices to HVM domains HVM domains (including Windows VMs) can be [assigned PCI devices](/doc/assigning-devices/) just like normal AppVMs. E.g. one can assign one of the USB controllers to the Windows VM and should be able to use various devices that require Windows software, such as phones, electronic devices that are configured via FTDI, etc. -Once problem, however, at the moment, is that after the whole system gets suspend into S3 sleep, and subsequently resumed, such attached devices stop working and should be restarted within the VM. Under Windows this can be achieved by opening the Device Manager, selecting the actual device, such as a USB controller, and then first 'Disabling', and then 'Enabling' the device again. This is illustrated on the screenshot below: +One problem at the moment however, is that after the whole system gets suspended into S3 sleep and subsequently resumed, some attached devices may stop working and should be restarted within the VM. This can be achieved under a Windows HVM by opening the Device Manager, selecting the actual device (such as a USB controller), 'Disabling' the device, and then 'Enabling' the device again. This is illustrated on the screenshot below: [![r2b1-win7-usb-disable.png](/attachment/wiki/HvmCreate/r2b1-win7-usb-disable.png)](/attachment/wiki/HvmCreate/r2b1-win7-usb-disable.png) diff --git a/managing-os/kali.md b/managing-os/kali.md deleted file mode 100644 index 466f4806..00000000 --- a/managing-os/kali.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -layout: doc -title: How to create a Kali Linux VM -permalink: /doc/kali/ ---- - -How to Create a Kali Linux VM -============================= - -This guide is being created to give guidance on ways in which you could implement Kali Pen-Testing distrubution within Qubes-OS. - -There are multiple ways in which this can be achieved, for example you could create a HVM and use the ISO to install the system straight to that virtual machine. - - -Build Based on Debian Template ---- - -1 - Install debian-8 template (if not already installed) - -2 - Clone debian-8 template - -3 - Add kali repo to /etc/apt/sources.list: - - * deb http://http.kali.org/kali kali-rolling main non-free contrib - -4 - Find and add kali signing keys: - - * gpg --keyserver hkp://keys.gnupg.net --recv-key 7D8D0BF6 (this is the key ID I found on Kali web site) - - * gpg --list-keys --with-fingerprint 7D8D0BF6 - - * gpg --export --armor 7D8D0BF6 > kali.asc - - * sudo apt-key add kali.asc - - * sudo apt-key list - -5 - sudo apt-get update - -6 - sudo halt - -7 - backup template (cloned...) - -8 - sudo apt-get apt-get install kali-*** (or similar) --> installs fine but break the template X settings. As mentioned, X packaged need to be masked prior to this, I did not take the time to look-up how to do that... - -9 - Create a appvm from the kali template and attach necessary devices. - - -Note: - -If you do not want to modify the sources.list file and add the signing keys yourself, alternatively you can use KATOOLIN after cloning the Debian Template. Guide on how to use KATOOLIN - http://www.tecmint.com/install-kali-linux-tools-using-katoolin-on-ubuntu-debian/ - - - -Alternative Options to Kali ---- - -PenTester Framework (PTF) - - diff --git a/managing-os/linux-hvm-tips.md b/managing-os/linux-hvm-tips.md index 53e56348..c1c99fa3 100644 --- a/managing-os/linux-hvm-tips.md +++ b/managing-os/linux-hvm-tips.md @@ -11,24 +11,61 @@ redirect_from: Tips for Linux in HVM domain ============================ +How to fix bootup kernel error +------------------------------- + +The HVM may pause on boot, showing a fixed cursor. +After a while a series of warnings may be shown similar to this: + + BUG: soft lockup - CPU#0 stuck for 23s! [systemd-udevd:244] + +To fix this: + +1. Kill the HVM. +1. Start the HVM +1. Press "e" at the grub screen to edit the boot parameters +1. Find the /vmlinuz line, and edit it to replace "rhgb" with "modprobe.blacklist=bochs_drm" +1. Press "Ctrl-x" to start the HVM + +If this solves the problem then you will want to make the change permanent: + +1. Edit the file `/etc/default/grub`. +1. Find the line which starts: + ~~~ + GRUB_CMDLINE_LINUX= + ~~~ +1. Remove this text from that line: + ~~~ + rhgb + ~~~ +1. Add this text to that line: + ~~~ + modprobe.blacklist=bochs_drm + ~~~ +1. Run this command: + ~~~ + grub2-mkconfig --output=/boot/grub2/grub.cfg + ~~~ + +The HVM should now start normally. + + Screen resolution ----------------- -Some kernel/Xorg combination use only 640x480 in HVM, which is quite small. To enable maximum resolution, some changes in Xorg configuration are needed: - +Some kernel/Xorg combinations use only 640x480 in HVM, which is quite small. +To enable maximum resolution, some changes in the Xorg configuration are needed: 1. Force "vesa" video driver 2. Provide wide horizontal synchronization range -To achieve it (all commands run as root): +To achieve it (all commands to be run as root): 1. Generate XOrg configuration (if you don't have it): - ~~~ X -configure :1 && mv ~/xorg.conf.new /etc/X11/xorg.conf ~~~ -2. Add HorizSync line to Monitor section, it should look something like: - +1. Add HorizSync line to Monitor section, it should look something like: ~~~ Section "Monitor" Identifier "Monitor0" @@ -38,8 +75,7 @@ To achieve it (all commands run as root): EndSection ~~~ -3. Change driver to "vesa" in Device section: - +1. Change driver to "vesa" in Device section: ~~~ Section "Device" # (...) @@ -51,9 +87,10 @@ To achieve it (all commands run as root): EndSection ~~~ -Now you should get at least 1280x1024 and be able to choose other modes. +Now you should get resolution of at least 1280x1024 and should be able to choose other modes. Qubes agents ------------ -Linux Qubes agents are written with PV domain in mind, but it looks to be possible to run them also in HVM domain. However some work is required to achieve it. Check [this thread](https://groups.google.com/group/qubes-devel/browse_thread/thread/081df4a43e49e7a5). +Linux Qubes agents are written primarily for PV qubes, but it is possible to run them also in a HVM qube. +However some work may be required to achieve this. Check [this thread](https://groups.google.com/group/qubes-devel/browse_thread/thread/081df4a43e49e7a5). diff --git a/managing-os/netbsd.md b/managing-os/netbsd.md index 29754fb7..5b4977e0 100644 --- a/managing-os/netbsd.md +++ b/managing-os/netbsd.md @@ -20,4 +20,4 @@ How to Create a NetBSD VM For further discussion, please see this [thread] and this [guide]. [thread]: https://groups.google.com/group/qubes-devel/msg/4015c8900a813985 -[guide]: http://wiki.xen.org/wiki/How_to_install_a_NetBSD_PV_domU_on_a_Debian_Squeeze_host_%28Xen_4.0.1%29 +[guide]: https://wiki.xen.org/wiki/How_to_install_a_NetBSD_PV_domU_on_a_Debian_Squeeze_host_%28Xen_4.0.1%29 diff --git a/managing-os/pentesting.md b/managing-os/pentesting.md new file mode 100644 index 00000000..56d79260 --- /dev/null +++ b/managing-os/pentesting.md @@ -0,0 +1,30 @@ +--- +layout: doc +title: Penetration Testing +permalink: /doc/pentesting/ +--- + +**Legal notice:** + +The usage of penetration testing tools outside your own laboratory environment requires the permission of the organization you attack. Penetration testing without permission can have legal consequences. + +To avoid such legal conflicts please refer to the [EC-Council: Code of Ethics](https://www.eccouncil.org/Support/code-of-ethics). + +Penetration Testing +=================== + +"A penetration test, colloquially known as a pen test, is an authorised simulated attack on a computer system that looks for security weaknesses, potentially gaining access to the system's features and data." (Source: [Wikipedia](https://en.wikipedia.org/wiki/Penetration_test)). + +Penetration Testing Distributions +--------------------------------- + +The following instructions explain how to install a penetration testing distribution within Qubes OS. + +- [BlackArch](/doc/pentesting/blackarch/) +- [Kali](/doc/pentesting/kali/) +- [PenTester Framework (PTF)](/doc/pentesting/ptf/) + +Using Qubes OS to host a "hacking" laboratory +--------------------------------------------- + +Qubes OS is a hypervisor based operating system. Qubes OS can host various operating systems such as Linux, Unix or Windows and run them in parallel. Qubes OS can therefore be used to host your own "hacking" laboratory. diff --git a/managing-os/pentesting/blackarch.md b/managing-os/pentesting/blackarch.md new file mode 100644 index 00000000..f02575e6 --- /dev/null +++ b/managing-os/pentesting/blackarch.md @@ -0,0 +1,96 @@ +--- +layout: doc +title: How to Create a BlackArch VM +permalink: /doc/pentesting/blackarch/ +redirect_from: +- /doc/blackarch/ +--- + +**General Remainder:** + +- The installation scripts and provided tools may have bugs, be vulnerable to Man in the Middle (MitM) attacks or other vulnerabilities. + +- Adding additional repositories or tools for installing software extends your trust to those tool provider. + +Please keep in mind that using such a VM or VM's based on the template for security and privacy critical tasks is not recommended. + +How to Create a BlackArch VM +============================ + +[BlackArch](https://www.blackarch.org) Linux is an [Arch Linux](https://www.archlinux.org)-based distribution for penetration testers and security researchers. The repository contains [1434](https://www.blackarch.org/tools.html) tools. + +- List of [tools](https://www.blackarch.org/tools.html) +- [Installation Instructions](https://www.blackarch.org/downloads.html) + +Create ArchLinux Based BlackArch Template +----------------------------------------- + +1. Create ArchlLinux Template + + - Follow the [Archlinux Template instructions](/doc/templates/archlinux/) + + +2. Update Template + + sudo pacman -Syyu + +3. Clone template + + 1. Via Qubes VM Manager + + 2. Via command line + + qvm-clone archlinux blackarch + +4. Install BlackArch repository + + $ curl -O https://blackarch.org/strap.sh + + # The SHA1 sum should match: 34b1a3698a4c971807fb1fe41463b9d25e1a4a09 + $ sha1sum strap.sh + + # Set execute bit + $ chmod +x strap.sh + + # Run strap.sh + $ sudo ./strap.sh + +5. Install tools + + - install all tools + + sudo pacman -S blackarch + + - or by category: + + # list available categories + pacman -Sg | grep blackarch + + # install category + sudo pacman -S blackarch- + + # example + sudo pacman -S blackarch-forensic + + - or specific tool + + # Search for tool + pacman -Ss + + # Install tool + sudo pacman -S + + # Example + pacman -Ss burpsuite + sudo pacman -S burpsuite + +6. Create a AppVMs based on the `blackarch` template + + - (Optional) Attach necessary devices + +Alternative Options to BlackArch +-------------------------------- + +- [Kali](/doc/pentesting/kali/) +- [PenTester Framework (PTF)](/doc/pentesting/ptf/) +- [Pentesting](/doc/pentesting/) diff --git a/managing-os/pentesting/kali.md b/managing-os/pentesting/kali.md new file mode 100644 index 00000000..e87dad3c --- /dev/null +++ b/managing-os/pentesting/kali.md @@ -0,0 +1,308 @@ +--- +layout: doc +title: How to create a Kali Linux VM +permalink: /doc/pentesting/kali/ +redirect_from: +- /doc/kali/ +--- + +**General Remainder:** + +- The installation scripts and provided tools may have bugs, be vulnerable to Man in the Middle (MitM) attacks or other vulnerabilities. + +- Adding additional repositories or tools for installing software extends your trust to those tool provider. + +Please keep in mind that using such a VM or VM's based on the template for security and privacy critical tasks is not recommended. + +How to Create a Kali Linux VM +============================= + +This guide is being created to give guidance on ways in which you could create a [Kali Linux][kali] penetration testing VM (qube) in Qubes OS. + +Kali Linux is the most widely used penetration testing Linux distribution. + +There are multiple ways to create a Kali Linux VM: + + 1. Create a HVM and use the offical ISO to install the system or convert a [Virtual Image][kali-vbox]. Explained [here](#hvm). + 2. Clone the Qubes OS Debian image and turn it into a Kali Linux distribution using [katoolin]. Explained [here](#katoolin). + 3. Clone the Qubes OS 'jessie' Debian template, upgrade it to 'stretch' + (Debian 9.0) and turn it into a Kali linux template. Explained + [here](#debian-upgrade). + +## Alternative Options to Kali + +- [BlackArch][qubes-blackarch] +- [PenTester Framework (PTF)][qubes-ptf] +- [Pentesting][qubes-pentesting] + +## Kali Linux HVM + +1. Download the Kali installation DVD + +2. Create a new HVM + +3. Start the HVM with attached CD/DVD + + qvm-start --cdrom :/home/user/Downloads/.iso + +## Create Debian Based Kali Template + +Katoolin is a script (written in Python) which helps you to install Kali tools. + +1. *(Optional)* Install `debian-8` template (if not already installed) + +2. Update your `debian-8` template + + sudo apt-get update + sudo apt-get dist-upgrade + +3. Clone `debian-8` template (two options) + + 1. Via Qubes VM Manager + + ![Clone Debian Template](/attachment/wiki/Kali/clone-kali.png) + + 2. Via command line + + qvm-clone debian-8 kali + +4. Start and upgrade the `kali` Template from Debian 8 to Debian 9 + + sudo sed -i 's/jessie/stretch/g' /etc/apt/sources.list + sudo sed -i 's/jessie/stretch/g' /etc/apt/sources.list.d/qubes-r3.list + sudo apt-get update + sudo apt-get dist-upgrade + sudo apt-get autoremove + +6. Install Katoolin and add Kali Linux repositories + + 1. Install Katoolin + + sudo apt-get install git + git clone https://github.com/LionSec/katoolin.git + sudo cp katoolin/katoolin.py /usr/bin/katoolin + sudo chmod +x /usr/bin/katoolin + rm -rf katoolin + + 2. Add Kali Linux repositories + + - start katoolin + + sudo katoolin + + - select 'Add Kali repositories & Update' + + 1) Add Kali repositories & Update + 2) View Categories + 3) Install classicmenu indicator + 4) Install Kali menu + 5) Help + + kat > 1 + + ![Add Kali repositories and Update menu](/attachment/wiki/Kali/katoolin-add-update-repo-menu.png) + + - select 'Add kali linux repositories' + + 1) Add kali linux repositories + 2) Update + 3) Remove all kali linux repositories + 4) View the contents of sources.list file + + What do you want to do ?> 1 + + ![Add Kali repositories](/attachment/wiki/Kali/katoolin-add-repos-menu.png) + + - update Kali repositories + + + 1) Add kali linux repositories + 2) Update + 3) Remove all kali linux repositories + 4) View the contents of sources.list file + + What do you want to do ?> 2 + + - quit katoolin by pressing `CRTL` + `c` keys + + What do you want to do ?> ^CShutdown requested...Goodbye... + +7. Clean up and update `kali` template + + sudo apt-get dist-upgrade + sudo apt-get autoremove + +8. Shutdown and trim `kali` template + + - Shutdown `kali` template + + sudo shutdown -h now + + - In `dom0` console: + + qvm-trim-template kali + +9. Start image + +11. Install tools + + 1. View Categories + + - start katoolin + + sudo katoolin + + - select `2) View Categories` + + 2. Select the categories/tools you want to install + + - For more information on how to use Katoolin see [How to Auto Install All Kali Linux Tools Using “Katoolin” on Debian/Ubuntu][katoolin-howto]. + + - **Note:** The `all` option does not work for `Information Gathering`, `Web Apps`, `Forensic Tools`, `Reverse Engineering` and `Extra`. + +12. Create a AppVMs based on the `kali` template + + - (Optional) Attach necessary devices + +## Installing Kali from a Debian template + +This section will explain how to create your own [Kali] Linux VM as a VM +template. The basic idea is to personalize the template with the tools you need +and then spin up isolated AppVMs based on the template. + +This has been tested on Qubes OS 3.2. + +The steps can be summarised as: + +1. Install Qubes' Debian 8.0 (Jessie) template +2. Upgrade the template to Debian 9.0 (Stretch) +3. Install kali through the ``kali-linux-full`` package +4. Use the template to build appVM so that you can maintain isolation between + e.g. pentesting jobs + + +Steps to build a Kali template +------------------------------ + +### Get the GPG key + +1. You'll need to fetch the Kali GPG key from a dispVM as the template you'll + build won't have direct internet connectivity unless you enable it from the + firewall: + + # in a dispVM + gpg --keyserver hkp://keys.gnupg.net --recv-key 7D8D0BF6 + gpg --list-keys --with-fingerprint 7D8D0BF6 + gpg --export --armor 7D8D0BF6 > kali.asc + +2. **DO NOT TURN OFF** the dispVM + +3. Make sure the key ID is the valid one listed on the [Kali website]. Ideally, + verify the fingerprint through other channels as recommended on that link. + +Once you have the key, keep the dispVM on as you'll need to copy the key over +to the Kali template. + +### Customize the template + +1. Install [the debian-8 template] if not already installed + +2. Clone the debian template and start a terminal in it: + + # in dom0: + qvm-clone debian-8 debian-9 + qvm-run -a debian-9 gnome-terminal + + # in the debian-9 template terminal: + # substitute jessie for stretch in + sudo -s + sensible-editor /etc/apt/sources.list + sensible-editor /etc/apt/sources.list.d/qubes-r3.list + apt-get update && apt-get dist-upgrade + # (hat tip: [the Debian wiki]) + + Restart the template when done and make sure you can open a terminal. + +3. Prepare the kali template: + + # in dom0: + qvm-shutdown debian-9 + qvm-clone debian-9 kali-tpl + qvm-run -a kali-tpl gnome-terminal + +3. Add the sources to install Kali linux to the `kali-tpl` template: + + # in kali-tpl: + sudo -s + echo 'deb http://http.kali.org/kali kali-rolling main non-free contrib' >> /etc/apt/sources.list + +4. Copy the Kali key from the dispVM into the template: + + # in the dispVM: + qvm-copy-to-vm kali-tpl kali.asc + + # in kali-tpl: + cat /home/user/QubesIncoming/dispXXX/kali-key.asc | sudo apt-key add - + + The last command should return `OK` on a line by itself. + +5. Update the system: + + # in kali-tpl: + sudo -s + apt-get update && apt-get dist-upgrade + +6. Shut down the `kali-tpl` template: + + # in dom0: + qvm-shutdown kali-tpl + +### Install the Kali tools + +At this point you should have a working template and you can install the tools you need. + +1. [resize the template] if you plan on installing the full Kali distribution. For example to install `kali-linux-full` you must **grow** the size of the VM system from 10Gb to at least 20Gb. + +1. Install Kali linux: + + # in kali-tpl: + sudo apt-get install kali-linux-full + +2. [optional] Customise the template's home directory (e.g. install your licensed copy of Burp Suite Professional) + +### Use the template + +The template is ready to be used. You can now spin up AppVMs based on the `kali-tpl` template. + + + +Alternative Options to Kali +=========================== + + * PenTester Framework: [PTF] ([PTF Qubes OS guide]) + * Black Arch with [BA Qubes OS guide]) + * [KATOOLIN] + +Notes +----- + +Thanks to the people in [the discussion thread]. + +[qubes-blackarch]: /doc/pentesting/blackarch/ +[qubes-ptf]: /doc/pentesting/ptf/ +[qubes-pentesting]: /doc/pentesting/ + +[kali-vbox]: https://www.offensive-security.com/kali-linux-vmware-virtualbox-image-download/ +[kali]: https://www.kali.org/ +[kali website]: https://docs.kali.org/introduction/download-official-kali-linux-images. +[KATOOLIN]: http://www.tecmint.com/install-kali-linux-tools-using-katoolin-on-ubuntu-debian/ +[the debian-8 template]: https://www.qubes-os.org/doc/templates/debian/#install +[PTF]: https://www.trustedsec.com/may-2015/new-tool-the-pentesters-framework-ptf-released/ +[audio CDs]: https://www.reddit.com/r/Nirvana/comments/3hmra1/the_main_character_in_the_tv_show_mr_robot_has_a/ +[resize the template]: https://www.qubes-os.org/doc/resize-disk-image/ +[the Debian wiki]: https://wiki.debian.org/Qubes#Install_Debian_Templates +[the discussion thread]: https://github.com/QubesOS/qubes-issues/issues/1981 +[PTF Qubes OS guide]: https://www.qubes-os.org/doc/pentesting/ptf/ +[BA Qubes OS guide]: https://www.qubes-os.org/doc/pentesting/blackarch/ +[katoolin]: https://github.com/LionSec/katoolin +[katoolin-howto]: http://www.tecmint.com/install-kali-linux-tools-using-katoolin-on-ubuntu-debian/ diff --git a/managing-os/pentesting/ptf.md b/managing-os/pentesting/ptf.md new file mode 100644 index 00000000..0e3cb216 --- /dev/null +++ b/managing-os/pentesting/ptf.md @@ -0,0 +1,121 @@ +--- +layout: doc +title: How to create Penetration Testers Framework (PTF) VM +permalink: /doc/pentesting/ptf/ +redirect_from: +- /doc/ptf/ +--- + +**General Remainder:** + +- The installation scripts and provided tools may have bugs, be vulnerable to Man in the Middle (MitM) attacks or other vulnerabilities. + +- Adding additional repositories or tools for installing software extends your trust to those tool provider. + +Please keep in mind that using such a VM or VM's based on the template for security and privacy critical tasks is not recommended. + +How to create Penetration Testers Framework (PTF) VM +==================================================== + +"The PenTesters Framework (PTF) is a Python script designed for Debian/Ubuntu/ArchLinux based distributions to create a similar and familiar distribution for Penetration Testing. + +PTF attempts to install all of your penetration testing tools (latest and greatest), compile them, build them, and make it so that you can install/update your distribution on any machine." (source [PTF Readme](https://github.com/trustedsec/ptf/blob/master/README.md)) + +**Note** PTF works on Debian testing as well as on Debian 8. PTF itself works with Debian 8, but the software tools will have missing dependencies. Metasploit for examples requires a newer Ruby version than Debian 8 has in the repositories. Therefor the best way to install PTF is by upgrading a Debian 8 into Debian testing with additional Kali repositories. Instead of installing the tools from Kali, PTF will install and update the newest tools. + +Create Debian Based Penetration Testers Framework (PTF) Template +---------------------------------------------------------------- + +1. Create PTF template + + 1. Follow [Create Debian Based Kali Template](/doc/pentesting/kali/) till step 7. + + 2. (Optional) Rename the cloned template to `ptf` + +2. Download PTF + + sudo apt-get install git + cd /opt + sudo git clone https://github.com/trustedsec/ptf.git + + - (Optional) Configure PTF + + 1. Go to configuration directory + + cd /opt/ptf/config + + 2. Edit the configuration file + + for example by using vim: + + sudo vim ptf.config + + the configuration options are described in the `ptf.config` file + +3. Install PTF + + cd /opt/ptf + sudo ./ptf + + **Note:** the config file has to be in the same directory as the executable. It is not +possible to do sudo ptf/ptf + + PTF will put itself into `/usr/local/bin/ptf`. You can use `ptf` from now on. + +4. Install/Update modules (tools) + + 1. Start PTF + + sudo ptf + + ![PTF start banner](/attachment/wiki/PTF/ptf-banner.png) + + 2. Show available modules (tools) + + ptf> show modules + + 3. Install/Update modules (all/) + + - Install/Update all tools + + ptf> use modules/install_update_all + + - or by category Install/Update + + ptf> use modules/code-audit/install_update_all + + - or individually (example Metasploit) + + 1. Search for module + + ptf> search metasploit + [*] Search results below: + modules/exploitation/metasploit + + 2. Use module + + ptf> use modules/exploitation/metasploit + ptf:(modules/exploitation/metasploit)> + + 3. Install module + + ptf:(modules/exploitation/metasploit)>install + + 4. Run Metasploit + + ptf:(modules/exploitation/metasploit)>exit + ptf> quit + [*] Exiting PTF - the easy pentest platform creation framework. + sudo msfconsole + +5. Create a AppVMs based on the `ptf` template + + - (Optional) Attach necessary devices + + +Alternative Options to PTF +-------------------------- + +- [BlackArch](/doc/pentesting/blackarch/) +- [Kali](/doc/pentesting/kali/) +- [Pentesting](/doc/pentesting/) diff --git a/managing-os/reinstall-template.md b/managing-os/reinstall-template.md new file mode 100644 index 00000000..d992a1ce --- /dev/null +++ b/managing-os/reinstall-template.md @@ -0,0 +1,103 @@ +--- +layout: doc +title: How to Reinstall a TemplateVM +permalink: /doc/reinstall-template/ +redirect_from: +- /doc/whonix/reinstall/ +--- + +How to Reinstall a TemplateVM +============================= + +If you suspect your [TemplateVM] is broken, misconfigured, or compromised, you +can reinstall any TemplateVM that was installed from the Qubes repository. +Starting in Qubes 3.1, the process is greatly simplified. + +First, copy any files that you wish to keep from the TemplateVM's `/home` and +`/rw` folders to a safe storage location. Then, in a dom0 terminal, run: + + $ sudo qubes-dom0-update --action=reinstall qubes-template-package-name + +Replace `qubes-template-package-name` with the name of the *package* of the +template you wish to reinstall. For example, use `qubes-template-fedora-24` if +you wish to reinstall the `fedora-24` template. Only one template can be +reinstalled at a time. + +Note that Qubes may initially refuse to perform the reinstall if the exact revision of +the template package on your system is no longer in the Qubes online repository. In +this case, you can specify `upgrade` as the action instead and the newer version will be +used. The other `dnf` package actions that are now supported in addition to `reinstall` +and `upgrade` are `upgrade-to` and `downgrade`. + +**Reminder:** If you're trying to reinstall a template that is not in an enabled +repo, you must enable that repo. For example: + + $ sudo qubes-dom0-update --enablerepo=qubes-templates-community --action=reinstall qubes-template-whonix-ws + +**Note:** VMs that are using the reinstalled template will not be affected until they are +restarted. + + +Manual Reinstallation Method +---------------------------- + +If you're using Qubes 3.0 or older, you should use the manual reinstallation +method. You can also use this method on later Qubes versions if, for any reason, +you want to reinstall a template manually. + +In what follows, the term "target TemplateVM" refers to whichever TemplateVM you +want to reinstall. If you want to reinstall more than one TemplateVM, repeat +these instructions for each one. + +1. (Optional) Clone the existing target TemplateVM. + + This can be a good idea if you've customized the existing template and want + to keep your customizations. On the other hand, if you suspect that this + template is broken, misconfigured, or compromised, you may want to remove it + without cloning it. + +2. Create a temporary dummy template: + + mkdir /var/lib/qubes/vm-templates/dummy + touch /var/lib/qubes/vm-templates/dummy/{root.img,private.img} + qvm-add-template dummy + +3. Temporarily change all VMs based on the target TemplateVM to the new dummy + template, or remove them. + + This can be a good idea if you have user data in these VMs that you want to + keep. On the other hand, if you suspect that these VMs (or the templates on + which they are based) are broken, misconfigured, or compromised, you may + want to remove them instead. You can do this in Qubes Manager by + right-clicking on the VM and clicking **Remove VM**, or you can use the + command `qvm-remove ` in dom0. + + Using a dummy template as a temporary template is preferable to using another + real TemplateVM because you can't accidentally boot any VMs from the dummy + template. (There is no OS in the dummy template, so the boot will fail.) + +4. Uninstall the target TemplateVM from dom0: + + $ sudo yum remove + + For example, to uninstall the `whonix-gw` template: + + $ sudo yum remove qubes-template-whonix-gw + +5. Reinstall the target TemplateVM in dom0: + + $ sudo qubes-dom0-update --enablerepo= \ + + + For example, to install the `whonix-gw` template: + + $ sudo qubes-dom0-update --enablerepo=qubes-templates-community \ + qubes-template-whonix-gw + +6. If you temporarily changed all VMs based on the target TemplateVM to the + dummy template in step 3, change them back to the new target TemplateVM now. + If you instead removed all VMs based on the old target TemplateVM, you can + recreate your desired VMs from the newly reinstalled target TemplateVM now. + +[TemplateVM]: /doc/templates/ + diff --git a/managing-os/templates.md b/managing-os/templates.md index 6837e739..216991d9 100644 --- a/managing-os/templates.md +++ b/managing-os/templates.md @@ -11,29 +11,22 @@ redirect_from: TemplateVMs =========== -Every TemplateBasedVM in Qubes is, as the name implied, based on some -TemplateVM. The TemplateVM is where all the software available to -TemplateBasedVMs is installed. The default template is based on Fedora, -but there are additional templates based on other Linux distributions. There -are also templates available with or without certain software preinstalled. The -concept of TemplateVMs is initially described -[here](/doc/getting-started/#appvms-domains-and-templatevms). The technical -details of this implementation are described in the developer documentation -[here](/doc/template-implementation/). +Every TemplateBasedVM in Qubes is, as the name implies, based on some TemplateVM. +The TemplateVM is where all the software available to TemplateBasedVMs is installed. +The default template is based on Fedora, but there are additional templates based on other Linux distributions. +There are also templates available with or without certain software preinstalled. +The concept of TemplateVMs is initially described [here](/getting-started/#appvms-qubes-and-templatevms). +The technical details of this implementation are described in the developer documentation [here](/doc/template-implementation/). -Some templates are available in ready-to-use binary form, but some of them are -available only as source code, which can be built using -[Qubes Builder](/doc/qubes-builder/). In particular, some template "flavors" -are available in source code form only. Take a look at the [Qubes Builder -documentation](/doc/qubes-builder/) for instructions on how to compile them. +Some templates are available in ready-to-use binary form, but some of them are available only as source code, which can be built using the [Qubes Builder](/doc/qubes-builder/). In particular, some template "flavors" are available in source code form only. Take a look at the [Qubes Builder documentation](/doc/qubes-builder/) for instructions on how to compile them. +To reinstall a currently installed TemplateVM, see [here](/doc/reinstall-template/). -ITL Supported templates +Invisible Things Lab (ITL) Supported templates ----------------------- -These are templates which ITL is responsible for building and releasing updates -for. ITL guarantees that the binary updates are compiled from exactly the same -source code as we publish. +These are the templates ITL builds and releases updates for. +ITL guarantees that the binary updates are compiled from exactly the same source code as we publish. * Fedora (default base template) * [Fedora - Minimal](/doc/templates/fedora-minimal) @@ -43,15 +36,9 @@ source code as we publish. Community Supported templates ----------------------------- -These templates are supported by the Qubes community. Some of them are -available in ready-to-use binary package form (built by ITL), while others -are available only in source code form. In all cases ITL, does not provide -updates for these templates. However, such updates may be provided by the -template maintainer. +These templates are supported by the Qubes community. Some of them are available in ready-to-use binary package form (built by ITL), while others are available only in source code form. In all cases ITL, does not provide updates for these templates. However, such updates may be provided by the template maintainer. -By installing these templates, you are trusting not only ITL and the -distribution maintainers, but also the template maintainer. In addition, -these templates may be somewhat less stable, since ITL does not test them. +By installing these templates, you are trusting not only ITL and the distribution maintainers, but also the template maintainer. In addition, these templates may be somewhat less stable, since ITL does not test them. * [Whonix](/doc/templates/whonix/) * [Ubuntu](/doc/templates/ubuntu/) @@ -84,14 +71,25 @@ Important Notes update a template from dom0 (and thereby lose any user modifications in the existing template), you must first uninstall the existing template from dom0: - $ sudo yum remove qubes-template-fedora-23 + $ sudo yum remove qubes-template-fedora-24 + * Standalone VMs using Template VMs as a basis can be created easily. These + VMs receive a *copy* of the operating system and do not get automatically + updated when Template VMs are updated--they must be updated individually. + + * Template VMs can occupy more space on the dom0 filesystem than necessary + because they cannot employ automatic TRIM/discard on the root fs. The + `qvm-trim-template` command in dom0 is used to recover this unused space. + + Conversely, the root filesystems in Standalone VMs *can* employ + TRIM/discard on the root fs using normal tools and configuration options. + * On XFCE based Dom0, a manual action may be required to remove the "Start Menu" sub-menu of the removed TemplateVM. For example, to remove a dangling sub-menu - for a removed "fedora-21" template, open a Dom0 Terminal and type: + for a removed "fedora-24" template, open a Dom0 Terminal and type: - $ sudo rm ~/.local/share/applications/fedora-21-* + $ rm ~/.local/share/applications/fedora-24-* - Just make sure there are no other TemplateVMs whose names start with "fedora-21" + Just make sure there are no other TemplateVMs whose names start with "fedora-24" or else their menu items will be removed too. diff --git a/managing-os/templates/archlinux.md b/managing-os/templates/archlinux.md index f9c0bcba..3bb15f2f 100644 --- a/managing-os/templates/archlinux.md +++ b/managing-os/templates/archlinux.md @@ -9,8 +9,7 @@ redirect_from: - /wiki/Templates/Archlinux/ --- -Archlinux Template -=============== +# Archlinux Template Archlinux template is one of the templates made by Qubes community. It should be considered experimental as Qubes developers team use mainly Fedora-based VMs @@ -18,366 +17,100 @@ to test new features/updates. Main maintainer of this template is [Olivier Médoc](mailto:o_medoc@yahoo.fr). -
+Updates for this template are provided by [Olivier Médoc](mailto:o_medoc@yahoo.fr) and are signed by the following key: -## Instructions ## -
-**These are the instructions for Qubes 3.1. They will take you step by step thru the entire process start to finish** + pub 2048R/2043E7ACC1833B9C 2014-03-27 [expires: 2018-03-29] + Key fingerprint = D85E E12F 9678 51CC F433 515A 2043 E7AC C183 3B9C + uid Olivier MEDOC (Qubes-OS signing key) -*Note: Currently there are no binary packages and it must be compiled from source using the instructions below.* - -
-
-
- -#### **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. -
-
-![arch-template-01](/attachment/wiki/ArchlinuxTemplate/arch-template-01.png) -
-
-* Ensure there is at least 25GB preferably 30GB of free space in the private storage. I made the private storage 30GB to be safe. -
-
-![arch-template-02](/attachment/wiki/ArchlinuxTemplate/arch-template-02.png) -
-
- -*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 -
-
-![arch-template-03](/attachment/wiki/ArchlinuxTemplate/arch-template-03.png) -
-
-
- -##### **3: Install necessary packages to 'development' VM for "Qubes Automated Build System":** ##### - -* Necessary packages to install: - - * git - - * createrepo - - * rpm-build - - * make - - * rpmdevtools - - * python-sh - - * dailog - - * rpm-sign -
- - -* 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** -
-
-![arch-template-04](/attachment/wiki/ArchlinuxTemplate/arch-template-04.png) -
-
-
- -##### **4: Installing the "Qubes Automated Build System":** ##### - -* To get the most current build system its best to use marmarek's git repository. - - * $ **git clone https://github.com/marmarek/qubes-builder.git** -
-
-![arch-template-05](/attachment/wiki/ArchlinuxTemplate/arch-template-05.png) -
-
- -* You will now have the Qubes Builder System environment installed in the directory below: - - * **/home/user/qubes-builder** -
-
-
- -##### **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.1.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.1.conf** or **$ gedit qubes-os-r3.1.conf** or etc…. -
-
-![arch-template-06](/attachment/wiki/ArchlinuxTemplate/arch-template-06.png) -
-
- * 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. -
-
-![arch-template-07](/attachment/wiki/ArchlinuxTemplate/arch-template-07.png) -
-
-
- -##### **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** -
-
-![arch-template-08](/attachment/wiki/ArchlinuxTemplate/arch-template-08.png) -
-
- * 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**' -
-
-![arch-template-09](/attachment/wiki/ArchlinuxTemplate/arch-template-09.png) -
-
- - * 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**' -
-
-![arch-template-10](/attachment/wiki/ArchlinuxTemplate/arch-template-10.png) -
-
- - * This screen will give you the choice of which Qubes Release to build the template for. - - * Select '**Qubes Release 3.1**' - * Select '**OK**' Press '**Enter**' -
-
-![arch-template-11](/attachment/wiki/ArchlinuxTemplate/arch-template-11.png) -
-
- - * Screen "**Choose Repos To Use To Build Packages**" - - * Select 'QubesOS/qubes- Stable - Default Repo' - * Select '**OK**' Press '**Enter**' -
-
- - * Screen "**Build Template Only?**" - - * Select '**Yes**' Press '**Enter**' -
-
-![arch-template-12](/attachment/wiki/ArchlinuxTemplate/arch-template-12.png) -
-
- - * Screen '**Builder Plugin Selection**' will give choices of builder plugins to use for the build. - - * Deselect '**Fedora**' - - * Deselect '**mgnt_salt**' - - * Select '**archlinux**' - - * Select '**OK**' Press **Enter** -
-
-![arch-template-13](/attachment/wiki/ArchlinuxTemplate/arch-template-13.png) -
-
- - * Screen '**Get sources**' wants to download additional packages needed for the choosen plugin/s. - - * Select '**No**' Press '**Enter**' -
-
-![arch-template-14](/attachment/wiki/ArchlinuxTemplate/arch-template-14.png) -
- - * 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**' -
-
-![arch-template-16](/attachment/wiki/ArchlinuxTemplate/arch-template-16.png) -
-
- - *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* -
-
-![arch-template-17](/attachment/wiki/ArchlinuxTemplate/arch-template-17.png) -
-
- * Archlinux builder is not(yet?) in official Qubes release branch, so it has to be downloaded from different repository. - - * Open file builder.conf with your favourite text editor and find section **"O V E R R I D E B R A N C H"** (single space -between letters) and add: - - * **GIT_URL_builder_archlinux = $(GIT_BASEURL)/marmarek/qubes-builder-archlinux.git** - -
-
-![arch-template-17](/attachment/wiki/ArchlinuxTemplate/arch-template-17a.png) -
-
-
- -##### **7: Install all the dependencies:** ##### - -*Note: make sure you are in the “qubes-builder” directory to run the following cmds* - -* **$ make install-deps** -
-
-![arch-template-18](/attachment/wiki/ArchlinuxTemplate/arch-template-18.png) -
-
-
- -##### **8: Get all the require sources for the build: (Note: this may take some time)** ##### - -* **$ make get-sources** -
-
-![arch-template-19](/attachment/wiki/ArchlinuxTemplate/arch-template-19.png) -
-
-
- -##### **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** -
-
-![arch-template-20](/attachment/wiki/ArchlinuxTemplate/arch-template-20.png) -
-
- - - * 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** -
-
+## Installation +A prebuilt template is available only for Qubes 3.2. Before Qubes 3.2, it should be compiled from source as described in [building-archlinux-template](/doc/building-archlinux-template/). -##### **10: Make the actual Archlinux template:** ##### + [user@dom0 ~]$ sudo qubes-dom0-update --enablerepo=qubes-templates-community qubes-template-archlinux -* **$ make template** -
-
-![arch-template-21](/attachment/wiki/ArchlinuxTemplate/arch-template-21.png) -
-
-
+## Binary packages activation +The update repository is disabled when you install (signed) template package. You can however choose to trust it by registering it into pacman. -##### **11: Transfer Template into Dom0** ##### +Enable the repository by running the following command: -* You need to ensure these two files are in the '**noarch**' directory + # mv /etc/pacman.d/99-qubes-repository-3.2.disabled /etc/pacman.d/99-qubes-repository-3.2.conf - * **$ cd /home/user/qubes-builder/qubes-src/linux-template-builder/rpm/** +Then you need to install and sign the public GPG key of the package maintainer (note that accessing to GPG servers requires to temporarily disable the firewall in your template): - * **$ ls** *(confirm the below two files are there)* + # pacman-key --recv-key 2043E7ACC1833B9C + # pacman-key --finger 2043E7ACC1833B9C + +If the fingerprint is correct, you can then sign the key: - * **install-templates.sh** (script to install template in dom0) + # pacman-key --lsign-key 2043E7ACC1833B9C - * **$ cd noarch** +## Default packages - * **$ ls** +In order to keep the template as small and simple as possible, default installed package have been arbitrarily selected based on multiple subjective criterias that however essentially include libraries dependencies. This packages are: +* Some font packages to keep good user experience +* leafpad: a note pad +* xfce4-terminal: a terminal +* thunar: a file browser that support mounting usb keys +* firefox: web browser +* thunderbird: a mail browser +* evince: a document viewer - * **qubes-template-archlinux-X.X.X-XXXXXXXXXXXX.noarch.rpm** (this is the template package 'X' replaces version and build digits) -
-
-![arch-template-22](/attachment/wiki/ArchlinuxTemplate/arch-template-22.png) -
-
+Note that Archlinux does not install GUI packages by default as this decision is left to users. This packages have only been selected to have a usable template. -* **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* +## Updating a Qubes-3.1 Archlinux Template - * Swtich to Domo and open a terminal window. +If you decide to use binary packages but that you where using a Qubes-3.1 Template, your can follow these instructions to enable Qubes 3.2 agents. - **Note:** Take care when entering these cmd strings. They are very long and have a number of characters that are easy to mix '**-**' vs '**.**' '**Templates** (correct) vs **templates** (wrong) or **Template_**'(also wrong) This script will also take care of transfering the actual template.rpm to Dom0 as well. +You can use a template that you built for Qubes 3.1 in Qubes 3.2. The qrexec and gui agent functionnalities should still be working so that you can at least open a terminal. +In order to enable binary packages for Qubes 3.2, add the following lines to the end of /etc/pacman.conf - * **$ cd /** +``` +[qubes-r3.2] +Server = http://olivier.medoc.free.fr/archlinux/current/ +``` - * **$ sudo qvm-run --pass-io development 'cat /home/user/qubes-builder/qubes-src/linux-template-builder/rpm/install-templates.sh' > install-templates.sh** +You should then follow the instruction related to pacman-key in order to sign the binary packages PGP key. With the key enabled, a pacman update will update qubes agents: +` # pacman -Suy ` -
-
-![arch-template-23](/attachment/wiki/ArchlinuxTemplate/arch-template-23.png) -
-
-![arch-template-24](/attachment/wiki/ArchlinuxTemplate/arch-template-24.png) -
-
-
-
+The two line that have just been added to /etc/pacman.conf should then be removed as they have been included in the qubes-vm-core update in the file `/etc/pacmand.d/99-qubes-repository-3.2.conf` -##### **If everything went correct there should be a Archlinux template listed in your Qubes VM Manager** ##### +## Known Issues -
-
-
---------------- +### Package cannot be updated because of errors related to xorg-server or pulseaudio versions -## **Package Manager Proxy Setup Section** ## +In case archlinux upgrade pulseaudio major version or xorg-server version, updating these packages will break the qubes GUI agent. To avoid breaking things, the update is blocked until a new version of the GUI agent is available. +In this case, the gui-agent-linux component of Qubes-OS needs to be rebuild using these last xorg-server or pulseaudio libraries. You can try to rebuilt it yourself or wait for a new qubes-vm-gui package to be available. -One last thing to setup to have a "PROPERLY" functioning archlinux template. +### qubes-vm is apparently starting properly (green dot) however graphical applications do not appears to work -Archlinux package manager Pacman is a fine package mangers except that we could not find a way to configure it to use the Qubes Update Proxy Service (QUPS) that would comply with Qubes QUPS usage policy. +They are multiple potential reasons. Some of them are described in the following issues: +* https://github.com/QubesOS/qubes-issues/issues/2612 + +In issue 2612, check that the option `noauto` is present for all lines in /etc/fstab related to /rw or /home. This bug can appears if you come from an old Archlinux Template (pre February 2017). + +## Debugging a broken VM + +In order to identify the issue, you should start by getting a console access to the VM: + +* Either by running in dom0 `qvm-run --pass-io --nogui yourbrokenvm 'your command here'` + +* Or by running in dom0 `sudo xl console yourbrokenvm` + +Starts by trying to run a GUI application such as xfce4-terminal in order to identify any error message. + +Then you can check potential broken systemd service by running the following command inside the broken vm: `systemctl | grep fail`. + +If you identified a broken service check `journalctl -la -u yourbrokenservice`. If not check `journalctl -b` for errors. + +Finally, errors related to the GUI agent can be found inside the VM in `/home/user/.xsession-errors` + +## Packages manager wrapper -*If someone does find a way please post to the Qubes-Users or Devel google groups mailing list.* Powerpill is a full Pacman wrapper that not only give easy proxy configuration but further offers numerous other advantages. @@ -388,7 +121,7 @@ Please check out: [XYNE's (dev) Powerpill](http://xyne.archlinux.ca/projects/powerpill/) -**Important Note:** Until Powerpill is configured you will have to open network access to the template to get the initial packages etc downloaded. You can use the "allow full access for" a given time period in the FW settings of the template in the VMM or open up the various services thru the same window. Remember to change it back if you choose the later route. Actions needing network access will be noted with (needs network access) +**Important Note:** As you are working in a template vm, by default, you will have to open network access to the template to download files manually, except for package managed which should be handled by the Qubes proxy. You can use the "allow full access for" a given time period in the FW settings of the template in the VMM or open up the various services through the same window. Remember to change it back if you choose the later route. Actions needing network access will be noted with (needs network access)

@@ -564,14 +297,14 @@ Please check out:

-##### **3: Install Powerpill (Pacman wrapper)** (needs network access) ##### +##### **3: Install Powerpill (Pacman wrapper)** ##### * **$ sudo pacman -S powerpill**

-##### **4: Install Reflector** (needs network access) ##### +##### **4: Install Reflector** ##### *Note: It scripts mirror updating. Grabbing the most up to date gen mirror list. It ranks them by most recently sync'd. Then ranks them on fastest speed. Also can be used by Powerpill config to allow a once stop conf file for all if so wanted.* @@ -670,30 +403,10 @@ Note: For info on Reflector and its configs: [Reflector](https://wiki.archlinux.

-#### **Known Issues:** #### - -* If there is an Arch upgrade of Pulse Audio it will require rebuilding and installing Qubes component: gui-agent-linux - -* There May also be a similar issue of dependencies with Xorg. - -* Upgrade Relfector functionality to allow its use thru the QUPS - -* Pacman functionality changes and allows it to be directly configured to work thru QUPS. - -
- -#### **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) - -
- -#### **Want to contribute?** #### +## Want to contribute? * [How can I contribute to the Qubes Project?](/doc/contributing/) -* [Guidelines for Documentation Contributors](doc/doc-guidelines/) +* [Guidelines for Documentation Contributors](/doc/doc-guidelines/)
diff --git a/managing-os/templates/debian.md b/managing-os/templates/debian.md index efb61509..4e6c05df 100644 --- a/managing-os/templates/debian.md +++ b/managing-os/templates/debian.md @@ -12,9 +12,9 @@ redirect_from: Debian template(s) =============== -If you like to use Debian Linux distribution in your AppVMs, you can install one of available Debian templates. +If you would like to use Debian Linux distribution in your qubes, you can install one of the available Debian templates. -Updates for this template are provided by ITL and are signed by this key: +Updates for these templates are provided by ITL and are signed by this key: pub 4096R/47FD92FA 2014-07-27 Key fingerprint = 2D43 E932 54EE EA7C B31B 6A77 5E58 18AB 47FD 92FA @@ -28,21 +28,17 @@ which is also integrity-protected using signed git tags. Install ------- -It can be installed via the following command: +Templates can be installed with the following command: -Debian 7 (wheezy) - old stable: +Debian 7 (wheezy) - obsolete/archive: [user@dom0 ~]$ sudo qubes-dom0-update qubes-template-debian-7 -(The download will take a while, and there will be no progress indicator.) - -Debian 8 (jessie) - stable: +Debian 8 (jessie) - oldstable: [user@dom0 ~]$ sudo qubes-dom0-update qubes-template-debian-8 -(The download will take a while, and there will be no progress indicator.) - -Debian 9 (stretch) - testing: +Debian 9 (stretch) - stable: A prebuilt template is not yet available, but there are two options for achieving a stretch template: @@ -58,4 +54,45 @@ reboot should "just work." Known issues ------------ +###Starting services + + +The Debian way (generally) is to start daemons if they are installed. +This means that if you install (say) ssh-server in a template, *all* the qubes that use that template will run a ssh server when they start. (They will, naturally, all have the same server key.) This may not be what you want. + +So be very careful when installing software in Templates - if the daemon spawns outbound connections then there is a serious security risk. + +In general, a reasonable approach would be, (using ssh as example): +- Install the ssh service. +- systemctl stop ssh +- systemctl disable ssh +- systemctl mask ssh +- Close down template + +Now the ssh service will **NOT** start in qubes based on this template. + +Where you **DO** want the service to run, put this in /rw/config/rc.local: + + systemctl unmask ssh + systemctl start ssh + +Don't forget to make the file executable. + + +###Unattended Upgrades + +Some users have noticed that on upgrading to Stretch, the unattended-upgrade package is installed. + +This package is pulled in as part of a Recommend chain, and can be purged. + +The lesson is that you should carefully look at what is being installed to your system, particularly if you run dist-upgrade. + + +###Contributing + If you want to help in improving the template, feel free to [contribute](/wiki/ContributingHowto). + +More information +---------------- + +* [Debian wiki](https://wiki.debian.org/Qubes) diff --git a/managing-os/debian-template-upgrade-8.md b/managing-os/templates/debian/upgrade-8-to-9.md similarity index 81% rename from managing-os/debian-template-upgrade-8.md rename to managing-os/templates/debian/upgrade-8-to-9.md index fa7209cf..6b397f20 100644 --- a/managing-os/debian-template-upgrade-8.md +++ b/managing-os/templates/debian/upgrade-8-to-9.md @@ -1,8 +1,9 @@ --- layout: doc -title: Upgrading the Debian 8 Template -permalink: /doc/debian-template-upgrade-8/ +title: Upgrading the Debian 8 Template to Debian 9 +permalink: /doc/template/debian/upgrade-8-to-9/ redirect_from: +- /doc/debian-template-upgrade-8/ - /en/doc/debian-template-upgrade-8/ - /doc/DebianTemplateUpgrade8/ - /wiki/DebianTemplateUpgrade8/ @@ -11,10 +12,10 @@ redirect_from: Upgrading the Debian 8 Template =============================== -Disclaimer: Debian 9 (Stretch) is marked testing for a reason. You may notice stability problems when using it. +Please note that if you installed packages from one of the testing repositories you must make sure that the repository is enabled in `/etc/apt/sources.list.d/qubes-r3.list` before attempting the upgrade. Otherwise, your upgrade will [break](https://github.com/QubesOS/qubes-issues/issues/2418). -Summary: Upgrading the Standard Debian 8 Template to Debian 9 -------------------------------------------------------------- +Summary: Upgrading a Debian 8 Template to Debian 9 +-------------------------------------------------- [user@dom0 ~]$ qvm-clone debian-8 debian-9 [user@dom0 ~]$ qvm-run -a debian-9 gnome-terminal @@ -78,7 +79,7 @@ any template based on the standard Debian 8 template. Compacting the Upgraded Template -================================ +-------------------------------- Neither `fstrim` nor the `discard` mount option works on the TemplateVM's root filesystem, so when a file is removed in the template, space is not freed in @@ -110,18 +111,17 @@ TemplateVM's max size + the actually used space there) free space in dom0. [user@dom0 ~]$ mv root.img.new root.img Additional Information -====================== - -It should be noted that Debian 9 (Stretch) is currently marked testing and -should be treat as such. For projects that need absolute stability, upgrading -may not be the best option. +---------------------- Debian Stretch packages were first made available in the Qubes R3.1 repositories. If sound is not working, you may need to enable the Qubes testing repository to get the testing version of qubes-gui-agent. This can be done by editing the /etc/apt/sources.list.d/qubes-r3.list file and uncommenting the Qubes Updates Candidates repo. -Relevant Mailing List Discussions ---------------------------------- +User-initiated updates/upgrades may not run when a templateVM first starts. This is due to a new Debian config setting that attempts to update automatically; it can be [disabled with](https://github.com/QubesOS/qubes-issues/issues/2621) `systemctl disable apt-daily.timer`. + +Relevant Discussions +-------------------- * [Stretch Template Installation](https://groups.google.com/forum/#!topicsearchin/qubes-devel/debian$20stretch/qubes-devel/4rdayBF_UTc) * [Stretch availability in 3.2](https://groups.google.com/forum/#!topicsearchin/qubes-devel/debian$20stretch/qubes-devel/cekPfBqQMOI) - * [Fixing sound in Debian Stretch](https://groups.google.com/forum/#!topic/qubes-users/JddCE54GFiU) \ No newline at end of file + * [Fixing sound in Debian Stretch](https://groups.google.com/forum/#!topic/qubes-users/JddCE54GFiU) + * [User apt commands blocked on startup](https://github.com/QubesOS/qubes-issues/issues/2621) diff --git a/managing-os/templates/fedora-minimal.md b/managing-os/templates/fedora-minimal.md index 5b77088a..433e6e5c 100644 --- a/managing-os/templates/fedora-minimal.md +++ b/managing-os/templates/fedora-minimal.md @@ -12,71 +12,65 @@ redirect_from: Fedora - minimal ================ -The template weighs only about 300MB and has most of the stuff cut off, except for minimal X and xterm. It is really just a barebone and not even usable in this form - but you can customize it to meet your needs. You can find some usage examples in the section below. +The template only weighs about 300 MB and has only the most vital packages installed, including a minimal X and xterm installation. +The minimal template, however, can be easily extended to fit your requirements. The sections below contain the instructions on duplicating the template and provide some examples for commonly desired use cases. +Installation +------------ +The Fedora minimal template can be installed with the following command: -Install +~~~ +[user@dom0 ~]$ sudo qubes-dom0-update qubes-template-fedora-24-minimal +~~~ + +The download may take a while depending on your connection speed. + +Duplication and first steps +--------------------------- + +It is higly recommended to clone the original template, and make any changes in the clone instead of the original template. The following command clones the template. Replace `your-new-clone` with your desired name. + +~~~ +[user@dom0 ~]$ qvm-clone fedora-24-minimal your-new-clone +~~~ + +You must start the template in order to customize it. +A recommended first step is to install the `sudo` package, which is not installed by default in the minimal template: + +~~~ +[user@your-new-clone ~]$ su - +[user@your-new-clone ~]$ dnf install sudo +~~~ + +Customization +------------- + +Customizing the template for specific use cases normally only requires installing additional packages. +The following table provides an overview of which packages are needed for which purpose. + +As expected, the required packages are to be installed in the running template with the following command. Replace "packages` with a space-delimited list of packages to be installed. + +~~~ +[user@your-new-clone ~]$ sudo dnf install packages +~~~ + +Use case | Description | Required steps +--- | --- | --- +**Standard utilities** | If you need the commonly used utilities | Install the following packages: `pciutils` `vim-minimal` `less` `psmisc` `gnome-keyring` +**FirewallVM** | You can use the minimal template as a [FirewallVM](/doc/firewall/), such as the basis template for `sys-firewall` | No extra packages are needed for the template to work as a firewall. +**NetVM** | You can use this template as the basis for a NetVM such as `sys-net` | Install the following packages: `NetworkManager` `NetworkManager-wifi` `network-manager-applet` `wireless-tools` `dbus-x11 dejavu-sans-fonts` `tinyproxy` `notification-daemon` `gnome-keyring`. +**NetVM (extra firmware)** | If your network devices need extra packages for the template to work as a network VM | Use the `lspci` command to identify the devices, then run `dnf search firmware` (replace `firmware` with the appropriate device identifier) to find the needed packages and then install them. +**Network utilities** | If you need utilities for debugging and analyzing network connections | Install the following packages: `tcpdump` `telnet` `nmap` `nmap-ncat` +**USB** | If you want USB input forwarding to use this template as the basis for a [USB](/doc/usb/) qube such as `sys-usb` | Install `qubes-input-proxy-sender` +**VPN** | You can use this template as basis for a [VPN](/doc/vpn/) qube | Use the `dnf search "NetworkManager VPN plugin"` command to look up the VPN packages you need, based on the VPN technology you'll be using, and install them. Some GNOME related packages may be needed as well. After creation of a machine based on this template, follow the [VPN howto](/doc/vpn/#set-up-a-proxyvm-as-a-vpn-gateway-using-networkmanager) to configure it. +**DVM Template** | If you want to use this VM as a [DVM Template](/doc/glossary/#dvm-template) | Install `perl-Encode` + +Logging ------- -It can be installed via the following command: +The `rsyslog` logging service is not installed by default, as all logging is instead being handled by the `systemd` journal. +Users requiring the `rsyslog` service should install it manually. -~~~ -[user@dom0 ~]$ sudo qubes-dom0-update qubes-template-fedora-23-minimal -~~~ +To access the `journald` log, use the `journalctl` command. -Download will take a while and there will be no progress indicator. - -Usage ------ - -It is a good idea to clone the original template, and make any changes in the new clone instead: - -~~~ -[user@dom0 ~]$ qvm-clone fedora-23-minimal -~~~ - -The sudo package is not installed by default, so let's install it: - -~~~ -[user@F23-Minimal ~]$ su - -[user@F23-Minimal ~]$ dnf install sudo -~~~ - -The rsyslog logging service is not installed by default. All logging is now being handled by the systemd journal. Users requiring the rsyslog service should install it manually. - -To access the journald log, use the `journalctl` command. - -### as a NetVM - -If you want to use this template to for standard NetVMs you should install some more packeges: - -~~~ -[user@F21-Minimal ~]$ sudo dnf install NetworkManager NetworkManager-wifi network-manager-applet wireless-tools dbus-x11 dejavu-sans-fonts tinyproxy -~~~ - -And maybe some more optional but useful packages as well: - -~~~ -[user@F21-Minimal ~]$ sudo dnf install pciutils vim-minimal less tcpdump telnet psmisc nmap nmap-ncat gnome-keyring -~~~ - -If your network device needs some firmware then you should also install the corresponding packages as well. The `lspci` and `dnf search firmware` command will help to choose the right one :) - -### as a ProxyVM - -If you want to use this template as a ProxyVM you may want to install even more packages - -#### Firewall - -This template is now ready to use for a standard firewall VM. - -#### VPN - -The needed packages depend on the VPN technology. The `dnf search "NetworkManager VPN plugin"` command may help you to choose the right one. You should also install the corresponding GNOME related packages as well. - -[More details about setting up a VPN Gateway](/wiki/VPN#ProxyVM) - -#### TOR - -[UserDoc/TorVM](/wiki/UserDoc/TorVM) diff --git a/managing-os/templates/fedora.md b/managing-os/templates/fedora.md new file mode 100644 index 00000000..8c78d6d9 --- /dev/null +++ b/managing-os/templates/fedora.md @@ -0,0 +1,11 @@ +--- +layout: doc +title: The Fedora TemplateVM +permalink: /doc/templates/fedora/ +--- + +The Fedora TemplateVM +===================== + +The Fedora TemplateVM is the default TemplateVM in Qubes OS. + diff --git a/managing-os/fedora-template-upgrade-18.md b/managing-os/templates/fedora/upgrade-18-to-20.md similarity index 92% rename from managing-os/fedora-template-upgrade-18.md rename to managing-os/templates/fedora/upgrade-18-to-20.md index d4f92a76..00f4394a 100644 --- a/managing-os/fedora-template-upgrade-18.md +++ b/managing-os/templates/fedora/upgrade-18-to-20.md @@ -1,14 +1,15 @@ --- layout: doc -title: Upgrading the Fedora 18 Temlpate -permalink: /doc/fedora-template-upgrade-18/ +title: Upgrading the Fedora 18 Template to Fedora 20 +permalink: /doc/template/fedora/upgrade-18-to-20/ redirect_from: +- /doc/fedora-template-upgrade-18/ - /en/doc/fedora-template-upgrade-18/ - /doc/FedoraTemplateUpgrade18/ - /wiki/FedoraTemplateUpgrade/ --- -Upgrading the Fedora 18 Temlpate +Upgrading the Fedora 18 Template ================================ (**Note:** There is a [newer version of this page for upgrading from Fedora 20 to Fedora 21](/doc/fedora-template-upgrade-20/).) @@ -50,7 +51,7 @@ sudo yum --releasever=20 --setopt=cachedir=/mnt/removable distro-sync After upgrade is finished, you can remove /var/tmp/template-upgrade-cache.img file. Compacting templates root.img -============================= +----------------------------- fstrim, nor "discard" mount option do not work on template root fs, so when some file is removed in the template, space isn't freed in dom0. This means that template will use about twice a space that is really need after upgrade. diff --git a/managing-os/fedora-template-upgrade-20.md b/managing-os/templates/fedora/upgrade-20-to-21.md similarity index 97% rename from managing-os/fedora-template-upgrade-20.md rename to managing-os/templates/fedora/upgrade-20-to-21.md index c85185db..402a022d 100644 --- a/managing-os/fedora-template-upgrade-20.md +++ b/managing-os/templates/fedora/upgrade-20-to-21.md @@ -1,8 +1,9 @@ --- layout: doc -title: Upgrading the Fedora 20 Template -permalink: /doc/fedora-template-upgrade-20/ +title: Upgrading the Fedora 20 Template to Fedora 21 +permalink: /doc/template/fedora/upgrade-20-to-21/ redirect_from: +- /doc/fedora-template-upgrade-20/ - /en/doc/fedora-template-upgrade-20/ - /doc/FedoraTemplateUpgrade20/ - /wiki/FedoraTemplateUpgrade20/ @@ -157,7 +158,7 @@ minimal template) is the same as the procedure for the standard template above, Compacting the Upgraded Template -================================ +-------------------------------- Neither `fstrim` nor the `discard` mount option works on the TemplateVM's root filesystem, so when a file is removed in the template, space is not freed in @@ -190,7 +191,7 @@ TemplateVM's max size + the actually used space there) free space in dom0. Additional Information -====================== +---------------------- As mentioned above, you may encounter the following `yum` error: @@ -219,6 +220,6 @@ list which also apply to TemplateVM management and migration in general: * [Jason M](https://groups.google.com/d/msg/qubes-users/mCXkxlACILQ/5PxDfI-RKAsJ) Known issues with Fedora 21 -=========================== +--------------------------- * [The "Update VM" command in Qubes Manager does not work](https://github.com/QubesOS/qubes-issues/issues/982). diff --git a/managing-os/fedora-template-upgrade-21.md b/managing-os/templates/fedora/upgrade-21-to-23.md similarity index 97% rename from managing-os/fedora-template-upgrade-21.md rename to managing-os/templates/fedora/upgrade-21-to-23.md index c908ea43..0353de2c 100644 --- a/managing-os/fedora-template-upgrade-21.md +++ b/managing-os/templates/fedora/upgrade-21-to-23.md @@ -1,8 +1,9 @@ --- layout: doc -title: Upgrading the Fedora 21 Template -permalink: /doc/fedora-template-upgrade-21/ +title: Upgrading the Fedora 21 Template to Fedora 23 +permalink: /doc/template/fedora/upgrade-21-to-23/ redirect_from: +- /doc/fedora-template-upgrade-21/ - /en/doc/fedora-template-upgrade-21/ - /doc/FedoraTemplateUpgrade21/ - /wiki/FedoraTemplateUpgrade21/ @@ -140,7 +141,7 @@ minimal template) is the same as the procedure for the standard template above, Compacting the Upgraded Template -================================ +-------------------------------- Neither `fstrim` nor the `discard` mount option works on the TemplateVM's root filesystem, so when a file is removed in the template, space is not freed in @@ -173,7 +174,7 @@ TemplateVM's max size + the actually used space there) free space in dom0. Additional Information -====================== +---------------------- As mentioned above, you may encounter the following `yum` error: @@ -202,13 +203,13 @@ list which also apply to TemplateVM management and migration in general: * [Jason M](https://groups.google.com/d/msg/qubes-users/mCXkxlACILQ/5PxDfI-RKAsJ) Upgrading to Fedora 22 -====================== +---------------------- You may choose to upgrade to Fedora 22 instead of Fedora 23. In that case, simply replace version "23" with "22" in all above commands. Known issues with Fedora 23 -=========================== +--------------------------- * [Graphical update tools (using PackageKit) does not work](https://github.com/QubesOS/qubes-issues/issues/982). * [Dnf (new Fedora package manager) needs a lot of time to process repository metadata](https://bugzilla.redhat.com/show_bug.cgi?id=1227014), you may want to use `yum-deprecated` for now diff --git a/managing-os/templates/fedora/upgrade-23-to-24.md b/managing-os/templates/fedora/upgrade-23-to-24.md new file mode 100644 index 00000000..73b7b8af --- /dev/null +++ b/managing-os/templates/fedora/upgrade-23-to-24.md @@ -0,0 +1,238 @@ +--- +layout: doc +title: Upgrading the Fedora 23 Template to Fedora 24 +permalink: /doc/template/fedora/upgrade-23-to-24/ +redirect_from: +- /doc/fedora-template-upgrade-23/ +- /en/doc/fedora-template-upgrade-23/ +- /doc/FedoraTemplateUpgrade23/ +- /wiki/FedoraTemplateUpgrade23/ +--- + +Upgrading the Fedora 23 Template +================================ + +Summary: Upgrading the Standard Fedora 23 Template to Fedora 24 +--------------------------------------------------------------- + +**Note:** The prompt on each line indicates where each command should be entered +(`@dom0` or `@fedora-24`). + + [user@dom0 ~]$ qvm-clone fedora-23 fedora-24 + [user@dom0 ~]$ truncate -s 5GB /var/tmp/template-upgrade-cache.img + [user@dom0 ~]$ qvm-run -a fedora-24 gnome-terminal + [user@dom0 ~]$ qvm-block -A fedora-24 dom0:/var/tmp/template-upgrade-cache.img + [user@fedora-24 ~]$ sudo mkfs.ext4 /dev/xvdi + [user@fedora-24 ~]$ sudo mount /dev/xvdi /mnt/removable + [user@fedora-24 ~]$ sudo dnf clean all + [user@fedora-24 ~]$ sudo dnf --releasever=24 --setopt=cachedir=/mnt/removable distro-sync + + (Shut down TemplateVM by any normal means.) + + [user@dom0 ~]$ rm /var/tmp/template-upgrade-cache.img + [user@dom0 ~]$ qvm-trim-template fedora-24 + +(Optional cleanup: Switch everything over to the new template and delete the old +one. See instructions below for details.) + + +Detailed: Upgrading the Standard Fedora 23 Template to Fedora 24 +---------------------------------------------------------------- + +These instructions will show you how to upgrade the standard Fedora 23 +TemplateVM to Fedora 24. The same general procedure may be used to upgrade any +template based on the standard Fedora 23 template. + +**Note:** The command-line prompt on each line indicates where each command +should be entered (`@dom0` or `@fedora-24`). + + 1. Ensure the existing template is not running. + + [user@dom0 ~]$ qvm-shutdown fedora-23 + + 2. Clone the existing template and start a terminal in the new template. + + [user@dom0 ~]$ qvm-clone fedora-23 fedora-24 + [user@dom0 ~]$ qvm-run -a fedora-24 gnome-terminal + + 3. Attempt the upgrade process in the new template. + + [user@fedora-24 ~]$ sudo dnf clean all + [user@fedora-24 ~]$ sudo dnf --releasever=24 distro-sync + + **Note:** `dnf` might ask you to approve importing a new package signing + key. For example, you might see a prompt like this one: + + warning: /var/cache/dnf/fedora-d02ca361e1b58501/packages/python2-babel-2.3.4-1.fc24.noarch.rpm: Header V3 RSA/SHA256 Signature, key ID 81b46521: NOKEY + Importing GPG key 0x81B46521: + Userid : "Fedora (24) " + Fingerprint: 5048 BDBB A5E7 76E5 47B0 9CCC 73BD E983 81B4 6521 + From : /etc/pki/rpm-gpg/RPM-GPG-KEY-fedora-24-x86_64 + Is this ok [y/N]: + + This key was already checked when it was installed (notice that the "From" + line refers to a location on your local disk), so you can safely say yes to + this prompt. + + **Note:** If you encounter no errors, proceed to step 4. If you do encounter + errors, see the next two points first. + + * If `dnf` reports that you do not have enough free disk space to proceed + with the upgrade process, create an empty file in dom0 to use as a cache + and attach it to the template as a virtual disk. + + [user@dom0 ~]$ truncate -s 5GB /var/tmp/template-upgrade-cache.img + [user@dom0 ~]$ qvm-block -A fedora-24 dom0:/var/tmp/template-upgrade-cache.img + + Then reattempt the upgrade process, but this time use the virtual disk + as a cache. + + [user@fedora-24 ~]$ sudo mkfs.ext4 /dev/xvdi + [user@fedora-24 ~]$ sudo mount /dev/xvdi /mnt/removable + [user@fedora-24 ~]$ sudo dnf clean all + [user@fedora-24 ~]$ sudo dnf --releasever=24 --setopt=cachedir=/mnt/removable distro-sync + + If this attempt is successful, proceed to step 4. + + * `dnf` may complain: + + At least X MB more space needed on the / filesystem. + + In this case, one option is to [resize the TemplateVM's disk + image][resize-disk-image] before reattempting the upgrade process. + (See [Additional Information] below for other options.) + + 4. Shut down the new TemplateVM (from the command-line or Qubes VM Manager). + + [user@dom0 ~]$ qvm-shutdown fedora-24 + + 5. Remove the cache file, if you created one. + + [user@dom0 ~]$ rm /var/tmp/template-upgrade-cache.img + + 6. Trim the new template (see [Compacting the Upgraded Template] for details + and other options). + + [user@dom0 ~]$ qvm-trim-template fedora-24 + + 7. (Recommended) Switch everything that was set to the old template to the new + template, e.g.: + + 1. Make the new template the default template: + + Qubes Manager --> Global settings --> Default template + + 2. Base AppVMs on the new template. In Qubes Manager, for each VM that is + currently based on `fedora-23` that you would like to base on + `fedora-24`, enter its VM settings and change the Template selection: + + Qubes Manager --> (Select a VM) --> VM settings --> Template + + 3. Base the [DispVM] template on the new template. + + If you have set the new template as your default template: + + [user@dom0 ~]$ qvm-create-default-dvm --default-template + + Otherwise: + + [user@dom0 ~]$ qvm-create-default-dvm fedora-24 + + 8. (Optional) Remove the old template. (Make sure to type `fedora-23`, not + `fedora-24`.) + + [user@dom0 ~]$ sudo dnf remove qubes-template-fedora-23 + + +Summary: Upgrading the Minimal Fedora 23 Template to Fedora 24 +-------------------------------------------------------------- + +**Note:** The prompt on each line indicates where each command should be entered +(`@dom0` or `@fedora-24`). + + [user@dom0 ~]$ qvm-clone fedora-23-minimal fedora-24-minimal + [user@dom0 ~]$ qvm-run -a fedora-24-minimal xterm + [user@fedora-24-minimal ~]$ su - + [root@fedora-24-minimal ~]# dnf clean all + [user@fedora-24-minimal ~]# dnf --releasever=24 distro-sync + + (Shut down TemplateVM by any normal means.) + + [user@dom0 ~]$ qvm-trim-template fedora-24-minimal + +(If you encounter insufficient space issues, you may need to use the methods +described for the standard template above.) + + +Differences Between the Standard and Minimal Upgrade Procedures +--------------------------------------------------------------- + +The procedure for upgrading the minimal template (or any template based on the +minimal template) is the same as the procedure for the standard template above, +**with the following exceptions**: + + 1. `gnome-terminal` is not installed by default. Unless you've installed it + (or another terminal emulator), use `xterm`. (Of course, you can also use + `xterm` for the standard template, if you prefer.) + 2. `sudo` is not installed by default. Unless you've installed it, use `su` as + demonstrated above. (Of course, you can also use `su` for the standard + template, if you prefer.) + + +Compacting the Upgraded Template +-------------------------------- + +Neither `fstrim` nor the `discard` mount option works on the TemplateVM's root +filesystem, so when a file is removed in the template, space is not freed in +dom0. This means that the template will use about twice as much space as is +really necessary after upgrading. + +You can use the `qvm-trim-template` tool: + + [user@dom0 ~]$ qvm-trim-template fedora-24 + + +Upgrading StandaloneVMs +----------------------- + +The procedure for upgrading a StandaloneVM from Fedora 23 to Fedora 24 is the +same as for a TemplateVM, except that `qvm-trim-template` does not work on +StandaloneVMs. Instead, you should run the following command inside the +StandaloneVM in order to compact it: + + $ sudo fstrim -v -a + + +Additional Information +---------------------- + +As mentioned above, you may encounter the following `dnf` error: + + At least X MB more space needed on the / filesystem. + +In this case, you have several options: + + 1. [Increase the TemplateVM's disk image size][resize-disk-image]. + This is the solution mentioned in the main instructions above. + 2. Delete files in order to free up space. One way to do this is by + uninstalling packages. You may then reinstalling them again after you + finish the upgrade process, if desired). However, you may end up having to + increase the disk image size anyway (see previous option). + 3. Increase the `root.img` size with `qvm-grow-root`. + 4. Do the upgrade in parts, e.g., by using package groups. (First upgrade + `@core` packages, then the rest.) + 5. Do not perform an in-place upgrade. Instead, simply download and install a + new template package, then redo all desired template modifications. + + With regard to the last option, here are some useful messages from the + mailing list which also apply to TemplateVM management and migration in + general: + + * [Marek](https://groups.google.com/d/msg/qubes-users/mCXkxlACILQ/dS1jbLRP9n8J) + * [Jason M](https://groups.google.com/d/msg/qubes-users/mCXkxlACILQ/5PxDfI-RKAsJ) + + +[resize-disk-image]: /doc/resize-disk-image/ +[Additional Information]: #additional-information +[Compacting the Upgraded Template]: #compacting-the-upgraded-template +[DispVM]: /doc/dispvm/ diff --git a/managing-os/templates/ubuntu.md b/managing-os/templates/ubuntu.md index 3a100cc5..832ccd1d 100644 --- a/managing-os/templates/ubuntu.md +++ b/managing-os/templates/ubuntu.md @@ -12,11 +12,11 @@ redirect_from: Ubuntu template(s) ================== -If you like to use Ubuntu Linux distribution in your AppVMs, you can build and -install one of available Ubuntu templates. Those template currently are not +If you would like to use Ubuntu Linux distribution in your AppVMs, you can build and +install one of the available Ubuntu templates. These templates are currently not available in ready to use binary packages, because Canonical does not allow -to redistribute a modified Ubuntu. The redistribution is not allowed by their -[Intellectual property rights policy](http://www.ubuntu.com/legal/terms-and-policies/intellectual-property-policy). +redistribution of a modified Ubuntu. The redistribution is not allowed by their +[Intellectual property rights policy](https://www.ubuntu.com/legal/terms-and-policies/intellectual-property-policy). Install @@ -26,19 +26,15 @@ It can built using [Qubes Builder](/doc/qubes-builder/). You can also access its documentation in the [source code repository](https://github.com/QubesOS/qubes-builder/blob/master/README.md). -To quickly prepare the builder configuration, you can use `setup` script +To quickly prepare the builder configuration, you can use the `setup` script available in the repository - it will interactively ask you which templates you want to build. -Known issues ------------- +The build for Ubuntu 14.4 LTS (Trusty) should be straightforward. -Building an Ubuntu 14.4 LTS template can be difficult ([see](https://groups.google.com/forum/#!topic/qubes-users/w0uZNr8nno8)). -A workaround is creating an ubuntu HVM A and use X over ssh from a second vm B ([see](https://groups.google.com/forum/#!topic/qubes-users/-wkG7E55PUI)). -To do this you have to enable networking between A and B, or set B as netvm of A. -If B supports copy and paste or seamless mode so does (indirectly) A. (you will be missing some features. e.g.: send file to vm A) -Doing this reduces the security of A to the security of B! -This is no problem, if B's only purpose is providing X over ssh only for vm A. +The build for Ubuntu 16.4 LTS (Xenial) is straightforward. + +---------- If you want to help in improving the template, feel free to -[contribute](/wiki/ContributingHowto). +[contribute](/doc/contributing/). diff --git a/managing-os/uninstalling-windows-tools-2.md b/managing-os/windows/uninstalling-windows-tools-2.md similarity index 99% rename from managing-os/uninstalling-windows-tools-2.md rename to managing-os/windows/uninstalling-windows-tools-2.md index caa89c45..d275eeb9 100644 --- a/managing-os/uninstalling-windows-tools-2.md +++ b/managing-os/windows/uninstalling-windows-tools-2.md @@ -60,7 +60,7 @@ If you need network access to copy the uninstall script to the HVM, use *Safe Mo The uninstall script -==================== +-------------------- Save it as a .BAT file in the HVM and run in Safe Mode. diff --git a/managing-os/windows-appvms.md b/managing-os/windows/windows-appvms.md similarity index 79% rename from managing-os/windows-appvms.md rename to managing-os/windows/windows-appvms.md index ab46af5d..c43487b9 100644 --- a/managing-os/windows-appvms.md +++ b/managing-os/windows/windows-appvms.md @@ -51,6 +51,14 @@ sudo qubes-dom0-update --enablerepo=qubes-dom0-current-testing qubes-windows-too This package brings the ISO with Qubes Windows Tools that is passed to the VM when `--install-windows-tools` is specified for the `qvm-start` command. Please note that none of this software ever runs in Dom0 or any other part of the system except for the Windows AppVM in which it is to be installed. +Before proceeding with the installation we need to disable Windows mechanism that allows only signed drivers to be installed, because currently (beta releases) the drivers we provide as part of the Windows Tools are not digitally signed with a publicly recognizable certificate. To do that: + +- Start command prompt as Administrator, i.e. right click on the Command Prompt icon and choose "Run as administrator" +- In the command prompt type `bcdedit /set testsigning on` +- Reboot your Windows VM + +In the future this step will not be necessary anymore, because we will sign our drivers with a publicly verifiable certificate. However, it should be noted that even now, the fact that those drivers are not digitally signed, this doesn't affect security of the Windows VM in 'any' way. This is because the actual installation ISO (the `qubes-windows-tools-*.iso` file) is distributed as a signed RPM package and its signature is verified by the `qubes-dom0-update` utility once it's being installed in Dom0. The only downside of those drivers not being signed is the inconvenience to the user that he or she must disable the signature enforcement policy before installing the tools. + To install the Qubes Windows Tools in a Windows VM one should start the VM passing the additional option `--install-windows-tools`: ~~~ @@ -59,9 +67,7 @@ qvm-start lab-win7 --install-windows-tools Once the Windows VM boots, a CDROM should appear in the 'My Computer' menu (typically as `D:`) with a setup program in its main directory. -Before proceeding with the installation we need to disable Windows mechanism that allows only signed drivers to be installed, because currently (beta releases) the drivers we provide as part of the Windows Tools are not digitally signed with a publicly recognizable certificate. How to do that is explained in the `README` file also located on the installation CDROM. In the future this step will not be necessary anymore, because we will sign our drivers with a publicly verifiable certificate. However, it should be noted that even now, the fact that those drivers are not digitally signed, this doesn't affect security of the Windows VM in 'any' way. This is because the actual installation ISO (the `qubes-windows-tools-*.iso` file) is distributed as a signed RPM package and its signature is verified by the `qubes-dom0-update` utility once it's being installed in Dom0. The only downside of those drivers not being signed is the inconvenience to the user that he or she must disable the signature enforcement policy before installing the tools. - -After successful installation, the Windows VM must be shut down and started again. +After successful installation, the Windows VM must be shut down and started again, possibly a couple of times (see [this page](/doc/windows-tools-3/) for detailed configuration options). Qubes (R2 Beta 3 and later releases) will automatically detect the tools has been installed in the VM and will set appropriate properties for the VM, such as `qrexec_installed`, `guiagent_installed`, and `default_user`. This can be verified (but is not required) using qvm-prefs command: @@ -69,7 +75,7 @@ Qubes (R2 Beta 3 and later releases) will automatically detect the tools has bee qvm-prefs ~~~ -NOTE: it is recommended to increase the default value of `qrexec_timeout` property from 60 (seconds) to, for example, 300. During one of the first reboots after Windows Tools installation Windows user profiles are moved onto the private VM's virtual disk (private.img) and this operation can take some time. Moving profiles is performed in an early boot phase when qrexec is not yet running, so timeout may occur with the default value. To change the property use this command in dom0: +NOTE: it is recommended to increase the default value of Windows VM's `qrexec_timeout` property from 60 (seconds) to, for example, 300. During one of the first reboots after Windows Tools installation Windows user profiles are moved onto the private VM's virtual disk (private.img) and this operation can take some time. Moving profiles is performed in an early boot phase when qrexec is not yet running, so timeout may occur with the default value. To change the property use this command in dom0: ~~~ qvm-prefs -s qrexec_timeout 300 @@ -93,7 +99,7 @@ Also, the inter-VM services work as usual -- e.g. to request opening a document ~~~ ~~~ -[user@work ~]$ qvm-open-in-vm work-win7 http://www.invisiblethingslab.com +[user@work ~]$ qvm-open-in-vm work-win7 https://invisiblethingslab.com ~~~ ... just like in case of Linux AppVMs. Of course all those operations are governed by central policy engine running in Dom0 -- if the policy doesn't contain explicit rules for the source and/or target AppVM, the user will be asked for decision whether to allow or deny the operation. @@ -104,10 +110,10 @@ To simulate CTRL-ALT-DELETE in the HVM (SAS, Secure Attention Sequence), press C ![windows-seamless-7.png](/attachment/wiki/WindowsAppVms/windows-seamless-7.png) -Forcing Windows AppVM into full desktop mode --------------------------------------------- +Changing between seamless and full desktop mode +----------------------------------------------- -You can switch between seamless and "full desktop" mode for Windows HVMs in their settings in Qubes Manager. +You can switch between seamless and "full desktop" mode for Windows HVMs in their settings in Qubes Manager. The latter is the default. Using template-based Windows AppVMs (Qubes R2 Beta 3 and later) --------------------------------------------------------------- @@ -123,7 +129,7 @@ qvm-create --hvm-template win7-x64-template -l green - The private disk is initialized and formatted on the first reboot after tools installation. It can't be done **during** the installation because Xen mass storage drivers are not yet active. - User profiles are moved to the private disk on the next reboot after the private disk is initialized. Reboot is required because the "mover utility" runs very early in the boot process so OS can't yet lock any files in there. This can take some time depending on the profiles' size and because the GUI agent is not yet active dom0/Qubes Manager may complain that the AppVM failed to boot. That's a false alarm (you can increase AppVM's default boot timeout using `qvm-prefs`), the VM should appear "green" in Qubes Manager shortly after. -It also makes sense to disable Automatic Updates for all the Windows-based AppVMs -- of course this should be done in the Template VM, not in individual AppVMs, because the system-wide setting are stored in the root filesystem (which holds the system-wide registry hives). +It also makes sense to disable Automatic Updates for all the template-based AppVMs -- of course this should be done in the Template VM, not in individual AppVMs, because the system-wide setting are stored in the root filesystem (which holds the system-wide registry hives). Then, periodically check for updates in the Template VM and the changes will be carried over to any child AppVMs. Once the template has been created and installed it is easy to create AppVMs based on: diff --git a/managing-os/windows-tools-2.md b/managing-os/windows/windows-tools-2.md similarity index 100% rename from managing-os/windows-tools-2.md rename to managing-os/windows/windows-tools-2.md diff --git a/managing-os/windows-tools-3.md b/managing-os/windows/windows-tools-3.md similarity index 85% rename from managing-os/windows-tools-3.md rename to managing-os/windows/windows-tools-3.md index 879602b8..8d4a5fea 100644 --- a/managing-os/windows-tools-3.md +++ b/managing-os/windows/windows-tools-3.md @@ -32,16 +32,17 @@ Qubes Windows Tools (QWT for short) contain several components than can be enabl **In testing VMs only** it's probably a good idea to install a VNC server before installing QWT. If something goes very wrong with the Qubes gui agent, a VNC server should still allow access to the OS. -**NOTE**: Xen PV disk drivers are not installed by default. This is because they seem to cause severe problems, including disk image/files corruption in Qubes HVMs. We're investigating this. *However*, the problem doesn't always occur in tests -- disk drivers often work *if they are installed separately after the main portion of QWT is up and running*. **Do this at your own risk** of course, but we welcome reports of success/failure in any case. With disk PV drivers absent `qvm-block` will not work for the VM, but you can still use standard Qubes inter-VM file copying mechanisms. +**NOTE**: Xen PV disk drivers are not installed by default. This is because they seem to cause problems (BSOD). We're working with upstream devs to fix this. *However*, the BSOD seems to only occur after the first boot and everything works fine after that. **Enable the drivers at your own risk** of course, but we welcome reports of success/failure in any case (backup your VM first!). With disk PV drivers absent `qvm-block` will not work for the VM, but you can still use standard Qubes inter-VM file copying mechanisms. -Verbose installation --------------------- +Xen PV driver components may display a message box asking for reboot during installation -- it's safe to ignore them and defer the reboot. -If the install process fails you can retry it using the command line below to get a detailed installation log (and send that to us): +Installation logs +----------------- -`msiexec /i path-to-qubes-tools.msi /lv path-to-log-file.txt` +If the install process fails or something goes wrong during it, include the installation logs in your bug report. They are created in the `%TEMP%` directory, by default `\AppData\Local\Temp`. There are two text files, one small and one big, with names starting with `Qubes_Windows_Tools`. -Uninstalling QWT 3.x is **not recommended**. It will most likely make the OS non-bootable because drivers for Xen storage devices will be uninstalled. This will be fixed in the future. +Uninstalling QWT is supported from version 3.2.1. Uninstalling previous versions is **not recommended**. +After uninstalling you need to manually enable the DHCP Client Windows service, or set IP settings yourself to restore network access. Configuration ------------- diff --git a/privacy/anonymizing-your-mac-address.md b/privacy/anonymizing-your-mac-address.md index ea3b623a..b59c6ada 100644 --- a/privacy/anonymizing-your-mac-address.md +++ b/privacy/anonymizing-your-mac-address.md @@ -9,26 +9,62 @@ redirect_from: Anonymizing your MAC Address ============================ -Changing the default [MAC Address](https://en.wikipedia.org/wiki/MAC_address) of your hardware is [crucial in protecting -privacy](https://tails.boum.org/contribute/design/MAC_address/#index1h1). Currently, Qubes OS *does not* "anonymize" or spoof the MAC Address, so until this is implemented by default you can randomize your MAC Address with the following guide. +Although it is not the only metadata broadcast by network hardware, changing the default [MAC Address](https://en.wikipedia.org/wiki/MAC_address) of your hardware could be [an important step in protecting +privacy](https://tails.boum.org/contribute/design/MAC_address/#index1h1). Currently, Qubes OS *does not* automatically "anonymize" or spoof the MAC Address, so until this is implemented by default you can randomize your MAC Address with one of the following guides using either Network Manager or macchanger... -## Configuring Qubes +## Upgrading and configuring Network Manager in Qubes + +Newer versions of Network Manager have a robust set of options for randomizing MAC addresses, and can handle the entire process across reboots, sleep/wake cycles and different connection states. In particular, versions 1.4.2 and later should be well suited for Qubes. + +NM 1.4.2 is currently available from the Debian 9 (testing) repository, and has been tested in Qubes using a Debian template [upgraded to version 9.](https://www.qubes-os.org/doc/debian-template-upgrade-8/) + +In the Debian 9 template you intend to use as a NetVM, check that Network Manager version is now at least 1.4.2: + +~~~ +$ sudo NetworkManager -V +1.4.2 +~~~ + +Write the settings to a new file in the `/etc/NetworkManager/conf.d/` directory, such as `mac.conf`. The following example enables Wifi and Ethernet MAC address randomization while scanning (not connected), and uses a randomly generated but persistent MAC address for each individual Wifi and Ethernet connection profile. + +~~~ +[device] +wifi.scan-rand-mac-address=yes + +[connection] +wifi.cloned-mac-address=stable +ethernet.cloned-mac-address=stable +~~~ + +`stable` generates a random address that persists for each boot session. +`random` generates a random address each time a link goes up. + +To see all the available configuration options, refer to the man page: `man nm-settings` + +Next, create a new NetVM using the new template and assign network devices to it. + +Finally, shutdown all VMs and change the settings of sys-firewall, etc. to use the new NetVM. + +You can check the MAC address currently in use by looking at the status pages of your router device(s), or in the NetVM with the command `sudo ip link show`. + + +## Configuring Qubes with macchanger and scripts First thing you need to do is install **macchanger** package by opening your `fedora-23` TemplateVM and typing -``` +~~~ sudo dnf install macchanger -``` +~~~ Then create the file `macspoof@.service` in `fedora-23` located at `/etc/systemd/system/` directory using a text editor such as `vim`, `emacs`, or `gedit` -``` +~~~ sudo gedit /etc/systemd/system/macspoof@.service -``` +~~~ Paste the following inside of that newly created file -``` +~~~ [Unit] Description=macchanger on %I # Hack since macspoof@%i contains @ which is not allowed yet @@ -44,15 +80,15 @@ Type=oneshot [Install] WantedBy=multi-user.target -``` +~~~ **How random do you want your MAC address?** Note in the above line `ExecStart=/usr/bin/macchanger -e %I` we recommend the use of `macchanger` with the `-e` flag which randomizes the MAC address to an address by the same device vendor/manufacturer. There a [number of other flags](http://manpages.ubuntu.com/manpages/xenial/en/man1/macchanger.1.html) you could use instead, such as `-r` which makes a totally random MAC address, which may map to a non-existent device vendor/manufacturer and make it obvious you are spoofing your MAC address. Some reasons why we have recommended `-e` rather than `-r` are in these resources: -* https://tails.boum.org/contribute/design/MAC_address/#index5h2 -* https://tails.boum.org/contribute/design/MAC_address/#limitation-only-spoof-nic-part -* https://help.ubuntu.com/community/AnonymizingNetworkMACAddresses#Fully_Random +* +* +* **Get the right iface names** @@ -60,7 +96,7 @@ It's crucial to get the correct **iface name** for the devices (ethernet and wif open your `sys-net` (or wherever your device drivers are) and type in `terminal` the command `ifconfig` the printout will look like: -``` +~~~ enp0s0: flags=4099 mtu 1500 ether 9e:d6:53:02:4b:b6 txqueuelen 1000 (Ethernet) RX packets 0 bytes 0 (0.0 B) @@ -86,7 +122,7 @@ wlp0s1: flags=4163 mtu 1500 RX errors 0 dropped 0 overruns 0 frame 0 TX packets 32 bytes 3712 (3.6 KiB) TX errors 0 dropped 0 overruns 0 carrier 0 collisions 0 -``` +~~~ The **iface name** values you're interested in are `enp0s0` and `wlp0s1` as those represent your ethernet and wifi devices, respectively. @@ -98,29 +134,29 @@ respectively. *Copy these MAC addresses down somewhere for later.* Now, go back to your `fedora-23` TemplateVM and use the `touch` command to create service files in the appropriate place, note that the `iface name` values at the end: -``` +~~~ cd /var/run/qubes-service/ sudo touch macspoof-enp0s0 sudo touch macspoof-wlp0s1 -``` +~~~ Verify the correct files exist in the directory -``` +~~~ [user@fedora-23 qubes-service]$ ls cups macspoof-wlp0s1 qubes-update-check macspoof-enp0s0 meminfo-writer updates-proxy-setup -``` +~~~ Now, also within the TemplateVM, type the following commands for each hardware device that you want to randomize a MAC addresses for -``` +~~~ sudo systemctl enable macspoof@wlp0s1 Created symlink from /etc/systemd/system/multi-user.target.wants/macspoof@wlp0s1.service to /etc/systemd/system/macspoof@.service. sudo systemctl enable macspoof@enp0s0 Created symlink from /etc/systemd/system/multi-user.target.wants/macspoof@enp0s0.service to /etc/systemd/system/macspoof@.service. -``` +~~~ Now you can do the following: - Stop your `fedora-23` VM @@ -132,10 +168,10 @@ Open your VM settings for `sys-net`, navigate to Services, and add the new servi Alternatively, you can enable these services for `sys-net` from the command line by opening up Terminal in `dom0` and running the following: -``` +~~~ qvm-service -e sys-net macspoof-wlp0s1 qvm-service -e sys-net macspoof-enp0s0 -``` +~~~ Now restart `sys-net`. @@ -147,14 +183,14 @@ Your MAC address should now randomize each time you restart your computer or res --- -## Usage Notes +## Usage Notes - Macchanger This approach to MAC Randomizing has been tested and used by some users as well as some of the Qubes team. Observations that are to be expected are: - This does not randomize your MAC Address on sleep and wake state (only on restarting the `sys-net` VM) - The `sys-net` networking VM takes longer for device drivers to start up than usual, this delayed startup may cause the first attempt of `sys-whonix` to connect to Tor to fail -## Disabling / Uninstalling +## Disabling / Uninstalling Macchanger To disable MAC Randomizing if you find that a network connecting to does not like changing MAC Addresses, you can disable temporarily or if you want to permanently remove this solution, do the following: diff --git a/privacy/martus.md b/privacy/martus.md index 70a15590..f54c285e 100644 --- a/privacy/martus.md +++ b/privacy/martus.md @@ -7,11 +7,10 @@ permalink: /doc/martus/ Martus ====== -[Martus] is a free, open source, secure information collection and management -tool that empowers rights activists to be stronger in their fight against -injustice and abuse. +[Martus] is a free, open source, secure information collection and management tool +that empowers rights activists to be stronger in their fight against injustice and abuse. -How to install Martus in a qube: +To install Martus in a qube: 1. Create a Debian 8 backports template using the Qubes VM Manager or running `qvm-clone debian-8 debian-8-backports` in dom0. diff --git a/privacy/signal.md b/privacy/signal.md new file mode 100644 index 00000000..a630a50e --- /dev/null +++ b/privacy/signal.md @@ -0,0 +1,86 @@ +--- +layout: doc +title: Signal +permalink: /doc/signal/ +--- + +Signal +====== + +What is [Signal]? + +[According to Wikipedia:][signal-wikipedia] + +> Signal is an encrypted instant messaging and voice calling application +> for Android and iOS. It uses end-to-end encryption to secure all +> communications to other Signal users. Signal can be used to send and receive +> encrypted instant messages, group messages, attachments and media messages. +> Users can independently verify the identity of their messaging correspondents +> by comparing key fingerprints out-of-band. During calls, users can check the +> integrity of the data channel by checking if two words match on both ends of +> the call. +> +> Signal is developed by Open Whisper Systems. The clients are published as free +> and open-source software under the GPLv3 license. + +How to install Signal in Qubes +------------------------------ + +If you're a Signal user on Android, you can now have Signal inside Qubes. + +1. Install the Chromium browser in a TemplateVM. +2. Shut down the TemplateVM. +3. Create a new AppVM based on this TemplateVM. +4. Launch Chromium browser in the new AppVM, type `chrome://extensions/` in the + address bar, and follow the link to the Chrome app store. +4. In the app store, search for "Signal Private Messenger" and install the app. +5. The app launches automatically on first install. Follow the prompts to "link" + this app with your phone. +6. Signal should now work in your AppVM. + +Creating a Shortcut in the applications menu +-------------------------------------------- + +Let's make Signal a bit more usable by creating a shortcut in our desktop +panel that launches Signal directly. This assumes that you're using KDE or Xfce in Dom0, +you use Signal in an AppVM named `Signal`, and this AppVM uses `fedora-23` as its TemplateVM. + +1. Follow [these instructions][shortcut] to create a desktop shortcut on the Desktop of your Signal AppVM. + Let's assume the shortcut file you get is `/home/user/Desktop/chrome-bikioccmkafdpakkkcpdbhpfkkhcmohk-Default.desktop` +2. Copy this shortcut file to the AppVM's TemplateVM - in this case, to `fedora-23`. + + [user@Signal ~]$ qvm-copy-to-vm fedora-23 /home/user/Desktop/chrome-bikioccmkafdpakkkcpdbhpfkkhcmohk-Default.desktop + +3. You'll also want to copy across an icon for your new shortcut - you can find this at + `/home/user/.local/share/icons/hicolor/48x48/apps/chrome-bikioccmkafdpakkkcpdbhpfkkhcmohk-Default.png` + Copy this icon to the `fedora-23` TemplateVM in the same way as step 2. +4. Open a terminal in your `fedora-23` TemplateVM and `cd` to `/home/user/QubesIncoming/Signal/`. + You should find your shortcut and icon files just transferred across from the Signal AppVM. + Move these files to the following locations: + + [user@fedora-23 Signal]$ sudo mv chrome-bikioccmkafdpakkkcpdbhpfkkhcmohk-Default.desktop /usr/share/applications/ + [user@fedora-23 Signal]$ sudo mv chrome-bikioccmkafdpakkkcpdbhpfkkhcmohk-Default.png /usr/share/icons/hicolor/48x48/apps/ + +5. From a Dom0 terminal, instruct Qubes to synchronize the application menus of this TemplateVM: + + [user@dom0 ~]$ qvm-sync-appmenus fedora-23 + +6. Stop both the AppVM (`Signal`) and its TemplateVM (`fedora-23`). + The `Signal` VM will now see the desktop file in `/usr/share/applications` when it is next started. + +7. With your mouse select the `Q` menu -> `Domain: Signal` -> `Signal: Add more shortcuts` + Select `Signal Private Messenger` from the left `Available` column, move it to the right `Selected` column by clicking the `>` button and then `OK` to apply the changes and close the window. +8. (optional, only on KDE:) Follow the `Q` menu once more, right-click on the new `Signal: Signal Private Messenger` menu item and select `Add to Panel`. + +You can now launch the Signal messenger inside its own dedicated AppVM directly from the desktop. + +The same steps should work for any Chrome app. + +----- + +[Signal]: https://whispersystems.org/ +[signal-wikipedia]: https://en.wikipedia.org/wiki/Signal_(software) +[shortcut]: https://support.whispersystems.org/hc/en-us/articles/216839277-Where-is-Signal-Desktop-on-my-computer- +[shortcut-desktop]: /doc/managing-appvm-shortcuts/#tocAnchor-1-1-1 +[message]: https://groups.google.com/d/msg/qubes-users/rMMgeR-KLbU/XXOFri26BAAJ +[mailing list]: /mailing-lists/ diff --git a/privacy/tails.md b/privacy/tails.md index 8227fed8..0f8e8570 100644 --- a/privacy/tails.md +++ b/privacy/tails.md @@ -9,17 +9,20 @@ redirect_from: Running Tails in Qubes ============================ -Tails is the amnesic incognito live system. Its aims are preserving privacy and anonymity. +[Tails](https://tails.boum.org) stands for The Amnesic Incognito Live System. +It is a live operating system that aims to preserve your privacy and anonymity. +Tails is intended to be booted off of a live CD and leave no trace on the computer it is run on, but using Tails this way requires the user to restart their computer every time they want to switch from their installed OS to Tails. +Despite this, in case that method becomes cumbersome, Tails can be used inside virtualization software and Qubes. To run Tails under Qubes: 1. Read about [creating and using HVM qubes](https://www.qubes-os.org/doc/hvm/) -2. Download and verify Tails from http://tails.boum.org in a qube, (saved as `/home/user/Downloads/tails.iso` on qube "isoVM" for purposes of this guide). +2. Download and verify Tails from [https://tails.boum.org](https://tails.boum.org) in a qube, (saved as `/home/user/Downloads/tails.iso` on qube "isoVM" for purposes of this guide). 3. Create a HVM - - in Manager, click VM menu and select "Create VM" + - In Manager, click "VM menu" and select "Create VM" - Name the new qube - "Tails" - Select "HVM" - Configure networking @@ -33,42 +36,45 @@ To run Tails under Qubes: 6. Once the Tails qube has started, configure networking in the qube. - - Check the IP address allocated to the qube - either from GUI Manager, or ```qvm-ls -n Tails``` in Konsole. (E.g. 10.137.1.101 with gateway 10.137.1.1) + - Check the IP address allocated to the qube - either from GUI Manager, or ```qvm-ls -n Tails``` in Konsole. (E.g. `10.137.1.101` with gateway `10.137.1.1`) - In the Tails qube, open systems menu in top-right corner. Select "Wired Settings", and change IPv4 configuration from "Automatic (DHCP)" to "Manual". - - Enter the Address: 10.137.1.101 in our example. - - Enter the Netmask: 255.255.255.0 - - Enter the Gateway: 10.137.1.1 in our example. - - Enter DNS: 10.137.1.1 in our example. + - Enter the Address: `10.137.1.101` in our example. + - Enter the Netmask: `255.255.255.0` + - Enter the Gateway: `10.137.1.1` in our example. + - Enter DNS: `10.137.1.1` in our example. - Click "Apply". You should now see "Connected". 7. Use Tails as normal. ## Usage Notes -###Display issues: +### Display issues: **Black screen on start up.** -This was reported with earlier versions of Tails: I believe the problem is now fixed. +This was reported with earlier versions of Tails: The problem should now be fixed. If you do encounter this problem, you can try to constrain display settings by appending vga codes to the Tails boot parameters. -(If you do not know the codes, append vga=999, and a helpful prompt will appear.) +(If you do not know the codes, append `vga=999`, and a helpful prompt will appear.) N.B Tails 2.3 does not appear to honour the vga code. -**Window extends beyond bottom of screen.** +**Window extends beyond the bottom of the screen.** This seems to arise because Tails sizes to the height of the screen, but there is a title bar at the top of the window. Either remove the title bar altogether, or move the window upwards using ALT+drag. -###Persistent Volume +### Persistent Volume The persistence tools will not work because Tails has not been launched from USB. The HVM disk(s) can be configured and mounted from within Tails to provide persistent storage. -###Shutdown +### Shutdown The Tails qube will not shut down cleanly. Kill it from the GUI Manager or ```qvm-kill Tails``` in Konsole. -###Security +### Security You will probably want to implement [MAC spoofing](https://www.qubes-os.org/doc/anonymizing-your-mac-address/). -Read [the warnings](https://tails.boum.org/doc/advanced_topics/virtualization/) from the Tails team about operating in a virtual machine. +There are added security concerns for Tails users when running it in a virtual machine. +If you intend to do this, you should read [the warnings](https://tails.boum.org/doc/advanced_topics/virtualization/) from the Tails team about it. While the Qubes security model mitigates most of the risks identified, traces of the Tails session may remain on the disk. +Live booting Tails, though less convenient, is always more secure than using it inside virtualization software or Qubes, because you don't run the added risk of the virtualization software or Host OS being compromised. +Depending on your threat model, this might induce too much risk. diff --git a/privacy/torvm.md b/privacy/torvm.md index d333476e..bb1ddf13 100644 --- a/privacy/torvm.md +++ b/privacy/torvm.md @@ -33,7 +33,7 @@ identifying information (IP address and MAC address). Due to the nature of the Tor network, only IPv4 TCP and DNS traffic is allowed. All non-DNS UDP and IPv6 traffic is silently dropped. -See [this article](http://theinvisiblethings.blogspot.com/2011/09/playing-with-qubes-networking-for-fun.html) for a description of the concept, architecture, and the original implementation. +See [this article](https://blog.invisiblethings.org/2011/09/28/playing-with-qubes-networking-for-fun.html) for a description of the concept, architecture, and the original implementation. ## Warning + Disclaimer diff --git a/privacy/whonix.md b/privacy/whonix.md index dfcca26e..5db698ac 100644 --- a/privacy/whonix.md +++ b/privacy/whonix.md @@ -29,16 +29,18 @@ To install Whonix, you must have a working Qubes machine already. * [Install Whonix in Qubes](/doc/whonix/install/) * [Updating Whonix in Qubes](/doc/whonix/update/) -## Customizing & Uninstalling Whonix +## Customizing, Reinstalling, & Uninstalling Whonix * [Customizing Whonix](/doc/whonix/customize/) * [Uninstall Whonix from Qubes](/doc/whonix/uninstall/) -*The following links are on Whonix's website and are technical.* +*The following links are on Whonix's website and may be technical.* -* [Security Advice for after installing Whonix on Qubes](https://www.whonix.org/wiki/Post_Install_Advice) -* [How to set up Tor Bridges in Whonix on Qubes](https://www.whonix.org/wiki/Bridges#How_to_use_bridges_in_Whonix) -* [Using Multiple Whonix-Workstations with Whonix on Qubes](https://www.whonix.org/wiki/Multiple_Whonix-Workstations#Qubes-Whonix) +* [Using Whonix with DisposableVMs](https://www.whonix.org/blog/qubes-whonix-dispvm) +* [Security Advice for after installing Whonix on Qubes](https://www.whonix.org/wiki/Post_Install_Advice) +* [How to set up Tor Bridges in Whonix on Qubes](https://www.whonix.org/wiki/Bridges#How_to_use_bridges_in_Whonix) +* [Using Multiple Whonix-Workstations with Whonix on Qubes](https://www.whonix.org/wiki/Multiple_Whonix-Workstations#Qubes-Whonix) +* [How to use Corridor (a Tor traffic whitelisting gateway) with Whonix](https://www.whonix.org/wiki/Corridor) ## Support for Whonix diff --git a/reference/dom0-tools/qvm-service.md b/reference/dom0-tools/qvm-service.md index eabc08a4..e077265b 100644 --- a/reference/dom0-tools/qvm-service.md +++ b/reference/dom0-tools/qvm-service.md @@ -88,7 +88,7 @@ Enable CUPS service. The user can disable cups in VM which do not need printing crond Default: disabled -Enable CRON service. +Enable CRON service. To have cron jobs persist across reboots, /var/spool/cron is bind-mounted from /rw/bind-dirs. To override this see [Bind-Dir Instructions](/doc/bind-dirs/) ) network-manager Default: enabled in NetVM diff --git a/reference/glossary.md b/reference/glossary.md index 53dc5bad..817c7190 100644 --- a/reference/glossary.md +++ b/reference/glossary.md @@ -13,163 +13,165 @@ Glossary of Qubes Terminology Qubes OS -------- -A security-oriented operating system (OS). The main principle of Qubes OS is -security by compartmentalization (or isolation), in which activities are -compartmentalized (or isolated) in separate **qubes**. +A security-oriented operating system (OS). +The main principle of Qubes OS is security by compartmentalization (or isolation), in which activities are compartmentalized (or isolated) in separate **qubes**. * The official name is `Qubes OS` (note the capitalization and spacing). - However, in casual conversation this is often shortened to `Qubes`, and in - technical contexts where spaces are not permitted, (e.g., usernames), the - space may be omitted, as in `QubesOS`. + However, in casual conversation this is often shortened to `Qubes`, and in technical contexts where spaces are not permitted, (e.g., usernames), the space may be omitted, as in `QubesOS`. VM -- -An abbreviation for "virtual machine." A software implementation of a machine -(for example, a computer) which executes programs like a physical machine. +An abbreviation for "virtual machine." +A software implementation of a machine (for example, a computer) which executes programs like a physical machine. Qube ---- A user-friendly term for a [VM](#vm) in Qubes OS. - * Example: "In Qubes OS, you do your banking in your 'banking' qube and your - web surfing in your 'untrusted' qube. That way, if your 'untrusted' qube is - compromised, your banking activities will remain secure." + * Example: "In Qubes OS, you do your banking in your 'banking' qube and your web surfing in your 'untrusted' qube. That way, if your 'untrusted' qube is compromised, your banking activities will remain secure." - * "Qube" is an informal term intended to make it easier for less technical - users to understand Qubes OS and learn how to use it. In technical - discussions, the other, more precise terms defined on this page are to be - preferred. + * "Qube" is an informal term intended to make it easier for less technical users to understand Qubes OS and learn how to use it. In technical discussions, the other, more precise terms defined on this page are to be preferred. - * The term "qube" should be lowercase unless it is the first word in a - sentence. Note that starting a sentence with the plural of "qube" (i.e., - "Qubes...") can be ambiguous, since it may not be clear whether the referent - is a collection of qubes or [Qubes OS](#qubes-os). + * The term "qube" should be lowercase unless it is the first word in a sentence. Note that starting a sentence with the plural of "qube" (i.e., "Qubes...") can be ambiguous, since it may not be clear whether the referent is a collection of qubes or [Qubes OS](#qubes-os). Domain ------ -An area or set of activities in one's digital life that has certain security -requirements and therefore involves the use of certain [qubes](#qube). For -example, suppose your "email" domain encompasses the activity of sending -PGP-encrypted email. This domain may include your email qube and your [Split -GPG](/doc/split-gpg) qube. Note that domains and qubes are not the same thing. -In this example, your "email" domain includes the use of two qubes. Furthermore, -a qube can fall under multiple domains simultaneously. For example, your Split -GPG qube may also be part of your "software development" domain if you PGP-sign -your Git commits. +An area or set of activities in one's digital life that has certain security requirements and therefore involves the use of certain [qubes](#qube). +For example, suppose your "email" domain encompasses the activity of sending PGP-encrypted email. +This domain may include your email qube and your [Split GPG](/doc/split-gpg) qube. +Note that domains and qubes are not the same thing. +In this example, your "email" domain includes the use of two qubes. +Furthermore, a qube can fall under multiple domains simultaneously. +For example, your Split GPG qube may also be part of your "software development" domain if you PGP-sign your Git commits. Dom0 ---- -Domain Zero. Also known as the **host** domain, dom0 is the initial VM -started by the Xen hypervisor on boot. Dom0 runs the Xen management toolstack -and has special privileges relative to other domains, such as direct access to -most hardware. (Note that the use of "domain" for a synonym for "VM" is specific -to Xen. Qubes diverges from this practice. See: [domain](#domain).) +Domain Zero. +Also known as the **host** domain, dom0 is the initial VM started by the Xen hypervisor on boot. +Dom0 runs the Xen management toolstack and has special privileges relative to other domains, such as direct access to most hardware. +(Note that the use of "domain" for a synonym for "VM" is specific to Xen. Qubes diverges from this practice. See: [domain](#domain).) DomU ---- -Unprivileged Domain. Also known as **guest** domains, domUs are the counterparts -to dom0. All VMs except dom0 are domUs. By default, most domUs lack direct -hardware access. (Note that the use of "domain" for a synonym for "VM" is -specific to Xen. Qubes diverges from this practice. See: [domain](#domain).) +Unprivileged Domain. +Also known as **guest** domains, domUs are the counterparts to dom0. +All VMs except dom0 are domUs. +By default, most domUs lack direct hardware access. +(Note that the use of "domain" for a synonym for "VM" is specific to Xen. Qubes diverges from this practice. See: [domain](#domain).) TemplateVM ---------- -Template Virtual Machine. Any [VM](#vm) which supplies its root filesystem to -another VM. TemplateVMs are intended for installing and updating software -applications, but not for running them. +Template Virtual Machine. +Any [VM](#vm) which supplies its root filesystem to another VM. +TemplateVMs are intended for installing and updating software applications, but not for running them. * Colloquially, TemplateVMs are often referred to as "templates." TemplateBasedVM --------------- -Any [VM](#vm) which depends on a TemplateVM for its root filesystem. +Any [VM](#vm) which depends on a [TemplateVM](#templatevm) for its root filesystem. Standalone(VM) -------------- -Standalone (Virtual Machine). In general terms, a [VM](#vm) is described as -**standalone** if and only if it does not depend on any other VM for its root -filesystem. (In other words, a VM is standalone if and only if it is not a -TemplateBasedVM.) More specifically, a **StandaloneVM** is a type of VM in Qubes -which is created by cloning a TemplateVM. Unlike TemplateVMs, however, -StandaloneVMs do not supply their root filesystems to other VMs. (Therefore, -while a TemplateVM is a type of standalone VM, it is not a StandaloneVM.) +Standalone (Virtual Machine). +In general terms, a [VM](#vm) is described as **standalone** if and only if it does not depend on any other VM for its root filesystem. +(In other words, a VM is standalone if and only if it is not a TemplateBasedVM.) +More specifically, a **StandaloneVM** is a type of VM in Qubes which is created by cloning a TemplateVM. +Unlike TemplateVMs, however, StandaloneVMs do not supply their root filesystems to other VMs. +(Therefore, while a TemplateVM is a type of standalone VM, it is not a StandaloneVM.) AppVM ----- -Application Virtual Machine. A [VM](#vm) which is intended for running software -applications. Typically a TemplateBasedVM, but may be a StandaloneVM. Never a -TemplateVM. +Application Virtual Machine. +A [VM](#vm) which is intended for running software applications. +Typically a TemplateBasedVM, but may be a StandaloneVM. Never a TemplateVM. NetVM ----- -Network Virtual Machine. A type of [VM](#vm) which connects directly to a -network and provides access to that network to other VMs which connect to the -NetVM. A NetVM called `sys-net` is created by default in most Qubes -installations. +Network Virtual Machine. +A type of [VM](#vm) which connects directly to a network and provides access to that network to other VMs which connect to the NetVM. +A NetVM called `sys-net` is created by default in most Qubes installations. -Alternatively, "NetVM" may refer to whichever VM is directly connected to a VM -for networking purposes. For example, if `untrusted` is directly connected to -`sys-firewall` for network access, then it is accurate to say, "`sys-firewall` -is `untrusted`'s NetVM," even though `sys-firewall` is a ProxyVM. +Alternatively, "NetVM" may refer to whichever VM is directly connected to a VM for networking purposes. +For example, if `untrusted` is directly connected to `sys-firewall` for network access, then it is accurate to say, "`sys-firewall` is `untrusted`'s NetVM," even though `sys-firewall` is a ProxyVM. ProxyVM ------- -Proxy Virtual Machine. A type of [VM](#vm) which proxies network access for -other VMs. Typically, a ProxyVM sits between a NetVM and another VM (such as an -AppVM or a TemplateVM) which requires network access. +Proxy Virtual Machine. +A type of [VM](#vm) which proxies network access for other VMs. +Typically, a ProxyVM sits between a NetVM and another VM (such as an AppVM or a TemplateVM) which requires network access. FirewallVM ---------- -Firewall Virtual Machine. A type of [ProxyVM](#proxyvm) which is used to enforce -network-level policies (a.k.a. "firewall rules"). A FirewallVM called -`sys-firewall` is created by default in most Qubes installations. +Firewall Virtual Machine. +A type of [ProxyVM](#proxyvm) which is used to enforce network-level policies (a.k.a. "firewall rules"). +A FirewallVM called `sys-firewall` is created by default in most Qubes installations. DispVM ------ -Disposable Virtual Machine. A temporary [AppVM](#appvm) which can quickly be -created, used, and destroyed. +[Disposable Virtual Machine]. A temporary [AppVM](#appvm) based on a [DVM Template](#dvm-template) which can quickly be created, used, and destroyed. DVM --- -An abbreviation of [DispVM](#dispvm), typically used to refer to the TemplateVM -on which DispVMs are based. By default, a VM named `fedora-XX-dvm` is created on -most Qubes installations (where `XX` is the current Fedora version). +An abbreviation of [DispVM](#dispvm), typically used to refer to [DVM Templates](#dvm-template). + +DVM Template +------------ +TemplateBasedVMs on which [DispVMs](#dispvm) are based. +By default, a DVM Template named `fedora-XX-dvm` is created on most Qubes installations (where `XX` is the Fedora version of the default TemplateVM). +DVM Templates are neither [TemplateVMs](#templatevm) nor [AppVMs](#appvm). +They are intended neither for installing nor running software. +Rather, they are intended for *customizing* or *configuring* software that has already been installed on the TemplateVM on which the DVM Template is based (see [DispVM Customization]). +This software is then intended to be run (in its customized state) in DispVMs that are based on the DVM Template. PV -- -Paravirtualization. An efficient and lightweight virtualization technique -originally introduced by the Xen Project and later adopted by other -virtualization platforms. Unlike HVMs, paravirtualized [VMs](#vm) do not require -virtualization extensions from the host CPU. However, paravirtualized VMs -require a PV-enabled kernel and PV drivers, so the guests are aware of the -hypervisor and can run efficiently without emulation or virtual emulated -hardware. +Paravirtualization. +An efficient and lightweight virtualization technique originally introduced by the Xen Project and later adopted by other virtualization platforms. +Unlike HVMs, paravirtualized [VMs](#vm) do not require virtualization extensions from the host CPU. +However, paravirtualized VMs require a PV-enabled kernel and PV drivers, so the guests are aware of the hypervisor and can run efficiently without emulation or virtual emulated hardware. HVM --- -Hardware Virtual Machine. Any fully virtualized, or hardware-assisted, [VM](#vm) -utilizing the virtualization extensions of the host CPU. Although HVMs are -typically slower than paravirtualized VMs due to the required emulation, HVMs -allow the user to create domains based on any operating system. +Hardware Virtual Machine. +Any fully virtualized, or hardware-assisted, [VM](#vm) utilizing the virtualization extensions of the host CPU. +Although HVMs are typically slower than paravirtualized VMs due to the required emulation, HVMs allow the user to create domains based on any operating system. StandaloneHVM ------------- -Any [HVM](#hvm) which is standalone (i.e., does not depend on any other VM for -its root filesystem). In Qubes, StandaloneHVMs are referred to simply as -**HVMs**. +Any [HVM](#hvm) which is standalone (i.e., does not depend on any other VM for its root filesystem). +In Qubes, StandaloneHVMs are referred to simply as **HVMs**. TemplateHVM ----------- -Any [HVM](#hvm) which functions as a [TemplateVM](#templatevm) by supplying its -root filesystem to other VMs. In Qubes, TemplateHVMs are referred to as **HVM -templates**. +Any [HVM](#hvm) which functions as a [TemplateVM](#templatevm) by supplying its root filesystem to other VMs. +In Qubes, TemplateHVMs are referred to as **HVM templates**. -PVH ---- -[PV](#pv) on [HVM](#hvm). To boost performance, fully virtualized HVM guests can -use special paravirtual device drivers (PVHVM or PV-on-HVM drivers). These -drivers are optimized PV drivers for HVM environments and bypass the emulation -for disk and network I/O, thus providing PV-like (or better) performance on HVM -systems. This allows for optimal performance on guest operating systems such as -Windows. +TemplateBasedHVM +---------------- +Any [HVM](#hvm) that depends on a [TemplateVM](#templatevm) for its root filesystem. + +ServiceVM +--------- +Service Virtual Machine. +A [VM](#vm) the primary purpose of which is to provide a service or services to other VMs. +NetVMs and ProxyVMs are examples of ServiceVMs. + +PVHVM +----- +[PV](#pv) on [HVM](#hvm). +To boost performance, fully virtualized HVM guests can use special paravirtual device drivers (PVHVM or PV-on-HVM drivers). +These drivers are optimized PV drivers for HVM environments and bypass the emulation for disk and network I/O, thus providing PV-like (or better) performance on HVM systems. +This allows for optimal performance on guest operating systems such as Windows. + +Windows Tools +----- +Qubes Windows Tools are a set of programs and drivers that provide integration of Windows [AppVMs](#appvm) with the rest of the Qubes system. + +QWT +---- +An abbreviation of Qubes [Windows Tools](#windows-tools). + +[Disposable Virtual Machine]: /doc/dispvm/ +[DispVM Customization]: /doc/dispvm-customization/ diff --git a/reference/qubes-service.md b/reference/qubes-service.md index b863d1cc..568ebc99 100644 --- a/reference/qubes-service.md +++ b/reference/qubes-service.md @@ -12,15 +12,12 @@ Usage documentation is on [qvm-service manual page](/doc/dom0-tools/qvm-service/ Under the hood enabled service in VM is signaled by file in /var/run/qubes-service. This can be used to implement almost enable/disable **per-VM** switch controlled by dom0. Adding support for systemd services is pretty simple: -1. Disable old service: `systemctl disable ` -2. Create `/etc/systemd/system/.service` file containing: +In the VM, create `/etc/systemd/system/.service.d/30_qubes.conf` file +containing (you may need to create a directory for this file first): - ~~~ - .include /lib/systemd/system/.service - [Unit] - ConditionPathExists=/var/run/qubes-service/ - ~~~ +~~~ +[Unit] +ConditionPathExists=/var/run/qubes-service/ +~~~ -3. Enable new service: `systemctl enable `. - -This will cause service to be started only when you enable it with qvm-service for given VM. +This will cause service to be started only when you enable it with qvm-service for this VM. diff --git a/releases/3.1/release-notes.md b/releases/3.1/release-notes.md index 9a659b7d..657f06f3 100644 --- a/releases/3.1/release-notes.md +++ b/releases/3.1/release-notes.md @@ -7,8 +7,6 @@ permalink: /doc/releases/3.1/release-notes/ Qubes R3.1 release notes ======================== -*this page is a draft for yet unreleased version* - New features since 3.0 ---------------------- @@ -73,6 +71,6 @@ using](/doc/releases/3.0/release-notes/#upgrading) first, then follow the instructions above. This will be time consuming process. [salt-doc]: /doc/salt/ -[pvgrub-doc]: /doc/managing-vm-kernel/#tocAnchor-1-3 +[pvgrub-doc]: /doc/managing-vm-kernel/#using-kernel-installed-in-the-vm [input-proxy]: https://github.com/QubesOS/qubes-app-linux-input-proxy/blob/master/README.md [github-release-notes]: https://github.com/QubesOS/qubes-issues/issues?q=is%3Aissue+sort%3Aupdated-desc+milestone%3A%22Release+3.1%22+label%3Arelease-notes+is%3Aclosed diff --git a/releases/3.1/schedule.md b/releases/3.1/schedule.md index 296ca3e0..ede408ed 100644 --- a/releases/3.1/schedule.md +++ b/releases/3.1/schedule.md @@ -9,15 +9,7 @@ redirect_from: Qubes R3.1 Release Schedule =========================== -This schedule is based on [Version Scheme](/doc/version-scheme/#tocAnchor-1-1-3). - - +This schedule is based on [Version Scheme](/doc/version-scheme/#release-schedule). | Date | Stage | | -----------:| --------------------------------------- | diff --git a/releases/3.2/release-notes.md b/releases/3.2/release-notes.md new file mode 100644 index 00000000..7a083562 --- /dev/null +++ b/releases/3.2/release-notes.md @@ -0,0 +1,77 @@ +--- +layout: doc +title: Qubes R3.2 release notes +permalink: /doc/releases/3.2/release-notes/ +--- + +Qubes R3.2 release notes +======================== + +New features since 3.1 +---------------------- + +* Management Stack extended to support in-VM configuration - [documentation][salt-doc] +* PV USB - [documentation][usb] +* Dom0 update to Fedora 23 for better hardware support +* Kernel 4.4.x +* Default desktop environment switched to Xfce4 +* KDE 5 support (but it is no longer the default one) +* Tiling window managers support: awesome, [i3][i3] +* More flexible Qubes RPC services - [related ticket][qrexec-argument], [documentation][qrexec-doc] + +You can get detailed description in [completed github issues][github-release-notes] + +Known issues +------------ + +* [Fedora 23 reached EOL in December 2016](https://fedoraproject.org/wiki/End_of_life). There is a [manual procedure to upgrade your VMs](https://www.qubes-os.org/news/2016/11/15/fedora-24-template-available/). + +* Windows Tools: `qvm-block` does not work + +* Some icons in the Qubes Manager application might not be drawn correctly when using the Xfce4 environment in Dom0. If this bothers you, please use the KDE environment instead. + +* For other known issues take a look at [our tickets](https://github.com/QubesOS/qubes-issues/issues?q=is%3Aopen+is%3Aissue+milestone%3A%22Release+3.2%22+label%3Abug) + +It is advised to install updates just after system installation to apply bug fixes for (some of) the above problems. + +Downloads +--------- + +See [Qubes Downloads](/downloads/). + +Installation instructions +------------------------- + +See [Installation Guide](/doc/installation-guide/). +After installation, [manually upgrade to Fedora 24](https://www.qubes-os.org/news/2016/11/15/fedora-24-template-available/). + +Upgrading +--------- + +### From R3.1 + +The easiest and safest way to upgrade to Qubes R3.2 is to install it from +scratch and use [qubes backup and restore tools][backup] for +migrating of all of the user VMs. + +Users of Qubes R3.1 can also upgrade using [this +procedure][upgrade]. + +### From R3.0 or earlier + +When upgrading from earlier versions the easiest and safest way is to install +it from scratch and use [qubes backup and restore tools][backup] +for migrating of all of the user VMs. + +Alternatively you can [upgrade to R3.1 using][upgrade-r3.1] first, then follow +the instructions above. This will be time consuming process. + +[salt-doc]: /doc/salt/ +[usb]: /doc/usb/ +[i3]: /doc/i3/ +[upgrade]: /doc/upgrade-to-r3.2/ +[upgrade-r3.1]: /doc/releases/3.1/release-notes/#upgrading +[backup]: /doc/backup-restore/ +[qrexec-argument]: https://github.com/QubesOS/qubes-issues/issues/1876 +[qrexec-doc]: /doc/qrexec3/#service-argument-in-policy +[github-release-notes]: https://github.com/QubesOS/qubes-issues/issues?q=is%3Aissue+sort%3Aupdated-desc+milestone%3A%22Release+3.2%22+label%3Arelease-notes+is%3Aclosed diff --git a/releases/3.2/schedule.md b/releases/3.2/schedule.md new file mode 100644 index 00000000..05dc5599 --- /dev/null +++ b/releases/3.2/schedule.md @@ -0,0 +1,23 @@ +--- +layout: doc +title: Qubes R3.2 Release Schedule +permalink: /doc/releases/3.2/schedule/ +redirect_from: +- /en/doc/releases/3.2/schedule/ +--- + +Qubes R3.2 Release Schedule +=========================== + +This schedule is based on [Version Scheme](/doc/version-scheme/#release-schedule). + +| Date | Stage | +| -----------:| --------------------------------------- | +| 18 Jun 2016 | 3.2-rc1 release | +| 2 Jul 2016 | decide whether 3.2-rc1 is the final 3.2 | +| 16 Jul 2016
20 Jul 2016 | current-testing freeze before 3.2-rc2 | +| 23 Jul 2016
27 Jul 2016 | 3.2-rc2 release | +| 5 Aug 2016
9 Aug 2016 | decide whether 3.2-rc2 is the final 3.2 | +| 24 Aug 2016 | current-testing freeze before 3.2-rc3 | +| 31 Aug 2016 | 3.2-rc3 release | +| 29 Sep 2016 | 3.2 release | diff --git a/security-info/canaries.md b/security-info/canaries.md new file mode 100644 index 00000000..5f92fd46 --- /dev/null +++ b/security-info/canaries.md @@ -0,0 +1,36 @@ +--- +layout: security +title: Canaries +permalink: /security/canaries/ +redirect_from: /doc/canaries/ +--- + +Qubes Canaries +============== + +Qubes Canaries are published through the [Qubes Security Pack](/security/pack/). + +2015 +---- + +- [Qubes Canary \#1](https://github.com/QubesOS/qubes-secpack/blob/master/canaries/canary-001-2015.txt) +- [Qubes Canary \#2](https://github.com/QubesOS/qubes-secpack/blob/master/canaries/canary-002-2015.txt) +- [Qubes Canary \#3](https://github.com/QubesOS/qubes-secpack/blob/master/canaries/canary-003-2015.txt) +- [Qubes Canary \#4](https://github.com/QubesOS/qubes-secpack/blob/master/canaries/canary-004-2015.txt) +- [Qubes Canary \#5](https://github.com/QubesOS/qubes-secpack/blob/master/canaries/canary-005-2015.txt) + +2016 +---- + +- [Qubes Canary \#6](https://github.com/QubesOS/qubes-secpack/blob/master/canaries/canary-006-2016.txt) +- [Qubes Canary \#7](https://github.com/QubesOS/qubes-secpack/blob/master/canaries/canary-007-2016.txt) +- [Qubes Canary \#8](https://github.com/QubesOS/qubes-secpack/blob/master/canaries/canary-008-2016.txt) +- [Qubes Canary \#9](https://github.com/QubesOS/qubes-secpack/blob/master/canaries/canary-009-2016.txt) +- [Qubes Canary \#10](https://github.com/QubesOS/qubes-secpack/blob/master/canaries/canary-010-2016.txt) + +2017 +---- + +- [Qubes Canary \#11](https://github.com/QubesOS/qubes-secpack/blob/master/canaries/canary-011-2017.txt) +- [Qubes Canary \#12](https://github.com/QubesOS/qubes-secpack/blob/master/canaries/canary-012-2017.txt) + diff --git a/security-info/canary-template.md b/security-info/canary-template.md new file mode 100644 index 00000000..6bd9cd20 --- /dev/null +++ b/security-info/canary-template.md @@ -0,0 +1,61 @@ +--- +layout: security +title: Canary Template +permalink: /security/canaries/template/ +redirect_from: /doc/canaries/template/ +--- + +Canary Template +=============== + +~~~ +Dear Qubes community, + +We have just published Qubes Canary #. The text of this canary is +reproduced below. This canary and its accompanying signatures will always be +available in the Qubes Security Pack (qubes-secpack). + +View Canary # in the qubes-secpack: + +`-``.txt> + +Learn about the qubes-secpack, including how to obtain, verify, and read it: + + + +View all past canaries: + + + +``` + ---===[ Qubes Canary # ]===--- + + +Statements +----------- + +[...] + +Special announcements +---------------------- + +[...] + +Disclaimers and notes +---------------------- + +[...] + +Proof of freshness +------------------- + +[...] + +Footnotes +---------- + +[...] +``` + +~~~ + diff --git a/security-info/security-bulletins-checklist.md b/security-info/security-bulletins-checklist.md new file mode 100644 index 00000000..877bfc49 --- /dev/null +++ b/security-info/security-bulletins-checklist.md @@ -0,0 +1,24 @@ +--- +layout: security +title: Security Bulletin Checklist +permalink: /security/bulletins/checklist/ +redirect_from: /doc/security-bulletins/checklist/ +--- + +Security Bulletin Checklist +=========================== + +Preparation +----------- + + * Draft QSB and push to private repository + * Build fixed packages + * Finalize QSB, sign, and add signed tags + +Announcement +------------ + + * Upload packages to `security-testing` and `current-testing` repositories + * Push QSB to public repository + * Announce on the [mailing lists](/mailing-lists/) using the [QSB Template](/security/bulletins/template/) + * Announce on social media diff --git a/security-info/security-bulletins-template.md b/security-info/security-bulletins-template.md new file mode 100644 index 00000000..1d8887db --- /dev/null +++ b/security-info/security-bulletins-template.md @@ -0,0 +1,82 @@ +--- +layout: security +title: Security Bulletin Template +permalink: /security/bulletins/template/ +redirect_from: /doc/security-bulletins/template/ +--- + +Security Bulletin Template +========================== + +~~~ +Dear Qubes community, + +We have just published Qubes Security Bulletin (QSB) #: . +The text of this QSB is reproduced below. This QSB and its accompanying +signatures will always be available in the Qubes Security Pack (qubes-secpack). + +View QSB #<number> in the qubes-secpack: + +<https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-`<number>`-`<year>`.txt> + +Learn about the qubes-secpack, including how to obtain, verify, and read it: + +<https://www.qubes-os.org/security/pack/> + +View all past QSBs: + +<https://www.qubes-os.org/security/bulletins/> + +View <XSA> in the XSA Tracker: + +<https://www.qubes-os.org/security/xsa/`<XSA>`> + +``` + ---===[ Qubes Security Bulletin #<number>]===--- + + <date> + + <title> + +Summary +======= + +[...] + +Description +=========== + +[...] + +Impact +====== + +[...] + +Discussion +========== + +[...] + +Patching +======== + +[...] + +Credits +======= + +[...] + +References +========== + +[...] + +-- +The Qubes Security Team +https://www.qubes-os.org/security/ +``` + +~~~ + diff --git a/security/security-bulletins.md b/security-info/security-bulletins.md similarity index 73% rename from security/security-bulletins.md rename to security-info/security-bulletins.md index 7ff11e5e..e39c1972 100644 --- a/security/security-bulletins.md +++ b/security-info/security-bulletins.md @@ -1,8 +1,9 @@ --- -layout: doc +layout: security title: Security Bulletins -permalink: /doc/security-bulletins/ +permalink: /security/bulletins/ redirect_from: +- /doc/security-bulletins/ - /en/doc/security-bulletins/ - /doc/SecurityBulletins/ - /wiki/SecurityBulletins/ @@ -12,7 +13,7 @@ redirect_from: Qubes Security Bulletins ======================== -Qubes Security Bulletins are published through the [Qubes Security Pack](/doc/security-pack/). +Qubes Security Bulletins are published through the [Qubes Security Pack](/security/pack/). 2010 ---- @@ -62,3 +63,19 @@ Qubes Security Bulletins are published through the [Qubes Security Pack](/doc/se - [Qubes Security Bulletin \#22](https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-022-2015.txt) (Critical Xen bug in PV memory virtualization code (XSA 148)) - [Qubes Security Bulletin \#23](https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-023-2015.txt) (Race condition bugs in Xen code (XSA-155 and XSA-166), other Xen bugs) +2016 +---- + +- [Qubes Security Bulletin \#24](https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-024-2016.txt) (Critical Xen bug in PV memory virtualization code (XSA 182)) +- [Qubes Security Bulletin \#25](https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-025-2016.txt) (Xen bug in event channel handling code (XSA 188)) +- [Qubes Security Bulletin \#26](https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-026-2016.txt) (Colored window border handling bug in Qubes GUI daemon) +- [Qubes Security Bulletin \#27](https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-027-2016.txt) (Xen 64-bit bit test instruction emulation broken (XSA 195)) +- [Qubes Security Bulletin \#28](https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-028-2016.txt) (Debian update mechanism vulnerability) + +2017 +---- + +- [Qubes Security Bulletin \#29](https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-029-2017.txt) (Critical Xen bug in PV memory virtualization code (XSA-212)) +- [Qubes Security Bulletin \#30](https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-030-2017.txt) (Critical Xen bugs related to PV memory virtualization (XSA-213, XSA-214)) +- [Qubes Security Bulletin \#31](https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-031-2017.txt) (Xen hypervisor vulnerabilities with unresearched impact (XSA 216-224)) + diff --git a/security-info/security-goals.md b/security-info/security-goals.md new file mode 100644 index 00000000..5f64e4e1 --- /dev/null +++ b/security-info/security-goals.md @@ -0,0 +1,17 @@ +--- +layout: security +title: Security Goals +permalink: /security/goals/ +redirect_from: +- /doc/security-goals/ +- /en/doc/security-goals/ +- /doc/SecurityGoals/ +- /wiki/SecurityGoals/ +--- + +Qubes Security Goals +==================== + +Qubes implements a Security by Isolation approach by providing the ability to easily create many security domains. These domains are implemented as lightweight Virtual Machines (VMs) running under the Xen hypervisor. Qubes' main objective is to provide strong isolation between these domains, so that even if an attacker compromises one of the domains, the others are still safe. Qubes, however, does not attempt to provide any security isolation for applications running within the same domain. For example, a buggy web browser running in a Qubes domain could still be compromised just as easily as on a regular Linux distribution. The difference that Qubes makes is that now the attacker doesn't have access to all the software running in the other domains. + +Qubes also provides features that make it easy and convenient to run these multiple domains, such as seamless GUI integration into one common desktop, secure clipboard copy and paste between domains, secure file transfer between domains, disposable VMs, and much more. Qubes also provides an advanced networking infrastructure that allows for the creation of multiple network VMs which isolate all the world-facing networking stacks and proxy VMs which can be used for advanced VPN configurations and tunneling over untrusted connections. diff --git a/security/security-pack.md b/security-info/security-pack.md similarity index 78% rename from security/security-pack.md rename to security-info/security-pack.md index 560ddce6..f875f679 100644 --- a/security/security-pack.md +++ b/security-info/security-pack.md @@ -1,34 +1,43 @@ --- -layout: doc +layout: security title: Security Pack -permalink: /doc/security-pack/ +permalink: /security/pack/ redirect_from: +- /doc/security-pack/ - /en/doc/security-pack/ - /doc/SecurityPack/ - /wiki/SecurityPack/ +- /qsp/ +- /sec-pack/ +- /secpack/ +- /doc/qsp/ +- /doc/sec-pack/ +- /doc/secpack/ --- Qubes Security Pack =================== -The **Qubes Security Pack (QSP)** is a Git repository which contains: +The **Qubes Security Pack** (`qubes-secpack`) is a Git repository that contains: - * [Qubes Security Bulletins (QSBs)](/doc/security-bulletins/) * [Qubes PGP keys](https://keys.qubes-os.org/keys/) - * [Qubes warrant canaries](https://canarywatch.org/qubesOS/) + * [Qubes Security Bulletins (QSBs)](/security/bulletins/) + * [Qubes warrant canaries](https://github.com/QubesOS/qubes-secpack/tree/master/canaries) + * [Qubes Bitcoin fund information](https://github.com/QubesOS/qubes-secpack/tree/master/fund) * Security-related information and announcements (e.g., key revocations) -The official location of the QSP is: +While `qubes-secpack` itself is independent of any particular host, its current +official location is: -`https://github.com/QubesOS/qubes-secpack` -[(link)](https://github.com/QubesOS/qubes-secpack) +<https://github.com/QubesOS/qubes-secpack> History and Rationale --------------------- -On 2013-01-05, Joanna Rutkowska announced the QSP and explained its rationale in -an [email](https://groups.google.com/d/msg/qubes-devel/twkOEaMLtNI/lZyGx6_jFCEJ) +On 2013-01-05, Joanna Rutkowska announced the `qubes-secpack` and explained its +rationale in an +[email](https://groups.google.com/d/msg/qubes-devel/twkOEaMLtNI/lZyGx6_jFCEJ) to the Qubes mailing lists: Hello, @@ -121,12 +130,12 @@ to the Qubes mailing lists: How to Obtain, Verify, and Read ------------------------------- -The following example demonstrates one method of obtaining the QSP, verifying -its contents, and reading them. +The following example demonstrates one method of obtaining the `qubes-secpack`, +verifying its contents, and reading them. - 1. Clone the QSP repo. + 1. Clone the `qubes-secpack` repo. - [user@qubes ~]$ git clone https://github.com/QubesOS/qubes-secpack.git + $ git clone https://github.com/QubesOS/qubes-secpack.git Cloning into 'qubes-secpack'... remote: Counting objects: 195, done. remote: Total 195 (delta 0), reused 0 (delta 0) @@ -136,7 +145,7 @@ its contents, and reading them. 2. Import the included PGP keys. - [user@qubes ~]$ gpg --import qubes-secpack/keys/*/* + $ gpg --import qubes-secpack/keys/*/* gpg: directory `/home/user/.gnupg' created gpg: new configuration file `/home/user/.gnupg/gpg.conf' created gpg: WARNING: options in `/home/user/.gnupg/gpg.conf' are not yet active during this run @@ -151,14 +160,14 @@ its contents, and reading them. gpg: key B298547C: public key "Marek Marczykowski (Qubes OS signing key) <marmarek@mimuw.edu.pl>" imported gpg: key AB5EEF90: public key "Marek Marczykowski (Qubes OS signing key) <marmarek@invisiblethingslab.com>" imported gpg: key A603BCB6: public key "Marek Marczykowski (Qubes OS signing key) <marmarek@invisiblethingslab.com>" imported - gpg: key 42CFA724: public key "Marek Marczykowski-G�recki (Qubes OS signing key) <marmarek@invisiblethingslab.com>" imported + gpg: key 42CFA724: public key "Marek Marczykowski-Górecki (Qubes OS signing key) <marmarek@invisiblethingslab.com>" imported gpg: key 15CE40BF: public key "Wojciech Zygmunt Porczyk (Qubes OS signing key) <woju@invisiblethingslab.com>" imported gpg: key 36879494: public key "Qubes Master Signing Key" imported gpg: key 211093A7: public key "Qubes OS Release 1 Signing Key" imported gpg: key 0A40E458: public key "Qubes OS Release 2 Signing Key" imported gpg: key 03FA5082: public key "Qubes OS Release 3 Signing Key" imported gpg: key 92C7B3DC: public key "Joanna Rutkowska (Qubes Security Pack Signing Key) <joanna@invisiblethingslab.com>" imported - gpg: key 1830E06A: public key "Marek Marczykowski-G�recki (Qubes security pack) <marmarek@invisiblethingslab.com>" imported + gpg: key 1830E06A: public key "Marek Marczykowski-Górecki (Qubes security pack) <marmarek@invisiblethingslab.com>" imported gpg: key 3F48CB21: public key "Qubes OS Security Team <security@qubes-os.org>" imported gpg: Total number processed: 17 gpg: imported: 17 (RSA: 17) @@ -166,7 +175,7 @@ its contents, and reading them. 3. Verify and trust the Qubes Master Signing Key. - [user@qubes ~]$ gpg --edit-key 36879494 + $ gpg --edit-key 36879494 gpg (GnuPG) 1.4.18; Copyright (C) 2014 Free Software Foundation, Inc. This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law. @@ -213,36 +222,40 @@ its contents, and reading them. a trustworthy source (ideally, multiple sources) *other than* this website and visually compare it (them) to the fingerprint displayed in the preceding step, ensuring they match. You can read more about digital signatures and - key verification [here](/doc/verifying-signatures/). + key verification [here](/security/verifying-signatures/). - 4. Verify and read the canaries. + 4. Verify signed Git tags. - [user@qubes ~]$ cd qubes-secpack/canaries/ - [user@qubes canaries]$ gpg --verify canary-001-2015.txt.sig.joanna canary-001-2015.txt + $ cd qubes-secpack/ + $ git tag -v `git describe` + object 2bb7f0b966593d8ed74e140a04d60c68b96b164e + type commit + tag joanna_sec_2bb7f0b9 + tagger Joanna Rutkowska <joanna@invisiblethingslab.com> 1468335706 +0000 + + Tag for commit 2bb7f0b966593d8ed74e140a04d60c68b96b164e + gpg: Signature made 2016-07-12T08:01:46 PDT + gpg: using RSA key 0x4E6829BC92C7B3DC + gpg: Good signature from "Joanna Rutkowska (Qubes Security Pack Signing Key) <joanna@invisiblethingslab.com>" [full] + + (The final line of output confirms that the signature is good.) + + 5. Verify detached PGP signatures. + + $ cd canaries/ + $ gpg --verify canary-001-2015.txt.sig.joanna canary-001-2015.txt gpg: Signature made Mon Jan 5 20:21:40 2015 UTC using RSA key ID 92C7B3DC gpg: Good signature from "Joanna Rutkowska (Qubes Security Pack Signing Key) <joanna@invisiblethingslab.com>" - [user@qubes canaries]$ gpg --verify canary-001-2015.txt.sig.marmarek canary-001-2015.txt + $ gpg --verify canary-001-2015.txt.sig.marmarek canary-001-2015.txt gpg: Signature made Mon Jan 5 20:13:37 2015 UTC using RSA key ID 1830E06A - gpg: Good signature from "Marek Marczykowski-G�recki (Qubes security pack) <marmarek@invisiblethingslab.com>" - [user@qubes canaries]$ cat canary-001-2015.txt - - - ---===[ Qubes Canary #1 ]===--- - - [...] + gpg: Good signature from "Marek Marczykowski-Górecki (Qubes security pack) <marmarek@invisiblethingslab.com>" - 5. Verify and read the QSBs. + (The fourth and final lines of output confirm that the two signatures are + good.) + +The same procedures can be applied to any directory or file in the +`qubes-secpack`. Two methods of verification (signed Git tags and deatched PGP +signatures) are provided to ensure that the system is robust (e.g., against a +potential failure in Git tag-based verification) and to give users more options +to verify the files. - [user@qubes canaries]$ cd ../QSBs/ - [user@qubes QSBs]$ gpg --verify qsb-013-2015.txt.sig.joanna qsb-013-2015.txt - gpg: Signature made Mon Jan 5 21:22:14 2015 UTC using RSA key ID 92C7B3DC - gpg: Good signature from "Joanna Rutkowska (Qubes Security Pack Signing Key) <joanna@invisiblethingslab.com>" - [user@qubes QSBs]$ gpg --verify qsb-013-2015.txt.sig.marmarek qsb-013-2015.txt - gpg: Signature made Mon Jan 5 21:38:11 2015 UTC using RSA key ID 1830E06A - gpg: Good signature from "Marek Marczykowski-G�recki (Qubes security pack) <marmarek@invisiblethingslab.com>" - [user@qubes QSBs]$ cat qsb-013-2015.txt - - - ---===[ Qubes Security Bulletin #13 ]===--- - - [...] diff --git a/security-info/security.md b/security-info/security.md new file mode 100644 index 00000000..77bcf7c4 --- /dev/null +++ b/security-info/security.md @@ -0,0 +1,53 @@ +--- +layout: default +title: Security +permalink: /security/ +redirect_from: +- /en/security/ +- /en/doc/security/ +- /en/doc/qubes-security/ +- /doc/QubesSecurity/ +- /wiki/QubesSecurity/ +- /en/doc/security-page/ +- /doc/SecurityPage/ +- /wiki/SecurityPage/ +- /trac/wiki/SecurityPage/ +--- + +Qubes OS Project Security Center +================================ + +- [Security Goals](/security/goals/) +- [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/) +- [PGP Keys](https://keys.qubes-os.org/keys/) + +Reporting Security Issues in Qubes OS +------------------------------------- + +If you believe you have found a security issue affecting Qubes OS, either directly or indirectly (e.g. the issue affects Xen in a configuration that is used in Qubes OS), then we would be more than happy to hear from you! + +We promise to treat any reported issue seriously and, if the investigation confirms it affects Qubes, to patch it within a reasonable time, release a public Security Bulletin that describes the issue, discuss potential impact of the vulnerability, reference applicable patches or workarounds, and credit the discoverer. + +The list of all Qubes Security Advisories published so far can be found [here](/security/bulletins/). + +The Qubes Security Team +----------------------- + +The Qubes Security Team can be contacted via email using the following address: + +~~~ +security at qubes-os dot org +~~~ + +### Qubes Security Team GPG Key ### + +Please use [this GPG key](https://keys.qubes-os.org/keys/qubes-os-security-team-key.asc) to encrypt any emails sent to this address. Like all GPG keys used by the Qubes project, this key is signed by the Qubes Master key. Please see [this page](/security/verifying-signatures/) for more information on how to verify the keys. + +### Members of the Security Team ### + +- Joanna Rutkowska \<joanna at invisiblethingslab dot com\> +- Marek Marczykowski \<marmarek at invisiblethingslab dot com\> diff --git a/security-info/verifying-signatures.md b/security-info/verifying-signatures.md new file mode 100644 index 00000000..edb55018 --- /dev/null +++ b/security-info/verifying-signatures.md @@ -0,0 +1,336 @@ +--- +layout: security +title: Verifying Signatures +permalink: /security/verifying-signatures/ +redirect_from: +- /doc/verifying-signatures/ +- /en/doc/verifying-signatures/ +- /doc/VerifyingSignatures/ +- /wiki/VerifyingSignatures/ +--- + +On Digital Signatures and Key Verification +========================================== + +What Digital Signatures Can and Cannot Prove +-------------------------------------------- + +Most people – even programmers – are confused about the basic concepts +underlying digital signatures. Therefore, most people should read this section, +even if it looks trivial at first sight. + +Digital signatures can prove both **authenticity** and **integrity** to a +reasonable degree of certainty. **Authenticity** ensures that a given file was +indeed created by the person who signed it (i.e., that it was not forged by a +third party). **Integrity** ensures that the contents of the file have not been +tampered with (i.e., that a third party has not undetectably altered its +contents *en route*). + +Digital signatures **cannot** prove any other property, e.g., that the signed +file is not malicious. In fact, there is nothing that could stop someone from +signing a malicious program (and it happens from time to time in reality). + +The point is, of course, that people must choose who they will trust (e.g., +Linus Torvalds, Microsoft, the Qubes Project, etc.) and assume that if a given +file was signed by a trusted party, then it should not be malicious or buggy in +some horrible way. But the decision of whether to trust any given party is +beyond the scope of digital signatures. It's more of a sociological and +political decision. + +Once we make the decision to trust certain parties, digital signatures are +useful, because they make it possible for us to limit our trust only to those +few parties we choose and not to worry about all the "Bad Things That Can +Happen In The Middle" between us and them, e.g., server compromises +(qubes-os.org will surely be compromised one day), dishonest IT staff at the +hosting company, dishonest staff at the ISPs, Wi-Fi attacks, etc. + +By verifying all the files we download which purport to be authored by a party +we've chosen to trust, we eliminate concerns about the bad things discussed +above, since we can easily detect whether any files have been tampered with +(and subsequently choose to refrain from executing, installing, or opening +them). + +However, for digital signatures to make any sense, we must ensure that the +public keys we use for signature verification are indeed the original ones. +Anybody can generate a GPG key pair that purports to belong to "The Qubes +Project," but of course only the key pair that we (i.e., the Qubes developers) +generated is the legitimate one. The next section explains how to verify the +validity of the Qubes signing keys. + +Importing Qubes Signing Keys +---------------------------- + +Every file published by the Qubes Project (ISO, RPM, TGZ files and git +repositories) is digitally signed by one of the developer or release signing +keys. Each such key is signed by the [Qubes Master Signing Key] +(`0xDDFA1A3E36879494`). + +The public portion of the Qubes Master Signing Key can be imported directly +from a [keyserver] (specified on first use with `--keyserver <URI>`, keyserver +saved in `~/.gnupg/gpg.conf`), e.g., + + gpg --keyserver pool.sks-keyservers.net --recv-keys 0x427F11FD0FAA4B080123F01CDDFA1A3E36879494 + +or downloaded [here][Qubes Master Signing Key] and imported with gpg, + + $ gpg --import ./qubes-master-signing-key.asc + +or fetched directly with gpg. + + $ gpg --fetch-keys https://keys.qubes-os.org/keys/qubes-master-signing-key.asc + +For additional security we also publish the fingerprint of the Qubes Master +Signing Key here in this document: + + pub 4096R/36879494 2010-04-01 + Key fingerprint = 427F 11FD 0FAA 4B08 0123 F01C DDFA 1A3E 3687 9494 + uid Qubes Master Signing Key + +There should also be a copy of this key at the project's main website, in the +[Qubes Security Pack], and in the archives of the project's +[developer][devel-master-key-msg] and [user][user-master-key-msg] [mailing lists]. + +Once you have obtained the Qubes Master Signing Key, +you should verify the fingerprint of this key very carefully by obtaining +copies of the fingerprint from multiple independent sources and comparing +them to the downloaded key's fingerprint to ensure they match. Here are some +ideas: + + * Use the PGP Web of Trust. + * Check the key against different keyservers. + * Use different search engines to search for the fingerprint. + * Use Tor to view and search for the fingerprint on various websites. + * Use various VPNs and proxy servers. + * Use different Wi-Fi networks (work, school, internet cafe, etc.). + * Ask people to post the fingerprint in various forums and chat rooms. + * Check against PDFs and photographs in which the fingerprint appears + (e.g., slides from a talk or on a T-shirt). + * Repeat all of the above from different computers and devices. + +In addition, some operating systems have built-in keyrings containing keys +capable of validating the Qubes Master Signing Key. For example, if you have +a Debian system, then your debian-keyring may already contain the necessary +keys. + +Once you're confident that you have the legitimate Qubes Master Signing Key, +set its trust level to "ultimate" (oh, well), so that it can be used to +automatically verify all the keys signed by the Qubes Master Signing Key: + + + $ gpg --edit-key 0x36879494 + gpg (GnuPG) 1.4.18; Copyright (C) 2014 Free Software Foundation, Inc. + This is free software: you are free to change and redistribute it. + There is NO WARRANTY, to the extent permitted by law. + + + pub 4096R/36879494 created: 2010-04-01 expires: never usage: SC + trust: unknown validity: unknown + [ unknown] (1). Qubes Master Signing Key + + gpg> fpr + pub 4096R/36879494 2010-04-01 Qubes Master Signing Key + Primary key fingerprint: 427F 11FD 0FAA 4B08 0123 F01C DDFA 1A3E 3687 9494 + + gpg> trust + pub 4096R/36879494 created: 2010-04-01 expires: never usage: SC + trust: unknown validity: unknown + [ unknown] (1). Qubes Master Signing Key + + Please decide how far you trust this user to correctly verify other users' keys + (by looking at passports, checking fingerprints from different sources, etc.) + + 1 = I don't know or won't say + 2 = I do NOT trust + 3 = I trust marginally + 4 = I trust fully + 5 = I trust ultimately + m = back to the main menu + + Your decision? 5 + Do you really want to set this key to ultimate trust? (y/N) y + + pub 4096R/36879494 created: 2010-04-01 expires: never usage: SC + trust: ultimate validity: unknown + [ unknown] (1). Qubes Master Signing Key + Please note that the shown key validity is not necessarily correct + unless you restart the program. + + gpg> q + +Now you can easily download any of the developer or release signing keys that +happen to be used to sign particular ISO, RPM, TGZ files or git tags. + +For example, the Qubes OS [Release 3 Signing Key] (`0xCB11CA1D03FA5082`) is +used for all Release 3 ISO images: + + $ gpg --recv-keys 0xC52261BE0A823221D94CA1D1CB11CA1D03FA5082 + gpg: requesting key 03FA5082 from hkp server keys.gnupg.net + gpg: key 03FA5082: public key "Qubes OS Release 3 Signing Key" imported + gpg: 3 marginal(s) needed, 1 complete(s) needed, PGP trust model + gpg: depth: 0 valid: 1 signed: 1 trust: 0-, 0q, 0n, 0m, 0f, 1u + gpg: depth: 1 valid: 1 signed: 0 trust: 1-, 0q, 0n, 0m, 0f, 0u + gpg: Total number processed: 1 + gpg: imported: 1 (RSA: 1) + +You can also download all the currently used developers' signing keys and +current and older release signing keys (and also a copy of the Qubes Master +Signing Key) from the [Qubes OS Keyserver] and from the [Qubes Security Pack]. + +The developer signing keys are set to be valid for 1 year only, while the Qubes +Master Signing Key has no expiration date. This latter key was generated and is +kept only within a dedicated, air-gapped "vault" machine, and the private +portion will (hopefully) never leave this isolated machine. + +You can now verify the ISO image (`Qubes-R3.2-x86_64.iso`) matches its +signature (`Qubes-R3.2-x86_64.iso.asc`): + + $ gpg -v --verify Qubes-R3.2-x86_64.iso.asc Qubes-R3.2-x86_64.iso + gpg: armor header: Version: GnuPG v1 + gpg: Signature made Tue 08 Mar 2016 07:40:56 PM PST using RSA key ID 03FA5082 + gpg: using PGP trust model + gpg: Good signature from "Qubes OS Release 3 Signing Key" + gpg: binary signature, digest algorithm SHA256 + +The Release 3 Signing Key used to sign this ISO image should be signed by the +Qubes Master Signing Key: + + $ gpg --list-sig 03FA5082 + pub 4096R/03FA5082 2014-11-19 + uid Qubes OS Release 3 Signing Key + sig 3 03FA5082 2014-11-19 Qubes OS Release 3 Signing Key + sig 36879494 2014-11-19 Qubes Master Signing Key + + +Verifying Digests +----------------- + +Each ISO is also accompanied by a plain text file ending in `.DIGESTS`. This +file contains the output of running several different crytographic hash +functions on the ISO in order to obtain alphanumeric outputs known as "digests" +or "hash values." These hash values are provided as an alternative verification +method to PGP signatures (though the `.DIGESTS` file is itself also PGP-signed +--- see below). If you've already verified the signatures on the ISO directly, +then verifying digests is not necessary. You can always find all the `.DIGESTS` +files for every Qubes ISO in the [Qubes Security Pack]. + +As an example, `Qubes-R3.2-x86_64.iso` is accompanied by +`Qubes-R3.2-x86_64.iso.DIGESTS` which has the following content: + + -----BEGIN PGP SIGNED MESSAGE----- + Hash: SHA256 + + 3c951138b8b9867d8657f173c1b58b82 *Qubes-R3.2-x86_64.iso + 1fc9508160d7c4cba6cacc3025165b0f996c843f *Qubes-R3.2-x86_64.iso + 6b998045a513dcdd45c1c6e61ace4f1b4e7eff799f381dccb9eb0170c80f678a *Qubes-R3.2-x86_64.iso + de1eb2e76bdb48559906f6fe344027ece20658d4a7f04ba00d4e40c63723171c62bdcc869375e7a4a4499d7bff484d7a621c3acfe9c2b221baee497d13cd02fe *Qubes-R3.2-x86_64.iso + -----BEGIN PGP SIGNATURE----- + Version: GnuPG v2 + + iQIcBAEBCAAGBQJX4XO/AAoJEMsRyh0D+lCCL9sP/jlZ26zhvlDEX/eaA/ANa/6b + Dpsh/sqZEpz1SWoUxdm0gS+anc8nSDoCQSMBxnafuBbmwTChdHI/P7NvNirCULma + 9nw+EYCsCiNZ9+WCeroR8XDFSiDjvfkve0R8nwfma1XDqu1bN2ed4n/zNoGgQ8w0 + t5LEVDKCVJ+65pI7RzOSMbWaw+uWfGehbgumD7a6rfEOqOTONoZOjJJTnM0+NFJF + Qz5yBg+0FQYc7FmfX+tY801AwSyevj3LKGqZN1GVcU9hhoHH7f2BcbdNk9I5WHHq + doKMnZtcdyadQGwMNB68Wu9+0CWsXvk6E00QfW69M4d6w0gbyoJyUL1uzxgixb5O + qodxrqeitXQSZZvU4kom5zlSjqZs4dGK+Ueplpkr8voT8TSWer0Nbh/VMfrNSt1z + 0/j+e/KMjor7XxehR+XhNWa2YLjA5l5H9rP+Ct/LAfVFp4uhsAnYf0rUskhCStxf + Zmtqz4FOw/iSz0Os+IVcnRcyTYWh3e9XaW56b9J/ou0wlwmJ7oJuEikOHBDjrUph + 2a8AM+QzNmnc0tDBWTtT2frXcotqL+Evp/kQr5G5pJM/mTR5EQm7+LKSl7yCPoCj + g8JqGYYptgkxjQdX3YAy9VDsCJ/6EkFc2lkQHbgZxjXqyrEMbgeSXtMltZ7cCqw1 + 3N/6YZw1gSuvBlTquP27 + =e9oD + -----END PGP SIGNATURE----- + +Four digests have been computed for this ISO. The hash functions used, in order +from top to bottom, are MD5, SHA1, SHA256, and SHA512. One way to verify that +the ISO you downloaded matches any of these hash values is by using the +respective `*sum` programs: + + $ md5sum -c Qubes-R3.2-x86_64.iso.DIGESTS + Qubes-R3.2-x86_64.iso: OK + md5sum: WARNING: 23 lines are improperly formatted + $ sha1sum -c Qubes-R3.2-x86_64.iso.DIGESTS + Qubes-R3.2-x86_64.iso: OK + sha1sum: WARNING: 23 lines are improperly formatted + $ sha256sum -c Qubes-R3.2-x86_64.iso.DIGESTS + Qubes-R3.2-x86_64.iso: OK + sha256sum: WARNING: 23 lines are improperly formatted + $ sha512sum -c Qubes-R3.2-x86_64.iso.DIGESTS + Qubes-R3.2-x86_64.iso: OK + sha512sum: WARNING: 23 lines are improperly formatted + +The `OK` response tells us that the hash value for that particular hash +function matches. The program also warns us that there are 23 improperly +formatted lines, but this is to be expected. This is because each file contains +lines for several different hash values (as mentioned above), but each `*sum` +program verifies only the line for its own hash function. In addition, there +are lines for the PGP signature which the `*sum` programs do not know how to +read. + +Another way is to use `openssl` to compute each hash value, then compare them +to the contents of the `.DIGESTS` file.: + + $ openssl dgst -md5 Qubes-R3.2-x86_64.iso + MD5(Qubes-R3.2-x86_64.iso)= 3c951138b8b9867d8657f173c1b58b82 + $ openssl dgst -sha1 Qubes-R3.2-x86_64.iso + SHA1(Qubes-R3.2-x86_64.iso)= 1fc9508160d7c4cba6cacc3025165b0f996c843f + $ openssl dgst -sha256 Qubes-R3.2-x86_64.iso + SHA256(Qubes-R3.2-x86_64.iso)= 6b998045a513dcdd45c1c6e61ace4f1b4e7eff799f381dccb9eb0170c80f678a + $ openssl dgst -sha512 Qubes-R3.2-x86_64.iso + SHA512(Qubes-R3.2-x86_64.iso)= de1eb2e76bdb48559906f6fe344027ece20658d4a7f04ba00d4e40c63723171c62bdcc869375e7a4a4499d7bff484d7a621c3acfe9c2b221baee497d13cd02fe + +(Notice that the outputs match the values from the `.DIGESTS` file.) + +However, it is possible that an attacker replaced `Qubes-R3.2-x86_64.iso` with +a malicious ISO, computed the hash values for that ISO, and replaced the values +in `Qubes-R3.2-x86_64.iso.DIGESTS` with his own set of values. Therefore, +ideally, we should also verify the authenticity of the listed hash values. +Since `Qubes-R3.2-x86_64.iso.DIGESTS` is a clearsigned PGP file, we can use +`gpg` to verify it from the command line: + + $ gpg -v --verify Qubes-R3.2-x86_64.iso.DIGESTS + gpg: armor header: Hash: SHA256 + gpg: armor header: Version: GnuPG v2 + gpg: original file name='' + gpg: Signature made Tue 20 Sep 2016 10:37:03 AM PDT using RSA key ID 03FA5082 + gpg: using PGP trust model + gpg: Good signature from "Qubes OS Release 3 Signing Key" + gpg: textmode signature, digest algorithm SHA256 + +The signature is good. Assuming our copy of the `Qubes OS Release 3 Signing +Key` is also authentic (see above), we can be confident that these hash values +came from the Qubes devs. + +Verifying Qubes Code +-------------------- + +Developers who fetch code from our Git server should always verify the PGP signature of the tag on the latest commit. +In some cases, commits themselves may also be signed. +Any unsigned commit that is not followed by a signed tag should not be trusted! + +To verify a signature on a git tag: + + $ git tag -v <tag name> + +or + + $ git verify-tag <tag name> + +To verify a signature on a git commit: + + $ git log --show-signature <commit ID> + +or + + $ git verify-commit <commit ID> + + +[Qubes Master Signing Key]: https://keys.qubes-os.org/keys/qubes-master-signing-key.asc +[keyserver]: https://en.wikipedia.org/wiki/Key_server_%28cryptographic%29#Keyserver_examples +[Qubes Security Pack]: /security/pack/ +[devel-master-key-msg]: https://groups.google.com/d/msg/qubes-devel/RqR9WPxICwg/kaQwknZPDHkJ +[user-master-key-msg]: https://groups.google.com/d/msg/qubes-users/CLnB5uFu_YQ/ZjObBpz0S9UJ +[mailing lists]: /mailing-lists/ +[Release 3 Signing Key]: https://keys.qubes-os.org/keys/qubes-release-3-signing-key.asc +[Qubes OS Keyserver]: https://keys.qubes-os.org/keys/ + diff --git a/security-info/xsa.md b/security-info/xsa.md new file mode 100644 index 00000000..b9313d59 --- /dev/null +++ b/security-info/xsa.md @@ -0,0 +1,108 @@ +--- +layout: security +title: Xen Security Advisory (XSA) Tracker +permalink: /security/xsa/ +--- + +Xen Security Advisory (XSA) Tracker +=================================== + +This tracker shows whether Qubes OS is affected by any given [Xen Security Advisory (XSA)][XSA]. +Shortly after a new XSA is published, we will add a new row to this tracker. +Whenever Qubes is significantly affected by an XSA, a [Qubes Security Bulletin (QSB)][QSB] is published, and a link to that QSB is added to the row for the associated XSA. + +Under the "Is Qubes Affected?" column, there are two possible values: **Yes** or **No**. + +* **Yes** means that the *security* of Qubes OS *is* affected. +* **No** means that the *security* of Qubes OS is *not* affected. + + +Important Notes +--------------- +* For the purpose of this tracker, we do *not* classify mere [denial-of-service (DoS) attacks][DoS] as affecting the *security* of Qubes OS. + Therefore, if an XSA pertains *only* to DoS attacks against Qubes, the value in the "Is Qubes Affected?" column will be **No**. +* For simplicity, we use the present tense ("is affected") throughout this page, but this does **not** necessarily mean that up-to-date Qubes installations are *currently* affected by any particular XSA. + In fact, it is extremely unlikely that any up-to-date Qubes installations are vulnerable to any XSAs on this page, since patches are almost always published concurrently with QSBs. + Please read the QSB (if any) for each XSA for patching details. +* Embargoed XSAs are excluded from this tracker until they are publicly released, since the [Xen Security Policy] does not permit us to state whether Qubes is affected prior to the embargo date. +* Unused XSA numbers are included in the tracker for the sake of completeness, but they are excluded from the [Statistics] section for the sake of accuracy. +* All dates are in UTC. + + +Statistics +---------- +{% assign date_first = site.data.xsa.first.date %} +{% assign date_first_epoch = date_first | date: "%s" %} +{% assign date_last = site.data.xsa.last.date %} +{% assign date_last_epoch = date_last | date: "%s" %} +{% assign timespan_epoch = date_last_epoch | minus: date_first_epoch %} +{% assign timespan_human = timespan_epoch | divided_by: 31536000.0 | round: 1 %} +{% assign xsa_total = site.data.xsa | size | plus: 1.0 %} +{% assign xsa_unused = 0.0 %} +{% assign xsa_affected = 0.0 %} +{% for xsa in site.data.xsa %} + {% if xsa.affected == true %} + {% assign xsa_affected = xsa_affected | plus: 1.0 %} + {% endif %} + {% if xsa.unused == true %} + {% assign xsa_unused = xsa_unused | plus: 1.0 %} + {% endif %} +{% endfor %} +{% assign xsa_used = xsa_total | minus: xsa_unused %} +{% assign affected_percentage = xsa_affected | divided_by: xsa_used | times: 100.0 | round: 2 %} + +* Total time span: **{{ timespan_human }} years** ({{ date_first }} to {{ date_last }}) +* Total XSAs published: **{{ xsa_used | round }}** +* Total XSAs affecting Qubes OS: **{{ xsa_affected | round }}** +* Percentage of XSAs affecting Qubes OS: **{{ affected_percentage }}%** + +Tracker +------- +<table> + <tr class="center"> + <th title="Anchor Link"><span class="fa fa-link"></span></th> + <th>Date</th> + <th title="Xen Security Advisory">XSA</th> + <th>Is Qubes Affected?</th> + </tr> +{% for xsa in site.data.xsa reversed %} + <tr id="{{ xsa.xsa }}"> + <td><a href="#{{ xsa.xsa }}" class="fa fa-link black-icon" title="Anchor link to tracker row: XSA-{{ xsa.xsa }}"></a></td> + <td>{{ xsa.date }}</td> + <td> + <a title="Xen Security Advisory {{ xsa.xsa }}" + {% if xsa.xsa <= 25 %} + href="https://wiki.xenproject.org/wiki/Security_Announcements_(Historical)" + {% else %} + href="https://xenbits.xen.org/xsa/advisory-{{ xsa.xsa }}.html" + {% endif %}> + XSA-{{ xsa.xsa }} <span class="fa fa-external-link"></span></a> + </td> + <td> + {% if xsa.affected == false %} + {% if xsa.unused %} + No (unused XSA number) + {% elsif xsa.mitigation %} + No (<a href="#{{ xsa.mitigation }}" title="No, the security of Qubes OS is not affected by XSA-{{ xsa.xsa }}. Click to read the explanation.">{{ xsa.mitigation }}</a>) + {% else %} + <span title="No, the security of Qubes OS is not affected by XSA-{{ xsa.xsa }}.">No</span> + {% endif %} + {% elsif xsa.affected == true %} + <span title="Yes, the security of Qubes OS is affected by XSA-{{ xsa.xsa }}.">Yes</span> + {% if xsa.qsb %} + | <a href="https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-{{ xsa.qsb }}.txt" title="Qubes Security Bulletin {{ xsa.qsb }}">QSB-{{ xsa.qsb }} <span class="fa fa-external-link"></span></a> + {% endif %} + {% else %} + {% endif %} + </td> + </tr> +{% endfor %} +</table> + + +[XSA]: https://xenbits.xen.org/xsa/ +[QSB]: /security/bulletins/ +[DoS]: https://en.wikipedia.org/wiki/Denial-of-service_attack +[Xen Security Policy]: https://www.xenproject.org/security-policy.html +[Statistics]: #statistics + diff --git a/security/anti-evil-maid.md b/security/anti-evil-maid.md index 4323bf10..f70dcbfb 100644 --- a/security/anti-evil-maid.md +++ b/security/anti-evil-maid.md @@ -14,7 +14,7 @@ Installing and Using Anti Evil Maid (AEM) with Qubes OS Background ---------- -Please read [this blog article](http://theinvisiblethings.blogspot.com/2011/09/anti-evil-maid.html). +Please read [this blog article](https://blog.invisiblethings.org/2011/09/07/anti-evil-maid.html). Installing ---------- @@ -30,9 +30,9 @@ More information regarding configuration in the [README](https://github.com/Qube Security Considerations ----------------------- -[Qubes security guidelines](/doc/security-guidelines/) dictate that USB devices should never be attached directly to dom0, since this can result in the entire system being compromised. However, in its default configuration, installing and using AEM requires attaching a USB drive (i.e., [mass storage device](https://en.wikipedia.org/wiki/USB_mass_storage_device_class)) directly to dom0. (The other option is to install AEM to an internal disk. However, this carries significant security implications, as explained [here](http://theinvisiblethings.blogspot.com/2011/09/anti-evil-maid.html).) This presents us with a classic security trade-off: each Qubes user must make a choice between protecting dom0 from a potentially malicious USB drive, on the one hand, and protecting the system from Evil Maid attacks, on the other hand. Given the practical feasibility of attacks like [BadUSB](https://srlabs.de/badusb/) and revelations regarding pervasive government hardware backdoors, this is no longer a straightforward decision. New, factory-sealed USB drives cannot simply be assumed to be "clean" (e.g., to have non-malicious microcontroller firmware). Therefore, it is up to each individual Qubes user to evaluate the relative risk of each attack vector against his or her security model. +[Qubes security guidelines](/doc/security-guidelines/) dictate that USB devices should never be attached directly to dom0, since this can result in the entire system being compromised. However, in its default configuration, installing and using AEM requires attaching a USB drive (i.e., [mass storage device](https://en.wikipedia.org/wiki/USB_mass_storage_device_class)) directly to dom0. (The other option is to install AEM to an internal disk. However, this carries significant security implications, as explained [here](https://blog.invisiblethings.org/2011/09/07/anti-evil-maid.html).) This presents us with a classic security trade-off: each Qubes user must make a choice between protecting dom0 from a potentially malicious USB drive, on the one hand, and protecting the system from Evil Maid attacks, on the other hand. Given the practical feasibility of attacks like [BadUSB](https://srlabs.de/badusb/) and revelations regarding pervasive government hardware backdoors, this is no longer a straightforward decision. New, factory-sealed USB drives cannot simply be assumed to be "clean" (e.g., to have non-malicious microcontroller firmware). Therefore, it is up to each individual Qubes user to evaluate the relative risk of each attack vector against his or her security model. -For example, a user who frequently travels with a Qubes laptop holding sensitive data may be at a much higher risk of Evil Maid attacks than a home user with a stationary Qubes desktop. If the frequent traveler judges her risk of an Evil Maid attack to be higher than the risk of a malicious USB device, she might reasonably opt to install and use AEM. On the other hand, the home user might deem the probability of an Evil Maid attack occurring in her own home to be so low that there is a higher probability that any USB drive she purchases is already compromised, in which case she might reasonably opt never to attach any USB devices directly to dom0. (In either case, users can--and should--secure dom0 against further USB-related attacks through the use of a [USBVM](/doc/SecurityGuidelines/#creating-and-using-a-usbvm).) +For example, a user who frequently travels with a Qubes laptop holding sensitive data may be at a much higher risk of Evil Maid attacks than a home user with a stationary Qubes desktop. If the frequent traveler judges her risk of an Evil Maid attack to be higher than the risk of a malicious USB device, she might reasonably opt to install and use AEM. On the other hand, the home user might deem the probability of an Evil Maid attack occurring in her own home to be so low that there is a higher probability that any USB drive she purchases is already compromised, in which case she might reasonably opt never to attach any USB devices directly to dom0. (In either case, users can--and should--secure dom0 against further USB-related attacks through the use of a [USBVM](/doc/security-guidelines/#creating-and-using-a-usbvm).) For more information, please see [this discussion thread](https://groups.google.com/d/msg/qubes-devel/EBc4to5IBdg/n1hfsHSfbqsJ). @@ -40,4 +40,4 @@ Known issues ------------ - USB 3.0 isn't supported yet - +- [AEM is not compatible with having an SSD cache](https://groups.google.com/d/msgid/qubes-users/70021590-fb3a-4f95-9ce5-4b340530ddbf%40petaramesh.org) diff --git a/security/data-leaks.md b/security/data-leaks.md index efd9513b..3fafeab5 100644 --- a/security/data-leaks.md +++ b/security/data-leaks.md @@ -14,7 +14,7 @@ Understanding and Preventing Data Leaks The Role of the Firewall ------------------------ -**[Firewalling in Qubes](/doc/qubes-firewall/) is not intended to be a leak-prevention mechanism.** +**[Firewalling in Qubes](/doc/firewall/) is not intended to be a leak-prevention mechanism.** There are several reasons for this, which will be explained below. However, the main reason is that Qubes cannot prevent an attacker who has compromised one AppVM (with restrictive firewall rules) from leaking data via cooperative covert channels through a different AppVM (with sufficiently nonrestrictive firewall rules, if any) which the attacker has also compromised. diff --git a/security/qubes-firewall.md b/security/firewall.md similarity index 63% rename from security/qubes-firewall.md rename to security/firewall.md index 980888ad..fa908a33 100644 --- a/security/qubes-firewall.md +++ b/security/firewall.md @@ -1,8 +1,9 @@ --- layout: doc -title: Qubes Firewall -permalink: /doc/qubes-firewall/ +title: The Qubes Firewall +permalink: /doc/firewall/ redirect_from: +- /doc/qubes-firewall/ - /en/doc/qubes-firewall/ - /doc/QubesFirewall/ - /wiki/QubesFirewall/ @@ -14,19 +15,19 @@ Understanding Qubes networking and firewall Understanding firewalling in Qubes ---------------------------------- -Every VM in Qubes is connected to the network via a FirewallVM, which is used to -enforce network-level policies. By default there is one default Firewall VM, but +Every qube in Qubes is connected to the network via a FirewallVM, which is used to +enforce network-level policies. By default there is one default FirewallVM, but the user is free to create more, if needed. For more information, see the following: - [https://groups.google.com/group/qubes-devel/browse\_thread/thread/9e231b0e14bf9d62](https://groups.google.com/group/qubes-devel/browse_thread/thread/9e231b0e14bf9d62) -- [http://theinvisiblethings.blogspot.com/2011/09/playing-with-qubes-networking-for-fun.html](http://theinvisiblethings.blogspot.com/2011/09/playing-with-qubes-networking-for-fun.html) +- [https://blog.invisiblethings.org/2011/09/28/playing-with-qubes-networking-for-fun.html](https://blog.invisiblethings.org/2011/09/28/playing-with-qubes-networking-for-fun.html) How to edit rules ----------------- -In order to edit rules for a given domain, select this domain in the Qubes +In order to edit rules for a given qube, select it in the Qubes Manager and press the "firewall" button: ![r2b1-manager-firewall.png](/attachment/wiki/QubesFirewall/r2b1-manager-firewall.png) @@ -37,76 +38,103 @@ connection. This means it will not work for servers using load balancing. More on this in the message quoted below. Alternatively, one can use the `qvm-firewall` command from Dom0 to edit the -firewall rules by hand: +firewall rules by hand. The firewall rules for each VM are saved in an XML file +in that VM's directory in dom0: + + /var/lib/qubes/appvms/<vm-name>/firewall.xml + +Please note that there is a 3 kB limit to the size of the `iptables` script. +This equates to somewhere between 35 and 39 rules. +If this limit is exceeded, the qube will not start. + +It is possible to work around this limit by enforcing the rules on the qube itself +by putting appropriate rules in `/rw/config`. See [below](#where-to-put-firewall-rules). +In complex cases, it might be appropriate to load a ruleset using `iptables-restore` +called from `/rw/config/rc.local`. Reconnecting VMs after a NetVM reboot ---------------------------------------- -Normally Qubes doesn't let the user to stop a NetVM if there are other VMs +Normally Qubes doesn't let the user stop a NetVM if there are other qubes running which use it as their own NetVM. But in case the NetVM stops for whatever reason (e.g. it crashes, or the user forces its shutdown via qvm-kill via terminal in Dom0), then there is an easy way to restore the connection to -the netvm by issuing: +the NetVM by issuing: ` qvm-prefs <vm> -s netvm <netvm> ` -Normally VMs do not connect directly to the actual NetVM which has networking -devices, but rather to the default FirewallVM first, and in most cases it would -be the NetVM that would crash, e.g. in response to S3 sleep/restore or other -issues with WiFi drivers. In that case it is necessary to just issue the above -command once, for the FirewallVM (this assumes default VM-naming used by the +Normally qubes do not connect directly to the actual NetVM which has networking +devices, but rather to the default sys-firewall first, and in most cases it would +be the NetVM that will crash, e.g. in response to S3 sleep/restore or other +issues with WiFi drivers. In that case it is only necessary to issue the above +command once, for the sys-firewall (this assumes default VM-naming used by the default Qubes installation): -` qvm-prefs firewallvm -s netvm netvm ` +` qvm-prefs sys-firewall -s netvm netvm ` -Enabling networking between two VMs +Enabling networking between two qubes -------------------------------------- -Normally any networking traffic between VMs is prohibited for security reasons. -However, in special situations, one might want to selectively allow specific VMs -to be able to establish networking connectivity between each other. For example, -this might come useful in some development work, when one wants to test +Normally any networking traffic between qubes is prohibited for security reasons. +However, in special situations, one might want to selectively allow specific qubes +to establish networking connectivity between each other. For example, +this might be useful in some development work, when one wants to test networking code, or to allow file exchange between HVM domains (which do not have Qubes tools installed) via SMB/scp/NFS protocols. -In order to allow networking between VM A and B follow those steps: +In order to allow networking between qubes A and B follow these steps: * Make sure both A and B are connected to the same firewall vm (by default all VMs use the same firewall VM). -* Note the Qubes IP addresses assigned to both VMs. This can be done using the - `qvm-ls -n` command, or via the Qubes Manager preferences pane for each VM. -* Start both VMs, and also open a terminal in the firewall VM +* Note the Qubes IP addresses assigned to both qubes. This can be done using the + `qvm-ls -n` command, or via the Qubes Manager preferences pane for each qube. +* Start both qubes, and also open a terminal in the firewall VM * In the firewall VM's terminal enter the following iptables rule: ~~~ sudo iptables -I FORWARD 2 -s <IP address of A> -d <IP address of B> -j ACCEPT ~~~ -* Now you should be able to reach the VM B from A -- test it using e.g. ping - issues from VM A. Note however, that this doesn't allow you to reach A from - B -- for this you would need another rule, with A and B addresses swapped. -* If everything works as expected, then the above iptables rule(s) should be - written into firewall VM's `qubes_firewall_user_script` script which is run - on every firewall update. This is necessary, because Qubes orders every - firewall VM to update all the rules whenever new VM is started in the system. - If we didn't enter our rules into this "hook" script, then shortly our custom - rules would disappear and inter-VM networking would stop working. Here's an - example how to update the script (note that, by default, there is no script - file present, so we likely will be creating it, unless we had some other - custom rules defines earlier in this firewallvm): +* In qube B's terminal enter the following iptables rule: ~~~ -[user@firewallvm ~]$ sudo bash -[root@firewallvm user]# echo "iptables -I FORWARD 2 -s 10.137.2.25 -d 10.137.2.6 -j ACCEPT" >> /rw/config/qubes_firewall_user_script -[root@firewallvm user]# chmod +x /rw/config/qubes_firewall_user_script +sudo iptables -I INPUT -s <IP address of A> -j ACCEPT ~~~ -Port forwarding to a VM from the outside world +* Now you should be able to reach B from A -- test it using e.g. ping + issued from A. Note however, that this doesn't allow you to reach A from + B -- for this you would need two more rules, with A and B swapped. +* If everything works as expected, then the above iptables rules should be + written into firewallVM's `qubes-firewall-user-script` script which is run + on every firewall update, and A and B's `rc.local` script which is run when + the qube is launched. The `qubes-firewall-user-script` is necessary because Qubes + orders every firewallVM to update all the rules whenever a new connected qube is + started. If we didn't enter our rules into this "hook" script, then shortly + our custom rules would disappear and inter-VM networking would stop working. + Here's an example how to update the script (note that, by default, there is no + script file present, so we will probably be creating it, unless we had some other + custom rules defined earlier in this firewallVM): + +~~~ +[user@sys-firewall ~]$ sudo bash +[root@sys-firewall user]# echo "iptables -I FORWARD 2 -s 10.137.2.25 -d 10.137.2.6 -j ACCEPT" >> /rw/config/qubes-firewall-user-script +[root@sys-firewall user]# chmod +x /rw/config/qubes-firewall-user-script +~~~ + +* Here is an example how to update `rc.local`: + +~~~ +[user@B ~]$ sudo bash +[root@B user]# echo "iptables -I INPUT -s 10.137.2.25 -j ACCEPT" >> /rw/config/rc.local +[root@B user]# chmod +x /rw/config/rc.local +~~~ + +Port forwarding to a qube from the outside world -------------------------------------------------- -In order to allow a service present in a VM to be exposed to the outside world -in the default setup (where the VM has the Firewall VM as network VM, which in -turn has the Net VM as network VM) +In order to allow a service present in a qube to be exposed to the outside world +in the default setup (where the qube has sys-firewall as network VM, which in +turn has sys-net as network VM) the following needs to be done: * In the sys-net VM: @@ -115,8 +143,8 @@ the following needs to be done: * In the sys-firewall VM: * Route packets from the sys-net VM to the VM * Allow packets through the sys-firewall VM firewall - * In the VM: - * Allow packets in the VM firewall to reach the service + * In the qube: + * Allow packets in the qube firewall to reach the service As an example we can take the use case of a web server listening on port 443 that we want to expose on our physical interface eth0, but only to our local @@ -222,7 +250,7 @@ interface Eth0 (i.e. 10.137.2.x) ` ifconfig | grep -i cast ` Back into the sys-firewall VM's Terminal, code a natting firewall rule to route -traffic on its outside interface for the service to the VM +traffic on its outside interface for the service to the qube ` iptables -t nat -A PREROUTING -i eth0 -p tcp --dport 443 -d 10.137.1.x -j DNAT --to-destination 10.137.2.y ` @@ -235,7 +263,7 @@ the service remove the ` -s 192.168.0.1/24 ` Once you have confirmed that the counters increase, store these command in -'/rw/config/qubes_firewall_user_script' +'/rw/config/qubes-firewall-user-script' ~~~ #!/bin/sh @@ -284,10 +312,10 @@ fi Finally make this file executable (so it runs at every Firewall VM update) ~~~ -sudo chmod +x /rw/config/qubes_firewall_user_script +sudo chmod +x /rw/config/qubes-firewall-user-script ~~~ -**3. Allow packets into the VM to reach the service** +**3. Allow packets into the qube to reach the service** Here no routing is required, only filtering. Proceed in the same way as above but store the filtering rule in the '/rw/config/rc.local' script. @@ -315,3 +343,15 @@ fi This time testing should allow connectivity to the service as long as the service is up :-) + +Where to put firewall rules +--------------------------- + +Implicit in the above example [scripts](/doc/config-files/), but worth +calling attention to: for all qubes *except* ProxyVMs, iptables commands +should be added to the `/rw/config/rc.local` script. For ProxyVMs +(`sys-firewall` inclusive), iptables commands should be added to +`/rw/config/qubes-firewall-user-script`. This is because a ProxyVM is +constantly adjusting its firewall, and therefore initial settings from +`rc.local` do not persist. + diff --git a/security/multifactor-authentication.md b/security/multifactor-authentication.md index b465bb38..9e935ab0 100644 --- a/security/multifactor-authentication.md +++ b/security/multifactor-authentication.md @@ -67,24 +67,24 @@ Optional Preparation Steps [minimal Fedora template][FedoraMinimal]. Get it if you haven't already done so: - [user@dom0 ~]$ sudo qubes-dom0-update qubes-template-fedora-21-minimal + [user@dom0 ~]$ sudo qubes-dom0-update qubes-template-fedora-24-minimal 2. Since we'll be making some modifications, you may want to clone the minimal template: - [user@dom0 ~]$ qvm-clone fedora-21-minimal fedora-21-min-mfa + [user@dom0 ~]$ qvm-clone fedora-24-minimal fedora-24-min-mfa 3. Since this is going to be a minimal environment in which we run `oathtool` from the command line, we'll install only a couple of packages: - [user@fedora-21-min-mfa ~]$ su - - [user@fedora-21-min-mfa ~]# yum install oathtool vim-minimal - [user@fedora-21-min-mfa ~]$ poweroff + [user@fedora-24-min-mfa ~]$ su - + [user@fedora-24-min-mfa ~]# yum install oathtool vim-minimal + [user@fedora-24-min-mfa ~]$ poweroff 4. Create an AppVM and set it to use the TemplateVM we just created: [user@dom0 ~]$ qvm-create -l black mfa - [user@dom0 ~]$ qvm-prefs -s mfa template fedora-21-min-mfa + [user@dom0 ~]$ qvm-prefs -s mfa template fedora-24-min-mfa 5. Isolate the new AppVM from the network: diff --git a/security/security-goals.md b/security/security-goals.md deleted file mode 100644 index 4fd8b3a3..00000000 --- a/security/security-goals.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -layout: doc -title: Security Goals -permalink: /doc/security-goals/ -redirect_from: -- /en/doc/security-goals/ -- /doc/SecurityGoals/ -- /wiki/SecurityGoals/ ---- - -Qubes Security Goals -==================== - -Qubes implements a Security by Isolation approach by providing the user with the ability to easily create many security domains. These domains are implemented as lightweight Virtual Machines (VMs) running under the Xen hypervisor. Qubes' main objective is to provide strong isolation between these domains, so that even if an attacker compromises one of the domains, the others are still safe. Qubes, however, does not attempt to provide any security isolation for applications running within the same domain. For example, a buggy web browser running in a Qubes domain could still be compromised just as easily as on a regular Linux distribution. The difference that Qubes makes is that now the attacker doesn't have access to all the software running in the other domains. - -Qubes also provides a number of mechanisms that make it easy and convenient for the user to run multiple domains, such as seamless GUI integration onto one common desktop, secure clipboard copy and paste between domains, secure file transfer between domains, disposable VMs, and much more. Qubes also provides an advanced networking infrastructure that allows for the creation of multiple network VMs (which isolate all the world-facing networking stacks) and proxy VMs which can be used for advanced VPN and tunneling over untrusted connections. diff --git a/security/security-guidelines.md b/security/security-guidelines.md index e955c986..1bfa6551 100644 --- a/security/security-guidelines.md +++ b/security/security-guidelines.md @@ -11,46 +11,62 @@ redirect_from: Security Guidelines =================== -The [Qubes introduction](http://theinvisiblethings.blogspot.com/2012/09/introducing-qubes-10.html) makes clear that without some active and responsible participation of the user, no real security is possible. So, for example, Qubes does not automagically make your Firefox (or any other app) running in one of the AppVMs suddenly more secure. It is just as [secure (or insecure)](https://en.wikipedia.org/wiki/Computer_insecurity) as on a normal Linux or Windows OS. But what drastically changes is the context in which your applications are used. [This context](/doc/qubes-architecture/) is a [responsibility of the user](/doc/security-goals/). But participation requires knowledge. So it is worth stressing some basic items: +Without some active and responsible participation of the user, no real security is possible. Running Firefox inside of an AppVM does not automagically make it (or any other app) more secure. +Programs themselves remain just as secure [(or insecure)](https://en.wikipedia.org/wiki/Computer_insecurity) on Qubes as on a normal Linux or Windows OS. +What drastically changes is the context in which your applications are used. +[This context](/doc/qubes-architecture/) is a [responsibility of the user](/security/goals/). +But managing security in this context well requires knowledge of some new concepts and procedures. So it is worth stressing some basic items: Download Verification --------------------- -**Verify the authenticity and integrity of your downloads, [particularly Qubes iso](/doc/verifying-signatures/).** +**Verify the authenticity and integrity of your downloads, [particularly the Qubes iso](/security/verifying-signatures/).** -Standard program installation +The internet is always a dangerous place. +While your connection to the Qubes website and download mirrors is encrypted, meaning that your downloads from here can't be modified by a third party en route, there is always the chance that these websites themselves have been compromised. +Signature verification allows us to validate for ourselves that these files were the ones authored and signed by their creators (in this case the Qubes development team). + +Because it's so easy for a hacker who manages to tamper with the downloaded iso files this way to patch in malware, it is of the utmost importance that you **verify the signature of the Qubes iso** you use to install Qubes. +See the page on [Verifying Signatures](https://www.qubes-os.org/security/verifying-signatures/) for more information and a tutorial on how to accomplish this. + +Once you have Qubes installed, the standard program installation command for Fedora and Qubes repositories ~~~ sudo yum install <program> ~~~ -on template terminal already accomplishes verification, for fedora and qubes repositories. +automatically accomplishes this verification. -If you install new repositories, they might have gpgcheck disabled. [Check the config files](http://docs.fedoraproject.org/en-US/Fedora/12/html/Deployment_Guide/sec-Configuring_Yum_and_Yum_Repositories.html) and be sure to check that +Custom user-added repositories might come with gpgcheck disabled. [Check the config files](https://docs.fedoraproject.org/en-US/Fedora/12/html/Deployment_Guide/sec-Configuring_Yum_and_Yum_Repositories.html) and verify that ~~~ gpgcheck=1 ~~~ -Plus, also make sure you **safely import their signing keys**. This may require you check from multiple sources that the signing key is always the same. +Plus, make sure you also **safely import their signing keys**. This may require you to check from multiple sources that the signing key is always the same. -Even then, you might want to consider new repository to be **less** secure and do not use it **in the template** that feeds your more trusted VMs. +Even then, you might want to consider new repositories to be **less** secure and not use them in templates that feed your more trusted VMs. + +If you **need** to download programs that cannot be verified, then it is much less dangerous to install them in a **cloned template or a standalone VM**. + +Remember: Qubes cannot automatically verify the signature of files that come from other sources like your browser, torrenting client, or home-made tofu recipe downloader. If the providers of these downloads provide keys for you to verify the signatures of their downloads, do it! -But if you need to download programs that cannot be verified, then it is certainly better to install them in a **cloned template or a standalone VM**. Observing Security Contexts --------------------------- -To each VM is associated a specific colour of window borders in Qubes. They are how Qubes communicates the **security context** of applications and data so that users can be easily aware of this at all times. So be sure to check the colour of window borders before taking any action, particularly if related to security, [see blog](http://theinvisiblethings.blogspot.com/2011/05/app-oriented-ui-model-and-its-security.html). +Each VM is assigned a specific colour for its window borders. These borders are how Qubes displays the **security context** of applications and data so that users can be easily aware of this at all times. Be sure to check the colour of window borders before taking any action, particularly if it affects the security of your system. [See this blog post for more information](https://blog.invisiblethings.org/2011/05/21/app-oriented-ui-model-and-its-security.html). -Also, be sure to use **Expose-like effect** when dealing with a smaller window displayed on top of a larger window. Remember that a "red" Firefox, can always draw a "green" password prompt box, and you don't want to enter your password there! - -Check **Expose-like effect** is activated (e.g. System Tools -\> System Settings -\> Desktop Effects -\> All Effects -\> Desktop Grid Present Windows effects in KDE, or, if you're a hard-core Xfce4 user or something, then manually move the more trusted window so that it is not displayed on top of a less trusted one, but rather over the trusted Dom0 wallpaper. +Always remember that any "red" window can draw "green" password prompts. +Don't let yourself be tricked into entering credentials designated to one qube into a forged input boxes rendered by another. +For XFCE users (which is the default desktop environment on QubesOS) it would be wise to manually move the more trusted window so that it is not displayed on top of a less trusted one, but rather over the trusted Dom0 wallpaper. +If you use KDE, it has a helpful feature called **Expose-like effect** that is activated in System Tools -\> System Settings -\> Desktop Effects -\> All Effects -\> Desktop Grid Present Windows. +Performing these steps makes it easier to tell the difference between when you're being phished and when you're genuinely being asked for credentials. Installing Versus Running Programs ---------------------------------- -With the exception of the editor required for configuration, one should not run applications in either template VMs or in Dom0. From a security standpoint there is a great difference between installing a program and running it. +With the exception of a text editor used to modify configuration files, one should not run applications in either template VMs or in Dom0. From a security standpoint there is a great difference between installing a program and running it. Enabling and Verifying VT-d/IOMMU --------------------------------- @@ -61,9 +77,9 @@ In **Dom0** terminal, run: qubes-hcl-report <userVM> ~~~ -where \<userVM\> is the name of the VM within which the report will be written (but the report will also be displayed in the Dom0 terminal). If it displays that VT-d is active, you should be able to assign **PCIe devices to a HVM** and **enjoy DMA protection** for your driver domains, so you successfully passed this step. +where \<userVM\> is the name of the VM within which the report will be written (but the report will also be displayed in the Dom0 terminal). If it displays that VT-d is active, you should be able to assign **PCIe devices to an HVM** and **enjoy DMA protection** for your driver domains, so you successfully passed this step. -If VT-d is not active, attempt to activate it by selecting the **VT-d flag** within the BIOS settings. If your processor/BIOS does not allow VT-d activation you still enjoy much better security than alternative systems, but you may be vulnerable to **DMA attacks**. Next time you buy a computer consult our **HCL (Hardware Compatibility List)** and possibly contribute to it. +If VT-d is not active, attempt to activate it by selecting the **VT-d flag** within the BIOS settings. If your processor/BIOS does not allow VT-d activation you still enjoy much better security than alternative systems, but you may be vulnerable to **DMA attacks**. Next time you buy a computer consult our **[HCL (Hardware Compatibility List)](https://www.qubes-os.org/hcl/)** and possibly contribute to it. Updating Software ----------------- @@ -85,35 +101,35 @@ or use the equivalent items in Qubes Manager, which displays an icon when an upd Handling Untrusted Files ------------------------ -When you receive or download any file from an **untrusted source**, do not browse to it with a file manager which has preview enabled. **To disable preview in Nautilus**: Gear (up-right-icon) -\> Preferences -\> Preview (tab) -\> Show thumbnails: Never. Note that this change can be made in a TemplateVM (including the [DispVM template](/doc/dispvm-customization/)) so that future AppVMs created from this TemplateVM will inherit this feature. +When you receive or download any file from an **untrusted source**, do not browse to it with a file manager which has preview enabled. Enabling previews in your file manager gives malware another attack vector. **To disable preview in Nautilus**: Gear (up-right-icon) -\> Preferences -\> Preview (tab) -\> Show thumbnails: Never. Note that this change can be made in a TemplateVM (including the [DispVM template](/doc/dispvm-customization/)) so that future AppVMs created from this TemplateVM will inherit this feature. -Also, **do not open it in trusted VMs**. Rather open it in a **disposable VM** right-clicking on it. You may even modify it within the disposable VM and then [copy it to other VM](/doc/copying-files/). +Also, **do not open it in trusted VMs**. Rather, open it in a **disposable VM** right-clicking on it. You may even modify it within the disposable VM and then [copy it to other VM](/doc/copying-files/). -Alternatively PDFs may be converted to **trusted PDF** right clicking on them. This converts text to graphic form, so size will increase. +Alternatively PDFs may be converted to **trusted PDFs** by right clicking on them. This converts the PDF's text to graphic form, so the disk size these documents take up will increase. Anti Evil Maid -------------- -If there is a risk that somebody may **physically attack** your computer when you leave it powered down, or if you use Qubes in **dual boot mode**, then you may want to [install AEM](/doc/anti-evil-maid/) (Anti Evil Maid). AEM will inform you of any unauthorized modifications to your BIOS or boot partition. If AEM alerts you of an attack it is really bad news because **there is no true fix**. If you are really serious about security you have to buy a new laptop and install Qubes from a trusted ISO. So buying a used laptop is not an option for a security focused one. +If there is a risk that somebody may gain **physical access** to your computer when you leave it powered down, or if you use Qubes in **dual boot mode**, then you may want to [install AEM](/doc/anti-evil-maid/) (Anti Evil Maid). AEM will inform you of any unauthorized modifications to your BIOS or boot partition. If AEM alerts you of an attack, it is really bad news because **there is no true fix**. If you are really serious about security, you will have to buy a new laptop and install Qubes from a trusted ISO. Buying a used laptop runs a higher risk of tampering and is not an option for a security focused environment. Reassigning USB Controllers --------------------------- -Before you [assign a USB controller to a VM](/doc/assigning-devices/) check if any **input devices** are included in that controller. +Before you [assign a USB controller to a VM](/doc/assigning-devices/), check if any **input devices** are included in that controller. -Assigning USB keyboard will **deprive Dom0 VM of a keyboard**. Since a USB controller assignment survives reboot, you may find yourself **unable to access your system**. Most non-Apple laptops have a PS/2 input for keyboard and mouse, so this problem does not exist. +Assigning a USB keyboard will **deprive Dom0 VM of a keyboard**. Since a USB controller assignment survives reboot, you may find yourself **unable to access your system**. Most non-Apple laptops have a PS/2 input for keyboard and mouse, so this problem does not exist. -But **if you need to use a USB keyboard or mouse**, identify the USB controller in which you have your keyboard/mouse plugged in and do NOT assign it to a VM. Also makes sure you know all the other USB ports for that controller, and use them carefully, with the knowledge **you are exposing Dom0** (ie NO bluetooth device on it). +But **if you need to use a USB keyboard or mouse**, identify the USB controller in which you have your keyboard/mouse plugged in and do NOT assign it to a VM. Also, makes sure you know all the other USB ports for that controller, and use them carefully, knowing **you are exposing Dom0** (ie NO bluetooth device on it). -All USB devices should be assumed as **side channel attack vectors** (mic via sound), others via power usage so user may prefer to remove them. [See this about rootkits](https://www.networkworld.com/news/2007/080207-black-hat-virtual-machine-rootkit-detection.html) +All USB devices should be assumed **side channel attack vectors** (mic via sound, others via power usage), so you might prefer to remove them. [See this about rootkits](https://web.archive.org/web/20070829112704/http://www.networkworld.com/news/2007/080207-black-hat-virtual-machine-rootkit-detection.html) -The **web-cam** also may involve a risk, so better to physically cover it with a adhesive tape if you do not use it. If you need it, you have **to assign it to a VM** and cover it with a cap or an elastic band when not in use. Attaching a **microphone** using Qubes VM Manager also may be risky, so attach it only when required. +Using a **web-cam** also involves a risk, so better to physically cover it with adhesive tape or disconnect it if you do not use it. If you need it, you need **to assign it to a VM** and cover it with a cap or an elastic band when not in use. Attaching a **microphone** using Qubes VM Manager may also be risky, so attach it only when required. -It is preferably to avoid using **Bluetooth** if you travel and if you do not trust your neighbours. Also there are zones roamed by kids with high-gain directional antennas. In this case, better buy a computer that does not have a Bluetooth hardware module, or, if you have it, assign it to an untrusted VM. This last solution will work also if you want to use Bluetooth without trusting it. +It is preferable to avoid using **Bluetooth** if you travel or do not trust your neighbours. Kids with high-gain directional antennas might also gain long range access to your Bluetooth. In this case, buy a computer that does not have a Bluetooth hardware module, or, if you have it, assign it to an untrusted VM. Assigning it to its own Qube will also allow you to use Bluetooth without trusting it, if need be. -Many laptops will also allow one to disable various hardware (Camera, BT, Mic, etc) **in BIOS**. This might or might not be safe, depending on how much you trust your BIOS vendor. +Many laptops allow one to disable various hardware (Camera, BT, Mic, etc) **in BIOS**. This might or might not be a dependable way of getting rid of those devices, depending on how much you trust your BIOS vendor. -If the VM will not start after you have assigned a USB controller, look at [this faq](../UserFaq/#i-created-a-usbvm-and-assigned-usb-controllers-to-it-now-the-usbvm-wont-boot) +If the VM will not start after you have assigned a USB controller, look at [this faq](../user-faq/#i-created-a-usbvm-and-assigned-usb-controllers-to-it-now-the-usbvm-wont-boot). Creating and Using a USBVM @@ -125,12 +141,12 @@ See [here](/doc/usb/). Dom0 Precautions ---------------- -As explained [here](/doc/GettingStarted/#appvms-domains-and-templatevms), dom0 should not be used for any user operations. There are several reasons for this: +As explained [here](/getting-started/#appvms-qubes-and-templatevms), dom0 should not be used for any user operations. There are several reasons for this: 1. Secure isolation among domUs (i.e., AppVMs, StandaloneVMs, HVMs, etc.) is the *raison d'être* of Qubes. This is the primary reason that we recommend the delegation of all user activities to some number of AppVMs. In the event that any given VM is compromised, only that particular VM is compromised. (TemplateVMs are the exception to this. If a TemplateVM were compromised, then every AppVM based on it might also be compromised. Even in this case, however, the entire system would not necessarily have been compromised, since StandaloneVM(s), HVM(s), and/or multiple TemplateVMs might be in use.) By contrast, if dom0 were ever compromised, the entire system would thereby be compromised. 2. Due to the absence of convenience mechanisms in dom0 such as the inter-VM clipboard and inter-VM file copying, it is significantly less convenient to attempt to use dom0 for user operations (e.g., password management) in conjunction with AppVMs than it is to use another dedicated AppVM (e.g., a "vault" VM). 3. Dom0 has access to every VM's data in the form of its private image file, including untrusted (e.g., red-bordered) VMs. If the user were to make a mistake (or be tricked into making one) and thereby inadvertently access untrusted files from dom0, those files could exploit the application which accessed them (e.g., a file manager) and gain control over dom0 and, therefore, the entire system. Even simply displaying the data in a [terminal emulator](http://securityvulns.com/docs4128.html) can be dangerous. For example, some file managers (such as the Thunar File Manager, which is pre-installed by default in the Xfce4 version of dom0) list loop devices used by running VMs. When one of these devices is selected in the file manager, the loop device is mounted to dom0, effectively [transferring the contents](https://groups.google.com/d/msg/qubes-users/_tkjmBa9m9w/9BbKh94PVtcJ) of the home directory of a (by definition less trusted) AppVM to dom0. -4. There is a (hopefully small but non-zero) chance that any given program which runs in dom0 (or anywhere, for that matter) is malicious. (For example, an attacker may have stolen a third-party developer's keys and used them to sign a malicious package, which has then been downloaded as part of a standard yum update.) For this reason, it is very important that as few programs as possible be run in dom0 in as restricted a manner as possible. For example, although GnuPG is used in dom0 for verifying updates received from the firewallvm, it does not follow that GnuPG should be used for regular user operations (e.g., key management) in dom0. This is because only a single GnuPG operation, the "verify signature" operation" (which is believed to be the most bulletproof operation in GnuPG), is used by default in dom0. No other key management operations (e.g., importing unverified keys) or any other data parsing takes place in dom0 by default. +4. There is a (hopefully small, but always non-zero) chance that any given program is malicious. Even packages by third party developers you trust might have been modified and then signed by an attacker who managed to get that developer's private key(s). For this reason, it is very important that as few programs as possible be run in dom0 in as restricted a manner as possible. For example, although GnuPG is used in dom0 for verifying updates received from the firewallvm, it does not follow that GnuPG should be used for regular user operations (e.g., key management) in dom0. This is because only a single GnuPG operation, the "verify signature" operation (which is believed to be the most bulletproof operation in GnuPG), is used by default in dom0. No other key management operations (e.g., importing unverified keys) or any other data parsing takes place in dom0 by default. 5. Any VM can be shut down in order to make it even more difficult for an adversary to access, and shutting down one VM does not restrict the user of other VMs. By contrast, one cannot shut down dom0 and use other VMs at the same time. 6. As far as we are aware, there are no special mechanisms in Xen which make dom0 more protected than any other VM, so there is no inherent security advantage to performing any user operations in dom0. @@ -138,9 +154,8 @@ As explained [here](/doc/GettingStarted/#appvms-domains-and-templatevms), dom0 s TemplateBasedVM Directories --------------------------- - * Whenever a TemplateBasedVM is created, the contents of the `/home` - directory of its parent TemplateVM are copied to the child TemplateBasedVM's - `/home`. From that point onward, the child TemplateBasedVM's `/home` + * Whenever a TemplateBasedVM is created, the contents of its `/home` + directory is copied from its parent TemplateVM. From that point onward, the child TemplateBasedVM's `/home` is independent from its parent TemplateVM's `/home`, which means that any subsequent changes to the parent TemplateVM's `/home` will no longer affect the child TemplateBasedVM's `/home`. diff --git a/security/split-bitcoin.md b/security/split-bitcoin.md index bddd5f90..bb284fa0 100644 --- a/security/split-bitcoin.md +++ b/security/split-bitcoin.md @@ -11,10 +11,46 @@ How to Set Up a Split Bitcoin Wallet in Qubes What is a "Split" Bitcoin Wallet? --------------------------------- +A "split" bitcoin wallet is a strategy of protecting your bitcoin by having your wallet split into an offline "[cold storage](https://en.bitcoin.it/wiki/Cold_storage)" wallet and an online "watching only" wallet. A "Watching" Wallet and a "Cold" Wallet --------------------------------------- +1. Create a Debian 8 backports template using the Qubes VM Manager or running + `qvm-clone debian-8 debian-8-backports` in dom0. +2. Add backports to the sources for the new template by opening a terminal in + the new template, run `sudo vi /etc/apt/sources.list` and add + `deb http://http.debian.net/debian jessie-backports main`. + + (If you are new to `vi` text editing, type `i` to be able to edit, and when + done editing press `ESC` then type `:x` and press `ENTER`.) + +3. Update source list: `sudo apt-get update`. + +4. Install `electrum` from backports: + `sudo apt-get -t jessie-backports install electrum`. + +5. shut down your `debian-8-backports` template + +6. create an `offline-bitcoin` qube based on `debian-8-backports` using the Qubes VM Manager or running `qvm-create -t debian-8-backports -l black offline-bitcoin` and `qvm-prefs -s offline-bitcoin netvm none` in dom0. + +7. follow the [electrum documentation in creating an offline wallet](http://docs.electrum.org/en/latest/coldstorage.html#create-an-offline-wallet) + +8. create a `watching-bitcoin` qubes based on `debian-8-backports` connecting to the internet how ever you prefer using the Qubes VM Manager or running for example `qvm-create -t debian-8-backports -l green watching-bitcoin` and `qvm-prefs -s watching-bitcoin netvm sys-whonix` in dom0. + +9. follow the [electrum documentation in creating an online watching-only wallet](http://docs.electrum.org/en/latest/coldstorage.html#create-a-watching-only-version-of-your-wallet) + +Important Notes +--------------- + +* The private keys (xpriv) should never be moved outside of `offline-bitcoin`. +* For copying out the public keys (xpub), Qubes provides two secure, convenient + methods: the [inter-VM clipboard] and [inter-VM file copy] tools. Compared to + traditional physically air-gapped machines, these tools makes it very easy to + copy out public keys. + +[inter-VM clipboard]: /doc/copy-paste/ +[inter-VM file copy]: /doc/copying-files/ diff --git a/security/split-gpg.md b/security/split-gpg.md index 9c685e7d..b0dc9baa 100644 --- a/security/split-gpg.md +++ b/security/split-gpg.md @@ -81,16 +81,16 @@ Configuring Split GPG In dom0, make sure the `qubes-gpg-split-dom0` package is installed. - sudo qubes-dom0-update qubes-gpg-split-dom0 + [user@dom0 ~]$ sudo qubes-dom0-update qubes-gpg-split-dom0 -If using templates based on Debian, make sure you have the `qubes-gpg-split` +If using templates based on Debian or Whonix, make sure you have the `qubes-gpg-split` package installed. - sudo apt-get install qubes-gpg-split + [user@debian-8 ~]$ sudo apt-get install qubes-gpg-split For Fedora. - sudo yum install qubes-gpg-split + [user@fedora-24 ~]$ sudo yum install qubes-gpg-split Start with creating a dedicated AppVM for storing your keys (the GPG backend domain). It is recommended that this domain be network disconnected (set its @@ -258,10 +258,11 @@ In this example, the following keys are stored in the following locations leave the `vault` VM, so it is extremely unlikely ever to be obtained by an adversary (see below). Second, an adversary who *does* manage to obtain the master secret key either possesses the passphrase to unlock the key - (if one is used), or he does not. If he does, then he can simply use - the passphrase in order to legally extend the expiration date of the key - (or remove it entirely). If he does not, then he cannot use the key at - all. In either case, an expiration date provides no additional benefit. + (if one is used) or does not. An adversary who *does* possess the passphrase + can simply use it to legally extend the expiration date of the key + (or remove it entirely). An adversary who does *not* possess the passphrase + cannot use the key at all. In either case, an expiration date provides no + additional benefit. By the same token, however, having a passphrase on the key is of little value. An adversary who is capable of stealing the key from your `vault` @@ -377,11 +378,11 @@ exercise caution and use your good judgment.) [#474]: https://github.com/QubesOS/qubes-issues/issues/474 [using split GPG with subkeys]: #advanced-using-split-gpg-with-subkeys [​subkeys]: https://wiki.debian.org/Subkeys -[copied]: /doc/copying-files#on-inter-domain-file-copy-security +[copied]: /doc/copying-files#on-inter-qube-file-copy-security [pasted]: /doc/copy-paste#on-copypaste-security [​MUA]: https://en.wikipedia.org/wiki/Mail_user_agent [covert channels]: /doc/data-leaks -[trusting-templates]: /doc/SoftwareUpdateVM#notes-on-trusting-your-template-vms +[trusting-templates]: /doc/software-update-vm/#notes-on-trusting-your-templatevms [openpgp-in-qubes-os]: https://groups.google.com/d/topic/qubes-users/Kwfuern-R2U/discussion [cabal]: https://alexcabal.com/creating-the-perfect-gpg-keypair/ [luck]: https://gist.github.com/abeluck/3383449 diff --git a/security/vm-sudo.md b/security/vm-sudo.md index d632c643..fd6c6b36 100644 --- a/security/vm-sudo.md +++ b/security/vm-sudo.md @@ -39,8 +39,8 @@ Background ([/etc/sudoers.d/qubes](https://github.com/QubesOS/qubes-core-agent-l # and for sure, root/user isolation is not a mitigating factor. # # Because, really, if somebody could find and exploit a bug in the Xen - # hypervisor -- so far there have been only one (!) publicly disclosed - # exploitable bug in the Xen hypervisor from a VM, found in 2008, + # hypervisor -- as of 2016, there have been only three publicly disclosed + # exploitable bugs in the Xen hypervisor from a VM -- then it would be # incidentally by one of the Qubes developers (RW) -- then it would be # highly unlikely if that person couldn't also found a user-to-root # escalation in VM (which as we know from history of UNIX/Linux @@ -95,16 +95,21 @@ Below is a complete list of configuration made according to the above statement, Replacing password-less root access with Dom0 user prompt --------------------------------------------------------- -While ITL still supports the statement above, some Qubes users may want to enable user/root isolation in VMs anyway. We do not support it in any of our packages, but of course nothing can stop the user from making some modifications his or her own system. A list of steps to do so is provided here without guarantee of completeness (read: **do not rely on this for extra security**): +While ITL supports the statement above, some Qubes users may wish to enable +user/root isolation in VMs anyway. We do not support it in any of our packages, +but of course nothing is preventing the user from modifying his or her own +system. A list of steps to do so is provided here **without any guarantee of +safety, accuracy, or completeness. Proceed at your own risk. Do not rely on +this for extra security.** -1. Adding Dom0 "VMAuth" service: +1. Adding Dom0 "VMAuth" service: [root@dom0 /]# echo -n "/usr/bin/echo 1" >/etc/qubes-rpc/qubes.VMAuth - [root@dom0 /]# echo -n "$anyvm dom0 ask" >/etc/qubes-rpc/policy/qubes.VMAuth + [root@dom0 /]# echo -n "\$anyvm dom0 ask" >/etc/qubes-rpc/policy/qubes.VMAuth - (Note: any VMs you would like still to have password-less root access (e.g. TemplateVMs) can be specified in the second file with "\<vmname\> dom0 allow") + (Note: any VMs you would like still to have password-less root access (e.g. TemplateVMs) can be specified in the second file with "\<vmname\> dom0 allow") -2. Configuring TemplateVM to prompt Dom0 for any authorization request: +2. Configuring Fedora TemplateVM to prompt Dom0 for any authorization request: - In /etc/pam.d/system-auth, replace all lines beginning with "auth" with one line: auth [success=done default=die] pam_exec.so seteuid /usr/lib/qubes/qrexec-client-vm dom0 qubes.VMAuth /usr/bin/grep -q ^1$ @@ -118,6 +123,32 @@ While ITL still supports the statement above, some Qubes users may want to enabl [root@fedora-20-x64]# rm /etc/polkit-1/rules.d/00-qubes-allow-all.rules [root@fedora-20-x64]# rm /etc/polkit-1/localauthority/50-local.d/qubes-allow-all.pkla +3. Configuring Debian/Whonix TemplateVM to prompt Dom0 for any authorization request: + - In /etc/pam.d/common-auth, replace all lines beginning with "auth" with one line: + + auth [success=done default=die] pam_exec.so seteuid /usr/lib/qubes/qrexec-client-vm dom0 qubes.VMAuth /bin/grep -q ^1$ + + - Require authentication for sudo. Replace the first line of /etc/sudoers.d/qubes with: + + user ALL=(ALL) ALL + + - Disable PolKit's default-allow behavior: + + [root@debian-8]# rm /etc/polkit-1/rules.d/00-qubes-allow-all.rules + [root@debian-8]# rm /etc/polkit-1/localauthority/50-local.d/qubes-allow-all.pkla + + - In /etc/pam.d/su, comment out this line near the bottom of the file: + + auth sufficient pam_permit.so + + - For Whonix, if prompts appear during boot, create /etc/sudoers.d/zz99 and add these lines: + + ALL ALL=NOPASSWD: /usr/sbin/virt-what + ALL ALL=NOPASSWD: /usr/sbin/service whonixcheck restart + ALL ALL=NOPASSWD: /usr/sbin/service whonixcheck start + ALL ALL=NOPASSWD: /usr/sbin/service whonixcheck stop + ALL ALL=NOPASSWD: /usr/sbin/service whonixcheck status + Dom0 password-less root access ------------------------------ diff --git a/services/admin-api.md b/services/admin-api.md new file mode 100644 index 00000000..53d19bad --- /dev/null +++ b/services/admin-api.md @@ -0,0 +1,308 @@ +--- +layout: doc-full +title: Admin API +permalink: /doc/admin-api/ +redirect_from: +- /doc/mgmt/ +- /doc/mgmt1/ +- /doc/mgmt-architecture/ +- /doc/admin-api-architecture/ +--- + +# Qubes OS Admin API + +*(This page is the current draft of the proposal. It is not implemented yet.)* + +## Goals + +The goals of the Admin API system is to provide a way for the user to manage +the domains without direct access to dom0. + +Foreseen benefits include: + +- Ability to remotely manage the Qubes OS. +- Possibility to create multi-user system, where different users are able to use + different sets of domains, possibly overlapping. This would also require to + have separate GUI domain. + +The API would be used by: + +- Qubes OS Manager (or any tools that would replace it) +- CLI tools, when run from another VM (and possibly also from dom0) +- remote management tools +- any custom tools + +## Threat model + +TBD + +## Components + +![Admin API Architecture][admin-api-architecture] + +A central entity in the Qubes Admin API system is a `qubesd` daemon, which +holds information about all domains in the system and mediates all actions (like +starting and stopping a qube) with `libvirtd`. The `qubesd` daemon also manages +the `qubes.xml` file, which stores all persistent state information and +dispatches events to extensions. Last but not least, `qubesd` is responsible for +querying the RPC policy for qrexec daemon. + +The `qubesd` daemon may be accessed from other domains through a set of qrexec +API calls called the "Admin API". This API is the intended +management interface supported by the Qubes OS. The API is stable. When called, +the RPC handler performs basic validation and forwards the request to the +`qubesd` via UNIX domain socket. The socket API is private and unstable. It is +documented [FIXME currently it isn't -- woju 20161221] in the developer's +documentation of the source code. + +## The calls + +The API should be implemented as a set of qrexec calls. This is to make it easy +to set the policy using current mechanism. + +| call | dest | argument | inside | return | note | +| ------------------------------------- | --------- | --------- | ----------------------------------------- | --------------------------------------------------------- | ---- | +| `admin.vmclass.List` | `dom0` | - | - | `<class>\n` | +| `admin.vm.List` | `dom0|<vm>` | - | - | `<name> class=<class> state=<state>\n` | +| `admin.vm.Create.<class>` | `dom0` | template | `name=<name> label=<label>` | - | +| `admin.vm.CreateInPool.<class>` | `dom0` | template | `name=<name> label=<label> `<br/>`pool=<pool> pool:<volume>=<pool>` | - | either use `pool=` to put all volumes there, <br/>or `pool:<volume>=` for individual volumes - both forms are not allowed at the same time +| `admin.vm.CreateTemplate` | `dom0` | name | `root.img` | - | +| `admin.vm.Remove` | vm | - | - | - | +| `admin.label.List` | `dom0` | - | - | `<property>\n` | +| `admin.label.Create` | `dom0` | label | `0xRRGGBB` | - | +| `admin.label.Get` | `dom0` | label | - | `0xRRGGBB` | +| `admin.label.Index` | `dom0` | label | - | `<label-index>` | +| `admin.label.Remove` | `dom0` | label | - | - | +| `admin.property.List` | `dom0` | - | - | `<property>\n` | +| `admin.property.Get` | `dom0` | property | - | `default={True|False} `<br/>`type={str|int|bool|vm|label} <value>` | +| `admin.property.Help` | `dom0` | property | - | `help` | +| `admin.property.HelpRst` | `dom0` | property | - | `help.rst` | +| `admin.property.Reset` | `dom0` | property | - | - | +| `admin.property.Set` | `dom0` | property | value | - | +| `admin.vm.property.List` | vm | - | - | `<property>\n` | +| `admin.vm.property.Get` | vm | property | - | `default={True|False} `<br/>`type={str|int|bool|vm|label} <value>` | +| `admin.vm.property.Help` | vm | property | - | `help` | +| `admin.vm.property.HelpRst` | vm | property | - | `help.rst` | +| `admin.vm.property.Reset` | vm | property | - | - | +| `admin.vm.property.Set` | vm | property | value | - | +| `admin.vm.feature.List` | vm | - | - | `<feature>\n` | +| `admin.vm.feature.Get` | vm | feature | - | value | +| `admin.vm.feature.CheckWithTemplate` | vm | feature | - | value | +| `admin.vm.feature.Remove` | vm | feature | - | - | +| `admin.vm.feature.Set` | vm | feature | value | - | +| `admin.vm.tag.List` | vm | - | - | `<tag>\n` | +| `admin.vm.tag.Get` | vm | tag | - | `0` or `1` | retcode? | +| `admin.vm.tag.Remove` | vm | tag | - | - | +| `admin.vm.tag.Set` | vm | tag | - | - | +| `admin.vm.firewall.Get` | vm | - | - | `<rule>\n` | rules syntax as in [firewall interface](/doc/vm-interface/#firewall-rules-in-4x) with addition of `expire=` and `comment=` options; `comment=` (if present) must be the last option +| `admin.vm.firewall.Set` | vm | - | `<rule>\n` | - | set firewall rules, see `admin.vm.firewall.Get` for syntax +| `admin.vm.firewall.Reload` | vm | - | - | - | force reload firewall without changing any rule +| `admin.vm.device.<class>.Attach` | vm | device | options | - | `device` is in form `<backend-name>+<device-ident>` <br/>optional options given in `key=value` format, separated with spaces; <br/>options can include `persistent=yes` to "persistently" attach the device (default is temporary) +| `admin.vm.device.<class>.Detach` | vm | device | - | - | `device` is in form `<backend-name>+<device-ident>` +| `admin.vm.device.<class>.List` | vm | - | - | `<device> <options>\n` | options can include `persistent=yes` for "persistently" attached devices (default is temporary) +| `admin.vm.device.<class>.Available` | vm | device-ident | - | `<device-ident> <properties> description=<desc>\n` | optional service argument may be used to get info about a single device, <br/>optional (device class specific) properties are in `key=value` form, <br/>`description` must be the last one and is the only one allowed to contain spaces +| `admin.pool.List` | `dom0` | - | - | `<pool>\n` | +| `admin.pool.ListDrivers` | `dom0` | - | - | `<pool-driver> <property> ...\n` | Properties allowed in `admin.pool.Add` +| `admin.pool.Info` | `dom0` | pool | - | `<property>=<value>\n` | +| `admin.pool.Add` | `dom0` | driver | `<property>=<value>\n` | - | +| `admin.pool.Remove` | `dom0` | pool | - | - | +| `admin.pool.volume.List` | `dom0` | pool | - | volume id | +| `admin.pool.volume.Info` | `dom0` | pool | vid | `<property>=<value>\n` | +| `admin.pool.volume.ListSnapshots` | `dom0` | pool | vid | `<snapshot>\n` | +| `admin.pool.volume.Snapshot` | `dom0` | pool | vid | snapshot | +| `admin.pool.volume.Revert` | `dom0` | pool | `<vid> <snapshot>` | - | +| `admin.pool.volume.Resize` | `dom0` | pool | `<vid> <size_in_bytes>` | - | +| `admin.pool.volume.Import` | `dom0` | pool | `<vid>\n<raw volume data>` | - | +| `admin.pool.volume.CloneFrom` | `dom0` | pool | vid | token, to be used in `admin.pool.volume.CloneTo` | obtain a token to copy volume `vid` in `pool`;<br/>the token is one time use only, it's invalidated by `admin.pool.volume.CloneTo`, even if the operation fails | +| `admin.pool.volume.CloneTo` | `dom0` | pool | `<vid> <token>` | - | copy volume pointed by a token to volume `vid` in `pool` | +| `admin.vm.volume.List` | vm | - | - | `<volume>\n` | `<volume>` is per-VM volume name (`root`, `private`, etc), `<vid>` is pool-unique volume id +| `admin.vm.volume.Info` | vm | volume | - | `<property>=<value>\n` | +| `admin.vm.volume.ListSnapshots` | vm | volume | - | snapshot | duplicate of `admin.pool.volume.`, but with other call params | +| `admin.vm.volume.Snapshot` | vm | volume | - | snapshot | id. | +| `admin.vm.volume.Revert` | vm | volume | snapshot | - | id. | +| `admin.vm.volume.Resize` | vm | volume | size_in_bytes | - | id. | +| `admin.vm.volume.Import` | vm | volume | raw volume data | - | id. | +| `admin.vm.volume.CloneFrom` | vm | volume | - | token, to be used in `admin.vm.volume.CloneTo` | obtain a token to copy `volume` of `vm`;<br/>the token is one time use only, it's invalidated by `admin.vm.volume.CloneTo`, even if the operation fails | +| `admin.vm.volume.CloneTo` | vm | volume | token, obtained with `admin.vm.volume.CloneFrom` | - | copy volume pointed by a token to `volume` of `vm` | +| `admin.vm.Start` | vm | - | - | - | +| `admin.vm.Shutdown` | vm | - | - | - | +| `admin.vm.Pause` | vm | - | - | - | +| `admin.vm.Unpause` | vm | - | - | - | +| `admin.vm.Kill` | vm | - | - | - | +| `admin.backup.Execute` | `dom0` | config id | - | - | config in `/etc/qubes/backup/<id>.conf`, only one backup operation of given `config id` can be running at once | +| `admin.backup.Info` | `dom0` | config id | - | backup info | info what would be included in the backup +| `admin.Events` | `dom0|vm` | - | - | events | + +Volume properties: + + - `pool` + - `vid` + - `size` + - `usage` + - `rw` + - `internal` + - `source` + - `save_on_stop` + - `snap_on_start` + + +## Returned messages + +First byte of a message is a message type. This is 8 bit non-zero integer. +Values start at 0x30 (48, `'0'`, zero digit in ASCII) for readability in hexdump. +Next byte must be 0x00 (a separator). + +This alternatively can be thought of as zero-terminated string containing +single ASCII digit. + +### OK (0) + +``` +30 00 <content> +``` + +Server will close the connection after delivering single message. + +### EVENT (1) + +``` +31 00 <subject> 00 <event> 00 ( <key> 00 <value> 00 )* 00 +``` + +Events are returned as stream of messages in selected API calls. Normally server +will not close the connection. + +A method yielding events will not ever return a `OK` or `EXCEPTION` message. + +When calling such method, it will produce an artificial event +`connection-established` just after connection, to help avoiding race +conditions during event handler registration. + +### EXCEPTION (2) + +``` +32 00 <type> 00 ( <traceback> )? 00 <format string> 00 ( <field> 00 )* +``` + +Server will close the connection. + +Traceback may be empty, can be enabled server-side as part of debug mode. +Delimiting zero-byte is always present. + +Fields are should substituted into `%`-style format string, possibly after +client-side translation, to form final message to be displayed unto user. Server +does not by itself support translation. + +## Tags + +The tags provided can be used to write custom policies. They are not used in +a default Qubes OS installation. However, they are created anyway. + +- `created-by-<vm>` — Created in an extension to qubesd at the + moment of creation of the VM. Cannot be changed via API, which is also + enforced by this extension. +- `managed-by-<vm>` — Can be used for the same purpose, but it is + not created automatically, nor is it forbidden to set or reset this tag. + +## Backup profile + +Backup-related calls do not allow (yet) to specify what should be included in +the backup. This needs to be configured separately in dom0, with a backup +profile, stored in `/etc/qubes/backup/<profile>.conf`. The file use yaml syntax +and have following settings: + +- `include` - list of VMs to include, can also contains tags using + `$tag:some-tag` syntax or all VMs of given type using `$type:AppVM`, known + from qrexec policy +- `exclude` - list of VMs to exclude, after evaluating `include` setting +- `destination_vm` - VM to which the backup should be send +- `destination_path` - path to which backup should be written in + `destination_vm`. This setting is given to `qubes.Backup` service and + technically it's up to it how to interpret it. In current implementation it is + interpreted as a directory where a new file should be written (with a name + based on the current timestamp), or a command where the backup should + be piped to +- `compression` - should the backup be compressed (default: True)? The value can be either + `False` or `True` for default compression, or a compression command (needs to + accept `-d` argument for decompression) +- `passphrase_text` - passphrase used to encrypt and integrity protect the backup +- `passphrase_vm` - VM which should be asked what backup passphrase should be + used. The asking is performed using `qubes.BackupPassphrase+profile_name` + service, which is expected to output chosen passphrase to its stdout. Empty + output cancel the backup operation. This service can be used either to ask + the user interactively, or to have some automated passphrase handling (for + example: generate randomly, then encrypt with a public key and send + somewhere) + +Not all settings needs to be set. + +Example backup profile: + +```yaml +# Backup only selected VMs +include: + - work + - personal + - vault + - banking + +# Store the backup on external disk +destination_vm: sys-usb +destination_path: /media/my-backup-disk + +# Use static passphrase +passphrase_text: "My$Very!@Strong23Passphrase" +``` + +And slightly more advanced one: + +```yaml +# Include all VMs with a few exceptions +include: + - $type:AppVM + - $type:TemplateVM + - $type:StandaloneVM +exclude: + - untrusted + - $tag:do-not-backup + +# parallel gzip for faster backup +compression: pigz + +# ask 'vault' VM for the backup passphrase +passphrase_vm: vault + +# send the (encrypted) backup directly to remote server +destination_vm: sys-net +destination_path: ncftpput -u my-ftp-username -p my-ftp-pass -c my-ftp-server /directory/for/backups +``` + +## General notes + +- there is no provision for `qvm-run`, but there already exists `qubes.VMShell` call +- generally actions `*.List` return a list of objects and have "object + identifier" as first word in a row. Such action can be also called with "object + identifier" in argument to get only a single entry (in the same format). +- closing qrexec connection normally does _not_ interrupt running operation; this is important to avoid leaving the system in inconsistent state +- actual operation starts only after caller send all the parameters (including a payload), signaled by sending EOF mark; there is no support for interactive protocols, to keep the protocol reasonable simple + +## TODO + +- something to configure/update policy +- notifications + - how to constrain the events? + - how to pass the parameters? maybe XML, since this is trusted anyway and + parser may be complicated +- how to constrain the possible values for `admin.vm.property.Set` etc, like + "you can change `netvm`, but you have to pick from this set"; this currently + can be done by writing an extension +- a call for executing `*.desktop` file from `/usr/share/applications`, for use + with appmenus without giving access to `qubes.VMShell`; currently this can be + done by writing custom qrexec calls +- maybe some generator for `.desktop` for appmenus, which would wrap calls in + `qrexec-client-vm` + +<!-- vim: set ts=4 sts=4 sw=4 et : --> + +[admin-api-architecture]: /attachment/wiki/AdminAPI/admin-api-architecture.svg + diff --git a/developers/services/dom0-secure-updates.md b/services/dom0-secure-updates.md similarity index 100% rename from developers/services/dom0-secure-updates.md rename to services/dom0-secure-updates.md diff --git a/developers/services/dvm-impl.md b/services/dvm-impl.md similarity index 100% rename from developers/services/dvm-impl.md rename to services/dvm-impl.md diff --git a/developers/services/qfilecopy.md b/services/qfilecopy.md similarity index 100% rename from developers/services/qfilecopy.md rename to services/qfilecopy.md diff --git a/developers/services/qfileexchgd.md b/services/qfileexchgd.md similarity index 100% rename from developers/services/qfileexchgd.md rename to services/qfileexchgd.md diff --git a/developers/services/qmemman.md b/services/qmemman.md similarity index 97% rename from developers/services/qmemman.md rename to services/qmemman.md index 499d3bf4..471acb95 100644 --- a/developers/services/qmemman.md +++ b/services/qmemman.md @@ -16,7 +16,7 @@ Rationale Traditionally, Xen VMs are assigned a fixed amount of memory. It is not the optimal solution, as some VMs may require more memory than assigned initially, while others underutilize memory. Thus, there is a need for solution capable of shifting free memory from VM to another VM. -The [tmem](http://oss.oracle.com/projects/tmem/) project provides a "pseudo-RAM" that is assigned on per-need basis. However this solution has some disadvantages: +The [tmem](https://oss.oracle.com/projects/tmem/) project provides a "pseudo-RAM" that is assigned on per-need basis. However this solution has some disadvantages: - It does not provide real RAM, just an interface to copy memory to/from fast, RAM-based storage. It is perfect for swap, good for file cache, but not ideal for many tasks. - It is deeply integrated with the Linux kernel. When Qubes will support Windows guests natively, we would have to port *tmem* to Windows, which may be challenging. diff --git a/developers/services/qrexec2.md b/services/qrexec2.md similarity index 99% rename from developers/services/qrexec2.md rename to services/qrexec2.md index a26e693f..d9f7bdc6 100644 --- a/developers/services/qrexec2.md +++ b/services/qrexec2.md @@ -216,7 +216,7 @@ appear after the invocation of this command. If we changed the policy from be allowed. **Note:** For a real world example of writing a qrexec service, see this -[blog post](http://theinvisiblethings.blogspot.com/2013/02/converting-untrusted-pdfs-into-trusted.html). +[blog post](https://blog.invisiblethings.org/2013/02/21/converting-untrusted-pdfs-into-trusted.html). ### More high-level RPCs? ### diff --git a/developers/services/qrexec3.md b/services/qrexec3.md similarity index 90% rename from developers/services/qrexec3.md rename to services/qrexec3.md index 62cb43d9..8227eff0 100644 --- a/developers/services/qrexec3.md +++ b/services/qrexec3.md @@ -105,15 +105,24 @@ In dom0, there is a bunch of files in `/etc/qubes-rpc/policy` directory, whose names describe the available rpc actions. Their content is the rpc access policy database. Currently defined actions are: + qubes.ClipboardPaste qubes.Filecopy + qubes.GetImageRGBA + qubes.GetRandomizedTime + qubes.Gpg + qubes.GpgImportKey + qubes.InputKeyboard + qubes.InputMouse + qubes.NotifyTools + qubes.NotifyUpdates qubes.OpenInVM + qubes.OpenURL + qubes.PdfConvert qubes.ReceiveUpdates qubes.SyncAppMenus + qubes.USB qubes.VMShell - qubes.ClipboardPaste - qubes.Gpg - qubes.NotifyUpdates - qubes.PdfConvert + qubes.WindowIconUpdater These files contain lines with the following format: @@ -127,10 +136,12 @@ means "new VM created for this particular request," so it is never a source of request). Currently there is no way to specify source VM by type. Whenever a rpc request for action X is received, the first line in `/etc/qubes-rpc/policy/X` that match srcvm/destvm is consulted to determine -whether to allow rpc, what user account the program should run in target -VM under, and what VM to redirect the execution to. If the policy file does -not exits, user is prompted to create one; if still there is no policy file -after prompting, the action is denied. +whether to allow rpc, what user account the program should run in target VM +under, and what VM to redirect the execution to. Note that if the request is +redirected (`target=` parameter), policy action remains the same - even if +there is another rule which would otherwise deny such request. If the policy +file does not exits, user is prompted to create one; if still there is no +policy file after prompting, the action is denied. In the target VM, the `/etc/qubes-rpc/RPC_ACTION_NAME` must exist, containing the file name of the program that will be invoked, or being that program itself @@ -153,16 +164,51 @@ Be very careful when coding and adding a new rpc service. Unless the offered functionality equals full control over the target (it is the case with e.g. `qubes.VMShell` action), any vulnerability in a rpc server can be fatal to Qubes security. On the other hand, this mechanism allows to -delegate processing of untrusted input to less privileged (or throwaway) +delegate processing of untrusted input to less privileged (or disposable) AppVMs, thus wise usage of it increases security. +### Extra keywords available in Qubes 4.0 and later + +**This section is about not yet released version, some details may change** + +In Qubes 4.0, target VM can be specified also as `$dispvm:DISP_VM`, which is +very similar to `$dispvm` but force using particular VM (`DISP_VM`) as a base +VM to be started as Disposable VM. For example: + + anon-whonix $dispvm:anon-whonix-dvm allow + +Adding such policy itself will not force usage of this particular `DISP_VM` - +it will only allow it when specified by the caller. But `$dispvm:DISP_VM` can +also be used as target in request redirection, so _it is possible_ to force +particular `DISP_VM` usage, when caller didn't specified it: + + anon-whonix $dispvm allow,target=$dispvm:anon-whonix-dvm + +Note that without redirection, this rule would allow using default Disposable +VM (`default_dispvm` VM property, which itself defaults to global +`default_dispvm` property). +Also note that the request will be allowed (`allow` action) even if there is no +second rule allowing calls to `$dispvm:anon-whonix-dvm`, or even if +there is a rule explicitly denying it. This is because the redirection happen +_after_ considering the action. + +In Qubes 4.0 there are also additional methods to specify source/target VM: + + * `$tag:some-tag` - meaning a VM with tag `some-tag` + * `$type:type` - meaning a VM of `type` (like `AppVM`, `TemplateVM` etc) + +Target VM can be also specified as `$default`, which matches the case when +calling VM didn't specified any particular target (either by using `$default` +target, or empty target). + ### Service argument in policy Sometimes just service name isn't enough to make reasonable qrexec policy. One example of such situation is [qrexec-based USB -passthrough](https://github.com/qubesos/qubes-issues/531) - using just service -name it isn't possible to express policy "allow access to device X and deny to -others". It isn't also feasible to create separate service for every device... +passthrough](https://github.com/qubesos/qubes-issues/issues/531) - using just +service name it isn't possible to express policy "allow access to device X and +deny to others". It isn't also feasible to create separate service for every +device... For this reason, starting with Qubes 3.2, it is possible to specify service argument, which will be subject to policy. Besides above example of USB @@ -240,7 +286,7 @@ on the target and returns back the result to the invoker. and we should get "3" as answer, after dom0 allows it. **Note:** For a real world example of writing a qrexec service, see this -[blog post](http://theinvisiblethings.blogspot.com/2013/02/converting-untrusted-pdfs-into-trusted.html). +[blog post](https://blog.invisiblethings.org/2013/02/21/converting-untrusted-pdfs-into-trusted.html). ### Qubes RPC example - with argument usage ### diff --git a/developers/fundamentals/architecture.md b/system/architecture.md similarity index 100% rename from developers/fundamentals/architecture.md rename to system/architecture.md diff --git a/developers/fundamentals/gui.md b/system/gui.md similarity index 73% rename from developers/fundamentals/gui.md rename to system/gui.md index 6bec826f..6a365b03 100644 --- a/developers/fundamentals/gui.md +++ b/system/gui.md @@ -15,43 +15,50 @@ Qubes GUI protocol qubes_gui and qubes_guid processes ------------------------------------ -All AppVM X applications connect to local (running in AppVM) Xorg server, that uses the following "hardware" drivers: +All AppVM X applications connect to local (running in AppVM) Xorg servers that use the following "hardware" drivers: -- *dummy_drv* - video driver, that paints onto a framebuffer located in RAM, not connected to real hardware +- *dummyqsb_drv* - video driver, that paints onto a framebuffer located in RAM, not connected to real hardware - *qubes_drv* - it provides a virtual keyboard and mouse (in fact, more, see below) -For each AppVM, there is a pair of *qubes_gui* (running in AppVM) and *qubes_guid* (running in dom0) processes, connected over vchan. Main responsibilities of *qubes_gui* are: +For each AppVM, there is a pair of *qubes_gui* (running in AppVM) and *qubes_guid* (running in dom0) processes connected over vchan. +The main responsibilities of *qubes_gui* are: - call XCompositeRedirectSubwindows on the root window, so that each window has its own composition buffer - instruct the local Xorg server to notify it about window creation, configuration and damage events; pass information on these events to dom0 - receive information about keyboard and mouse events from dom0, tell *qubes_drv* to fake appropriate events - receive information about window size/position change, apply them to the local window -Main responsibilities of *qubes_guid* are: +The main responsibilities of *qubes_guid* are: - create a window in dom0 whenever an information on window creation in AppVM is received from *qubes_gui* - whenever the local window receives XEvent, pass information on it to AppVM (particularly, mouse and keyboard data) - whenever AppVM signals damage event, tell local Xorg server to repaint a given window fragment - receive information about window size/position change, apply them to the local window -Note that keyboard and mouse events are passed to AppVM only if a window belonging to this AppVM has focus. AppVM has no way to get information on keystrokes fed to other AppVMs (e.g. XTEST extension will report the status of local AppVM keyboard only), nor synthesize and pass events to other AppVMs. +Note that keyboard and mouse events are passed to AppVM only if a window belonging to this AppVM has focus. +AppVM has no way to get information on keystrokes fed to other AppVMs (e.g. XTEST extension will report the status of local AppVM keyboard only) or synthesize and pass events to other AppVMs. Window content updates implementation ------------------------------------- -Typical remote desktop applications, like *vnc*, pass the information on all changed window content in-band (say, over tcp). As the channel has limited throughput, this impacts video performance. In case of Qubes, *qubes_gui* does not transfer all changed pixels via vchan. Instead, for each window, upon its creation or size change, *qubes_gui* +Typical remote desktop applications, like *vnc*, pass information on all changed window content in-band (say, over tcp). +As that channel has limited throughput, this impacts video performance. +In case of Qubes, *qubes_gui* does not transfer all changed pixels via vchan. Instead, for each window, upon its creation or size change, *qubes_gui* - asks *qubes_drv* driver for the list of physical memory frames that hold the composition buffer of a window -- pass this information via `MFNDUMP` message to *qubes_guid* in dom0 +- passes this information via `MFNDUMP` message to *qubes_guid* in dom0 -Now, *qubes_guid* has to tell dom0 Xorg server about the location of the buffer. There is no supported way (e.g. Xorg extension) to do this zero-copy style. The following method is used in Qubes: +Now, *qubes_guid* has to tell the dom0 Xorg server about the location of the buffer. +There is no supported way (e.g. Xorg extension) to do this zero-copy style. +The following method is used in Qubes: - in dom0, the Xorg server is started with *LD_PRELOAD*-ed library named *shmoverride.so*. This library hooks all function calls related to shared memory. - *qubes_guid* creates a shared memory segment, and then tells Xorg to attach it via *MIT-SHM* extension -- when Xorg tries to attach the segment (via glibc *shmat*) *shmoverride.so* intercepts this call and instead maps AppVM memory via *xc_map_foreign_range* +- when Xorg tries to attach the segment (via glibc *shmat*) *shmoverride.so* intercepts this call and instead maps AppVM memory via *xc_map_foreign_pages* - since then, we can use MIT-SHM functions, e.g. *XShmPutImage* to draw onto a dom0 window. *XShmPutImage* will paint with DRAM speed; actually, many drivers use DMA for this. -The important detail is that *xc_map_foreign_range* verifies that a given mfn range actually belongs to a given domain id (and the latter is provided by trusted *qubes_guid*). Therefore, rogue AppVM cannot gain anything by passing crafted mnfs in the `MFNDUMP` message. +The important detail is that *xc_map_foreign_pages* verifies that a given mfn range actually belongs to a given domain id (and the latter is provided by trusted *qubes_guid*). +Therefore, rogue AppVM cannot gain anything by passing crafted mnfs in the `MFNDUMP` message. To sum up, this solution has the following benefits: @@ -64,45 +71,49 @@ To sum up, this solution has the following benefits: Security markers on dom0 windows -------------------------------- -It is important that user knows which AppVM a given window belongs to. This prevents an attack when a rogue AppVM paints a window pretending to belong to other AppVM or dom0, and tries to steal e.g. passwords. +It is important that user knows which AppVM a given window belongs to. This prevents a rogue AppVM from painting a window pretending to belong to other AppVM or dom0 and trying to steal, for example, passwords. -In Qubes, the custom window decorator is used, that paints a colourful frame (the colour is determined during AppVM creation) around decorated windows. Additionally, window title always starts with **[name of the AppVM]**. If a window has a *override_redirect* attribute, meaning that it should not be treated by a window manager (typical case is menu windows), *qubes_guid* draws a two-pixel colourful frame around it manually. +In Qubes, a custom window decorator is used that paints a colourful frame (the colour is determined during AppVM creation) around decorated windows. Additionally, the window title always starts with **[name of the AppVM]**. If a window has a *override_redirect* attribute, meaning that it should not be treated by a window manager (typical case is menu windows), *qubes_guid* draws a two-pixel colourful frame around it manually. Clipboard sharing implementation -------------------------------- -Certainly, it would be insecure to allow AppVM to read/write clipboard of other AppVMs unconditionally. Therefore, the following mechanism is used: +Certainly, it would be insecure to allow AppVM to read/write the clipboards of other AppVMs unconditionally. +Therefore, the following mechanism is used: - there is a "qubes clipboard" in dom0 - its contents is stored in a regular file in dom0. - if user wants to copy local AppVM clipboard to qubes clipboard, she must focus on any window belonging to this AppVM, and press **Ctrl-Shift-C**. This combination is trapped by *qubes-guid*, and `CLIPBOARD_REQ` message is sent to AppVM. *qubes-gui* responds with *CLIPBOARD_DATA* message followed by clipboard contents. - user focuses on other AppVM window, presses **Ctrl-Shift-V**. This combination is trapped by *qubes-guid*, and `CLIPBOARD_DATA` message followed by qubes clipboard contents is sent to AppVM; *qubes_gui* copies data to the local clipboard, and then user can paste its contents to local applications normally. -This way, user can quickly copy clipboards between AppVMs. This action is fully controlled by the user, it cannot be triggered/forced by any AppVM. +This way, user can quickly copy clipboards between AppVMs. +This action is fully controlled by the user, it cannot be triggered/forced by any AppVM. *qubes_gui* and *qubes_guid* code notes ----------------------------------------- -Both applications are structures similarly. They use *select* function to wait for any of the two event sources +Both applications are structured similarly. They use *select* function to wait for any of these two event sources: - messages from the local X server - messages from the vchan connecting to the remote party -The XEvents are handled by *handle_xevent_eventname* function, messages are handled by *handle_messagename* function. One should be very careful when altering the actual *select* loop - e.g. both XEvents and vchan messages are buffered, meaning that *select* will not wake for each message. +The XEvents are handled by the *handle_xevent_eventname* function, and messages are handled by *handle_messagename* function. One should be very careful when altering the actual *select* loop, because both XEvents and vchan messages are buffered, and *select* will not wake for each message. If one changes the number/order/signature of messages, one should increase the *QUBES_GUID_PROTOCOL_VERSION* constant in *messages.h* include file. -*qubes_guid* writes debugging information to */var/log/qubes/qubes.domain_id.log* file; *qubes_gui* writes debugging information to */var/log/qubes/gui_agent.log*. Include these files when reporting a bug. +*qubes_guid* writes debugging information to */var/log/qubes/qubes.domain_id.log* file; *qubes_gui* writes debugging information to */var/log/qubes/gui_agent.log*. +Include these files when reporting a bug. AppVM -> dom0 messages ----------------------- -Proper handling of the below messages is security-critical. Observe that beside two messages (`CLIPBOARD` and `MFNDUMP`) the rest have fixed size, so the parsing code can be small. +Proper handling of the below messages is security-critical. +Observe that beside two messages (`CLIPBOARD` and `MFNDUMP`) the rest have fixed size, so the parsing code can be small. -The *override_redirect* window attribute is explained at [Override Redirect Flag](http://tronche.com/gui/x/xlib/window/attributes/override-redirect.html). The *transient_for* attribute is explained at [Transient_for attribute](http://tronche.com/gui/x/icccm/sec-4.html#WM_TRANSIENT_FOR). +The *override_redirect* window attribute is explained at [Override Redirect Flag](https://tronche.com/gui/x/xlib/window/attributes/override-redirect.html). The *transient_for* attribute is explained at [Transient_for attribute](https://tronche.com/gui/x/icccm/sec-4.html#WM_TRANSIENT_FOR). -Window manager hints and flags are described at [http://standards.freedesktop.org/wm-spec/latest/](http://standards.freedesktop.org/wm-spec/latest/), especially part about `_NET_WM_STATE`. +Window manager hints and flags are described in the [Extended Window Manager Hints (EWMH) spec](https://standards.freedesktop.org/wm-spec/latest/), especially under the `_NET_WM_STATE` section. -Each message starts with the following header +Each message starts with the following header: ~~~ struct msghdr { @@ -117,7 +128,7 @@ struct msghdr { }; ~~~ -The header is followed by message-specific data. +This header is followed by message-specific data: <table class="table"> <tr> @@ -266,8 +277,7 @@ struct msghdr { }; ~~~ -The header is followed by message-specific data. - `KEYPRESS`, `BUTTON`, `MOTION`, `FOCUS` messages pass information extracted from dom0 XEvent; see appropriate event documentation. +The header is followed by message-specific data: <table class="table"> <tr> @@ -398,3 +408,5 @@ struct msg_window_flags { <td>Window state change confirmation</td> </tr> </table> + + `KEYPRESS`, `BUTTON`, `MOTION`, `FOCUS` messages pass information extracted from dom0 XEvent; see appropriate event documentation. diff --git a/system/networking.md b/system/networking.md new file mode 100644 index 00000000..9fce8984 --- /dev/null +++ b/system/networking.md @@ -0,0 +1,43 @@ +--- +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| + + diff --git a/developers/fundamentals/security-critical-code.md b/system/security-critical-code.md similarity index 99% rename from developers/fundamentals/security-critical-code.md rename to system/security-critical-code.md index c9fad6db..7fd9a5d2 100644 --- a/developers/fundamentals/security-critical-code.md +++ b/system/security-critical-code.md @@ -14,7 +14,7 @@ Security-Critical Code in Qubes OS Below is a list of security-critical (AKA trusted) code in Qubes OS. A successful attack against any of those might allow to compromise the Qubes OS security. This code can be thought of as of a Trusted Computing Base (TCB) of Qubes OS. The goal of the project has been to minimize the amount of this trusted code to an absolute minimum. The size of the current TCB is of an order of hundreds thousands of lines of C code, which is several orders of magnitude less than in other OSes, such as Windows, Linux or Mac, where it is of orders of tens of millions of lines of C code. -For more information about the security goals of Qubes OS, see [this page](/doc/security-goals/). +For more information about the security goals of Qubes OS, see [this page](/security/goals/). Security-Critical Qubes-Specific Components ------------------------------------------- diff --git a/system/storage-pools.md b/system/storage-pools.md new file mode 100644 index 00000000..250ec1c2 --- /dev/null +++ b/system/storage-pools.md @@ -0,0 +1,50 @@ +--- +layout: doc +title: Storage Pools +permalink: /doc/storage-pools/ +--- + +Storage Pools in Qubes +====================== + +Qubes OS R 3.2 introduced the concept of storage drivers & pools. This feature +was a first step towards a saner storage API, which is heavily rewritten in R4. +A storage driver provides a way to store VM images in a Qubes OS system. +Currently, the default driver is `xen` which is the default way of storing +volume images as files in a directory tree like `/var/lib/qubes/`. + +A pool storage driver can be identified either by the driver name with the +`driver` key or by the class name like this: +`class=qubes.storage.xen.XenStorage`. Because R3.2 doesn't use Python +`setup_hooks`, to actually use a short driver name for a custom storage driver, +you have to patch `qubes-core-admin`. You can use the `class` config key +instead, when your class is accessible by `import` in Python. + +A pool (in R3.2) is a configuration information which can be referenced when +creating a new VM. Each pool is saved in `storage.conf`. It has a name, a +storage driver and some driver specific configuration attached. + +When installed, the system has, as you can see from the content of +`/etc/qubes/storage.conf`, a pool named `default`. It uses the driver `xen`. The +default pool is special in R3.2. It will add `dir_path=/var/lib/qubes` +configuration value from `defaults[pool_config]`, if not overwritten. + + +Currently the only supported driver out of the box is `xen`. The benefit of +pools (besides that you can write an own storage driver e.g. for Btrfs) in R3.2 +is that you can store your domains in multiple places. + +You can add a pool to `storage.conf` like this: + +``` +[foo] +driver=xen +dir_path=/opt/qubes-vm +``` + +Now, when creating a new VM on the command-line, a you may pass the `-Pfoo` +argument to `qvm-create` to have the VM images stored in pool `foo`. See also +`qvm-create --help`. + +While the current API is not as clean and beautiful as the R4 API, it allows +you to write your own storage drivers e.g. for Btrfs today. diff --git a/developers/fundamentals/template-implementation.md b/system/template-implementation.md similarity index 100% rename from developers/fundamentals/template-implementation.md rename to system/template-implementation.md diff --git a/troubleshooting/install-nvidia-driver.md b/troubleshooting/install-nvidia-driver.md index fd768f11..f3b946e5 100644 --- a/troubleshooting/install-nvidia-driver.md +++ b/troubleshooting/install-nvidia-driver.md @@ -8,15 +8,27 @@ redirect_from: - /wiki/InstallNvidiaDriver/ --- -#Nvidia proprietary driver installation +# Nvidia proprietary driver installation You can use rpm packages from rpmfusion, or you can build the driver yourself. -##RpmFusion packages +## Word of Caution + +Proprietary (NVIDIA/AMD) drivers are known to be sometimes highly problematic, or completely unsupported. +Radeon driver support is prebaked in the Qubes kernel (v4.4.14-11) but only versions 4000-9000 give or take. +Support for newer cards is limited until AMDGPU support in the 4.5+ kernel, which isn't released yet for Qubes. + +Built in Intel graphics, Radeon graphics (between that 4000-9000 range), and perhaps some prebaked NVIDIA card support that i don't know about. Those are your best bet for great Qubes support. + +If you do happen to get proprietary drivers working on your Qubes system (via installing them). Please take the time to go to the +[Hardware Compatibility List (HCL)](https://www.qubes-os.org/doc/hcl/#generating-and-submitting-new-reports ) +Add your computer, graphics card, and installation steps you did to get everything working. + +## RpmFusion packages There are rpm packages with all necessary software on rpmfusion. The only package you have to compile is the kernel module (but there is a ready built src.rpm package). -###Download packages +### Download packages You will need any Fedora 18 system to download and build packages. You can use Qubes AppVM for it, but it isn't necessary. To download packages from rpmfusion - add this repository to your yum configuration (instructions are on their website). Then download packages using yumdownloader: @@ -25,7 +37,7 @@ yumdownloader --resolve xorg-x11-drv-nvidia yumdownloader --source nvidia-kmod ~~~ -###Build kernel package +### Build kernel package You will need at least kernel-devel (matching your Qubes dom0 kernel), rpmbuild tool and kmodtool, and then you can use it to build package: @@ -40,21 +52,21 @@ Then you need to disable nouveau (normally it is done by install scripts from nv Edit /etc/default/grub: - ~~~ - GRUB_CMDLINE_LINUX="quiet rhgb nouveau.modeset=0 rd.driver.blacklist=nouveau video=vesa:off" - ~~~ +~~~ +GRUB_CMDLINE_LINUX="quiet rhgb nouveau.modeset=0 rd.driver.blacklist=nouveau video=vesa:off" +~~~ Regenerate grub configuration: - ~~~ - grub2-mkconfig -o /boot/grub2/grub.cfg - ~~~ +~~~ +grub2-mkconfig -o /boot/grub2/grub.cfg +~~~ Reboot. -##Manual installation +## Manual installation This process is quite complicated: First - download the source from nvidia.com site. Here "NVIDIA-Linux-x86\_64-260.19.44.run" is used. Copy it to dom0. Every next step is done in dom0. @@ -64,7 +76,7 @@ See [this page](/doc/copy-to-dom0/) for instructions on how to transfer files to -###Userspace components +### Userspace components Install libraries, Xorg driver, configuration utilities. This can by done by nvidia-installer: @@ -72,7 +84,7 @@ Install libraries, Xorg driver, configuration utilities. This can by done by nvi ./NVIDIA-Linux-x86_64-260.19.44.run --ui=none --no-x-check --keep --no-nouveau-check --no-kernel-module ~~~ -###Kernel module +### Kernel module You will need: @@ -96,7 +108,7 @@ mv /lib/modules/2.6.34.1-12.xenlinux.qubes.x86_64/kernel/drivers/video/nvidia.ko Ignore any errors while inserting nvidia.ko (at the end of make phase). -###Disable nouveau: +### Disable nouveau: ~~~ cat /etc/modprobe.d/nouveau-disable.conf @@ -106,7 +118,7 @@ install nouveau /bin/true Add *rdblacklist=nouveau* option to /boot/grub/menu.lst (at the end of line containing *vmlinuz*). -###Configure Xorg +### Configure Xorg After all, you should configure Xorg to use nvidia driver. You can use *nvidia-xconfig* or do it manually: @@ -118,7 +130,7 @@ mv /root/xorg.conf.new /etc/X11/xorg.conf Reboot to verify all this works. -#Troubleshooting lack of video output during installation +# Troubleshooting lack of video output during installation Specifically, the notes below are aimed to help when the GRUB menu shows up fine, the installation environment starts loading, and then the display(s) go into standby mode. This is, typically, related to some sort of an issue with the kernel's KMS/video card modules. diff --git a/troubleshooting/lenovo450-tinkering.md b/troubleshooting/lenovo450-tinkering.md deleted file mode 100644 index 3a441c34..00000000 --- a/troubleshooting/lenovo450-tinkering.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -layout: doc -title: Lenovo450 Tinkering -permalink: /doc/lenovo450-tinkering/ -redirect_from: -- /en/doc/lenovo450-tinkering/ -- /doc/Lenovo450Tinkering/ -- /wiki/Lenovo450Tinkering/ ---- - -Instructions for getting your Lenovo 450 laptop working with Qubes/Linux -========================================================================= - -Lenovo 450 uses UEFI, so some settings are needed to get Qubes (or Fedora) to boot, otherwise Qubes install USB stick will reboot right after boot selector screen and not continue install. - -Setting UEFI options to get Qubes install to boot -------------------------------------------------- - -1. Enable Legacy USB mode -2. Disable all Secure Boot and UEFI options, but leave this enabled: Config / USB / USB UEFI BIOS SUPPORT -3. Save settings and reboot -5. Install Qubes - -... and now enjoy :) These settings may be needed also in other UEFI computers. diff --git a/troubleshooting/macbook-troubleshooting.md b/troubleshooting/macbook-troubleshooting.md new file mode 100644 index 00000000..e59c1648 --- /dev/null +++ b/troubleshooting/macbook-troubleshooting.md @@ -0,0 +1,325 @@ +--- +layout: doc +title: Apple MacBook Troubleshooting +permalink: /doc/macbook-troubleshooting/ +--- + +Apple MacBook Troubleshooting +============================= + +MacBook Air 13" mid 2011 (MacBookAir 4,2) +----------------------------------------- + +In this section, I explain how to install Qubes on a MacBook Air 13" mid 2011 +(MacBookAir 4,2). + +This model has the following features: + +* Dual Intel i7-2677M 1.80 Ghz CPU (2 dual cores) +* Intel HD Graphics 3000 +* 4Gb RAM +* 256Gb SDD +* Broadcom BCM43224 802.11 a/b/g/n wifi and Bluetooth adapter +* Intel DSL2310 Thunderbolt controller +* It has 1 DVI/Thunderbolt display port, 2 USB2.0 ports, a Magsafe power + adapter, a standard 3.5mm audio jack and SD reader. + +I first tried to install Qubes using the UEFI boot, but it failed. Not wanting +to waste too much time, I quickly opted for the legacy BIOS install. + +### 1. Boot from Mac OS X (or Internet Recovery Image with `CMD`+`R` during bootup) + +Run in a terminal [[1]]: + +~~~ +# diskutil list +(find your usb device) +# bless –device /dev/diskX –legacy –setBoot –nextonly # bless the disk not the partition +# reboot +~~~ + +Insert your Qubes 3.2 USB flash drive. The ISOLINUX boot screen should come up. +Install Qubes normally. + +If you try to boot Qubes now, it will freeze while "setting up networking." You +need to put the Broadcom wireless device into PCI passtrough [[2],[3]]. Or, as +an alternative [remove it from your Mac][bluetooth-replacement] and Qubes will +boot up smoothly. If you choose to remove the card, jump to step 3. + +### 2. Boot from Mac OS X again + +Run in a terminal: + +~~~ +# diskutil list +(find your usb device) +# bless –device /dev/diskX –legacy –setBoot –nextonly # bless the disk not the partition +# reboot +~~~ + +Insert your Qubes 3.2 USB flash drive. The ISOLINUX boot screen should come up. +Select Troubleshooting and Boot the Rescue image. Enter your disk password when +prompted. Select continue and after mounting the HD filesystem and launching a +shell, `chroot` as instructed. + +Then find your Bluetooth card: + +~~~ +# lspci +.. +02:00.0 Network controller: Broadcom Corporation BCM43224 802.11a/b/g/n (rev 01) +… +# qvm-pci -a sys-net 02:00.0 # this assigns the device to sys-net VM +~~~ + +Then create `/etc/systemd/system/qubes-pre-netvm.service` with: + +~~~ +[Unit] +Description=Netvm fix for Broadcom +Before=qubes-netvm.service + +[Service] +ExecStart=/bin/sh -c 'echo 02:00.0 > /sys/bus/pci/drivers/pciback/permissive' +Type=oneshot +RemainAfterExit=yes + +[Install] +WantedBy=multi-user.target +~~~ + +Run: + +~~~ +systemctl enable qubes-pre-netvm.service +~~~ + +And that's it. + +### 3. After reboot, boot Mac OS X again + +Run in a terminal: + +~~~ +# diskutil list +(find the HD device where you installed Qubes) +# bless –device /dev/diskX –legacy –setBoot # bless the disk not the partition +# reboot +~~~ + +Results: + +* System booted and running smoothly +* Youtube video: OK (including full screen after configuration) +* Trackpad: OK +* Audio control: OK +* Brightness control: OK +* Keyboard light control:OK +* SD card access: OK (tested at dom0) +* Lid-close suspend: OK +* Wifi: +10%-20% ICMP packet loss when comparing with OSX (have similar rates + with tails Linux, more tests are required) + +### References + +1. <https://github.com/QubesOS/qubes-issues/issues/794> +2. <https://github.com/QubesOS/qubes-issues/issues/1261> +3. <https://www.qubes-os.org/doc/assigning-devices/> + + +MacBook Air 2012 (MacBookAir 5,1) +--------------------------------- + +Please see [this thread o the qubes-devel mailing list][macbook-air-2012-5-1]. + + +[1]: https://github.com/QubesOS/qubes-issues/issues/794 +[2]: https://github.com/QubesOS/qubes-issues/issues/1261 +[3]: https://www.qubes-os.org/doc/assigning-devices/ +[bluetooth-replacement]: https://www.ifixit.com/Guide/MacBook+Air+13-Inch+Mid+2011+AirPort-Bluetooth+Card+Replacement/6360 +[macbook-air-2012-5-1]: https://groups.google.com/d/topic/qubes-devel/uLDYGdKk_Dk/discussion + + + +MacBook Pro Retina, 15 inch, Mid-2015 (MacBookPro 11,5) +------------------------------------------------------- + +In this section, I explain how I installed Qubes 3.2 on a MacBook Pro Retina 2015 (MacBookPro 11,5). +Good news: the relevant stuff works. +Bad news: still some minor issue to investigate. + +For the time being, my setup is just for testing purposes and help to bypass some blocking issues: do not use it in production or on machine where security is a concern! +I hope to improve it as soon as possible. + +During my nigths trying to get Qubes OS working, I faced tow main and blocking issues: +* no boot, due to empty xen.cfg file +* system freeze, due to Broadcom BCM43602 wifi card + +I am already using Qubes for my daily job on Intel NUC. For the time being, I installed Qubes on Macbook for test purposes. Later on I will review the security implications. + +This model has the following features: + +* 2,5 GHz Intel Core i7-4870HQ (2 quad cores) +* Dual Graphic Card + * Intel Iris Pro + * AMD Radeon R9 M370X +* 16Gb RAM +* 512Gb SDD +* Broadcom BCM43602 802.11ac wifi adapter + +### 1. Reclaim space to be able to multiboot OSX + +For security reasons, you should install Qubes using the whole disk. I preferred to keep OSX, so I shrunk OS partition: +* reboot in recovery mode +* run disk utility and shrink OSX partition, eg 150GB for OSX and the remaining space for Qubes OS +* reboot + + +### 2. Boot installer + +Download and prepare a USB with Qubes 3.2 + +You can install Qubes using BIOS or UEFI: +* BIOS/CSM/Legacy: I have not been able to install using legagy, but I did not spent a lot of time on it. +* UEFI plain: grub menu appears, but any gave me a quick flash and returned the main menu. I can boot it manually fixing the grub.cfg file, adding commands linuexefi and initrdefi, pointing proper files in /efi/boot. After boot, I end up with not root file system. +* UEFI, using rEFInd: I have been successful, despite some issues to be fixed manually, after installation completion + * download [rEFInd] refind-bin-0.10.4.zip: this file is not signed, so decide if you trust it or not. SHA1 sum is 3d69c23b7d338419e5559a93cd6ae3ec66323b1e + * unzip it and run installer, which install rEFIind on the internal SSD + * if installation fails due to SIP, reboot in recovery mode, open a terminal and issue command + ~~~ + crsutil disable + ~~~ + * reboot and you will see some icons + * choose Boot EFI\BOOT\xen.efi from ANACONDA + * after a will the graphical installer is up and running, with keyboard and touchpad working + +### 3. Installation + +* As a general rule, keep the default values proposed during installation: you will change them later on +* Keep English, as language, locale +* My macbook has a US keyboard, so I cannot say what happens if you change keyboard layout +* DO NOT CHANGE the timezone, because it will trigger the wifi card, leading to a system freeze +* Choose the "installation destination": do not change anything and press DONE button +* Insert your password for Full Disk Encryption +* If you do not already have free space on internal SSD disk, you will be prompted to reclaim some space: +* If you shrunk OSX partition, disk utility left an empy partition: delete useless partition (eg: if you shrunk OSX parition, diskutil created an empty partition) +* Press on "reclaim space" +* Press on "begin installation" +* create your user and password +* after a while, installation completes +* DO NOT press "Reboot button" + +Qubes OS is now installed, but you cannot boot it due to some issues, with bootloader configuration and wifi card. +You cannot Qubes boot using EFI/qubes/xen.efi because XEN bootloader configuration is broken. +You cannot even Qubes without XEN support, using GRUB2, because its configuration is broken too. + +Let's fix it manually, switch to console, pressing Fn+CTRL+ALT+F2 + +### 4. Fix GRUB configuration + +You can skip this section, but I found it very useful - during troubleshooting - to have a rescue system at hand. I could boot Qubes, without XEN support + +Grub configuration file is using some wrong commands, which are not compatible with grub2-efi +~~~ +chroot /mnt/sysimage +sed -i.bak -e "s/multiboot/chainloader/" -e "s/module.*--nounzip/initrdefi/" -e "s/module/linuxefi/" /etc/grub.d/20_linux_efi +exit +~~~ + +Now, despite XEN configuration is still broken, you have a rescue system booting vmlinux from rEFInd screen. +TBV1: chainloading XEN does not work, unless you specify the right disk prefix, eg: (hd1,gpt4) +TBV2: grub.cfg set the wrong disk in "set root" command +TBV3: in case you reach grub shell, you can +~~~ +ls +~~~ +and also reload config file and change it manualy before booting +~~~ +configfile /EFI/qubes/grub.cfg +~~~ +then press "e", edit grub cfg and boot pressing Fn+F10 + + +### 5. Fix bootloader + +* Fix grub2 configuration, which uses wrong command for EFI boot +* analyzing /mnt/sysimage/var/log/anaconda/program.log I found the faulty commands issues by Anaconda installer +~~~ +chrooot /mnt/sysimage +~~~ +* edit /boot/efi/EFI/qubes/xen.cfg file putting the following content +~~~ +[global] +default=4.4.14-11.pvops.qubes.x868_64 + +[4.4.14-11.pvops.qubes.x868_64] +options=loglvl=all dom0_mem=min:1024M dom0_mem=max:4096M +kernel=vmlinuz-4.4.14-11.pvops.qubes.x86_64 +ramdisk=initramfs-4.4.14-11.pvops.qubes.x86_64.img +~~~ + +* The main mistake is the efibootmgr, that needs the right commands. Just in case, re-apply all the commands, adapting to your own disk layout (-d /dev/sdxxx -p partition_number) +~~~ +grep Running /mnt/sysimage/var/log/anaconda/program.log | tail -n 20 +efibootmgr -b 0000 -B +efibootmgr -c -w -L Qubes -d /dev/sda -p 4 -l \\EFI\\qubes\\xen-4.6.1.efi +/usr/libexec/mactel-boot-setup +kernel-install add 4.4.14-11.pvops.qubes.x86_64 /boot/vmlinuz-4.4.14-11.pvops.qubes.x86_64 +systemctl disable qubes-netvm +reboot +~~~ + +At rEFInd screen, choose Boot EFI/qubes/xen-4.6.1.efi +Everything should now be ok, Qubes OS boots using EFI and you will get the last setup screen +* select "Qubes OS", do not change anything and click on "Done" +* VMs are created, including NetVM + +### 6. Fix pulseaudio, which locks CPU freezing the system often for 20 seconds + +My macbook has frequent freezes. Looking at journalctl output I saw that pulseaudio locks CPU for 20 seconds, very often. + +You can fix this issue, killing audio support with this quick workaround: +* open a dom0 terminal, as root and edit /etc/pulse/client.conf +* add "autospawn = no" +* Then, as normal user, issue command "pulseaudio --kill" + +### 7. Fix system freezes due to Broadcom BCM43602 + +* If you experiences a system freeze, during VM setup, force a reboot and press OPTION key. + * You will reach grub shell + ~~~ + configfile /EFI/qubes/grub.cfg + ~~~ + press Fn+F10 to boot without XEN support + * Once booted, press Fn+CTRL+ALT+F4 to open a shell + * Log into system + ~~~ + sudo su - + systemctl disable qubes-netvm + ~~~ + Press Fn+F2 and complete setup +* reboot and you finally have your Qubes OS +* DO NOT launch sys-net machine +* Open its setting and remove wifi adapter from the Selected devices, using Qubes Manager or use the following command line. Get the BFD of the adapter and remove it. On my macbook BFD is 04:00.0 and you will use it later on, also +~~~ +qvm-pci -l sys-net +qvm-pci -d sys-net 04:00.0 +~~~ + +Ok, setup is complete and we are almost done. +* Open a dom0 terminal +~~~ +sudo su - +xl pci-assignable-list +echo 04:00.0 > /sys/bus/pci/drivers/pciback/permissive +qvm-start sys-net +xl pci-attach sys-net 04:00.0 +~~~ + +This latest steps are required to launch sys-net with wifi access. They can be automated in a custom systemd service + + + + + +[rEFInd]: http://www.rodsbooks.com/refind/getting.html diff --git a/troubleshooting/nvidia-troubleshooting.md b/troubleshooting/nvidia-troubleshooting.md index deb2ea98..ffbadb1e 100644 --- a/troubleshooting/nvidia-troubleshooting.md +++ b/troubleshooting/nvidia-troubleshooting.md @@ -13,61 +13,147 @@ NVidia Troubleshooting Guide If you have an NVidia graphics card it will probably not work under Xen out of the box. If your system freezes during boot and you don't see the graphical login manager after you installed Xen, then this problem most likely affects you. The following steps should provide a work around so that you should be able to use your NVidia with X under Xen, however without any fancy "desktop effects". -1. Boot your system using the "failsafe" boot menu, that should have been automatically added to your `grub.conf` when you installed the Dom0 kernel. +Boot in failsafe +--------------------- + +Boot your system using the "failsafe" boot menu, that should have been automatically added to your `grub.conf` when you installed the Dom0 kernel. If the X Window System doesn't start now, this is probably a non-Xen related issue and this guide will probably not help you. + +Configure X with nouveau +--------------------- + Assuming your X Window System works fine now when you booted from the "failsafe" configuration, do the next steps... -1. Do not log into X, but instead switch to a text console (press Ctrl-Alt-F2) + 1. Do not log into X, but instead switch to a text console (press Ctrl-Alt-F2) -1. Log in as root + 2. Log in as root -1. Switch to runlevel 3 (this should kill your X server): + 3. Switch to runlevel 3 (this should kill your X server): -~~~ -init 3 -~~~ + ~~~ + init 3 + ~~~ -1. Run X-autoconfiguration: + 4. Run X-autoconfiguration: -~~~ -Xorg -configure -~~~ + ~~~ + Xorg -configure + ~~~ -This should generate a file `xorg.conf.new` in the `/root` directory. + This should generate a file `xorg.conf.new` in the `/root` directory. -In most cases you can ignore any warning or error messages displayed by the X server, assuming it generated the xorg.conf.new file. + In most cases you can ignore any warning or error messages displayed by the X server, assuming it generated the xorg.conf.new file. -1. Edit this newly generated `xorg.conf.new` file and introduce the following two modifications: + 5. Edit this newly generated `xorg.conf.new` file and introduce the following two modifications: -- Uncomment the ShadowFB option, so that you should now have something like this: + First, uncomment the ShadowFB option, so that you should now have something like this: ~~~ Option "ShadowFB" # [<bool>] ~~~ -- Change the driver name to `nouveau` (you will probably have `nv` written there): + Second, change the driver name to `nouveau` (you will probably have `nv` written there): ~~~ Driver "nouveau" ~~~ -Save the modification, exit the editor. + Save the modification, exit the editor. -1. Move the file to `/etc/X11` and rename it as `xorg.conf`: + 6. Move the file to `/etc/X11` and rename it as `xorg.conf`: + + ~~~ + mv /root/xorg.conf.new /etc/X11/xorg.conf + ~~~ + + 7. Verify that X will work with those new settings: + + ~~~ + xinit + ~~~ + + If you see a terminal window in the top left corner, it means you most likely succeeded, even if your keyboard or mouse do not work now (don't worry about them). + + 8. Reboot and let the system boot from the normal boot configuration. You should be able to use X under Xen now. + + +Disabling Nouveau +--------------------- +If Qubes fails to properly boot after the GRUB Boot menu and you are stuck on a black screen that displays messages starting with `nouveau` then it means that the nouveau driver failed to launch properly. + +One way to get rid of this for now is to disable nouveau. + +Example error ~~~ -mv /root/xorg.conf.new /etc/X11/xorg.conf +nouveau E[ PGRAPH][0000:01:00.0] grctx template channel unload timeout +nouveau E[ PGRAPH][0000:01:00.0] failed to construct context +nouveau E[ PGRAPH][0000:01:00.0] init failed, -16 ~~~ -1. Verify that X will work with those new settings: +Tip: In case you only have an external monitor it is advised to attach it directly to a connector of the motherboard if it is present, this should ensure that you're using the integrated graphics card instead of the nvidia graphics card. -~~~ -xinit -~~~ +If you're seeing this error than that means another graphics card (most likely an integrated one) acted as failsafe. Disabling nouveau has the consequences of disabling nvidia support all together. -If you see a terminal window in the top left corner, it means you most likely succeeded, even if your keyboard or mouse do not work now (don't worry about them). + 1. Verify that that GRUB Boot Menu is displaying, you should be presented with two options and a progressbar/timer than goes rather fast. -1. Reboot and let the system boot from the normal boot configuration. You should be able to use X under Xen now. + ~~~ + Qubes + Qubes with advanced Xen options + ~~~ + + 2. Quickly press the "E" key before the time is up. + + 3. An editor will open up that allows you to temporarily change the grub options for the next boot. + + 4. Press the down arrow key and move the cursor to the line after the line with the kernel options. The line with the kernel options will look like this: + + ~~~ + module /vmlinux-4.1.13-9.pvops.qubes.x86_64 placeholder root=/dev/mapper/qubes_dom0-root ro ... rhgb quiet + ~~~ + + It is not an exact copy as it may differ from system to system. + + Please note: chose the module that starts with `vmlinux`! + + 5. Press the left/right arrow keys to position the cursor at the end of kernel options line, after `rhgb quiet` in this case. + + 6. Add the following: + + ~~~ + nouveau.modeset=0 rd.driver.blacklist=nouveau video=vesa:off + ~~~ + + This will tempororarily disable nouveau until boot. + + 7. Press either the F10 key or Ctrl+X to start the boot process. + + Qubes should now boot properly, if that's the case then we should make this change permanent such that the GRUB config knows to not run nouveau. + +You'll have to do the following to make this change persistent, so that it will work properly on every boot : + + 1. Open a terminal (do this by clicking on Q > 'run command' > type 'terminal' and hit enter) + + 2. type following commands: + + ~~~ + cd /etc/default/ + sudo nano grub + ~~~ + + 3. Edit `GRUB_CMDLINE_LINUX`, add the following to it at the end: + + ~~~ + nouveau.modeset=0 rd.driver.blacklist=nouveau video=vesa:off + ~~~ + + 4. ctrl + X and then y to save the file. + + 5. The final step is to compile the configuration file to something the bootloader can read. + + ~~~ + sudo grub2-mkconfig -o /boot/grub2/grub.cfg + ~~~ diff --git a/troubleshooting/out-of-memory.md b/troubleshooting/out-of-memory.md index 64fd8cbf..4ea235a9 100644 --- a/troubleshooting/out-of-memory.md +++ b/troubleshooting/out-of-memory.md @@ -8,17 +8,9 @@ redirect_from: - /wiki/OutOfmemory/ --- -VMs specially templates use disk space. Also default private storage max size is 2 GB, but it is very easy to increase it as required. If you use all disk space, you will get the Out of disk space error that may crash your system because Dom0 does not have enough disk space to work. +VMs (especially templates) use pre-allocated space. The default private storage max size is 2 GB, but it's very easy to increase as needed. If the disk is completely full, you will get an `Out of disk space` error that may crash your system because Dom0 does not have enough disk space to work. So it's good practice to regularly check disk space usage with the command `df -h` in dom0 terminal. -So it is a good practice to regularly check disk space usage with command - -~~~ -df -~~~ - -in dom0 terminal. - -A system in out of space condition should be able to boot, but may be unable to load a desktop manager. In this case it is possible to login to dom0 terminal with Alt + Ctrl + F2. To recover disk space it may be possible to delete files in a userVM connecting to the userVM terminal: +A system that's out of space should be able to boot, but may be unable to load a desktop manager. In this case it is possible to login to dom0 terminal with Alt + Ctrl + F2. To recover disk space it may be possible to delete files in a userVM by connecting to the userVM terminal: ~~~ qvm-start <VMname> @@ -27,7 +19,7 @@ sudo xl console <VMname> If this does not work, check the size of /var/lib/qubes/qubes.xml. If it is zero, you'll need to use one of the file backup (stored in /var/lib/qubes/backup), hopefully you have the current data there. Find the most recent one and place in /var/lib/qubes/qubes.xml instead of the empty file. -In any case you'll need some disk space to start the VM. Check "df" output if you have some. If not, some hints how to free some disk space: +In any case you'll need some disk space to start the VM. Check `df -h` output if you have some. If not, some hints how to free some disk space: 1. Clean yum cache: diff --git a/troubleshooting/remove-vm-manually.md b/troubleshooting/remove-vm-manually.md new file mode 100644 index 00000000..5bfec1c8 --- /dev/null +++ b/troubleshooting/remove-vm-manually.md @@ -0,0 +1,29 @@ +--- +layout: doc +title: How to Remove VMs Manually +permalink: /doc/remove-vm-manually/ +--- + +How to Remove VMs Manually +========================== + +How to Remove a TemplateVM Manually +----------------------------------- + +All commands should be executed in a dom0 terminal. + +1. Remove the TemplateVM's directory: + + $ rm -rf /var/lib/qubes/vm-templates/<template-name> + +2. Remove the TemplateVM from qubes.xml: + + $ qvm-remove --just-db <template-name> + +3. Remove the TemplateVM's `*.desktop` files from `~/.local/share/applications`: + + $ rm ~/.local/share/applications/<template-name>* + +4. Remove the TemplateVM's Applications Menu entry: + + $ sudo rm /etc/xdg/menus/applications-merged/<template-name>* diff --git a/troubleshooting/thinkpad-troubleshooting.md b/troubleshooting/thinkpad-troubleshooting.md new file mode 100644 index 00000000..4e5ed82b --- /dev/null +++ b/troubleshooting/thinkpad-troubleshooting.md @@ -0,0 +1,67 @@ +--- +layout: doc +title: Lenovo ThinkPad Troubleshooting +permalink: /doc/thinkpad-troubleshooting/ +redirect_from: +- /doc/thinkpad_x201/ +- /en/doc/thinkpad_x201/ +- /doc/Thinkpad_X201/ +- /wiki/Thinkpad_X201/ +- /doc/lenovo450-tinkering/ +- /en/doc/lenovo450-tinkering/ +- /doc/Lenovo450Tinkering/ +- /wiki/Lenovo450Tinkering/ +--- + +# Lenovo ThinkPad Troubleshooting # + +## ThinkPads with Intel HD 3000 graphics ## + +Several ThinkPad models have Intel HD 3000 graphics, including the T420s and the +T520. Some users with these laptops have experienced random reboots, which were +solved by adding `i915.enable_rc6=0` as a kernel parameter to +`GRUB_CMDLINE_LINUX` in the file `/etc/default/grub` in dom0. + + +## Instructions for getting your Lenovo Thinkpad X201 & X200 laptop working with Qubes/Linux ## + +For being able to boot the installer from USB, you have to disable VT-d in the BIOS. +Enter the BIOS by hitting F1, go to Config - CPU and then disable there VT-d. + +After the installation, you have to set a startup-parameter for Xen, to be able to activate VT-d again: + +1. Open a terminal in dom0 +2. Edit `/etc/default/grub` +3. Add to the line `GRUB_CMDLINE_XEN_DEFAULT` the setting `iommu=no-igfx`, save and quit +4. sudo `grub2-mkconfig --output /boot/grub2/grub.cfg` + +Then reboot, enter BIOS and re-enable VT-d. + +### Getting scrolling with the Trackpoint and the Middle Button to work ### + +1. Create a script with the following content: + + ~~~ + #!/bin/sh + xinput set-prop "TPPS/2 IBM TrackPoint" "Evdev Wheel Emulation" 1 + xinput set-prop "TPPS/2 IBM TrackPoint" "Evdev Wheel Emulation Button" 2 + xinput set-prop "TPPS/2 IBM TrackPoint" "Evdev Wheel Emulation Timeout" 200 + xinput set-prop "TPPS/2 IBM TrackPoint" "Evdev Wheel Emulation Axes" 6 7 4 5 + ~~~ + +2. Add the script to the startup-items of your desktop environment. + + +## Instructions for getting your Lenovo 450 laptop working with Qubes/Linux ## + +Lenovo 450 uses UEFI, so some settings are needed to get Qubes (or Fedora) to boot, otherwise Qubes install USB stick will reboot right after boot selector screen and not continue install. + +### Setting UEFI options to get Qubes install to boot ### + +1. Enable Legacy USB mode +2. Disable all Secure Boot and UEFI options, but leave this enabled: Config / USB / USB UEFI BIOS SUPPORT +3. Save settings and reboot +5. Install Qubes + +... and now enjoy :) These settings may be needed also in other UEFI computers. + diff --git a/troubleshooting/thinkpad_x201.md b/troubleshooting/thinkpad_x201.md deleted file mode 100644 index 5ee5fd6d..00000000 --- a/troubleshooting/thinkpad_x201.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -layout: doc -title: Getting Lenovo Thinkpad X201 to work -permalink: /doc/thinkpad_x201/ -redirect_from: -- /en/doc/thinkpad_x201/ -- /doc/Thinkpad_X201/ -- /wiki/Thinkpad_X201/ ---- - -Instructions for getting your Lenovo Thinkpad X201 laptop working with Qubes/Linux -========================================================================= - -For being able to boot the installer from USB, you have to disable VT-D in the BIOS. -Enter the BIOS by hitting F1, go to Config - CPU and then disable there VT-d. - -After the installation, you have to set a startup-parameter for Xen, to be able to activate VT-d again: - -1. Open a terminal in dom0 -2. Edit `/etc/default/grub` -3. Add to the line `GRUB_CMDLINE_XEN_DEFAULT` the setting `iommu=no-igfx`, save and quit -4. sudo `grub2-mkconfig --output /boot/grub2/grub.cfg` - -Then reboot, enter BIOS and re-enable VT-d. - -Getting scrolling with the Trackpoint and the Middle Button to work -------------------------------------------------- - -1. Create a script with the following content: - - ~~~ - #!/bin/sh - xinput set-prop "TPPS/2 IBM TrackPoint" "Evdev Wheel Emulation" 1 - xinput set-prop "TPPS/2 IBM TrackPoint" "Evdev Wheel Emulation Button" 2 - xinput set-prop "TPPS/2 IBM TrackPoint" "Evdev Wheel Emulation Timeout" 200 - xinput set-prop "TPPS/2 IBM TrackPoint" "Evdev Wheel Emulation Axes" 6 7 4 5 - ~~~ - -2. Add the script to the startup-items of your desktop environment. diff --git a/troubleshooting/uefi-troubleshooting.md b/troubleshooting/uefi-troubleshooting.md index 7eebc7c9..46b19886 100644 --- a/troubleshooting/uefi-troubleshooting.md +++ b/troubleshooting/uefi-troubleshooting.md @@ -8,25 +8,51 @@ Troubleshooting UEFI related problems ======================================== - -Cannot start installation, hangs at four penguins after choosing "Test media and install Qubes OS" in GRUB menu +Cannot start installation, installation completes successfully but then BIOS loops at boot device selection, hangs at four penguins after choosing "Test media and install Qubes OS" in GRUB menu --------------------- There is some [common bug in UEFI implementation](http://xen.markmail.org/message/f6lx2ab4o2fch35r), affecting mostly Lenovo systems, but probably some others too. You can try existing workaround: -1. In GRUB menu<sup id="a1-1">[1](#f1)</sup> press `e`. -2. At the end of `chainloader` line add `/mapbs /noexitboot`. -3. Perform installation normally, but not reboot system at the end yet. -4. Go to `tty2` (Ctrl-Alt-F2). -5. Execute `mount | grep boot/efi` and note device name (first column). It should be something like `/dev/sda1`. -6. Execute `efibootmgr -v`, search for `Qubes` entry and note its number (it should be something like `Boot0001` - `0001` is an entry number). -7. Replace existing `Qubes` entry with modified one. Replace `XXXX` with entry number from previous step, `/dev/sda` with your disk name and `-p 1` with `/boot/efi` partition number): +01. In GRUB menu<sup id="a1-1">[1](#f1)</sup>, select "Troubleshoot", then "Boot from device", then press `e`. +02. At the end of `chainloader` line add `/mapbs /noexitboot`. +03. Perform installation normally, but not reboot system at the end yet. +04. Go to `tty2` (Ctrl-Alt-F2). +05. Enable `/mapbs /noexitboot` on just installed system. This step differs between Qubes releases: + + **For Qubes 3.1:** + +06. Execute `mount | grep boot/efi` and note device name (first column). It should be something like `/dev/sda1`. +07. Execute `efibootmgr -v`, search for `Qubes` entry and note its number (it should be something like `Boot0001` - `0001` is an entry number). +08. Replace existing `Qubes` entry with modified one. Replace `XXXX` with entry number from previous step, `/dev/sda` with your disk name and `-p 1` with `/boot/efi` partition number): efibootmgr -b XXXX -B efibootmgr -v -c -u -L Qubes -l /EFI/qubes/xen.efi -d /dev/sda -p 1 "placeholder /mapbs /noexitboot" -8. Compare new entry with the old one (printed in step 6) - it should only differ in additional options at the end. -9. Now you can reboot the system by issuing `reboot` command. +09. Compare new entry with the old one (printed in step 6) - it should only differ in additional options at the end, and look probably something like this: + + Boot0001* Qubes HD(1,GPT,partition-guid-here,0x800,0x64000)/File(\EFI\qubes\xen.efi)p.l.a.c.e.h.o.l.d.e.r. ./.m.a.p.b.s. ./.n.o.e.x.i.t.b.o.o.t. + + If instead it looks like: + + Boot0001* Qubes HD(1,0,00000000...0,0x0,0x0)/File(\EFI\qubes\xen.efi)p.l.a.c.e.h.o.l.d.e.r. ./.m.a.p.b.s. ./.n.o.e.x.i.t.b.o.o.t. + + then try passing `/dev/sda1` or `/dev/nvme0n1p1` or whatever is your EFI partition instead of `/dev/sda` and `-p 1`. + +10. Now you can reboot the system by issuing `reboot` command. + + **For Qubes 3.2 or later:** + +11. Edit `/mnt/sysimage/boot/efi/EFI/qubes/xen.cfg` (you can use `vi` editor) and add to every kernel section: + + mapbs=1 + noexitboot=1 + + **Note:** You must add these parameters on two separate new lines (one + paramater on each line) at the end of each section that includes a kernel + line (i.e., all sections except the first one, since it doesn't have a + kernel line). + +12. Now you can reboot the system by issuing `reboot` command. System crash/restart when booting installer @@ -41,9 +67,62 @@ Some Dell systems and probably others have [another bug in UEFI firmware](http:/ 4. Go to `tty2` (Ctrl-Alt-F2). 5. Execute: - sed -i -e 's/^options=.*/\0 efi=attr=uc' /mnt/sysimage/boot/efi/qubes/xen.cfg + sed -i -e 's/^options=.*/\0 efi=attr=uc/' /mnt/sysimage/boot/efi/qubes/xen.cfg + + or if you're installing 3.2 execute: + + sed -i -e 's/^options=.*/\0 efi=attr=uc/' /mnt/sysimage/boot/efi/EFI/qubes/xen.cfg 6. Now you can reboot the system by issuing `reboot` command. * * * <b name="f1">1</b> If you use rEFInd, you can see 3 options regarding the USB installer. Choose "Fallback Boot Loader" to enter the GRUB menu. [↩](#a1-1) [↩](#a1-2) + + +Boot device not recognized after installing +------------------------------------------ + +Some firmware will not recognize the default Qubes EFI configuration. As such, +it will have to be manually edited to be bootable (this will need to be done after +every kernel and Xen update.) + +1. Copy `/boot/efi/EFI/qubes/` to `/boot/efi/EFI/BOOT/`. +2. Rename `/boot/efi/EFI/BOOT/xen.efi` to `/boot/efi/EFI/BOOT/BOOTX64.efi`. +3. Rename `/boot/efi/EFI/BOOT/xen.cfg` to `/boot/efi/EFI/BOOT/BOOTX64.cfg`. + +Installation finished but "Qubes" boot option is missing and xen.cfg is empty +-------------------------------------------------------------------------------------- + +In some cases installer fails to finish EFI setup and leave the system without +Qubes-specific EFI configuration. In such a case you need to finish those parts +manually. You can do that just after installation (switch to `tty2` with +Ctrl-Alt-F2), or booting from installation media in "Rescue a Qubes system" mode. + +1. Examine `/boot/efi/EFI/qubes` (if using Qubes installation media, it's in `/mnt/sysimage/boot/efi/EFI/qubes`). You should see there 4 files: + + - xen.cfg (empty, size 0) + - xen-(xen-version).efi + - vmlinuz-(kernel-version) + - initramfs-(kernel-version).img + +2. Copy `xen-(xen-version).efi` to `xen.efi`: + + cd /mnt/sysimage/boot/efi/EFI/qubes + cp xen-*.efi xen.efi + +3. Create xen.cfg with this content (adjust kernel version, and filesystem + locations, below values are based on default installation of Qubes 3.2): + + + [global] + default=4.4.14-11.pvops.qubes.x86_64 + + [4.4.14-11.pvops.qubes.x86_64] + options=loglvl=all dom0_mem=min:1024M dom0_mem=max:4096M + kernel=vmlinuz-4.4.14-11.pvops.qubes.x86_64 root=/dev/mapper/qubes_dom0-root rd.lvm.lv=qubes_dom0/root rd.lvm.lv=qubes_dom0/swap i915.preliminary_hw_support=1 rhgb quiet + ramdisk=initramfs-4.4.14-11.pvops.qubes.x86_64.img + +4. Create boot entry in EFI firmware (replace `/dev/sda` with your disk name and `-p 1` with `/boot/efi` partition number): + + efibootmgr -v -c -u -L Qubes -l /EFI/qubes/xen.efi -d /dev/sda -p 1 "placeholder /mapbs /noexitboot" + diff --git a/troubleshooting/wireless-troubleshooting.md b/troubleshooting/wireless-troubleshooting.md new file mode 100644 index 00000000..9c8ea33d --- /dev/null +++ b/troubleshooting/wireless-troubleshooting.md @@ -0,0 +1,121 @@ +--- +layout: doc +title: Wireless Troubleshooting +permalink: /doc/wireless-troubleshooting/ +redirect_from: +- /en/doc/wireless-troubleshooting/ +--- + +Wireless Troubleshooting Guide +============================== + +These instructions may help with suspend/resume issues for more devices than just wireless cards, that is just the (unfortunately not uncommon) example used here. + +Resetting wireless cards by reloading drivers +--------------------------------------------- + +If your wireless card works, but after suspending and resuming your computer, the Network-Manager applet just says "Device not ready", then try un-loading and re-loading the driver. + +### Determining your wireless card driver ### + +First, determine which kernel module corresponds to your wireless card. There are several ways to do this. + +The easiest is via the output of `lspci -k` in your sys-net VM: + +~~~ +[user@sys-net ~]$ lspci -k +00:00.0 Network controller: Intel Corporation Wireless 8260 (rev 3a) + Subsystem: Intel Corporation Device 0130 + Kernel driver in use: iwlwifi + Kernel modules: iwlwifi +~~~ + +Here we see that the machine in question has an Intel wireless card, being used by the `iwlwifi` kernel module. + + +### Checking logs for relevant messages ### + +View the output of `dmesg` in sys-net, and check if you see a bunch of wireless related errors. Depending on your hardware, they may look like the following (or not): + +~~~ +iwlwifi 0000:00:00.0: loaded firmware version 16.242414.0 op_mode iwlmvm +iwlwifi 0000:00:00.0: Detected Intel(R) Dual Band Wireless AC 8260, REV=0x208 +... +IPv6: ADDRCONF(NETDEV_UP): wlp0s0: link is not ready +iwlwifi 0000:00:00.0: L1 Enabled - LTR Enabled +iwlwifi 0000:00:00.0: L1 Enabled - LTR Enabled +iwlwifi 0000:00:00.0: Failed to load firmware chunk! +iwlwifi 0000:00:00.0: Could not load the [0] uCode section +iwlwifi 0000:00:00.0: Failed to start INIT ucode: -110 +iwlwifi 0000:00:00.0: Failed to run INIT ucode: -110 +... +iwlwifi 0000:00:00.0: Direct firmware load for iwlwifi-8000C-18.ucode failed with error -2 +~~~ + +### Seeing what modules you have loaded ### + +You can check which drivers are currently loaded with `lsmod`, and view details about a module with `modinfo <module_name>`. + +For example, we list what modules we have loaded: + +~~~ +[user@sys-net ~]$ lsmod +Module Size Used by +iwlmvm 315392 0 +iwlwifi 155648 1 iwlmvm +mac80211 708608 1 iwlmvm +cfg80211 557056 3 iwlwifi,mac80211,iwlmvm +... +~~~ + +and check one: + +~~~ +[user@sys-net ~]$ modinfo iwlmvm | grep -E '^(description|author|depends):' +author: Copyright(c) 2003- 2015 Intel Corporation <ilw@linux.intel.com> +description: The new Intel(R) wireless AGN driver for Linux +depends: iwlwifi,mac80211,cfg80211 +~~~ + +Hey, it's our wireless driver! + +Now, check if reloading the module makes wireless work again: + +~~~ +[user@sys-net ~]$ sudo rmmod iwlmvm +[user@sys-net ~]$ sudo modprobe iwlmvm +~~~ + +and try reconnecting to a network that is known to work. + +If that is successful, see below about having Qubes automatically reload the driver for you. If not, try also reloading some dependent modules, in our example we must also reload iwlwifi: + +~~~ +[user@sys-net ~]$ modinfo iwlwifi | grep -E '^(description|author|depends):' +author: Copyright(c) 2003- 2015 Intel Corporation <ilw@linux.intel.com> +description: Intel(R) Wireless WiFi driver for Linux +depends: cfg80211 +~~~ + +~~~ +[user@sys-net ~]$ sudo rmmod iwlmvm +[user@sys-net ~]$ sudo rmmod iwlwifi +[user@sys-net ~]$ sudo modprobe iwlwifi # note the reverse order of loading/unloading +[user@sys-net ~]$ sudo modprobe iwlmvm +~~~ + +Automatically reloading drivers on suspend/resume +------------------------------------------------- + +If reloading the driver (which resets the hardware into a known-state) resolves your issue when done manually, you can have Qubes automatically un/reload them on suspend & resume by listing the relevant modules in `/rw/config/suspend-module-blacklist`. + +In the above example, it would look like this: + +~~~ +[user@sys-net config]$ cat /rw/config/suspend-module-blacklist +# You can list here modules you want to be unloaded before going to sleep. This +# file is used only if the VM has any PCI device assigned. Modules will be +# automatically loaded after resume. +iwlmvm +iwlwifi +~~~ diff --git a/unsorted/propaganda.md b/unsorted/propaganda.md deleted file mode 100644 index a4d648f7..00000000 --- a/unsorted/propaganda.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -layout: doc -title: Propaganda -permalink: /doc/propaganda/ -redirect_from: -- /en/doc/propaganda/ -- /doc/Propaganda/ -- /wiki/Propaganda/ ---- - -Qubes Propaganda Page -===================== - -Mainstream press about Qubes ----------------------------- - -Technical press about Qubes ---------------------------- - -Conference presentations about Qubes ------------------------------------- - -Related projects ----------------- diff --git a/unsorted/sandbox/include.md b/unsorted/sandbox/include.md deleted file mode 100644 index 05b3323e..00000000 --- a/unsorted/sandbox/include.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -layout: doc -title: Include -permalink: /doc/sandbox/include/ -redirect_from: -- /en/doc/sandbox/include/ -- /doc/Sandbox/Include/ -- /wiki/Sandbox/Include/ ---- - -[Include(http://git.qubes-os.org/?p=mainstream/docs.git;a=blob\_plain;f=qvm-tools/qvm-sync-appmenus.rst;hb=HEAD, text/x-rst)?](/wiki/Sandbox/Include(http%3A/git.qubes-os.org?p=mainstream/docs.git;a=blob_plain;f=qvm-tools/qvm-sync-appmenus.rst;hb=HEAD,%20text/x-rst))