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

Merge pull request #1 from QubesOS/master

Browse Source 
merge
This commit is contained in:
xn0px90 2018-11-14 16:26:33 -05:00 committed by GitHub
commit f017d3ff75
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
291 changed files with 18820 additions and 7024 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

18
.travis.yml Normal file
View File

@ -0,0 +1,18 @@
language: ruby
dist: trusty
rvm:
- 2.4
install: git clone https://github.com/${TRAVIS_REPO_SLUG%%/*}/qubesos.github.io ~/qubesos.github.io
script: ~/qubesos.github.io/_utils/travis.sh
addons:
apt:
packages:
- hunspell
- pandoc
- jq
notifications:
email:
recipients:
- adw@qubes-os.org
on_success: never
on_failure: always

59
CONTRIBUTING.md
View File

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

1
_dev/.gitignore vendored Normal file
View File

@ -0,0 +1 @@
_build

177
_dev/Makefile Normal file
View File

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

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

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

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

193
_dev/conf.py Normal file
View File

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

9
_dev/index.rst Normal file
View File

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

71
about/code-of-conduct.md Normal file
View File

@ -0,0 +1,71 @@
---
layout: default
title: Code of Conduct
permalink: /code-of-conduct/
---
## Introduction
This Code of Conduct is a collaborative, evolving document that attempts to transparently set out a public set of standards regarding appropriate conduct in the Qubes OS Project.
It is *not* intended to be a statement or endorsement, whether implicit or explicit, of any particular political or philosophical attitude, belief, or way of living.
Rather, it is an attempt to find a reasonable middle ground among the inevitable disagreements regarding free expression that arise in a large, diverse community of people from around the world.
It is intended to be a practical means of serving the best interests of our users, contributors, and the project itself.
We welcome you to view the [history of changes] to this document and the [discussion] leading to its creation.
## Our Pledge
The Qubes OS project creates a reasonably secure OS. In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to make participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, sexual identity and orientation, or other characteristic.
## Our Standards
Examples of behavior that contributes to creating a positive environment include:
- Using welcoming and inclusive language
- Being respectful of differing viewpoints and experiences
- Gracefully accepting constructive criticism
- Focusing on what is best for the community
- Showing empathy towards other community members
Examples of unacceptable behavior by participants include:
- The use of sexualized language or imagery and unwelcome sexual attention or advances
- Trolling, insulting/derogatory comments, and personal or political attacks
- Reinforcing stereotypical models for illustration of non-technical users (e.g. our mothers/grandmothers, etc.)
- Public or private harassment, as defined by the [Citizen Code of Conduct]
- Publishing others' private information, such as a physical or electronic address, without explicit permission
- Other conduct which could reasonably be considered inappropriate in a professional setting
(Please also see our [mailing list discussion guidelines].)
## Our Responsibilities
Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior. This action can include removing, editing, or rejecting comments, commits, code, wiki edits, issues, and other contributions, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.
## Scope
This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers.
## Enforcement
Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at `mods@qubes-os.org`. All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.
Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership.
## A Note on Trust
Expect all contributions to be reviewed with some amount of healthy adversarial skepticism, regardless of your perceived standing in the community.
This is a security project, and allowing ourselves to get complacent while reviewing code simply because it comes from a well-known party would not be in the best interest of the project.
Please try not to get offended if you perceive your contributions as being met with distrust -- we are most definitely thankful and appreciative of your efforts, but must also remain vigilant in order to ensure continued quality and safeguard against potential sabotage.
## Attribution
The initial published version of this Code of Conduct was adapted from the [Contributor Covenant, version 1.4] and the [Rust Code of Conduct].
[history of changes]: https://github.com/QubesOS/qubes-doc/commits/master/about/code-of-conduct.md
[discussion]: https://github.com/QubesOS/qubes-issues/issues/2163
[Citizen Code of Conduct]: http://citizencodeofconduct.org/
[mailing list discussion guidelines]: /support/#discussion-list-guidelines
[Contributor Covenant, version 1.4]: http://contributor-covenant.org/version/1/4
[Rust Code of Conduct]: https://www.rust-lang.org/en-US/conduct.html

32
about/download-mirrors.md Normal file
View File

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

136
about/experts.md Normal file
View File

@ -0,0 +1,136 @@
---
layout: home
title: Experts
permalink: /experts/
---
<div class="home-content container">
<div class="row more-top">
<div class="col-lg-12 col-md-12">
<h2 class="text-center"><i class="fa fa-quote-left"></i> What the experts are saying about Qubes</h2>
</div>
</div>
<div class="white-box more-bottom">
<div class="row featured-quotes">
<div class="col-lg-3 col-md-3 text-center">
<a class="avatar-large" href="https://twitter.com/Snowden/status/781493632293605376" target="_blank">
<img src="/attachment/site/expert-edward-snowden.jpg">
</a>
</div>
<div class="col-lg-9 col-md-9 more-top">
<a href="https://twitter.com/Snowden/status/781493632293605376" target="_blank">
<blockquote>"If you're serious about security, QubesOS is the best OS available today. It's what I use, and free. Nobody does VM isolation better."
<i class="fa fa-twitter fa-fw" aria-hidden="true"></i>
<footer>Edward Snowden<cite>, whistleblower and privacy advocate</cite></footer>
</blockquote>
</a>
</div>
</div>
<div class="row featured-quotes">
<div class="col-lg-3 col-md-3 text-center">
<a class="avatar-large" href="https://twitter.com/hashbreaker/status/577206817475850240" target="_blank">
<img src="/attachment/site/expert-daniel-j-bernstein.jpg">
</a>
</div>
<div class="col-lg-9 col-md-9 more-top">
<a href="https://twitter.com/hashbreaker/status/577206817475850240" target="_blank">
<blockquote>"Happy thought of the day: An attacker who merely finds a browser bug can't listen to my microphone except when I've told Qubes to enable it."
<i class="fa fa-twitter fa-fw" aria-hidden="true"></i>
<footer>Daniel J. Bernstein<cite title="Source Title">, mathematician, cryptologist, and computer scientist</cite></footer>
</blockquote>
</a>
</div>
</div>
<div class="row featured-quotes">
<div class="col-lg-3 col-md-3 text-center">
<a class="avatar-large" href="https://twitter.com/micahflee/status/577998730340622337" target="_blank">
<img src="/attachment/site/expert-micah-lee.jpg">
</a>
</div>
<div class="col-lg-9 col-md-9 more-top">
<a href="https://twitter.com/micahflee/status/577998730340622337" target="_blank">
<blockquote>"When I use Qubes I feel like a god. Software thinks that it's in control, that it can do what it wants? It can't. I'm in control."
<i class="fa fa-twitter fa-fw" aria-hidden="true"></i>
<footer>Micah Lee<cite title="Source Title">, Freedom of the Press Foundation, The Intercept</cite></footer>
</blockquote>
</a>
</div>
</div>
<div class="row featured-quotes">
<div class="col-lg-3 col-md-3 text-center">
<a class="avatar-large" href="https://twitter.com/petertoddbtc/status/924981145871060996" target="_blank">
<img src="/attachment/site/expert-peter-todd.jpg">
</a>
</div>
<div class="col-lg-9 col-md-9 more-top">
<a href="https://twitter.com/petertoddbtc/status/924981145871060996" target="_blank">
<blockquote>"Donated a % of my consulting company's last year revenue to Qubes OS. I rely on it for all my work, and recommend it to clients too."
<i class="fa fa-twitter fa-fw" aria-hidden="true"></i>
<footer>Peter Todd<cite title="Source Title">, Applied Cryptography Consultant</cite></footer>
</blockquote>
</a>
</div>
</div>
<div class="row featured-quotes">
<div class="col-lg-3 col-md-3 text-center">
<a class="avatar-large" href="https://twitter.com/isislovecruft" target="_blank">
<img src="/attachment/site/expert-isis-agora-lovecruft.jpg">
</a>
</div>
<div class="col-lg-9 col-md-9 more-top">
<a href="https://twitter.com/isislovecruft" target="_blank">
<blockquote>"With QubesOS, I feel more comfortable accessing Tor Project infrastructure from the same laptop I use to execute random GameBoy ROMs I downloaded from the internet."
<i class="fa fa-twitter fa-fw" aria-hidden="true"></i>
<footer>Isis Agora Lovecruft<cite title="Source Title">, cypherpunk and Tor Project core developer</cite></footer>
</blockquote>
</a>
</div>
</div>
<div class="row featured-quotes">
<div class="col-lg-3 col-md-3 text-center">
<a class="avatar-large" href="https://twitter.com/csoghoian/status/756212792785534976" target="_blank">
<img src="/attachment/site/expert-christopher-soghoian.jpg">
</a>
</div>
<div class="col-lg-9 col-md-9 more-top">
<a href="https://twitter.com/csoghoian/status/756212792785534976" target="_blank">
<blockquote>"I am so much happier and less stressed out after switching to QubesOS. Can wholeheartedly recommend."
<i class="fa fa-twitter fa-fw" aria-hidden="true"></i>
<footer>Christopher Soghoian<cite title="Source Title">, privacy researcher, activist, and principal technologist at the ACLU</cite></footer>
</blockquote>
</a>
</div>
</div>
<div class="row featured-quotes">
<div class="col-lg-3 col-md-3 text-center">
<a class="avatar-large" href="https://twitter.com/legind/status/742504400854257664" target="_blank">
<img src="/attachment/site/expert-bill-budington.jpg">
</a>
</div>
<div class="col-lg-9 col-md-9 more-top">
<a href="https://twitter.com/legind/status/742504400854257664" target="_blank">
<blockquote>"I really like it [Qubes OS]. If your hardware supports it, I recommend it. Everything is super well thought-out."
<i class="fa fa-twitter fa-fw" aria-hidden="true"></i>
<footer>Bill Budington<cite title="Source Title">, security engineer and technologist, Electronic Frontier Foundation</cite></footer>
</blockquote>
</a>
</div>
</div>
<div class="row featured-quotes">
<div class="col-lg-3 col-md-3 text-center">
<a class="avatar-large" href="https://twitter.com/kennwhite/status/914924731400425475" target="_blank">
<img src="/attachment/site/expert-kenn-white.jpg">
</a>
</div>
<div class="col-lg-9 col-md-9 more-top">
<a href="https://twitter.com/kennwhite/status/914924731400425475" target="_blank">
<blockquote>"Periodic shout out to [Rutkowska] and the QubesOS team for *years* of hard work to improve desktop security. Qubes is the real deal."
<i class="fa fa-twitter fa-fw" aria-hidden="true"></i>
<footer>Kenn White<cite title="Source Title">, security researcher, Open Crypto Audit Project</cite></footer>
</blockquote>
</a>
</div>
</div>
</div>
{% include footer.html %}
</div>

584
about/faq.md Normal file
View File

@ -0,0 +1,584 @@
---
layout: sidebar
title: Frequently Asked Questions
permalink: /faq/
redirect_from:
- /doc/user-faq/
- /en/doc/user-faq/
- /doc/UserFaq/
- /wiki/UserFaq/
- /doc/devel-faq/
- /en/doc/devel-faq/
- /doc/DevelFaq/
- /wiki/DevelFaq/
---
# Frequently Asked Questions
## General & Security
### 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.
### 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.
### 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.
### 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.
### 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 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).
### How is Qubes affected by Xen Security Advisories (XSAs)?
See the [XSA Tracker](/security/xsa/).
### What about this other/new (micro)kernel/hypervisor?
Whenever starting a discussion about another (micro)kernel or hypervisor in relation to Qubes, we strongly suggest including answers to the following questions first:
1. What kinds of containers does it use for isolation? Processes? PV VMs? Fully virtualized VMs (HVMs)? And what underlying h/w technology is used (ring0/3, VT-x)?
2. Does it require specially written/built applications (e.g. patched Firefox)?
3. Does it require custom drivers, or can it use Linux/Windows ones?
4. Does it support VT-d, and does it allow for the creation of untrusted driver domains?
5. Does it support S3 sleep?
6. Does it work on multiple CPUs/Chipsets?
7. What are the performance costs, more or less? (e.g. "XYZ prevents concurrent execution of two domains/processes on shared cores of a single processor", etc.)
8. Other special features? E.g. eliminates cooperative covert channels between VMs?
Here are the answers for Xen 4.1 (which we use as of 2014-04-28):
1. PV and HVM Virtual Machines (ring0/3 for PV domains, VT-x/AMD-v for HVMs).
2. Runs unmodified usermode apps (binaries).
3. Runs unmodified Linux drivers (dom0 and driver domains). PV VMs require special written pvdrivers.
4. Full VT-d support including untrusted driver domains.
5. S3 sleep supported well.
6. Works on most modern CPUs/Chipsets.
7. Biggest performance hit on disk operations (especially in Qubes when complex 2-layer mapping used for Linux qubes). No GPU virtualization.
8. Mostly Works<sup>TM</sup> :)
### Which virtualization modes do VMs use?
Here is an overview of the VM virtualization modes that correspond to each currently-supported Qubes OS version (as of 2018-03-28):
VM type \ Qubes OS version | 3.2 | 4.0 |
------------------------------------------ | --- | --- |
Default VMs without PCI devices (most VMs) | PV | PVH |
Default VMs with PCI devices | PV | HVM |
Stub domains - Default VMs w/o PCI devices | N/A | N/A |
Stub domains - Default VMs w/ PCI devices | N/A | PV |
Stub domains - HVMs | PV | PV |
### 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.
### Why passwordless sudo?
Please refer to [this page](/doc/vm-sudo/).
### Why is dom0 so old?
Please see:
- [Why would one want to update software in dom0?](/doc/software-update-dom0/#why-would-one-want-to-install-or-update-software-in-dom0)
- [Note on dom0 and EOL](/doc/supported-versions/#note-on-dom0-and-eol)
### Do you recommend coreboot as an alternative to vendor BIOS?
Yes, where it is possible to use it an open source boot firmware ought to be more trustable than a closed source implementation. [coreboot](https://www.coreboot.org/) is as a result a requirement for [Qubes Certified Hardware](https://www.qubes-os.org/news/2016/07/21/new-hw-certification-for-q4/). The number of machines coreboot currently supports is limited and the use of some vendor supplied blobs is generally still required. Where coreboot does support your machine and is not already installed, you will generally need additional hardware to flash it. Please see the coreboot website / their IRC channel for further information.
### 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 on [GitHub Pages](https://pages.github.com/) ([why?](#why-do-you-use-github)).
Therefore, it is largely outside of our control.
We don't consider this a problem, however, since we explicitly [distrust the infrastructure](#what-does-it-mean-to-distrust-the-infrastructure).
For this reason, we don't think that anyone should place undue trust in the live version of this site on the Web.
Instead, if you want to obtain your own, trustworthy copy of this website in a secure way, you should clone our [website repo](https://github.com/QubesOS/qubesos.github.io), [verify the PGP signatures on the commits and/or tags](/security/verifying-signatures/#how-to-verify-qubes-repos) (signed by the [doc-signing keys](https://github.com/QubesOS/qubes-secpack/tree/master/keys/doc-signing)), then either [render the site on your local machine](https://github.com/QubesOS/qubesos.github.io/blob/master/README.md#instructions) or simply read the source, the vast majority of which was [intentionally written in Markdown so as to be readable as plain text for this very reason](/doc/doc-guidelines/#markdown-conventions).
We've gone to special effort to set all of this up so that no one has to trust the infrastructure and so that the contents of this website are maximally available and accessible.
### What does it mean to "distrust the infrastructure"?
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 do you use GitHub?
Three main reasons:
1. We [distrust the infrastructure](#what-does-it-mean-to-distrust-the-infrastructure), including GitHub (though there are aspects we're still [working on](https://github.com/QubesOS/qubes-issues/issues/3958)).
2. It's free (as in beer). We'd have to spend either time or money to implement a solution ourselves or pay someone to do so, and we can't spare either one right now.
3. It has low admin/overhead requirements, which is very important, given how little time we have to spare.
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.
So, if feature X isn't enabled, it's most likely for one of three reasons:
1. Our GitHub Pages platform doesn't support it.
2. Our platform supports it, but we've decided not to enable it.
3. Our platform supports it, but we're not aware that we can enable it or have forgotten to do so.
(If it seems like this is the case, let us know!)
----------
## Users
### 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 passthrough 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 is very difficult to **securely** implement multi-user support.
See [here](https://groups.google.com/group/qubes-devel/msg/899f6f3efc4d9a06) for details.
However, in Qubes 4.x we will be implementing management functionality. See [Admin API](/news/2017/06/27/qubes-admin-api/) and [Core Stack](/news/2017/10/03/core3/) for more details.
### What are the system requirements for Qubes OS?
See the [System Requirements](/doc/system-requirements/).
### Is there a list of hardware that is compatible with Qubes OS?
See the [Hardware Compatibility List](/hcl/).
### Is there any certified hardware for Qubes OS?
See [Certified Hardware](/doc/certified-hardware/).
### 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, but 8 GB is more realistic.
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 4.x on a system without VT-x or VT-d?
Qubes 4.x requires Intel VT-x with EPT / AMD-V with RVI (SLAT) and Intel VT-d / AMD-Vi (aka AMD IOMMU) for proper functionality (see the [4.x System Requirements](/doc/system-requirements/#qubes-release-4x)). If you are receiving an error message on install saying your "hardware lacks the features required to proceed", check to make sure the virtualization options are enabled in your BIOS/UEFI configuration. You may be able to install without the required CPU features for testing purposes only, but VMs may not function correctly and there will be no security isolation. For more information, see our post on [updated requirements for Qubes-certified hardware](/news/2016/07/21/new-hw-certification-for-q4/).
### Can I install Qubes 3.2 on a system without VT-x?
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 3.2 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 include 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?
Yes, and 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!)
### What is a terminal?
A [terminal emulator](https://en.wikipedia.org/wiki/Terminal_emulator), nowadays often referred to as just a *terminal*, is a program which provides a text window.
Inside that window, a [shell](https://en.wikipedia.org/wiki/Shell_(computing)) is typically running in it.
A shell provides a [command-line interface](https://en.wikipedia.org/wiki/Command-line_interface) where the user can enter and run [commands](https://en.wikipedia.org/wiki/Command_(computing)).
See introductions on Wikibooks: [here](https://en.wikibooks.org/wiki/Fedora_And_Red_Hat_System_Administration/Shell_Basics), [here](https://en.wikibooks.org/wiki/A_Quick_Introduction_to_Unix) and [here](https://en.wikibooks.org/wiki/Bash_Shell_Scripting).
### Why does my network adapter not work?
You may have an adapter (wired, wireless), that is not compatible with open-source drivers shipped by Qubes. There may be a binary blob, which provides drivers in the linux-firmware package.
Open a terminal and run `sudo dnf install linux-firmware` (or `sudo yum install linux-firmware` in Qubes versions prior to 3.2.1) 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 poses a security risk for your Qubes OS installation.
But if you understand the risk and accept it, read [documentation on multibooting](/doc/multiboot/),
it begins with an explanation of the risks with such a setup.
### Which version of Qubes am I running?
See [here](/doc/version-scheme/#check-installed-version).
### 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 dnf upgrade` (or `sudo yum upgrade` for Qubes older than 3.2.1).
### 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. In Qubes R3.x they are not. In R4.x, devices that are automatically added to sys-net and sys-usb on install but do not support FLR will be attached with the no-strict-reset option, but see the related warning in the last sentence in this answer.
A device that does not support reset is not ideal and generally should not be assigned to a VM.
Most likely the offending controller is a USB 3.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.
If the BIOS does not have the option to disable USB 3.0, try running the following command in dom0 to [force USB 2.0 modes for the USB ports][force_usb2]:
lspci -nn | grep USB | cut -d '[' -f3 | cut -d ']' -f1 | xargs -I@ setpci -H1 -d @ d0.l=0
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 in dom0:
- In Qubes R4.x, when attaching the PCI device to the VM (where `<BDF>` can be obtained from running [qvm-pci](/doc/dom0-tools/qvm-pci/)):
qvm-pci attach --persistent --option no-strict-reset=true usbVM dom0:<BDF>
- In Qubes R3.x, by modifying the VM's properties:
qvm-prefs usbVM -s pci_strictreset false
These options allow the VM to ignore the error and the VM will start.
Please review the notes on [this page](/doc/Dom0Tools/QvmPrefs/) and [here](/doc/assigning-devices/) and be aware of the potential risks.
### I assigned a PCI device to a qube, then unassigned it/shut down the qube. Why isn't the device available in dom0?
This is an intended feature.
A device which was previously assigned to a less trusted qube could attack dom0 if it were automatically reassigned there.
In order to re-enable the device in dom0, either:
* Reboot the physical machine.
or
* Go to the sysfs (`/sys/bus/pci`), find the right device, detach it from the pciback driver and attach back to the original driver. Replace `<BDF>` with your device, for example `00:1c.2`:
echo 0000:<BDF> > /sys/bus/pci/drivers/pciback/unbind
MODALIAS=`cat /sys/bus/pci/devices/0000:<BDF>/modalias`
MOD=`modprobe -R $MODALIAS | head -n 1`
echo 0000:<BDF> > /sys/bus/pci/drivers/$MOD/bind
See also [here](/doc/assigning-devices/).
### 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?
The recommended approach is to pass only the specific partition you intend to use from [`sys-usb`](/doc/usb/) to another qube via [qvm-block](/doc/dom0-tools/qvm-block/). They will show up in the destination qube as `/dev/xvd*` and must be mounted manually. Another approach is to attach the entire USB drive to your destination qube. However, this could theoretically lead to an attack because it forces the destination qube to parse the device's partition table. If you believe your device is safe, you may proceed to attach it.
In Qubes 4.0, this is accomplished with the Devices Widget located in the tool tray (default top right corner, look for an icon with a yellow square). From the top part of the list, click on the drive you want to attach, then select the qube to attach it to. Although you can also attach the entire USB device to a qube by selecting it from the bottom part of the list, in general this approach should not be used because you are exposing the target qube to unnecessary additional attack surface.
In Qubes 3.2, you can use the Qubes VM Manager. Simply insert your USB drive, right-click on the desired qube in the Qubes VM Manager list, click Attach/detach block devices, and select your desired action and device.
Although external media such as external hard drives or flash drives plugged in via USB are available in the USB qube, it is not recommended to access them directly from inside the USB qube. 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 workaround 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.
### My HVM in Qubes R4.0 won't let me start/install an OS
I see a screen popup with SeaBios and 4 lines, last one being `Probing EDD (edd=off to disable!... ok`.
From a `dom0` prompt, enter:
qvm-prefs <HVMname> kernel ""
### I keep getting "Failed to synchronize cache for repo" errors when trying to update my Fedora templates
This is general Fedora issue, not a Qubes-specific issue.
Usually, this is due to network problems (especially if downloading updates over Tor) or problems with the download mirrors.
Often, the problem can be resolved by trying again on a different connection (a different Tor circuit, if using Tor) or waiting and trying again later.
Here are some examples of non-Qubes reports about this problem:
- <https://ask.fedoraproject.org/en/question/88086/error-failed-to-synchronize-cache-for-repo-fedora/>
- <https://unix.stackexchange.com/questions/390805/repos-not-working-on-fedora-error-failed-to-synchronize-cache-for-repo-update>
- <https://www.reddit.com/r/Fedora/comments/74nldq/fedora_26_dnf_error_failed_to_synchronize_cache/>
- <https://bugzilla.redhat.com/show_bug.cgi?id=1494178>
- <https://stackoverflow.com/questions/45318256/error-failed-to-synchronize-cache-for-repo-updates>
More examples can be found by searching for "Failed to synchronize cache for repo" (with quotation marks) on your preferred search engine.
### Could you please make my preference the default?
Wouldn't it be great if Qubes were configured just the way you like it by default with all of your favorite programs and settings?
Then you could just install Qubes without having to install any programs in it or adjust any settings!
You might even think that if a particular program or setting works so well for *you*, it would work well for *everyone*, so you'd actually be doing everyone a favor!
The problem is that Qubes has [tens of thousands of different users](/statistics/) with radically different needs and purposes.
There is no particular configuration that will be ideal for everyone (despite how much you might feel that your preference would be better for everyone), so the best we can do is to put power in the hands of users to configure their Qubes installations the way they like (subject to security constraints, of course).
Please don't ask for your favorite program to be installed by default or for some setting that obviously varies by user preference to be changed so that it matches *your* preference.
This is an incredibly selfish attitude that demonstrates a complete lack of consideration for the thousands of other Qubes users who don't happen to share your preferences.
----------
## Developers
### Are there restrictions on the software that the Qubes developers are willing to use?
Yes.
In general, the Qubes developers will not use a piece of software unless there is an *easy* way to verify both its **integrity** and **authenticity**, preferably via PGP signatures (see [Verifying Signatures](/security/verifying-signatures/)).
Specifically:
* If PGP signatures are used, the signing key(s) should have well-publicized fingerprint(s) verifiable via multiple independent channels or be accessible to the developers through a web of trust.
* If the software is security-sensitive and requires communication with the outside world, a "split" implementation is highly preferred (for examples, see [Split GPG](/doc/split-gpg/) and [Split Bitcoin](/doc/split-bitcoin/)).
* If the software has dependencies, these should be packaged and available in repos for a [current, Qubes-supported version](/doc/supported-versions/#templatevms) of Fedora (preferred) or Debian (unless all the insecure dependencies can run in an untrusted VM in a "split" implementation).
* If the software must be built from source, the source code and any builders must be signed.
(Practically speaking, the more cumbersome and time-consuming it is to build from source, the less likely the developers are to use it.)
### 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 the 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).
[force_usb2]: https://www.systutorials.com/qa/1908/how-to-force-a-usb-3-0-port-to-work-in-usb-2-0-mode-in-linux
### Is Secure Boot supported?
UEFI Secure Boot is not supported out of the box as UEFI support in Xen is very basic.
Arguably secure boot reliance on UEFI integrity is not the best design.
The relevant binaries (shim.efi, xen.efi, kernel / initramfs) are not signed by the Qubes Team and secure boot has not been tested.
Intel TXT (used in [Anti Evil Maid](/doc/anti-evil-maid/)) at least tries to avoid or limit trust in BIOS.
See the Heads project [[1]](https://trmm.net/Heads) [[2]](http://osresearch.net/) for a better-designed non-UEFI-based secure boot scheme with very good support for Qubes.

13
about/join.md Normal file
View File

@ -0,0 +1,13 @@
---
layout: sidebar
title: Join
permalink: /join/
---
Joining the Qubes OS Team
=========================
The Qubes OS Project does not currently have any open positions.
This page will be updated when open positions become available.
In the meantime, there are many different ways you can [contribute to the Qubes OS project](/doc/contributing/).

26
about/research.md Normal file
View File

@ -0,0 +1,26 @@
---
layout: default
title: Research
permalink: /research/
redirect_from:
- /doc/qubes-research/
- /en/doc/qubes-research/
- /doc/QubesResearch/
- /wiki/QubesResearch/
---
Here are links to various research papers, projects, and blog posts that relate
to Qubes OS.
{% for category in site.data.research.categories %}
<h3>{{category.name}}</h3>
<ul class="add-top more-bottom">
{% for paper in site.data.research.papers %}
{% if paper.category == category.slug %}
<li>
<a href="{{paper.url}}">{{paper.title}}</a> by {{paper.author}}{% if paper.date %}, {{paper.date}}{% endif %}
</li>
{% endif %}
{% endfor %}
</ul>
{% endfor %}

123
about/screenshots.md Normal file
View File

@ -0,0 +1,123 @@
---
layout: default
title: Screenshots
permalink: /screenshots/
redirect_from:
- /media/
- /doc/QubesScreenshots/
- /wiki/QubesScreenshots/
---
Select Qubes OS Screenshots
===========================
[![r32-xfce-desktop.png](/attachment/wiki/QubesScreenshots/r32-xfce-desktop.png)](/attachment/wiki/QubesScreenshots/r32-xfce-desktop.png)
Beginning with Qubes 3.2, the default desktop environment is Xfce4.
* * * * *
[![r2b2-kde-start-menu.png](/attachment/wiki/QubesScreenshots/r2b2-kde-start-menu.png)](/attachment/wiki/QubesScreenshots/r2b2-kde-start-menu.png)
Starting applications from different domains (AppVMs) is very easy.
* * * * *
[![r2b2-kde-three-domains-at-work.png](/attachment/wiki/QubesScreenshots/r2b2-kde-three-domains-at-work.png)](/attachment/wiki/QubesScreenshots/r2b2-kde-three-domains-at-work.png)
In this example, the word processor runs in the “work” domain, which has been assigned the “green” label. It is fully isolated from other domains, such as the “untrusted” domain (assigned the “red” label -- “Watch out!”, “Danger!”) used for random Web browsing, news reading, as well as from the "work-web" domain (assigned the "yellow" label), which is used for work-related Web browsing that is not security critical. Apps from different domains run in different AppVMs and have different X servers, filesystems, etc. Notice the different color frames (labels) and VM names in the titlebars. These are drawn by the trusted Window Manager running in Dom0, and apps running in domains cannot fake them:
* * * * *
[![r2b3-windows-seamless-1.png](/attachment/wiki/QubesScreenshots/r2b3-windows-seamless-1.png)](/attachment/wiki/QubesScreenshots/r2b3-windows-seamless-1.png)
Qubes Release 2 can also run Windows AppVMs in seamless mode, integrated onto the common Qubes trusted desktop, just like Linux AppVMs! The seamless GUI integration has been introduced in Qubes R2 Beta 3. This requires our dedicated Qubes Windows Support Tools to be installed in the Windows VMs first. The Qubes Windows Tools are proprietary but we distribute the binaries for free with current Qubes OS releases.
* * * * *
[![r2b3-windows-seamless-filecopy.png](/attachment/wiki/QubesScreenshots/r2b3-windows-seamless-filecopy.png)](/attachment/wiki/QubesScreenshots/r2b3-windows-seamless-filecopy.png)
Windows AppVMs are fully integrated with the rest of the Qubes OS system, which includes things such as secure, policy governed, inter-VM file copy, clipboard, and generally our whole elastic qrexec infrastructure for secure inter-VM RPC! Starting with Qubes R2 Beta 3 we also support HVM-based templates allowing to instantly create many Windows AppVMs with shared "root filesystem" from the Template VM (but one should ensure their license allows for such instantiation of the OS in the template). Just like with Linux AppVMs!
* * * * *
[![r2b2-xfce4-programmers-desktop-2.png](/attachment/wiki/QubesScreenshots/r2b2-xfce4-programmers-desktop-2.png)](/attachment/wiki/QubesScreenshots/r2b2-xfce4-programmers-desktop-2.png)
Here we see Xfce4.10 Window Manager running in Dom0 (instead of KDE as on previous screens). Qubes supports customized Xfce4 in dom0 beginning with R2 Beta 2!
* * * * *
[![password-prompt.png](/attachment/wiki/QubesScreenshots/password-prompt.png)](/attachment/wiki/QubesScreenshots/password-prompt.png)
It is always clearly visible to which domain a given window belongs. Here it’s immediately clear that the passphrase-prompting window belongs to some domain with the “green” label. When we look at the titlebar, we see “[work]”, which is the name of the actual domain. Theoretically, the untrusted application (here, the “red” Firefox) beneath the prompt window could draw a similar looking window within its contents. In practice, this would be very hard, because it doesn’t know, e.g., the exact decoration style that is in use. However, if this is a concern, the user can simply try to move the more trusted window onto some empty space on the desktop such that no other window is present beneath it. Or, better yet, use the Expose-like effect (available via a hot-key). A malicious application from an untrusted domain cannot spoof the whole desktop because the trusted Window Manager will never let any domain “own” the whole screen. Its titlebar will always be visible.
* * * * *
[![r2b2-kde-tray-icons.png](/attachment/wiki/QubesScreenshots/r2b2-kde-tray-icons.png)](/attachment/wiki/QubesScreenshots/r2b2-kde-tray-icons.png)
Qubes is all about seamless integration from the user’s point of view. Here you can see how it virtualizes tray icons from other domains. Notice the network icon in a red frame. This icon is in fact managed by the Network Manager running in a separate NetVM. The notes icon (with the green frame around it) has been drawn by the note-taking app running in the work domain (which has the "green" label).
* * * * *
[![r2b2-manager-and-netvm-network-prompt.png](/attachment/wiki/QubesScreenshots/r2b2-manager-and-netvm-network-prompt.png)](/attachment/wiki/QubesScreenshots/r2b2-manager-and-netvm-network-prompt.png)
All the networking runs in a special, unprivileged NetVM. (Notice the red frame around the Network Manager dialog box on the screen above.) This means that in the event that your network card driver, Wi-Fi stack, or DHCP client is compromised, the integrity of the rest of the system will not be affected! This feature requires Intel VT-d or AMD IOMMU hardware (e.g., Core i5/i7 systems).
* * * * *
[![r2b2-software-update.png](/attachment/wiki/QubesScreenshots/r2b2-software-update.png)](/attachment/wiki/QubesScreenshots/r2b2-software-update.png)
Qubes lets you update all the software in all the domains all at once, in a centralized way. This is possible thanks to Qubes' unique TemplateVM technology. Note that the user is not required to shut down any AppVMs (domains) for the update process. This can be done later, at a convenient moment, and separately for each AppVM.
* * * * *
[![copy-paste-1.png](/attachment/wiki/QubesScreenshots/copy-paste-1.png)](/attachment/wiki/QubesScreenshots/copy-paste-1.png) [![copy-paste-2.png](/attachment/wiki/QubesScreenshots/copy-paste-2.png)](/attachment/wiki/QubesScreenshots/copy-paste-2.png)
Qubes supports secure copy-and-paste operations between AppVMs. Only the user can initiate a copy or paste operation using a special key combination (Ctrl-Shift-C/V). Other AppVMs have no access to the clipboard buffer, so they cannot steal data from the clipboard. Only the user decides which AppVM should be given access to the clipboard. (This is done by selecting the destination AppVM’s window and pressing the Ctrl-Shift-V combination.)
* * * * *
[!["r2b2-copy-to-other-appvm-1.png](/attachment/wiki/QubesScreenshots/r2b2-copy-to-other-appvm-1.png)](/attachment/wiki/QubesScreenshots/r2b2-copy-to-other-appvm-1.png) [![r2b2-copy-to-other-appvm-3.png](/attachment/wiki/QubesScreenshots/r2b2-copy-to-other-appvm-3.png)](/attachment/wiki/QubesScreenshots/r2b2-copy-to-other-appvm-3.png)
Qubes also supports secure file copying between AppVMs.
* * * * *
[![r2b2-open-in-dispvm-1.png](/attachment/wiki/QubesScreenshots/r2b2-open-in-dispvm-1.png)](/attachment/wiki/QubesScreenshots/r2b2-open-in-dispvm-1.png) [![r2b2-open-in-dispvm-3.png](/attachment/wiki/QubesScreenshots/r2b2-open-in-dispvm-3.png)](/attachment/wiki/QubesScreenshots/r2b2-open-in-dispvm-3.png)
Qubes' unique Disposable VMs (DispVMs) allow the user to open any file in a disposable VM in a matter of seconds! A file can be edited in a disposable VM, and any changes are projected back onto the original file. Currently, there is no way to mark files to be automatically opened in a disposable VM (one needs to right-click on the file and choose the "Open in Disposable VM" option), but this is planned for the R2 Beta 3 release.
* * * * *
[![r2b2-convert-to-trusted-pdf-3.png](/attachment/wiki/QubesScreenshots/r2b2-convert-to-trusted-pdf-3.png)](/attachment/wiki/QubesScreenshots/r2b2-convert-to-trusted-pdf-3.png) [![r2b2-converting-pdf-2.png](/attachment/wiki/QubesScreenshots/r2b2-converting-pdf-2.png)](/attachment/wiki/QubesScreenshots/r2b2-converting-pdf-2.png)
Qubes provides an advanced infrastructure for programming inter-VM services, such as a PDF converter for untrusted files (which is described in [this article](https://blog.invisiblethings.org/2013/02/21/converting-untrusted-pdfs-into-trusted.html)).
* * * * *
[![r2b1-manager-firewall.png](/attachment/wiki/QubesScreenshots/r2b1-manager-firewall.png)](/attachment/wiki/QubesScreenshots/r2b1-manager-firewall.png)
Qubes provides a dedicated firewall that itself runs in an isolated FirewallVM.
* * * * *
And some more screenshots:
[![r2b2-xfce4-start-menu-3.png](/attachment/wiki/QubesScreenshots/r2b2-xfce4-start-menu-3.png)](/attachment/wiki/QubesScreenshots/r2b2-xfce4-start-menu-3.png)
[![r2b2-kde-red-and-green-terminals.png](/attachment/wiki/QubesScreenshots/r2b2-kde-red-and-green-terminals.png)](/attachment/wiki/QubesScreenshots/r2b2-kde-red-and-green-terminals.png)
[![r2b3-windows-seamless-2.png](/attachment/wiki/QubesScreenshots/r2b3-windows-seamless-2.png)](/attachment/wiki/QubesScreenshots/r2b3-windows-seamless-2.png)
* * * * *
The following screenshots, [courtesy of Qubes user nalu](https://groups.google.com/d/topic/qubes-users/KhfzF19NG1s/discussion), demonstrate some of the ways in which KDE can be customized to work with Qubes:
[![r3rc1-nalu-desktop-1.png](/attachment/wiki/QubesScreenshots/r3rc1-nalu-desktop-1.png)](/attachment/wiki/QubesScreenshots/r3rc1-nalu-desktop-1.png)
[![r3rc1-nalu-desktop-2.png](/attachment/wiki/QubesScreenshots/r3rc1-nalu-desktop-2.png)](/attachment/wiki/QubesScreenshots/r3rc1-nalu-desktop-2.png)
[![r3rc1-nalu-desktop-3.png](/attachment/wiki/QubesScreenshots/r3rc1-nalu-desktop-3.png)](/attachment/wiki/QubesScreenshots/r3rc1-nalu-desktop-3.png)
[![r3rc1-nalu-desktop-4.png](/attachment/wiki/QubesScreenshots/r3rc1-nalu-desktop-4.png)](/attachment/wiki/QubesScreenshots/r3rc1-nalu-desktop-4.png)

70
about/statistics.md Normal file
View File

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

512
about/support.md Normal file
View File

@ -0,0 +1,512 @@
---
layout: sidebar
title: Help, Support, and Mailing Lists
permalink: /support/
redirect_from:
- /help/
- /mailing-lists/
- /doc/mailing-lists/
- /en/doc/mailing-lists/
- /en/doc/qubes-lists/
- /doc/qubes-lists/
- /doc/QubesLists/
- /wiki/QubesLists/
---
Help, Support, and Mailing Lists
================================
Help and support for Qubes OS is available from the [documentation] and the
[mailing lists], which are explained below. The Qubes OS Project does not offer
paid support services.
Staying safe
------------
The Qubes mailing lists are open to the public. The contents of the list are
crawled by search engines and archived by third-party services outside of our
control. Please do not send anything to the mailing lists that you are not
comfortable seeing discussed in public. If confidentiality is a concern, please
use PGP encryption in an off-list email.
The Qubes community includes people from all walks of life and from around the
world. Individuals differ in areas of experience and technical expertise. You
will come into contact with others whose views and agendas differ from your own.
Everyone is free to write what they please, as long as it doesn't violate our
[Code of Conduct][coc]. Be friendly and open, but do not believe everything you
read. Use good judgment, and be especially careful when following instructions
(e.g., copying commands) given by others on the lists.
All official announcements from the [Qubes team] will be signed by the PGP key
belonging to the team member who sends the announcement. However, anyone on the
list can choose to sign their messages, so the presence of a PGP signature does
not indicate authority. How, then, should you sort the good advice from the bad?
This is up to each individual to decide, but it helps to know that many members
of our community have proven themselves knowledgeable through their
[contributions] to the project. Typically, these individuals sign their messages
with the same key as (or another key authenticated by) the one they use to
[sign their contributions][code-signing].
For example, you might find it easier to trust advice from someone who has a
proven track record of [contributing software packages] or [contributing to the
documentation]. It's unlikely that individuals who have worked hard to build
good reputations for themselves through their contributions over the years would
risk giving malicious advice in signed messages to public mailing lists. Since
every contribution to the Qubes OS Project is publicly visible and
cryptographically signed, anyone would be in a position to [verify] that these
came from the same keyholder.
Discussion list guidelines
--------------------------
Qubes discussions mainly take place on two mailing lists: `qubes-users` and
`qubes-devel`, both of which are explained below. Please send all questions
regarding Qubes to one of these two lists. **Please do not send questions to
individual Qubes developers.** By sending a message to the appropriate mailing
list, you are not only giving others a chance to help you, but you may also be
helping others by starting a public discussion about a shared problem or
interest.
These are open mailing lists where people freely come together to discuss Qubes
and voluntarily help each other out of mutual interest and good will. They are
*not* your personal, paid support service. **No one owes you a reply.** No one
here is responsible for solving your problems for you. Nonetheless, there are
many things you can do to make it more likely that you will receive a reply.
This community is fortunate to have an exceptionally large number of friendly
and knowledgeable people who enjoy corresponding on these lists. The vast
majority of them will be happy to help you if you follow these simple
guidelines.
### Be polite and respectful ###
Remember, no one here is under any obligation
to reply to you. Think about your readers. Most of them are coming home after
a long, hard day at work. The last thing they need is someone's temper
tantrum in their inboxes. If you are rude and disrespectful, you are very
likely to be ignored.
### Be concise ###
Include only essential information. Most of your readers lead
busy lives and have precious little time. We *want* to spend some of that
time helping you, if we can. But if you ramble, it will be easier to skip
over you and help someone else who gets right to the point.
### Help us help you ###
Tell us what you've already tried, and which
documentation pages you've already read. Put yourself in your readers' shoes.
What essential information would they require in order to be able to help
you? Make sure to include that information in your message. [Ask
questions the smart way.][smart-questions]
### Be patient ###
Do not "bump" a thread more than once every three days *at
most*. If it seems like your messages to the mailing lists are consistently
being ignored, make sure you're following the guidelines explained on this
page. If you're already doing so but still not getting any replies, then it's
likely that no one who knows the answer has had time to reply yet. Remember
that the devs are very busy working on Qubes. They usually only have a chance
to answer questions on the mailing lists once every several days.
### Be a good community member ###
As with any social community, members of the
mailing list earn different reputations for themselves over time. We want the
mailing lists to be a friendly, productive place where information and ideas
are exchanged for the mutual benefit of all. We understand that the best way
to achieve this is to encourage and cultivate other like-minded individuals.
Those who have shown themselves to be good community members through their
past contributions have earned our good will, and we will be especially eager
to help them and collaborate with them. If you are new to the community, you
should understand that it will take time for you to earn the good will of
others. This does not mean that you will not receive help. On the contrary,
we are fortunate to have such a helpful and understanding community that many
of them spend hours of their personal time helping complete strangers,
including many who post to the lists anonymously. (Given the integration of
Qubes with [Whonix], we understand better than most the complexities of
privacy and anonymity, and we know that many users have no other choice but
to post anonymously.) You can read our project's [Code of Conduct][coc] for
more information.
### Report issues and submit changes in the right places ###
The mailing lists a good place to ask questions and discuss bugs and feature
requests. However, if you're submitting a more formal report, we'd prefer
that you submit it to our [issue tracker] so that it doesn't get overlooked.
Likewise, if you see that something in the documentation should be changed,
don't simply point it out in an email to one of the mailing lists. Instead,
[submit the change][contributing to the documentation].
### Specific rules and notes ###
#### Use the correct list ####
Send your message to the correct list. Read the sections below to determine
which list is correct for your message.
#### Do not top-post ####
[Top-posting] is placing your reply above the quoted message to which you're
replying. Please refrain from doing this. Instead, either [interleave] your
reply by placing parts of your message immediately below each quoted portion
to which it is replying, or [bottom-post] by placing your entire reply below
the quoted message to which you're replying.
#### Use proper subject lines ####
Include a precise and informative subject line. This will allow others to
easily find your thread in the future and use it as a reference. (Bad: "Help!
Qubes problems!" Good: "R2B2 Installation problem: Apple keyboard not working
in installer.")
#### Do not send duplicates ####
If your message is not successfully sent to the list, it probably got caught
in the spam filter. We check the spam filter regularly, so please be patient,
and your message should be approved (and your email address added to the
whitelist) within a few days.
#### Keep the list CCed ####
Keep the mailing list CCed throughout the conversation unless there's a
special need for privacy (in which case, use PGP encryption). This increases
the likelihood that a greater quantity of useful information will be
available to everyone in the future.
#### Quote appropriately ####
If you're replying to a thread (whether your own or
someone else's), you should make sure to quote enough from previous messages
in the thread so that people reading your message can understand the context
without having to find and read earlier messages from that thread. Each reply
should continue the conversation and, ideally, be readable as a conversation
in itself. Do not quote advertisements in signatures or inline PGP signature
blocks. (Quoting the latter interferes with the ability of programs like
Enigmail to properly quote replies thereafter).
#### English not required ####
If you do not speak English, you should feel free to post in your own
language. However, bear in mind that most members of the list can only read
English. You may wish to include an automated translation in your message out
of consideration for those readers. If you choose to write in English, please
do not apologize for doing so poorly, as it is unnecessary. We understand and
will ask for clarification if needed.
#### Suggestions ####
While we're generally open to hearing suggestions for new features, please
note that we already have a pretty well defined [roadmap], and it's rather
unlikely that we will change our schedule in order to accommodate your
request. If there's a particular feature you'd like to see in Qubes, a much
more effective way to make it happen is to contribute a patch that implements
it. We happily accept such contributions, provided they meet our standards.
Please note, however, that it's always a good idea to field a discussion of
your idea on the `qubes-devel` list before putting in a lot of hard work on
something that we may not be able or willing to accept.
#### Mailing lists vs. forums ####
While the mailing lists are implemented as Google Group web forums, a Google
account is in no way required, expected, or encouraged. Many discussants
(including most members of the Qubes team) treat these lists as conventional
[mailing lists], interacting with them solely through plain text email with
[MUAs] like [Thunderbird] and [Mutt]. The Google Groups service is just
free infrastructure, and we [distrust the infrastructure]. This is why, for
example, we encourage discussants to use [Split GPG] to sign all of their
messages to the lists, but we do not endorse the use of these Google Groups
as web forums. (There have been many discussions about why the Qubes OS
Project does not maintain a forum. The curious can find these by searching
the list archives.)
qubes-announce
--------------
This is a read-only list for those who wish to receive only very important,
infrequent messages. Only the core Qubes team can post to this list, and only
[Qubes Security Bulletins (QSBs)][qsb] and new Qubes OS releases are announced
here.
### How to subscribe
#### Google Groups
* To subscribe to the list, send a blank email to
`qubes-announce+subscribe@googlegroups.com`.
* Note: A Gmail account is *not* required. Any email address will work.
* To unsubscribe, send a blank email to
`qubes-announce+unsubscribe@googlegroups.com`.
* This list can also be browsed via an optional [Google Groups web
interface][qubes-announce-web].
qubes-users
-----------
### How to use this list
This list is for helping users solve various daily problems with Qubes OS.
Examples of topics or questions suitable for this list include:
* [HCL] reports
* Installation problems
* Hardware compatibility problems
* Questions of the form: "How do I...?"
### Read these first
Please try searching both the Qubes website and the archives of the mailing
lists before sending a question. In addition, please make sure that you have
read and understood the following basic documentation prior to posting to the
list:
* The [Installation Guide], [System Requirements], and [HCL] (for problems
related to installing Qubes OS)
* The [User FAQ]
* The [documentation] (for questions about how to use Qubes OS)
### How to subscribe and post
#### Google Groups
You don't have to subscribe in order to post to this list. However, subscribing
might nonetheless be desirable, as it ensures that your messages will not be
eaten by the Google Groups spam filter and allows you to receive messages which
were sent directly to the list.
* To subscribe to the list, send a blank email to
`qubes-users+subscribe@googlegroups.com`.
* Note: A Gmail account is *not* required. Any email address will work.
* To post a message to the list, address your email to
`qubes-users@googlegroups.com`.
* Note: You don't have to be subscribed in order to post.
* To unsubscribe, send a blank email to
`qubes-users+unsubscribe@googlegroups.com`.
* This list also has a [Google Groups web interface][qubes-users-web].
* Some users prefer to interact with the mailing list through the web
interface. This has the advantage that it allows you to search and reply to
messages which were sent prior to your subscription to the list. However, a
Google account is required in order to post through this interface.
* You can also search the [traditional mail archive][qubes-users-archive]
#### Gmane
The mailing list is also available via Gmane, a service that provides mailing
lists in the form of newsgroups. This makes it possible for you to subscribe
and read all mails sent to the list without having them all sent to your normal
mail account. To use Gmane, you need a newsreader such as [Thunderbird].
To add Gmane's server to Thunderbird, follow the instructions in
[Mozilla Thunderbird's documentation for how to add
newsgroups][thunderbird-newsgroup].
In the fourth step replace `news.mozilla.org` with `news.gmane.org`.
* To subscribe to the list, click on **Subscribe...** and search for the
newsgroup [`gmane.os.qubes.user`]. Click on the checkbox besides the name
and **OK**.
* You send and reply to mails the same way you would normally.
* To unsubscribe from the list, click on **Subscribe...**
search for the newsgroup [`gmane.os.qubes.user`], uncheck the checkbox, and
click on **OK**. Thunderbird will automatically remove the newsgroup.
qubes-devel
-----------
### How to use this list
This list is primarily intended for people who are interested in contributing to
Qubes or who are willing to learn more about its architecture and
implementation. Examples of topics and questions suitable for this list include:
* Questions about why we made certain architecture or implementation decisions.
* For example: "Why did you implement XYZ this way and not the other way?"
* Questions about code layout and where code is for certain functionality.
* Discussions about proposed new features, patches, etc.
* For example: "I would like to implement feature XYZ."
* Contributed code and patches.
* Security discussions which are relevant to Qubes in some way.
### How to subscribe and post
#### Google Groups
You must be subscribed in order to post to this list.
* To subscribe to the list, send a blank email to
`qubes-devel+subscribe@googlegroups.com`.
* Note: A Gmail account is *not* required. Any email address will work.
* To post a message to the list, address your email to
`qubes-devel@googlegroups.com`.
* Note: You must be subscribed in order to post. If your post does not
appear, please allow time for moderation to occur.
* To unsubscribe, send a blank email to
`qubes-devel+unsubscribe@googlegroups.com`.
* This list has a [Google Groups web interface][qubes-devel-web].
* Some users prefer to interact with the mailing list through the web
interface. This has the advantage that it allows you to search and reply to
messages which were sent prior to your subscription to the list. However, a
Google account is required in order to post through this interface.
* You can also search the [traditional mail archive][qubes-devel-archive]
#### Gmane
The mailing list is also available via Gmane, a service that provides mailing
lists in the form of newsgroups. This makes it possible for you to subscribe
and read all mails sent to the list without having them all sent to your normal
mail account. To use Gmane, you need a newsreader such as [Thunderbird].
To add Gmane's server to Thunderbird, follow the instructions in
[Mozilla Thunderbird's documentation for how to add
newsgroups][thunderbird-newsgroup].
In the fourth step replace `news.mozilla.org` with `news.gmane.org`.
* To subscribe to the list, click on **Subscribe...** and search for the
newsgroup [`gmane.os.qubes.devel`]. Click on the checkbox besides the name
and **OK**.
* You send and reply to mails the same way you would normally.
* To unsubscribe from the list, click on **Subscribe...**
search for the newsgroup [`gmane.os.qubes.devel`], uncheck the checkbox, and
click on **OK**. Thunderbird will automatically remove the newsgroup.
qubes-project
-------------
### How to use this list
This list is for non-technical discussion and coordination around the
Qubes OS project.
Examples of topics or question suitable for this list include:
* Participation (talks, workshops, etc.) at upcoming events
* Project funding applications and strategies
* FOSS governance discussions
* Most Github issues tagged "[business]"
### How to subscribe and post
#### Google Groups
You don't have to subscribe in order to post to this list. However, subscribing
might nonetheless be desirable, as it ensures that your messages will not be
eaten by the Google Groups spam filter and allows you to receive messages which
were sent directly to the list.
* To subscribe to the list, send a blank email to
`qubes-project+subscribe@googlegroups.com`.
* Note: A Gmail account is *not* required. Any email address will work.
* To post a message to the list, address your email to
`qubes-project@googlegroups.com`.
* Note: You don't have to be subscribed in order to post.
* To unsubscribe, send a blank email to
`qubes-project+unsubscribe@googlegroups.com`.
* This list also has a [Google Groups web interface][qubes-project-web].
* Some users prefer to interact with the mailing list through the web
interface. This has the advantage that it allows you to search and reply to
messages which were sent prior to your subscription to the list. However, a
Google account is required in order to post through this interface.
#### Gmane
The mailing list is also available via Gmane, a service that provides mailing
lists in the form of newsgroups. This makes it possible for you to subscribe
and read all mails sent to the list without having them all sent to your normal
mail account. To use Gmane, you need a newsreader such as [Thunderbird].
To add Gmane's server to Thunderbird, follow the instructions in
[Mozilla Thunderbird's documentation for how to add
newsgroups][thunderbird-newsgroup].
In the fourth step replace `news.mozilla.org` with `news.gmane.org`.
* To subscribe to the list, click on **Subscribe...** and search for the
newsgroup [`gmane.os.qubes.project`]. Click on the checkbox besides the name
and **OK**.
* You send and reply to mails the same way you would normally.
* To unsubscribe from the list, click on **Subscribe...**
search for the newsgroup [`gmane.os.qubes.project`], uncheck the checkbox, and
click on **OK**. Thunderbird will automatically remove the newsgroup.
qubes-translation
-----------------
### How to use this list
This list is for discussion around the localization and translation of Qubes OS,
its documentation, and the website.
Examples of topics or question suitable for this list include:
* Questions about or issues with [Transifex], the translation platform we use
* Who is managing localization for a given language
* Most Github issues tagged "[localization]"
### How to subscribe and post
#### Google Groups
You must be subscribed in order to post to this list.
* To subscribe to the list, send a blank email to
`qubes-translation+subscribe@googlegroups.com`.
* Note: A Gmail account is *not* required. Any email address will work.
* To post a message to the list, address your email to
`qubes-translation@googlegroups.com`.
* Note: You don't have to be subscribed in order to post.
* To unsubscribe, send a blank email to
`qubes-translation+unsubscribe@googlegroups.com`.
* This list also has a [Google Groups web interface][qubes-translation-web].
* Some users prefer to interact with the mailing list through the web
interface. This has the advantage that it allows you to search and reply to
messages which were sent prior to your subscription to the list. However, a
Google account is required in order to post through this interface.
[mailing lists]: https://en.wikipedia.org/wiki/Electronic_mailing_list
[Qubes team]: /team/
[contributions]: /doc/contributing/
[code-signing]: /doc/code-signing/
[contributing software packages]: /doc/package-contributions/
[contributing to the documentation]: /doc/doc-guidelines/
[verify]: /security/verifying-signatures/
[qsb]: /security/bulletins/
[qubes-announce-web]: https://groups.google.com/group/qubes-announce
[Top-posting]: https://en.wikipedia.org/wiki/Posting_style#Top-posting
[interleave]: https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
[bottom-post]: https://en.wikipedia.org/wiki/Posting_style#Bottom-posting
[roadmap]: https://github.com/QubesOS/qubes-issues/milestones
[smart-questions]: http://www.catb.org/esr/faqs/smart-questions.html
[Whonix]: /doc/whonix/
[HCL]: /doc/hcl/
[Installation Guide]: /doc/installation-guide/
[System Requirements]: /doc/system-requirements/
[User FAQ]: /faq/#users
[documentation]: /doc/
[MUAs]: https://en.wikipedia.org/wiki/Email_client
[Thunderbird]: https://www.thunderbird.net/
[Mutt]: http://www.mutt.org/
[distrust the infrastructure]: /faq/#what-does-it-mean-to-distrust-the-infrastructure
[Split GPG]: /doc/split-gpg/
[thunderbird-newsgroup]: https://support.mozilla.org/en-US/kb/creating-newsgroup-account
[qubes-users-archive]: https://www.mail-archive.com/qubes-users@googlegroups.com/
[qubes-devel-archive]: https://www.mail-archive.com/qubes-devel@googlegroups.com/
[qubes-users-web]: https://groups.google.com/group/qubes-users
[qubes-devel-web]: https://groups.google.com/group/qubes-devel
[qubes-translation-web]: https://groups.google.com/group/qubes-translation
[qubes-project-web]: https://groups.google.com/group/qubes-project
[`gmane.os.qubes.user`]: http://dir.gmane.org/gmane.os.qubes.user
[`gmane.os.qubes.devel`]: http://dir.gmane.org/gmane.os.qubes.devel
[`gmane.os.qubes.project`]: http://dir.gmane.org/gmane.os.qubes.project
[business]: https://github.com/QubesOS/qubes-issues/issues?utf8=%E2%9C%93&q=is%3Aissue%20is%3Aopen%20label%3Abusiness
[localization]: https://github.com/QubesOS/qubes-issues/issues?utf8=%E2%9C%93&q=is%3Aissue%20is%3Aopen%20label%3Alocalization
[coc]: /code-of-conduct/
[Transifex]: https://www.transifex.com/otf/qubes/
[issue tracker]: /doc/reporting-bugs/

111
about/video-tours.html Normal file
View File

@ -0,0 +1,111 @@
---
layout: default
title: Video Tours of Qubes OS
permalink: /video-tours/
---
<div id="tour">
<div class="row">
<div class="col-lg-12 col-md-12 col-xs-12">
<h2 class="add-bottom">Micah Lee presents "Qubes OS: The Operating System That Can Protect You Even If You Get Hacked"</h2>
<p><a href="https://micahflee.com/">Micah Lee</a>, a long-time Qubes <a href="/experts/">advocate</a>, presented <a href="https://www.hope.net/schedule.html#-qubes-os-the-operating-system-that-can-protect-you-even-if-you-get-hacked-">Qubes OS: The Operating System That Can Protect You Even If You Get Hacked</a> at the <a href="https://www.hope.net/index.html">Circle of HOPE</a> conference, which took place July 20-22, 2018 in New York City.</p>
<iframe id="ls_embed_1533360087" src="https://livestream.com/accounts/9197973/events/8286152/videos/178431606/player?width=960&height=540&enableInfo=true&defaultDrawer=feed&autoPlay=false&mute=false" width="960" height="540" frameborder="0" scrolling="no" allowfullscreen> </iframe>
</div>
</div>
<hr class="more-top more-bottom">
<div class="row">
<div class="col-lg-4 col-md-4 col-xs-12">
<h2>Introduction</h2>
<p>Learn the basics in this introduction to Qubes OS.</p><br>
<a href="/intro/" class="btn btn-primary">
<i class="fa fa-flag"></i> What is Qubes OS?
</a>
</div>
<div class="col-lg-4 col-md-4 col-xs-12">
<h2>Screenshots</h2>
<p>See what using Qubes actually looks like with these screenshots of various applications running in Qubes.</p>
<a href="/screenshots/" class="btn btn-primary">
<i class="fa fa-picture-o"></i> See Screenshots
</a>
</div>
<div class="col-lg-4 col-md-4 col-xs-12">
<h2>Getting Started</h2>
<p>Ready to get started with Qubes? Here's what you need to know after installing.</p>
<a href="/getting-started/" class="btn btn-primary">
<i class="fa fa-cubes"></i> Getting Started
</a>
</div>
</div>
<hr class="more-top more-bottom">
<div class="row">
<div class="col-lg-8 col-md-12 col-xs-12">
<h2 class="add-bottom">A Video Tour of Qubes 3.1 by Matthew Wilson</h2>
<div id="player0"></div>
<p>This video by Matthew Wilson provides an overview of Qubes 3.1. You can use the menu links to browse to specific chapters.</p>
</div>
<div class="col-lg-4 col-md-12 col-xs-12">
<h2 class="add-bottom">&nbsp;</h2>
<ul id="player0-menu" class="list-unstyled remove-bottom">
<li><a href="00:00" class="player0-seek">An Overview of Qubes OS</a></li>
<li><a href="01:47" class="player0-seek">Web browsing with multiple identities</a></li>
<li><a href="05:26" class="player0-seek">Isolating files in different Qubes</a></li>
<li><a href="07:28" class="player0-seek">Moving files between Qubes</a></li>
<li><a href="09:21" class="player0-seek">Using the secure clipboard</a></li>
<li><a href="11:13" class="player0-seek">Web browsing securely in a Disposable Qube</a></li>
<li><a href="13:51" class="player0-seek">Handling untrusted files in a Disposable Qube</a></li>
<li><a href="16:50" class="player0-seek">Exploring the Qubes Manager</a></li>
<li><a href="18:54" class="player0-seek">Templates and App Qubes</a></li>
<li><a href="20:04" class="player0-seek">Installing temporary applications</a></li>
<li><a href="21:57" class="player0-seek">Installing persistent applications</a></li>
<li><a href="24:20" class="player0-seek">Managing the applications menu</a></li>
<li><a href="25:09" class="player0-seek">Creating & using a Standalone Qube</a></li>
<li><a href="26:38" class="player0-seek">Editing settings of a Qube</a></li>
<li><a href="28:40" class="player0-seek">Creating a Qube for added security & privacy</a></li>
<li><a href="29:42" class="player0-seek">Whonix and Tor for privacy & anonymity</a></li>
</ul>
</div>
</div>
<hr class="more-top more-bottom">
<div class="row">
<div class="col-lg-4 col-md-4 col-xs-12">
<h2>Docs</h2>
<p>Dive into the Qubes documentation with guides, tips, and troubleshooting help.</p>
<a href="/doc/" class="btn btn-primary">
<i class="fa fa-book"></i> Documentation
</a>
</div>
<div class="col-lg-4 col-md-4 col-xs-12">
<h2>Downloads</h2>
<p>Download an ISO, verify your download, and install Qubes.</p>
<a href="/downloads/" class="btn btn-primary">
<i class="fa fa-download"></i> Downloads
</a>
</div>
<div class="col-lg-4 col-md-4 col-xs-12">
<h2>Security</h2>
<p>Get PGP keys, security bulletins, and canaries. Learn more about our security practices.</p>
<a href="/security/" class="btn btn-primary">
<i class="fa fa-lock"></i> Security Center
</a>
</div>
</div>
<hr class="more-top more-bottom">
<div class="row">
<div class="col-lg-8 col-md-12 col-xs-12">
<h2 class="add-bottom">French Video Series by Paf LeGeek (6 Parts)</h2>
<div id="player1"></div>
<p>This French series by Paf LeGeek provides a guide to Qubes OS across six videos. You can use the menu links to browse to specific videos in the series.</p>
</div>
<div class="col-lg-4 col-md-12 col-xs-12">
<h2 class="add-bottom">&nbsp;</h2>
<ul id="player1-menu" class="list-unstyled remove-bottom">
<li><a href="q7mCeYCrQ24" class="player1-play">Partie 1: Présentation du projet Qubes OS</a></li>
<li><a href="a8YIVqaP8Lk" class="player1-play">Partie 2: ProxyVM VPN et Tor</a></li>
<li><a href="RcUUAGdAFHo" class="player1-play">Partie 3: Installer Qubes OS</a></li>
<li><a href="Zu9ab7E-Mqk" class="player1-play">Partie 4: Installer Windows 7</a></li>
<li><a href="HgIKtopFZxU" class="player1-play">Partie 5: Créer un coffre fort numérique</a></li>
<li><a href="Yr-oRWtCZGI" class="player1-play">Partie 6: ProxyVM VPN avec kill switch</a></li>
</ul>
</div>
</div>
</div>

96
basics_dev/code-signing.md
View File

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

51
basics_dev/coding-style.md
View File

@ -15,39 +15,39 @@ Coding Guidelines for Qubes Developers
Rationale
---------
Maintaining proper coding style is very important for any larger software project, such as Qubes. Here's why:
Maintaining proper coding style is very important for any large software project, such as Qubes. Here's why:
- It eases maintenance, such as adding new functionality or generalization later,
- It allows others (as well as the original author after some time!) to easily understand fragments of code, what they were supposed to do, and so makes it easier to later extend them with newer functionality or bug fixes,
- It eases maintenance tasks, such as adding new functionality or generalizing code later,
- It allows others (as well as the future you!) to easily understand fragments of code and what they were supposed to do, and thus makes it easier to later extend them with newer functionality or bug fixes,
- It allows others to easily review the code and catch various bugs,
- It provides for an aesthetically pleasing experience when one reads the code...
Often, developers, usually smart developers, neglect the value of proper coding style, thinking that it's most important how their code works, and expecting that if it solves some problem using a nice and neat trick, then it's all that is really required. Such thinking shows, however, immaturity and is a signal that the developer, however bright and smart, might not be a good fit for any larger project. Writing a clever exploit, that is to be used at one Black Hat show is one thing, while writing a useful software that is to be used and maintained for years, is quite a different story. If you want to show off what a smart programmer you are, then you should become a researcher and write exploits. If, on the other hand, you want to be part of a team that makes real, useful software, you should ensure your coding style is impeccable. We often, at Qubes project, often took shortcuts, and often wrote nasty code, and this always back fired at us, sometime months, sometime years later, the net result being we had to spend time fixing code, rather than implementing new functionality.
Often, developers, usually smart ones, undersell the value of proper coding style, thinking that it's much more important how their code works. These developers expect that if their code solves some problem using a nice and neat trick, then that's all that is really required. Such thinking shows, however, immaturity and is a signal that the developer, no matter how bright and smart, might not be a good fit for larger projects. Writing a clever exploit for a Black Hat show is one thing - writing useful software supposed to be used and maintained for years is quite a different story. If you want to show off what a smart programmer you are, then you should become a researcher and write exploits. If, on the other hand, you want to be part of a team that makes real, useful software, you should ensure your coding style is impeccable. At Qubes project, we often took shortcuts and wrote nasty code, and this has always back fired at us, sometime months, sometime years later, the net result being we had to spend time fixing code, rather than implementing new functionality.
And here's a [link to the real case](https://groups.google.com/forum/#!msg/qubes-devel/XgTo6L8-5XA/JLOadvBqnqMJ) (one Qubes Security Bulletin) demonstrating how the above described problem lead to a real security bug. Never assume you're smart enough that you can disregard clean and rigorous coding!
And here's a [link to the real case](https://groups.google.com/forum/#!msg/qubes-devel/XgTo6L8-5XA/JLOadvBqnqMJ) (one Qubes Security Bulletin) demonstrating how the lackadaisical coding style lead to a real security bug. Never assume you're smart enough to disregard clean and rigorous coding!
General typographic conventions
-------------------------------
- **Use space-expanded tabs that equal 4 spaces.** Yes, we know, there are many arguments for using "real" tabs, instead of space-expanded tabs, but we need to pick one convention to make the project consistent. One argument for using space-expanded tabs is that this way the programmer is in control of how the code will look like, despite how other users have configured their editors to visualize the tabs (of course, we assume any sane person uses a fixed-width font for viewing the source code). Anyway, if this makes you feel better, assume this is just an arbitrary choice.
- **Use space-expanded tabs that equal 4 spaces.** Yes, we know, there are many arguments for using "real" tabs instead of space-expanded tabs, but we need to pick one convention to make the project consistent. One argument for using space-expanded tabs is that this way the programmer is in control of how the code will look like, despite how other users have configured their editors to visualize the tabs (of course, we assume any sane person uses a fixed-width font for viewing the source code). If it makes you feel any better, assume this is just an arbitrary choice made to enforce a unified style.
- **Maintain max. line length of 80 characters**. Even though today's monitors often are very wide and it's often not a problem to have 120 characters displayed in an editor, still maintaining shorter line lengths improves readability. It also allows to have two parallel windows open, side by side, each with different parts of the source code.
- **Maintain max. line length of 80 characters**. Even though today's monitors often are very wide and it's often not a problem to have 120 characters displayed in an editor, maintaining shorter line lengths improves readability. It also allows others to have two parallel windows open, side by side, each with different parts of the source code.
- Class, functions, variables, and arguments naming convention for any OS other than Windows:
- **Naming conventions for any OS *other than Windows***:
- `ClassName`
- `some_variable`, `some_function`, `some_argument`
- Class, functions, variables, and arguments naming convention for **Windows OS** -- exceptionally to preserve Windows conventions please use the following:
- **Naming convention *for Windows OS*** -- exceptionally to preserve Windows conventions please use the following:
- `ClassName`, `FunctionName`
- `pszArgumentOne`, `hPipe` -- use Hungarian notation for argument and variables
- Horizontal spacing -- maintain at least decent amount of horizontal spacing, such as e.g. add obligatory space after `if` or before `{` in C, and similar in other languages. Whether to also use spaces within expressions, such as (x\*2+5) vs. (x \* 2 + 5) is left to the developer's judgment. Do not put spaces immediately after and before the brackets in expressions, so avoid constructs like this: `if ( condition )` and use `if (condition)` instead.
- **Maintain a decent amount of horizontal spacing**, e.g. add a space after `if` or before `{` in C, and similar in other languages. Whether and where to also use spaces within expressions, such as (x\*2+5) vs. (x \* 2 + 5) is left to the developer's judgment. Do not put spaces immediately after or before the brackets in expressions, so avoid constructs like this: `if ( condition )` and use ones like this: `if (condition)` instead.
- **Use single new lines** ('\\n' aka LF) in any non-Windows source code. On Windows, exceptionally, use the CRLF line endings -- this will allow the source code to be easily view-able in various Windows-based programs.
- **Use single new lines** ('\\n' aka LF) in any non-Windows source code. On Windows, exceptionally, use the CRLF line endings (--). This will allow the source code to be easily viewable in various Windows-based programs.
- **Use descriptive names for variables and functions**! Really, these days, when most editors have auto-completion feature, there is no excuse for using short variable names.
- **Use descriptive names for variables and functions**! Really, at a time when most editors have auto-completion features, there is no excuse for using short variable names.
- Comments should be indent together with the code, e.g. like this:
- **Comments should be indented together with the code**, e.g. like this:
~~~
for (...) {
@ -78,7 +78,7 @@ File naming conventions
**File naming in Windows systems:**
- All base qubes-related files in `C:\Program Files\Invisible Things Lab\Qubes\` (Exceptionally spaces are allowed here to adhere to Windows naming conventions)
- Other, 3rd party files, not Qubes-specific, such as e.g. Xen PV drivers might be in different vendor subdirs, e.g. `C:\Program Files\Xen PV Drivers`
- Other, third-party files, not Qubes-specific, such as e.g. Xen PV drivers might be in different vendor subdirs, e.g. `C:\Program Files\Xen PV Drivers`
General programming style guidelines
------------------------------------
@ -97,7 +97,7 @@ General programming style guidelines
}
~~~
- Do **not** use comments to disable code fragments. In a production code there should really be no commented or disabled code fragments. If you really, really have a good reason to retain some fragment of unused code, use \#if or \#ifdef to disable it, e.g.:
- Do **not** use comments to disable code fragments. In production code there should really be no commented or disabled code fragments. If you really, really have a good reason to retain some fragment of unused code, use \#if or \#ifdef to disable it, e.g.:
~~~
#if 0
@ -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 changed 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
--------------------------
@ -150,7 +165,7 @@ Security coding guidelines
height = untrusted_conf.height;
~~~
- Use another variables, without the `untrusted_` prefix to hold the sanitized values, as shown above.
- Use others variables, without the `untrusted_` prefix to hold the sanitized values, as shown above.
Python-specific guidelines
--------------------------
@ -163,7 +178,7 @@ C and C++ specific guidelines
- Do not place code in `*.h` files.
- Use `const` whenever possible, e.g. in function arguments passed via pointers.
- Do not mix procedural and objective code together -- if you write in C++, use classes and objects.
- Think about classes hierarchy, before start implementing specific methods.
- Think about classes hierarchy, before starting to implement specific methods.
Bash-specific guidelines
------------------------

34
basics_dev/contributing.md
View File

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

26
basics_dev/devel-books.md
View File

@ -10,20 +10,20 @@ redirect_from:
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)
- 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 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)
- 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 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)
- 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:
- [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)
- 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.)

47
basics_dev/devel-faq.md
View File

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

168
basics_dev/doc-guidelines.md
View File

@ -1,168 +0,0 @@
---
layout: doc
title: Documentation Guidelines
permalink: /doc/doc-guidelines/
redirect_from:
- /en/doc/doc-guidelines/
- /wiki/DocStyle/
- /doc/DocStyle/
---
Documentation Guidelines
========================
All Qubes OS documentation pages are stored as plain text files in the
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
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.
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
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.
How to Contribute
-----------------
Editing the documentation is easy, so if you spot any errors, please help us
fix them! (As mentioned above, the documentation maintainers are just volunteers
who have day jobs of their own, so we rely heavily on the community to improve
the documentation.) Since Qubes is a security-oriented project, every
documentation change will be reviewed before it's published to the web. This
allows us to maintain quality control and protect our users.
As mentioned above, we keep all the documentation in a dedicated [Git
repository][qubes-doc] hosted on [GitHub]. Thanks to GitHub interface, you can
edit the documentation even if you don't know Git at all! The only thing you
need is a GitHub account, which is free.
(Note: If you're already familiar with GitHub or wish to work from the command
line, you can skip the rest of this section. All you need to do to contribute is
to [fork and clone][gh-fork] the [qubes-doc] repo, make your changes, then
[submit a pull request][gh-pull].)
Ok, let's start. Every documentation page has an "Edit this page" button. It may
be on the right side (in the desktop layout):
![edit-button-desktop](/attachment/wiki/doc-edit/03-button2.png)
Or at the bottom (in the mobile layout):
![edit-button-mobile](/attachment/wiki/doc-edit/02-button1.png)
When you click on it, you'll be prompted for your GitHub username and password
(if you aren't already logged in). You can also create an account from here.
![github-sign-in](/attachment/wiki/doc-edit/04-sign-in.png)
If this is your first contribution to the documentation, you need to "fork" the
repository (make your own copy). It's easy --- just click the big green button
on the next page. This step is only needed the first time you make a
contribution.
![fork](/attachment/wiki/doc-edit/05-fork.png)
Now you can make your modifications. You can also preview the changes to see how
they'll be formatted by clicking the "Preview changes" tab.
![edit](/attachment/wiki/doc-edit/06-edit.png)
Once you're finish, describe your changes at the bottom and click "Propose file
change".
![commit](/attachment/wiki/doc-edit/07-commit-msg.png)
After that, you'll see exactly what modifications you've made. At this stage,
those changes are still in your own copy of the documentation ("fork"). If
everything looks good, send those changes to us by pressing the "Create pull
request" button.
![pull-request](/attachment/wiki/doc-edit/08-review-changes.png)
You will be able to adjust the pull request message and title there. In most
cases, the defaults are ok, so you can just confirm by pressing the "Create pull
request" button again.
![pull-request-confirm](/attachment/wiki/doc-edit/09-create-pull-request.png)
That's all! We will review your changes. If everything looks good, we'll pull
them into the official documentation. Otherwise, we may have some questions for
you, which we'll post in a comment on your pull request. (GitHub will
automatically notify you if we do.) If, for some reason, we can't accept your
pull request, we'll post a comment explaining why we can't.
![done](/attachment/wiki/doc-edit/10-done.png)
Style Guidelines
----------------
* Familiarize yourself with the terms defined in the [glossary]. Use these
terms consistently and accurately throughout your writing.
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.
[qubes-doc]: https://github.com/QubesOS/qubes-doc
[glossary]: /doc/glossary/
[report]: #how-to-report-issues
[contribute]: #how-to-contribute
[qubes-issues]: https://github.com/QubesOS/qubes-issues/issues
[gh-fork]: https://guides.github.com/activities/forking/
[gh-pull]: https://help.github.com/articles/using-pull-requests/
[GitHub]: https://github.com/
[md]: https://daringfireball.net/projects/markdown/
[git-commit]: http://chris.beams.io/posts/git-commit/

529
basics_dev/gsoc.md Normal file
View File

@ -0,0 +1,529 @@
---
layout: sidebar
title: Google Summer of Code
permalink: /gsoc/
redirect_from: /GSoC/
---
2018 Google Summer of Code
================
## Information for Students
Thank you for your interest in participating in the [Google Summer of Code program][gsoc-qubes] with the [Qubes OS team][team]. You can read more about the Google Summer of Code program at the [official website][gsoc] and the [official FAQ][gsoc-faq].
Being accepted as a Google Summer of Code student is quite competitive. Students wishing to participate in the Summer of Code must be aware that you will be required to produce code for Qubes OS for 3 months. Your mentors, Qubes developers, will dedicate a portion of their time towards mentoring you. Therefore, we seek candidates who are committed to helping Qubes long-term and are willing to do quality work and be proactive in communicating with your mentor.
You don't have to be a proven developer -- in fact, this whole program is meant to facilitate joining Qubes and other free and open source communities. The Qubes community maintains information about [contributing to Qubes development][contributing] and [how to send patches][patches]. In order to contribute code to the Qubes project, you must be able to [sign your code][code-signing].
You should start learning the components that you plan on working on before the start date. Qubes developers are available on the [mailing lists][ml-devel] for help. The GSoC timeline reserves a lot of time for bonding with the project -- use that time wisely. Good communication is key, you should plan to communicate with your team daily and formally report progress and plans weekly. Students who neglect active communication will be failed.
You can view the projects we had in 2017 in the [GSoC archive here][2017-archive].
### Overview of Steps
- Join the [qubes-devel list][ml-devel] and introduce yourself, and meet your fellow developers
- Read [Google's instructions for participating][gsoc-participate] and the [GSoC Student Manual][gsoc-student]
- Take a look at the list of ideas below
- Come up with a project that you are interested in (and feel free to propose your own! Don't feel limited by the list below.)
- Read the Student Proposal guidelines below
- Write a first draft proposal and send it to the qubes-devel mailing list for review
- Submit proposal using [Google's web interface][gsoc-submit] ahead of the deadline (this requires a Google Account!)
- Submit proof of enrollment well ahead of the deadline
Coming up with an interesting idea that you can realistically achieve in the time available to you (one summer) is probably the most difficult part. We strongly recommend getting involved in advance of the beginning of GSoC, and we will look favorably on applications from students who have already started to act like free and open source developers.
Before the summer starts, there are some preparatory tasks which are highly encouraged. First, if you aren't already, definitely start using Qubes as your primary OS as soon as possible! Also, it is encouraged that you become familiar and comfortable with the Qubes development workflow sooner than later. A good way to do this (and also a great way to stand out as an awesome applicant and make us want to accept you!) might be to pick up some issues from [qubes-issues][qubes-issues] (our issue-tracking repo) and submit some patches addressing them. Some suitable issues might be those with tags ["help wanted" and "P: minor"][qubes-issues-suggested] (although more significant things are also welcome, of course). Doing this will get you some practice with [qubes-builder][qubes-builder], our code-signing policies, and some familiarity with our code base in general so you are ready to hit the ground running come summer.
### Student proposal guidelines
A project proposal is what you will be judged upon. Write a clear proposal on what you plan to do, the scope of your project, and why we should choose you to do it. Proposals are the basis of the GSoC projects and therefore one of the most important things to do well. The proposal is not only the basis of our decision of which student to choose, it has also an effect on Google's decision as to how many student slots are assigned to Qubes.
Below is the application template:
```
# Introduction
Every software project should solve a problem. Before offering the solution (your Google Summer of Code project), you should first define the problem. What’s the current state of things? What’s the issue you wish to solve and why? Then you should conclude with a sentence or two about your solution. Include links to discussions, features, or bugs that describe the problem further if necessary.
# Project goals
Be short and to the point, and perhaps format it as a list. Propose a clear list of deliverables, explaining exactly what you promise to do and what you do not plan to do. “Future developments” can be mentioned, but your promise for the Google Summer of Code term is what counts.
# Implementation
Be detailed. Describe what you plan to do as a solution for the problem you defined above. Include technical details, showing that you understand the technology. Illustrate key technical elements of your proposed solution in reasonable detail.
# Timeline
Show that you understand the problem, have a solution, have also broken it down into manageable parts, and that you have a realistic plan on how to accomplish your goal. Here you set expectations, so don’t make promises you can’t keep. A modest, realistic and detailed timeline is better than promising the impossible.
If you have other commitments during GSoC, such as a job, vacation, exams, internship, seminars, or papers to write, disclose them here. GSoC should be treated like a full-time job, and we will expect approximately 40 hours of work per week. If you have conflicts, explain how you will work around them. If you are found to have conflicts which you did not disclose, you may be failed.
Open and clear communication is of utmost importance. Include your plans for communication in your proposal; daily if possible. You will need to initiate weekly formal communications such as a detailed email to the qubes-devel mailing list. Lack of communication will result in you being failed.
# About me
Provide your contact information and write a few sentences about you and why you think you are the best for this job. Prior contributions to Qubes are helpful; list your commits. Name people (other developers, students, professors) who can act as a reference for you. Mention your field of study if necessary. Now is the time to join the relevant mailing lists. We want you to be a part of our community, not just contribute your code.
Tell us if you are submitting proposals to other organizations, and whether or not you would choose Qubes if given the choice.
Other things to think about:
* Are you comfortable working independently under a supervisor or mentor who is several thousand miles away, and perhaps 12 time zones away? How will you work with your mentor to track your work? Have you worked in this style before?
* If your native language is not English, are you comfortable working closely with a supervisor whose native language is English? What is your native language, as that may help us find a mentor who has the same native language?
* After you have written your proposal, you should get it reviewed. Do not rely on the Qubes mentors to do it for you via the web interface, although we will try to comment on every proposal. It is wise to ask a colleague or a developer to critique your proposal. Clarity and completeness are important.
```
## Project Ideas
These project ideas were contributed by our developers and may be incomplete. If you are interested in submitting a proposal based on these ideas, you should contact the [qubes-devel mailing list][ml-devel] and associated GitHub issue to learn more about the idea.
```
### Adding a Proposal
**Project**: Something that you're totally excited about
**Brief explanation**: What is the project, where does the code live?
**Expected results**: What is the expected result in the timeframe given
**Knowledge prerequisite**: Pre-requisites for working on the project. What coding language and knowledge is needed?
If applicable, links to more information or discussions
**Mentor**: Name and email address.
```
### Template manager, new template distribution mechanism
**Project**: Template manager, new template distribution mechanism
**Brief explanation**: Template VMs currently are distributed using RPM
packages. There are multiple problems with that, mostly related to static
nature of RPM package (what files belong to the package). This means such
Template VM cannot be renamed, migrated to another storage (like LVM), etc.
Also we don't want RPM to automatically update template package itself (which
would override all the user changes there). More details:
[#2064](https://github.com/QubesOS/qubes-issues/issues/2064),
[#2534](https://github.com/QubesOS/qubes-issues/issues/2534).
**Expected results**:
- Design new mechanism for distributing templates (possibly including some
package format - either reuse something already existing, or design
new one). The mechanism needs to handle:
- integrity protection (digital signatures), not parsing any data in dom0
prior to signature verification
- efficient handling of large sparse files
- ability to deploy the template into various storage mechanisms (sparse
files, LVM thin volumes etc).
- template metadata, templates repository - enable the user to browse
available templates (probably should be done in dedicated VM, or Disposable VM)
- Implement the above mechanism:
- tool to download named template - should perform download operation in
some VM (as dom0 have no network access), then transfer the data to dom0,
verify its integrity and then create Template VM and feed it's root
filesystem image with downloaded data.
- tool to browse templates repository - both CLI and GUI (preferably in (py)GTK)
- integrate both tools - user should be able to choose some template to be
installed from repository browsing tool - see
[#1705](https://github.com/QubesOS/qubes-issues/issues/1705) for some idea
(this one lack integrity verification, but similar service could
be developed with that added)
- If new "package" format is developed, add support for it into
[linux-template-builder](https://github.com/QubesOS/qubes-linux-template-builder).
- Document the mechanism.
- Write unit tests and integration tests.
**Knowledge prerequisite**:
- Large files (disk images) handling (sparse files, archive formats)
- Bash and Python scripting
- Data integrity handling - digital signatures (gpg2, gpgv2)
- PyGTK
- RPM package format, (yum) repository basics
**Mentor**: [Marek Marczykowski-Górecki](/team/)
### Easy inter-VM networking configuration
**Project**: Easy inter-VM networking configuration
**Brief explanation**: Utility to easily configure selected VMs to be reachable (by network) from other VMs or outside network. Currently such configuration require adding iptables rules in multiple VMs manually. For exposing VM to outside network, it may be good to adopt qrexec-based TCP forwarding ([#2148](https://github.com/QubesOS/qubes-issues/issues/2148)).
**Expected results**:
- support firewall rules for inter-VM traffic in qubes-firewall - both VM side (qubes-firewall service) and dom0 configuration side (relevant Admin API calls)
- mechanism for configuring firewall in target VM, especially INPUT iptables chain - currently it is hardcoded to drop new incoming connections
- convenient tool (or modification to existing tool) for controlling above mechanisms
- integration the above with existing GUI tools (especially VM settings)
Relevant links:
- [Qubes networking and firewall documentation](/doc/firewall/)
- [qubes-firewall service code](https://github.com/QubesOS/qubes-core-agent-linux/blob/master/qubesagent/firewall.py)
**Knowledge prerequisite**:
- iptables
- basics of nft
- python3
**Mentor**: [Marek Marczykowski-Górecki](/team/)
### Mechanism for maintaining in-VM configuration
**Project**: Mechanism for maintaining in-VM configuration
**Brief explanation**: Large number of VMs is hard to maintain. Templates helps with keeping them updated, but many applications have configuration in user home directory, which is not synchronized.
**Expected results**:
- Design a mechanism how to _safely_ synchronize application configuration living in user home directory (`~/.config`, some other "dotfiles"). Mechanism should be resistant against malicious VM forcing its configuration on other VMs. Some approach could be a strict control which VM can send what changes (whitelist approach, not blacklist).
- Implementation of the above mechanism.
- Documentation how to configure it securely.
**Knowledge prerequisite**:
- shell and/or python scripting
- Qubes OS qrexec services
**Mentor**: [Marek Marczykowski-Górecki](/team/), [Wojtek Porczyk](/team/).
### Wayland support in GUI agent and/or GUI daemon
**Project**: Wayland support in GUI agent and/or GUI daemon
**Brief explanation**: Currently both GUI agent (VM side of the GUI virtualization) and GUI daemon (dom0 side of GUI virtualization) support X11 protocol only. It may be useful to add support for Wayland there. Note that those are in fact two independent projects:
1. GUI agent - make it work as Wayland compositor, instead of extracting window's composition buffers using custom X11 driver
2. GUI daemon - act as Wayland application, showing windows retrieved from VMs, keeping zero-copy display path (window content is directly mapped from application running in VM, not copied)
**Expected results**:
Choose either of GUI agent, GUI daemon. Both are of similar complexity and each separately looks like a good task for GSoC time period.
- design relevant GUI agent/daemon changes, the GUI protocol should not be affected
- consider window decoration handling - VM should have no way of spoofing those, so it must be enforced by GUI daemon (either client-side - by GUI daemon itself, or server-side, based on hints given by GUI daemon)
- implement relevant GUI agent/daemon changes
- implement tests for new GUI handling, similar to existing tests for X11 based GUI
Relevant links:
- [Low level GUI documentation](/doc/gui/)
- [qubes-gui-agent-linux](https://github.com/qubesos/qubes-gui-agent-linux)
- [qubes-gui-daemon](https://github.com/qubesos/qubes-gui-daemon)
- [Use Wayland instead of X11 to increase performance](https://github.com/qubesos/qubes-issues/issues/3366)
**Knowledge prerequisite**:
- Wayland architecture
- basics of X11 (for understanding existing code)
- C language
- using shared memory (synchronization methods etc)
**Mentor**: [Marek Marczykowski-Górecki](/team/).
### Qubes Live USB
**Project**: Revive Qubes Live USB, integrate it with installer
**Brief explanation**: Qubes Live USB is based on Fedora tools to build live
distributions. But for Qubes we need some adjustments: starting Xen instead of
Linux kernel, smarter copy-on-write handling (we run there multiple VMs, so a
lot more data to save) and few more. Additionally in Qubes 3.2 we have
so many default VMs that default installation does not fit in 16GB image
(default value) - some subset of those VMs should be chosen. Ideally we'd like
to have just one image being both live system and installation image. More
details: [#1552](https://github.com/QubesOS/qubes-issues/issues/1552),
[#1965](https://github.com/QubesOS/qubes-issues/issues/1965).
**Expected results**:
- Adjust set of VMs and templates included in live edition.
- Update and fix build scripts for recent Qubes OS version.
- Update startup script to mount appropriate directories as either
copy-on-write (device-mapper snapshot), or tmpfs.
- Optimize memory usage: should be possible to run sys-net, sys-firewall, and
at least two more VMs on 4GB machine. This include minimizing writes to
copy-on-write layer and tmpfs (disable logging etc).
- Research option to install the system from live image. If feasible add
this option.
**Knowledge prerequisite**:
- System startup sequence: bootloaders (isolinux, syslinux, grub, UEFI), initramfs, systemd.
- Python and Bash scripting
- Filesystems and block devices: loop devices, device-mapper, tmpfs, overlayfs, sparse files.
**Mentor**: [Marek Marczykowski-Górecki](/team/)
### Unikernel-based firewallvm with Qubes firewall settings support
**Project**: Unikernel based firewallvm with Qubes firewall settings support
**Brief explanation**: [blog post](http://roscidus.com/blog/blog/2016/01/01/a-unikernel-firewall-for-qubesos/), [repo](https://github.com/talex5/qubes-mirage-firewall)
**Expected results**: A firewall implemented as a unikernel which supports all the networking-related functionality as the default sys-firewall VM, including configuration via Qubes Manager. Other duties currently assigned to sys-firewall such as the update proxy may need to be appropriately migrated first.
**Knowledge prerequisite**:
- [OCaml](https://ocaml.org/) + [MirageOS](https://mirage.io/) or other unikernel framework,
- Xen network stack,
- Qubes networking model & firewall semantics.
**Mentor**: [Thomas Leonard](mailto:talex5@gmail.com), [Marek Marczykowski-Górecki](/team/)
### Thunderbird, Firefox and Chrome extensions
**Project**: additional Thunderbird, Firefox and Chrome extensions
**Brief explanation**:
* browser/mail: open link in vm
* browser/mail: open link in dispvm
* browser: save destination to vm
* mail: add whitelisted senders option (address-based and signing key-based) [#845](https://github.com/QubesOS/qubes-issues/issues/845)
**Expected results**:
- Extend existing Thunderbird extension to decide on action (where to open/save attachments) based on message sender - recognized as email address, or signing key
- Add Firefox extension to open links in Disposable VM / selected VM (right-click option and a default action for not-whitelisted URLs/domains)
- The same for Chrome
- Add tests for above enhancements
- Update user documentation
**Knowledge prerequisite**:
- writing Thunderbird/Firefox extensions (XUL, javascript)
- writing Chrome extensions (javascript)
**Mentor**: Inquire on [qubes-devel][ml-devel].
### LogVM(s)
**Project**: LogVM(s)
**Brief explanation**: Qubes AppVMs do not have persistent /var (on purpose).
It would be useful to send logs generated by various VMs to a dedicated
log-collecting VM. This way logs will not only survive VM shutdown, but also be
immune to altering past entries. See
[#830](https://github.com/QubesOS/qubes-issues/issues/830) for details.
**Expected results**:
- Design a _simple_ protocol for transferring logs. The less metadata (parsed
in log-collecting VM) the better.
- Implement log collecting service. Besides logs itself, should save
information about logs origin (VM name) and timestamp. The service should
_not_ trust sending VM in any of those.
- Implement log forwarder compatible with systemd-journald and rsyslog. A
mechanism (service/plugin) fetching logs in real time from those and sending
to log-collecting VM over qrexec service.
- Document the protocol.
- Write unit tests and integration tests.
**Knowledge prerequisite**:
- syslog
- systemd
- Python/Bash scripting
**Mentor**: [Marek Marczykowski-Górecki](/team/)
### Xen GPU pass-through for Intel integrated GPUs
**Project**: Xen GPU pass-through for Intel integrated GPUs (largely independent of Qubes)
**Brief explanation**: This project is prerequisite to full GUI domain support,
where all desktop environment is running in dedicated VM, isolated from
dom0. There is already some support for GPU passthrough in Xen, but needs to be
integrated in to Qubes and probably really make working, even when using qemu
in stubdomain. GUI domain should be a HVM domain (not PV).
This should be done without compromising Qubes security features, especially:
using VT-d for protection against DMA attacks, using stubdomain for sandboxing
qemu process (if needed) - qemu running in dom0 is not acceptable. More
details in [#2618](https://github.com/QubesOS/qubes-issues/issues/2618).
**Expected results**:
- Ability to start a VM with GPU connected. VM should be able to handle video
output (both laptop internal display, and external monitors if apply). That
VM also should be able to use hardware acceleration.
- This project may require patching any/all of Xen hypervisor, Libvirt, Qemu,
Linux. In such a case, patches should be submitted to appropriate upstream
project.
- It's ok to focus on a specific, relatively new Intel-based system with Intel
integrated GPU.
**Knowledge prerequisite**:
- C language
- Kernel/hypervisor debugging
- Basics of x86_64 architecture, PCIe devices handling (DMA, MMIO, interrupts), IOMMU (aka VT-d)
- Xen hypervisor architecture
**Mentor**: [Marek Marczykowski-Górecki](/team/)
### Whonix IPv6 and nftables support
**Project**: Whonix IPv6 and nftables support
**Brief explanation**: [T509](https://phabricator.whonix.org/T509)
**Expected results**:
- Work at upstream Tor: An older version of https://trac.torproject.org/projects/tor/wiki/doc/TransparentProxy page was the origin of Whonix. Update that page for nftables / IPv6 support without mentioning Whonix. Then discuss that on the tor-talk mailing list for wider input. - https://trac.torproject.org/projects/tor/ticket/21397
- implement corridor feature request add IPv6 support / port to nftables - https://github.com/rustybird/corridor/issues/39
- port [whonix-firewall](https://github.com/Whonix/whonix-firewall) to nftables
- make connections to IPv6 Tor relays work
- make connections to IPv6 destinations work
**Knowledge prerequisite**:
- nftables
- iptables
- IPv6
**Mentor**: [Patrick Schleizer](/team/)
### Audio support for Qubes Windows Tools
**Project**: Audio support for Qubes Windows Tools
**Brief explanation**: Add audio support for Windows HVMs via Qubes Windows Tools. [#2624](https://github.com/QubesOS/qubes-issues/issues/2624)
**Expected results**: Windows HVMs should have an audio device that supports playback and recording.
**Knowledge prerequisite**: C/C++ languages, familiarity with Windows API, possibly familiarity with Windows audio stack on the driver level.
**Mentor**: [Rafał Wojdyła](/team/)
### Improve Windows GUI agent performance and stability
**Project**: Improve Windows GUI agent performance and stability
**Brief explanation**: Previous profiling has shown that the Windows GUI agent uses significant portion of VM's CPU time for mouse input simulation. This can be improved, as well as agent's stability in some cases (desktop/user switching, logon/logoff, domain-joined VMs, multiple monitors). Seamless GUI experience can be significantly improved, but that may require changes in the Qubes video driver. [#1044](https://github.com/QubesOS/qubes-issues/issues/1044) [#1045](https://github.com/QubesOS/qubes-issues/issues/1045) [#1500](https://github.com/QubesOS/qubes-issues/issues/1500) [#2138](https://github.com/QubesOS/qubes-issues/issues/2138) [#2487](https://github.com/QubesOS/qubes-issues/issues/2487) [#2589](https://github.com/QubesOS/qubes-issues/issues/2589)
**Expected results**: Reduction of agent's CPU usage, improved stability.
**Knowledge prerequisite**: C language, Familiarity with Windows API, especially the windowing stack. Familiarity with profiling and debugging tools for Windows.
**Mentor**: [Rafał Wojdyła](/team/)
### GUI agent for Windows 8/10
**Project**: GUI agent for Windows 8/10
**Brief explanation**: Add support for Windows 8+ to the Qubes GUI agent and video driver. Starting from Windows 8, Microsoft requires all video drivers to conform to the WDDM display driver model which is incompatible with the current Qubes video driver. Unfortunately the WDDM model is much more complex than the old XPDM one and officially *requires* a physical GPU device (which may be emulated). Some progress has been made to create a full WDDM driver that *doesn't* require a GPU device, but the driver isn't working correctly yet. Alternatively, WDDM model supports display-only drivers which are much simpler but don't have access to system video memory and rendering surfaces (a key feature that would simplify seamless GUI mode). [#1861](https://github.com/QubesOS/qubes-issues/issues/1861)
**Expected results**: Working display-only WDDM video driver or significant progress towards making the full WDDM driver work correctly.
**Knowledge prerequisite**: C/C++ languages, familiarity with Windows API, familiarity with the core Windows WDM driver model. Ideally familiarity with the WDDM display driver model.
**Mentor**: [Rafał Wojdyła](/team/)
### GNOME support in dom0 / GUI VM
**Project**: GNOME support in dom0
**Brief explanation**: Integrating GNOME into Qubes dom0. This include:
- patching window manager to add colorful borders
- removing stuff not needed in dom0 (file manager(s), indexing services etc)
- adjusting menu for easy navigation (same applications in different VMs and such problems, dom0-related entries in one place)
- More info: [#1806](https://github.com/QubesOS/qubes-issues/issues/1806)
**Expected results**:
- Review existing support for other desktop environments (KDE, Xfce4, i3, awesome).
- Patch window manager to draw colorful borders (we use only server-side
decorations), there is already very similar patch in
[Cappsule project](https://github.com/cappsule/cappsule-gui).
- Configure GNOME to not make use of dom0 user home in visible way (no search
in files there, no file manager, etc).
- Configure GNOME to not look into external devices plugged in (no auto
mounting, device notifications etc).
- Package above modifications as rpms, preferably as extra configuration files
and/or plugins than overwriting existing files. Exceptions to this rule may
apply if no other option.
- Adjust comps.xml (in installer-qubes-os repo) to define package group with
all required packages.
- Document installation procedure.
**Knowledge prerequisite**:
- GNOME architecture
- C language (patching metacity)
- Probably also javascript - for modifying GNOME shell extensions
**Mentor**: [Marek Marczykowski-Górecki](/team/)
### Generalize the Qubes PDF Converter to other types of files
**Project**: Qubes Converters
**Brief explanation**: One of the pioneering ideas of Qubes is to use disposable virtual machines to convert untrustworthy files (such as documents given to journalists by unknown and potentially malicious whistleblowers) into trusthworhty files. See [Joanna's blog on the Qubes PDF Convert](http://theinvisiblethings.blogspot.co.uk/2013/02/converting-untrusted-pdfs-into-trusted.html) for details of the idea. Joanna has implemented a prototype for PDF documents. The goal of this project would be to generalize beyond the simple prototype to accommodate a wide variety of file formats, including Word documents, audio files, video files, spreadsheets, and so on. The converters should prioritise safety over faithful conversion. For example the Qubes PDF converter typically leads to lower quality PDFs (e.g. cut and paste is no longer possible), because this makes the conversion process safer.
**Expected results**: We expect that in the timeframe, it will be possible to implement many converters for many file formats. However, if any unexpected difficulties arise, we would prioritise a small number of safe and high quality converters over a large number of unsafe or unuseful converters.
**Knowledge prerequisite**: Most of the coding will probably be implemented as shell scripts to interface with pre-existing converts (such as ImageMagick in the Qubes PDF converter). However, shell scripts are not safe for processing untrusted data, so any extra processing will need to be implemented in another language -- probably Python.
**Mentors**: Andrew Clausen and Jean-Philippe Ouellet
### Mitigate focus-stealing attacks
**Project**: Mitigate focus-stealing attacks
**Brief explanation**: [Focus stealing attacks](https://en.wikipedia.org/wiki/Focus_stealing) have long been an issue in Qubes OS. The Qubes community has long punted the issue due to having higher priority things to work on, and it being viewed as the responsability of the window manager, but nevertheless it remains a serious issue, and an *effective* mitigation would be most welcome. Any student wishing to work on this would need to engage the community in a discussion about the effectiveness of their proposed earlier rather than later. [#1166](https://github.com/QubesOS/qubes-issues/issues/1166)
**Expected results**: Working robust focus stealing prevention for Xfce (currently the default Qubes desktop environment) or Gnome (the targeted future Qubes desktop environment).
**Knoledge prerequisite**: X APIs, Qubes GUI protocol, familiarity with the targeted window manager.
**Mentor**: Inquire on [qubes-devel][ml-devel].
### Progress towards reproducible builds
**Project**: Progress towards reproducible builds
**Brief explanation**: A long-term goal is to be able to build the entire OS and installation media in a completely bit-wise deterministic manner, but there are many baby steps to be taken along that path. See:
- "[Security challenges for the Qubes build process](/news/2016/05/30/build-security/)"
- [This mailing list post](https://groups.google.com/d/msg/qubes-devel/gq-wb9wTQV8/mdliS4P2BQAJ)
- and [reproducible-builds.org](https://reproducible-builds.org/)
for more information and qubes-specific background.
**Expected results**: Significant progress towards making the Qubes build process deterministic. This would likely involve cooperation with and hacking on several upstream build tools to eliminate sources of variability.
**Knoledge prerequisite**: qubes-builder [[1]](/doc/qubes-builder/) [[2]](/doc/qubes-builder-details/) [[3]](https://github.com/QubesOS/qubes-builder/tree/master/doc), and efficient at introspecting complex systems: comfortable with tracing and debugging tools, ability to quickly identify and locate issues within a large codebase (upstream build tools), etc.
**Mentor**: [Marek Marczykowski-Górecki](/team/)
### Android development in Qubes
**Project**: Research running Android in Qubes VM (probably HVM) and connecting it to Android Studio
**Brief explanation**: The goal is to enable Android development (and testing!)
on Qubes OS. Currently it's only possible using qemu-emulated Android for ARM.
Since it's software emulation it's rather slow.
Details, reference: [#2233](https://github.com/QubesOS/qubes-issues/issues/2233)
**Expected results**:
**Knowledge prerequisite**:
**Mentor**: Inquire on [qubes-devel][ml-devel].
----
We adapted some of the language here about GSoC from the [KDE GSoC page](https://community.kde.org/GSoC).
[2017-archive]: https://summerofcode.withgoogle.com/archive/2017/organizations/5074771758809088/
[gsoc-qubes]: https://summerofcode.withgoogle.com/organizations/6239659689508864/
[gsoc]: https://summerofcode.withgoogle.com/
[team]: /team/
[gsoc-faq]: https://developers.google.com/open-source/gsoc/faq
[contributing]: /doc/contributing/#contributing-code
[patches]: /doc/source-code/#how-to-send-patches
[code-signing]: /doc/code-signing/
[ml-devel]: /support/#qubes-devel
[gsoc-participate]: https://developers.google.com/open-source/gsoc/
[gsoc-student]: https://developers.google.com/open-source/gsoc/resources/manual#student_manual
[how-to-gsoc]: http://teom.org/blog/kde/how-to-write-a-kick-ass-proposal-for-google-summer-of-code/
[gsoc-submit]: https://summerofcode.withgoogle.com/
[mailing-lists]: /support/
[qubes-issues]: https://github.com/QubesOS/qubes-issues/issues
[qubes-issues-suggested]: https://github.com/QubesOS/qubes-issues/issues?q=is%3Aissue%20is%3Aopen%20label%3A%22P%3A%20minor%22%20label%3A%22help%20wanted%22
[qubes-builder]: /doc/qubes-builder/

2
basics_dev/license.md
View File

@ -18,4 +18,4 @@ The full text of the GPL v2 license can be found [here](http://www.gnu.org/licen
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.
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.

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

@ -0,0 +1,98 @@
---
layout: doc
title: Package Contributions
permalink: /doc/package-contributions/
---
Package Contributions
=====================
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 to 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]: /support/#qubes-devel
[QubesOS-contrib]: https://github.com/QubesOS-contrib
[qubes-issues]: https://github.com/QubesOS/qubes-issues/issues/

81
basics_dev/reporting-bugs.md
View File

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

15
basics_dev/source-code.md
View File

@ -26,7 +26,7 @@ All of our repositories are available under the [QubesOS GitHub account].
To clone a repository:
~~~
git clone https://github.com/QubesOS/<repo_name>.git <repo_name>
git clone https://github.com/QubesOS/qubes-<repo_name>.git <repo_name>
~~~
e.g.:
@ -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]: /support/#qubes-devel

8
basics_dev/style-guide.md
View File

@ -9,7 +9,7 @@ Style Guide
## Fonts
Currently Qubes OS is using the following fonts for our website, branding, and other public facing (non-OS) materials. The OS itself uses what is normal for a users desktop environment of choice.
Currently Qubes OS is using the following fonts for our website, branding, and other public facing (non-OS) materials. The OS itself uses what is normal for a user's desktop environment of choice.
<div class="styleguide">
{% for font in site.data.styleguide.fonts %}
@ -28,7 +28,7 @@ Currently Qubes OS is using the following fonts for our website, branding, and o
## Colors
The following **grayscale** colors are currently used on the Qubes website, documentation, and will eventually match colors within the OS itself.
The following **grayscale** colors are currently used on the Qubes website and documentation, and they will eventually match colors within the OS itself.
<div class="styleguide">
{% for color in site.data.styleguide.colors %}
@ -42,7 +42,7 @@ The following **grayscale** colors are currently used on the Qubes website, docu
{% endfor %}
</div>
The following **colors** are currently being used on the Qubes website, documentation, and will eventually match the colors within the OS itself!
The following **colors** are currently being used on the Qubes website and documentation, and they will eventually match the colors within the OS itself!
<div class="styleguide">
{% for color in site.data.styleguide.colors %}
@ -68,7 +68,7 @@ Currently, all the icons on the Qubes-OS.org website are generated using [FontAw
## Logos
The following is a collection of various sizes & versions of the Qubes logo used both in the OS itself and on our website. All of these files are licensed GPLv2 and the source can be [downloaded here](https://github.com/QubesOS/qubes-artwork).
The following is a collection of various sizes and versions of the Qubes logo used both in the OS itself and on our website. All of these files are licensed GPLv2 and the source can be [downloaded here](https://github.com/QubesOS/qubes-artwork).
<div class="styleguide">
{% for logo in site.data.styleguide.logos %}

44
basics_dev/system-doc.md
View File

@ -6,47 +6,7 @@ redirect_from:
- /en/doc/system-doc/
- /doc/SystemDoc/
- /wiki/SystemDoc/
redirect_to:
- /doc/#developer-documentation
---
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/)

84
basics_dev/usability-ux.md
View File

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

80
basics_user/contributing.md Normal file
View File

@ -0,0 +1,80 @@
---
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
* [Contribute packages]
* [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]
* Add a [Qubes download mirror]
* Answer questions on the [mailing lists]
* Engage with us on social media:
* Follow us on [Twitter]
* Join us on [Reddit]
* Like us on [Facebook]
* 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
[Contribute packages]: /doc/package-contributions
[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]: /support/
[Donate]: /donate/
[Qubes partner]: /partners/
[Twitter]: https://twitter.com/QubesOS
[Reddit]: https://www.reddit.com/r/Qubes/
[Facebook]: https://www.facebook.com/QubesOS
[GitHub issues]: https://github.com/QubesOS/qubes-issues/issues
[qubes-devel]: /support/#qubes-devel
[Community-Developed Feature Tracker]: /qubes-issues/
[Qubes download mirror]: /downloads/mirrors/

287
basics_user/doc-guidelines.md Normal file
View File

@ -0,0 +1,287 @@
---
layout: doc
title: Documentation Guidelines
permalink: /doc/doc-guidelines/
redirect_from:
- /en/doc/doc-guidelines/
- /wiki/DocStyle/
- /doc/DocStyle/
---
Documentation Guidelines
========================
All Qubes OS documentation pages are stored as plain text files in the
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. 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 or improve existing content.
Questions, problems, and improvements
-------------------------------------
If you have a question about something you read in the documentation, please send it to the appropriate [mailing list][support].
If you see that something in the documentation should be fixed or improved, please [contribute] the change yourself.
To report an issue with the documentation, please follow our standard [issue reporting guidelines][report].
(If you report an issue with the documentation, you will likely be asked to address it, unless there is a clear indication in your report that you are not willing or able to do so.)
How to Contribute
-----------------
Editing the documentation is easy, so if you spot any errors, please help us
fix them! (As mentioned above, the documentation maintainers are just volunteers
who have day jobs of their own, so we rely heavily on the community to improve
the documentation.) Since Qubes is a security-oriented project, every
documentation change will be reviewed before it's published to the web. This
allows us to maintain quality control and protect our users.
As mentioned above, we keep all the documentation in a dedicated [Git
repository][qubes-doc] hosted on [GitHub]. Thanks to the GitHub's interface, you can
edit the documentation even if you don't know Git at all! The only thing you
need is a GitHub account, which is free.
(Note: If you're already familiar with GitHub or wish to work from the command
line, you can skip the rest of this section. All you need to do to contribute is
to [fork and clone][gh-fork] the [qubes-doc] repo, make your changes, then
[submit a pull request][gh-pull].)
Ok, let's start. Every documentation page has an "Edit this page" button. It may
be on the right side (in the desktop layout):
![edit-button-desktop](/attachment/wiki/doc-edit/03-button2.png)
Or at the bottom (in the mobile layout):
![edit-button-mobile](/attachment/wiki/doc-edit/02-button1.png)
When you click on it, you'll be prompted for your GitHub username and password
(if you aren't already logged in). You can also create an account from here.
![github-sign-in](/attachment/wiki/doc-edit/04-sign-in.png)
If this is your first contribution to the documentation, you need to "fork" the
repository (make your own copy). It's easy --- just click the big green button
on the next page. This step is only needed the first time you make a
contribution.
![fork](/attachment/wiki/doc-edit/05-fork.png)
Now you can make your modifications. You can also preview the changes to see how
they'll be formatted by clicking the "Preview changes" tab. **Important:** If
you're making any formatting changes, please [render the site locally] to verify
that everything looks correct before submitting any changes.
![edit](/attachment/wiki/doc-edit/06-edit.png)
Once you're finished, describe your changes at the bottom and click "Propose file
change".
![commit](/attachment/wiki/doc-edit/07-commit-msg.png)
After that, you'll see exactly what modifications you've made. At this stage,
those changes are still in your own copy of the documentation ("fork"). If
everything looks good, send those changes to us by pressing the "Create pull
request" button.
![pull-request](/attachment/wiki/doc-edit/08-review-changes.png)
You will be able to adjust the pull request message and title there. In most
cases, the defaults are ok, so you can just confirm by pressing the "Create pull
request" button again.
![pull-request-confirm](/attachment/wiki/doc-edit/09-create-pull-request.png)
That's all! We will review your changes. If everything looks good, we'll pull
them into the official documentation. Otherwise, we may have some questions for
you, which we'll post in a comment on your pull request. (GitHub will
automatically notify you if we do.) If, for some reason, we can't accept your
pull request, we'll post a comment explaining why we can't.
![done](/attachment/wiki/doc-edit/10-done.png)
How to add images
-----------------
To add an image to a page, use the following syntax in the main document:
```
![Image Title](/attachment/wiki/page-title/image-filename.png)
```
Then, submit your image(s) in a separate pull request to the [qubes-attachment](https://github.com/QubesOS/qubes-attachment) repository using the same path and filename.
Version-specific Documentation
------------------------------
We maintain only one set of documentation for Qubes OS.
We do not maintain a different set of documentation for each version of Qubes.
Our single set of Qubes OS documentation is updated on a continual, rolling basis.
Our first priority is to document all **current, stable releases** of Qubes.
Our second priority is to document the next, upcoming release (if any) that is currently in the beta or release candidate stage.
In cases where a documentation page covers functionality that differs considerably between Qubes OS versions, the page should be subdivided into clearly-labeled sections that cover the different functionality in different versions:
### Incorrect Example ###
```
# Page Title #
## How to Foo ##
Fooing is the process by which one foos. There are both general and specific
versions of fooing, which vary in usefulness depending on your goals, but for
the most part, all fooing is fooing.
To foo in Qubes 3.2:
$ qvm-foo <foo-bar>
Note that this does not work in Qubes 4.0, where there is a special widget
for fooing, which you can find in the lower-right corner of the screen in
the Foo Manager. Alternatively, you can use the more general `qubes-baz`
command introduced in 4.0:
$ qubes-baz --foo <bar>
Once you foo, make sure to close the baz before fooing the next bar.
```
### Correct Example ###
```
# Page Title #
## Qubes 3.2 ##
### How to Foo ###
Fooing is the process by which one foos. There are both general and specific
versions of fooing, which vary in usefulness depending on your goals, but for
the most part, all fooing is fooing.
To foo:
$ qvm-foo <foo-bar>
Once you foo, make sure to close the baz before fooing the next bar.
## Qubes 4.0 ##
### How to Foo ###
Fooing is the process by which one foos. There are both general and specific
versions of fooing, which vary in usefulness depending on your goals, but for
the most part, all fooing is fooing.
There is a special widget for fooing, which you can find in the lower-right
corner of the screen in the Foo Manager. Alternatively, you can use the
general `qubes-baz` command:
$ qubes-baz --foo <bar>
Once you foo, make sure to close the baz before fooing the next bar.
```
[Here][version-example] is a good example of a page that is correctly subdivided to account for version-specific differences.
Subdividing the page into clearly-labeled sections for each version has several benefits:
* It preserves good content for older (but still supported) versions.
Many documentation contributors are also people who prefer to use the latest version.
Many of them are tempted to *replace* existing content that applies to an older, supported version with content that applies only to the latest version.
This is somewhat understandable.
Since they only use the latest version, they may be focused on their own experience, and they may even regard the older version as deprecated, even when it's actually still supported.
However, allowing this replacement of content would do a great disservice to those who still rely on the older, supported version.
In many cases, these users value the stability and reliability of the older, supported version.
With the older, supported version, there has been more time to fix bugs and make improvements in both the software and the documentation.
Consequently, much of the documentation content for this version may have gone through several rounds of editing, review, and revision.
It would be a tragedy for this content to vanish while the very set of users who most prize stability and reliability are depending on it.
* It's easy for readers to quickly find the information they're looking for, since they can go directly to the section that applies to their version.
* It's hard for readers to miss information they need, since it's all in one place.
In the incorrect example, information that the reader needs could be in any paragraph in the entire document, and there's no way to tell without reading the entire page.
In the correct example, the reader can simply skim the headings in order to know which parts of the page need to be read and which can be safely ignored.
The fact that some content is repeated in the two version-specific sections is not a problem, since no reader has to read the same thing twice.
Moreover, as one version gets updated, it's likely that the documentation for that version will also be updated.
Therefore, content that is initially duplicated between version-specific sections will not necessarily stay that way, and this is a good thing:
We want the documentation for a version that *doesn't* change to stay the same, and we want the documentation for a version that *does* change to change along with the software.
* It's easy for documentation contributors and maintainers to know which file to edit and update, since there's only one page for all Qubes OS versions.
Initially creating the new headings and duplicating content that applies to both is only a one-time cost for each page, and many pages don't even require this treatment, since they apply to all currently-supported Qubes OS versions.
By contrast, an alternative approach, such as segregating the documentation into two different branches, would mean that contributions that apply to both Qubes versions would only end up in one branch, unless someone remembered to manually submit the same thing to the other branch and actually made the effort to do so.
Most of the time, this wouldn't happen.
When it did, it would mean a second pull request that would have to be reviewed.
Over time, the different branches would diverge in non-version-specific content.
Good general content that was submitted only to one branch would effectively disappear once that version was deprecated.
(Even if it were still on the website, no one would look at it, since it would explicitly be in the subdirectory of a deprecated version, and there would be a motivation to remove it from the website so that search results wouldn't be populated with out-of-date information.)
For further discussion about version-specific documentation in Qubes, see [here][version-thread].
Style Guidelines
----------------
* Familiarize yourself with the terms defined in the [glossary]. Use these
terms consistently and accurately throughout your writing.
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.
* In order to enable offline browsing, use relative paths (e.g., `/doc/doc-guidelines/` instead of `https://www.qubes-os.org/doc/doc-guidelines/`, except when the source text will be reproduced outside of the Qubes website repo.
Examples of exceptions:
* [QSBs] (intended to be read as plain text)
* [News] posts (plain text is reproduced on the [mailing lists][support])
* URLs that appear inside code blocks (e.g., in comments and document templates)
* Files like `README.md` and `CONTRIBUTING.md`
* Insert a newline at, and only at, the end of each sentence, except when the text will be reproduced outside of the Qubes website repo (see previous item for examples).
* Rationale: This practice results in one sentence per line, which 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 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 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
[glossary]: /doc/glossary/
[report]: /doc/reporting-bugs/
[contribute]: #how-to-contribute
[qubes-issues]: https://github.com/QubesOS/qubes-issues/issues
[gh-fork]: https://guides.github.com/activities/forking/
[gh-pull]: https://help.github.com/articles/using-pull-requests/
[GitHub]: https://github.com/
[support]: /support/
[version-example]: /doc/template/fedora/upgrade-25-to-26/
[version-thread]: https://groups.google.com/d/topic/qubes-users/H9BZX4K9Ptk/discussion
[QSBs]: /security/bulletins/
[News]: /news/
[md]: https://daringfireball.net/projects/markdown/
[git-commit]: /doc/coding-style/#commit-message-guidelines
[render the site locally]: https://github.com/QubesOS/qubesos.github.io#instructions

208
basics_user/getting-started.md Normal file
View File

@ -0,0 +1,208 @@
---
layout: default
title: Get Started
permalink: /getting-started/
redirect_from:
- /doc/getting-started/
- /en/doc/getting-started/
- /doc/GettingStarted/
- /wiki/GettingStarted/
---
<a name="already-installed"></a>After [installing Qubes](/doc/installation-guide/), let's cover some basic concepts.
You might also like to refer to the [Glossary](/doc/glossary/).
AppVMs (qubes) and TemplateVMs
--------------------------------
In Qubes, you run all your programs in lightweight Virtual Machines called **qubes**.
Not every app runs in its own qube.
(That would be a big waste of resources!)
Instead, each qube represents a *security domain* (e.g., "work," "personal," "banking," etc.).
By default all qubes are based on a single, common **TemplateVM** , although you can create more TemplateVMs if you wish.
When you create a new qube, you don't copy the whole root filesystem needed for this qube to work (which would include copying all the programs).
Instead, each qube *shares* the root filesystem with its respective TemplateVM.
A qube has read-only access to the filesystem of the Template on which it's based, so a qube cannot modify a TemplateVM in any way.
This is important, as it means that if a qube is ever compromised, the TemplateVM on which it's based (and any other qubes based on that TemplateVM) will still be safe.
So creating a large number of domains is cheap: each one needs only as much disk space as is necessary to store its private files (e.g., the "home" folder).
If you've installed Qubes using the default options, a few qubes have already been created for you:
- work
- personal
- untrusted
Each qube, apart from having a distinct name, is also assigned a **label**, which is one of several pre-defined colors.
The trusted window manager uses these colors in order to draw window decorations (color frames) around the windows of applications running in each qube.
It's totally up to you how you'd like to interpret these colors.
You might like to use them to quickly and easily identify the trust level of a given window at a glance.
Personally, I find it natural to associate red with that which is untrusted and dangerous (the “red light” -- stop! danger!), green with that which is safe and trusted, and yellow and orange with things in the middle.
I've also extended this scheme to include blue and black, which I interpret as indicating progressively more trusted domains than green, with black being ultimately trusted.
Alternatively you might use the colors to show that qubes belong to the same domain - for example, you might use 3 or 4 qubes for work activities, and give them all the same distinct color label. It's entirely up to you.
![snapshot12.png](/attachment/wiki/GettingStarted/snapshot12.png)
In addition to qubes and TemplateVMs, there's one special domain called "dom0," which is where the Desktop Manager runs.
This is where you log in to the system.
Dom0 is more trusted than any other domain (including TemplateVMs and black-labeled qubes).
If dom0 were ever compromised, it would be Game Over<sup>TM</sup>.
(The entire system would effectively be compromised.)
Due to its overarching importance, dom0 has no network connectivity and is used only for running the Window and Desktop Managers.
Dom0 shouldn't be used for anything else.
In particular, [you should never run user applications in dom0](/doc/security-guidelines/#dom0-precautions).
(That's what your qubes are for!)
Qubes VM Manager and Command Line Tools
---------------------------------------
All aspects of the Qubes system can be controlled using command line tools run under a dom0 console.
Opening a console window in dom0 can be done in several ways:
* Go to the Start Menu and click Terminal Emulator
* Press Alt-F3, type `xfce terminal` and press Enter twice
* Right-click on the desktop and select Open Terminal Here
* In previous versions of Qubes with KDE:
* Start → System Tools → Konsole
* Press Alt-F2 and type `konsole`.
Various command line tools are described as part of this guide, and the whole reference can be found [here](/doc/tools/).
![r2b1-dom0-konsole.png](/attachment/wiki/GettingStarted/r2b1-dom0-konsole.png)
Alternatively, you can use a rather intuitive GUI tool called **Qubes VM Manager**.
It supports most of the functionality that command line tools provide.
The Qubes VM Manager starts and opens automatically when Qubes starts up, but you can also start it by going to Start → System Tools → Qubes Manager.
Once the Qubes VM Manager is running, you can open the window at any time by clicking on the Qubes tray icon, which typically resides in the bottom-right corner of the screen.
![r2b1-qubes-manager-2.png](/attachment/wiki/GettingStarted/r2b1-qubes-manager-2.png)
Starting Apps in qubes
------------------------
Apps can be started either by using the shortcuts in the Desktop Manager's menu or by using the command line (i.e., a console running in dom0).
You can start apps directly from the Start Menu or the Application Finder (Alt-F3).
Each qube has its own menu directory under the scheme **Domain: \<name\>**.
After navigating into one of these directories, simply click on the application you'd like to start:
![r2b1-appsmenu-1.png](/attachment/wiki/GettingStarted/r2b1-appsmenu-1.png) ![r2b1-appsmenu-3.png](/attachment/wiki/GettingStarted/r2b1-appsmenu-3.png)
By default, each qube's menu contains only a few shortcuts.
If you'd like to add more, simply click **Add more shortcuts...**, select the desired applications, and click **OK**.
You can also add shortcuts manually.
(This is sometimes necessary if the desired application doesn't show up in the Qubes VM Manager window.)
To do this in KDE, right-click on the **Start** button and click **Menu Editor**.
Click the qube directory in which you'd like the menu to appear, click **New Item**, enter its name as **\<qube name\>: \<app name\>**, and provide the command for starting the app (see below).
Then click **Save** and wait approximately 15 seconds for the changes to propagate to the KDE menu.
To start apps from the console in dom0, type:
qvm-run -a <qube> "<app name> [arguments]"
e.g.:
qvm-run -a untrusted firefox
The -a parameter will start the qube if it is not already running.
Adding, Removing, and Listing qubes
-------------------------------------
A qube can easily be added and removed by clicking on the **Add** and **Remove** buttons in the Qubes VM Manager.
A qube can also be added, removed, and qubes may be listed from the command line (i.e., a console running in dom0) using the following tools:
- `qvm-create`
- `qvm-remove`
- `qvm-ls`
How Many Qubes Do I Need?
---------------------------
That's a great question, but there's no one-size-fits-all answer.
It depends on the structure of your digital life, and this is at least a little different for everyone.
If you plan on using your system for work, then it also depends on what kind of job you do.
It's a good idea to start out with the three qubes created automatically by the installer: work, personal, and untrusted.
Then, if and when you start to feel that some activity just doesn't fit into any of your existing qubes, or you want to partition some part of your life, you can easily create a new qube for it.
You'll also be able to easily copy any files you need to the newly created qube, as explained [here](/doc/copying-files/).
More paranoid people might find it worthwhile to read [this article](https://blog.invisiblethings.org/2011/03/13/partitioning-my-digital-life-into.html), which describes how one of the Qubes authors partitions her digital life into security domains.
Common Tasks
------------
Here are the documentation pages for some of the main actions you'll want to perform.
A full list is available in the [Common Tasks](/doc/#common-tasks) section of the documentation.
* [Copying and Pasting Text Between Domains](/doc/copy-paste/)
* [Copying and Moving Files Between Domains](/doc/copying-files/)
* [Copying from (and to) dom0](/doc/copy-from-dom0/)
* [Updating Software in dom0](/doc/software-update-dom0/)
* [Updating and Installing Software in VMs](/doc/software-update-vm/)
* [Backup, Restoration, and Migration](/doc/backup-restore/)
* [Using Disposable VMs](/doc/dispvm/)
* [Using and Managing USB Devices](/doc/usb/)
Running an application Full Screen
----------------------------------
By default, Qubes doesn't allow any application window to occupy the entire screen such that its window name (which includes the name of the qube to which it belongs) and colored window border are no longer visible.
This is a security precaution designed to prevent a situation in which an application which has been allowed to enter full screen mode begins to emulate the entire Qubes system.
The user should always be able to identify which qube is displaying any given window.
Otherwise, a compromised qube which is able to occupy the entire screen could trick the user into thinking that she is interacting with a variety of different qubes (including dom0), when in fact she is interacting with only a single, compromised qube pretending to be the whole system.
**Note:** A similar attack is possible even *without* fullscreen mode.
Since a compromised qube can draw pixels within its own windows however it likes, it could draw a fake password prompt, for example, which appears to have a different colored border so that it looks like it belongs to a different qube.
This is why you should always drag such prompts away from other windows (or use some other means of manipulating the windows) to ensure that they belong to the qube to which they appear to belong.
To allow a qube to enter full screen mode, one should edit the `/etc/qubes/guid.conf` file in dom0.
To allow all qubes to enter full screen mode, set `allow_fullscreen` flag to `true` in the `global` section:
global: {
# default values
allow_fullscreen = false;
#allow_utf8_titles = false;
#secure_copy_sequence = "Ctrl-Shift-c";
#secure_paste_sequence = "Ctrl-Shift-v";
#windows_count_limit = 500;
};
To allow only select qubes to enter full screen mode, create a per-VM section, and set `allow_fullscreen` flag there to `true`:
VM: {
work: {
allow_fullscreen = true;
};
};
In order for the changes to take effect, restart the qube(s).
More details can be found [here](/doc/full-screen-mode/).
<div class="row">
<div class="col-lg-4 col-md-4">
<h2>Compatible Hardware</h2>
<p>Ready to install Qubes? Make sure your hardware is compatible, as Qubes cannot run on every type of computer. Also, check out <a href="/doc/certified-laptops/">Qubes-certified Laptops</a>.</p>
<a href="/hcl/" class="btn btn-primary">
<i class="fa fa-laptop"></i> Hardware Compatibility List
</a>
</div>
<div class="col-lg-4 col-md-4">
<h2>Downloads</h2>
<p>Download an ISO, learn how to verify its authenticity and integrity, and follow our guides to install Qubes. Looking for the source code? You'll find it on <a href="https://github.com/QubesOS">GitHub</a>.</p>
<a href="/downloads/" class="btn btn-primary">
<i class="fa fa-download"></i> Downloads
</a>
</div>
<div class="col-lg-4 col-md-4">
<h2>Documentation</h2>
<p>Peruse our extensive library of documentation for users and developers of Qubes. You can even help us <a href="/doc/doc-guidelines/">improve</a> it!</p>
<a href="/doc/" class="btn btn-primary">
<i class="fa fa-book"></i> Documentation
</a>
</div>
</div>
<hr class="more-top more-bottom">

236
basics_user/intro.md Normal file
View File

@ -0,0 +1,236 @@
---
layout: intro
title: An Introduction to Qubes OS
permalink: /intro/
redirect_from:
- /tour/
- /en/tour/
- /tour/#what-is-qubes-os
- /about/
- /en/about/
---
What is Qubes OS?
-----------------
Qubes OS is a security-oriented operating system (OS). The OS is the software
that runs all the other programs on a computer. Some examples of popular
OSes are Microsoft Windows, Mac OS X, Android, and iOS. Qubes is free and
open-source software (FOSS). This means that everyone is free to use, copy,
and change the software in any way. It also means that the source code is
openly available so others can contribute to and audit it.
Why is OS security important?
-----------------------------
Most people use an operating system like Windows or OS X on their desktop
and laptop computers. These OSes are popular because they tend to be easy
to use and usually come pre-installed on the computers people buy. However,
they present problems when it comes to security. For example, you might
open an innocent-looking email attachment or website, not realizing that
you're actually allowing malware (malicious software) to run on your
computer. Depending on what kind of malware it is, it might do anything
from showing you unwanted advertisements to logging your keystrokes to
taking over your entire computer. This could jeopardize all the information
stored on or accessed by this computer, such as health records, confidential
communications, or thoughts written in a private journal. Malware can also
interfere with the activities you perform with your computer. For example,
if you use your computer to conduct financial transactions, the malware
might allow its creator to make fraudulent transactions in your name.
Aren't antivirus programs and firewalls enough?
-----------------------------------------------
Unfortunately, conventional security approaches like antivirus programs
and (software and/or hardware) firewalls are no longer enough to keep out
sophisticated attackers. For example, nowadays it's common for malware
creators to check to see if their malware is recognized by any signature-based
antivirus programs. If it's recognized, they scramble their code until it's
no longer recognizable by the antivirus programs, then send it out. The
best of these programs will subsequently get updated once the antivirus
programmers discover the new threat, but this usually occurs at least a
few days after the new attacks start to appear in the wild. By then, it's
too late for those who have already been compromised. More advanced antivirus
software may perform better in this regard, but it's still limited to a
detection-based approach. New zero-day vulnerabilities are constantly being
discovered in the common software we all use, such as our web browsers, and no
antivirus program or firewall can prevent all of these vulnerabilities from
being exploited.
How does Qubes OS provide security?
-----------------------------------
Qubes takes an approach called **security by compartmentalization**, which
allows you to compartmentalize the various parts of your digital life into
securely isolated compartments called *qubes*.
This approach allows you to keep the different things you do on your computer
securely separated from each other in isolated qubes so that one qube getting
compromised won't affect the others. For example, you might have one qube for
visiting untrusted websites and a different qube for doing online banking. This
way, if your untrusted browsing qube gets compromised by a malware-laden
website, your online banking activities won't be at risk. Similarly, if
you're concerned about malicious email attachments, Qubes can make it so
that every attachment gets opened in its own single-use [disposable
qube]. In this way, Qubes allows you to do everything on the same physical
computer without having to worry about a single successful cyberattack taking
down your entire digital life in one fell swoop.
Moreover, all of these isolated qubes are integrated into a single, usable
system. Programs are isolated in their own separate qubes, but all windows are
displayed in a single, unified desktop environment with [unforgeable colored
window borders][getting started] so that you can easily identify windows from
different security levels. Common attack vectors like network cards and USB
controllers are isolated in their own hardware qubes while their functionality
is preserved through secure [networking], [firewalls], and [USB device
management][USB]. Integrated [file] and [clipboard] copy and paste operations
make it easy to work across various qubes without compromising security. The
innovative [Template] system separates software installation from software use,
allowing qubes to share a root filesystem without sacrificing security (and
saving disk space, to boot). Qubes even allows you to sanitize PDFs and images
in a few clicks. Users concerned about privacy will appreciate the
[integration][Qubes-Whonix] of [Whonix] with Qubes, which makes it easy to use
[Tor] securely, while those concerned about physical hardware attacks will
benefit from [Anti Evil Maid].
How does Qubes OS compare to using a "live CD" OS?
--------------------------------------------------
Booting your computer from a live CD (or DVD) when you need to perform
sensitive activities can certainly be more secure than simply using your main
OS, but this method still preserves many of the risks of conventional OSes. For
example, popular live OSes (such as [Tails] and other Linux distributions)
are still **monolithic** in the sense that all software is still running in
the same OS. This means, once again, that if your session is compromised,
then all the data and activities performed within that same session are also
potentially compromised.
How does Qubes OS compare to running VMs in a conventional OS?
--------------------------------------------------------------
Not all virtual machine software is equal when it comes to security. You may
have used or heard of VMs in relation to software like VirtualBox or VMware
Workstation. These are known as "Type 2" or "hosted" hypervisors. (The
**hypervisor** is the software, firmware, or hardware that creates and
runs virtual machines.) These programs are popular because they're designed
primarily to be easy to use and run under popular OSes like Windows (which
is called the **host** OS, since it "hosts" the VMs). However, the fact
that Type 2 hypervisors run under the host OS means that they're really
only as secure as the host OS itself. If the host OS is ever compromised,
then any VMs it hosts are also effectively compromised.
By contrast, Qubes uses a "Type 1" or "bare metal" hypervisor called
[Xen]. Instead of running inside an OS, Type 1 hypervisors run directly on the
"bare metal" of the hardware. This means that an attacker must be capable of
subverting the hypervisor itself in order to compromise the entire system,
which is vastly more difficult.
Qubes makes it so that multiple VMs running under a Type 1 hypervisor can be
securely used as an integrated OS. For example, it puts all of your application
windows on the same desktop with special colored borders indicating the
trust levels of their respective VMs. It also allows for things like secure
copy/paste operations between VMs, securely copying and transferring files
between VMs, and secure networking between VMs and the Internet.
How does Qubes OS compare to using a separate physical machine?
---------------------------------------------------------------
Using a separate physical computer for sensitive activities can certainly be
more secure than using one computer with a conventional OS for everything,
but there are still risks to consider. Briefly, here are some of the main
pros and cons of this approach relative to Qubes:
<div class="focus">
<i class="fa fa-check"></i> <strong>Pros</strong>
</div>
* Physical separation doesn't rely on a hypervisor. (It's very unlikely
that an attacker will break out of Qubes' hypervisor, but if one were to
manage to do so, one could potentially gain control over the entire system.)
* Physical separation can be a natural complement to physical security. (For
example, you might find it natural to lock your secure laptop in a safe
when you take your unsecure laptop out with you.)
<div class="focus">
<i class="fa fa-times"></i> <strong>Cons</strong>
</div>
* Physical separation can be cumbersome and expensive, since we may have to
obtain and set up a separate physical machine for each security level we
need.
* There's generally no secure way to transfer data between physically
separate computers running conventional OSes. (Qubes has a secure inter-VM
file transfer system to handle this.)
* Physically separate computers running conventional OSes are still
independently vulnerable to most conventional attacks due to their monolithic
nature.
* Malware which can bridge air gaps has existed for several years now and
is becoming increasingly common.
(For more on this topic, please see the paper
[Software compartmentalization vs. physical separation][paper-compart].)
<hr class="add-top more-bottom">
<div class="row">
<div class="col-lg-4 col-md-4 col-xs-12">
<h2>Video Tours</h2>
<p>Want to see Qubes OS in action? Sit back and watch a guided tour!</p>
<a href="/video-tours/" class="btn btn-primary">
<i class="fa fa-play-circle"></i> Video Tours
</a>
</div>
<div class="col-lg-4 col-md-4 col-xs-12">
<h2>Screenshots</h2>
<p>See what using Qubes actually looks like with these screenshots of various applications running in Qubes.</p>
<a href="/screenshots/" class="btn btn-primary">
<i class="fa fa-picture-o"></i> Screenshots
</a>
</div>
<div class="col-lg-4 col-md-4 col-xs-12">
<h2>Getting Started</h2>
<p>Ready to get started with Qubes? Here's what you need to know after installing.</p>
<a href="/getting-started/" class="btn btn-primary">
<i class="fa fa-cubes"></i> Getting Started
</a>
</div>
</div>
<hr class="more-top more-bottom">
More information
----------------
This page is just a brief sketch of what Qubes is all about, and many
technical details have been omitted here for the sake of presentation.
* If you're a current or potential Qubes user, you may want to check out the
[documentation][doc] and the [FAQ][user-faq].
* If you're a developer, there's dedicated [documentation][system-doc]
and an [FAQ][devel-faq] just for you.
* Ready to give Qubes a try? Head on over to the [downloads] page.
[disposable qube]: /doc/dispvm/
[networking]: /doc/networking/
[firewalls]: /doc/firewall/
[USB]: /doc/usb/
[file]: /doc/copying-files/
[clipboard]: /doc/copy-paste/
[Template]: /doc/templates/
[Qubes-Whonix]: /doc/whonix/
[Whonix]: https://www.whonix.org/
[Tor]: https://www.torproject.org/
[Anti Evil Maid]: /doc/anti-evil-maid/
[Tails]: https://tails.boum.org/
[Xen]: https://www.xenproject.org
[paper-compart]: https://invisiblethingslab.com/resources/2014/Software_compartmentalization_vs_physical_separation.pdf
[doc]: /doc/
[user-faq]: /faq/#users
[system-doc]: /doc/system-doc/
[devel-faq]: /faq/#developers
[downloads]: /downloads/
[getting started]: /getting-started/

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

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

50
basics_user/testing.md Normal file
View File

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

304
basics_user/user-faq.md
View File

@ -1,304 +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)
* [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)
[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)
-----------------
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.
### 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](http://theinvisiblethings.blogspot.com/2008/09/three-approaches-to-computer-security.html) are “Security by Correctness” and “Security by Obscurity.” We don't believe either of these approaches are capable of providing reasonable security today, nor do we believe that they will be capable of doing so in the foreseeable future.
### What about safe languages and formally verified microkernels?
In short: these are non-realistic solutions today. We discuss this in further depth in our [Architecture Specification document](/attachment/wiki/QubesArchitecture/arch-spec-0.3.pdf).
### Why does Qubes use virtualization?
We believe that this is currently the only practically viable approach to implementing strong isolation while simultaneously providing compatibility with existing applications and drivers.
### What do all these terms mean?
All Qubes-specific terms are defined in the [glossary](/doc/glossary/).
### Does Qubes run every app in a separate VM?
No! This would not make much sense. Qubes uses lightweight VMs to create security qubes (e.g., "work," "personal," and "banking,"). A typical user would likely need around five qubes. Very paranoid users, or those who are high-profile targets, might use a dozen or more qubes.
### Why does Qubes use Xen instead of KVM or some other hypervisor?
In short: we believe the Xen architecture allows for the creation of more secure systems (i.e. with a much smaller TCB, which translates to a smaller attack surface). We discuss this in much greater depth in our [Architecture Specification document](/attachment/wiki/QubesArchitecture/arch-spec-0.3.pdf).
### What about this other/new (micro)kernel/hypervisor?
Whenever starting a discussion about another (micro)kernel or hypervisor in relation to Qubes, we strongly suggest including answers to the following questions first:
1. What kinds of containers does it use for isolation? Processes? PV VMs? Fully virtualized VMs (HVMs)? And what underlying h/w technology is used (ring0/3, VT-x)?
2. Does it require specially written/built applications (e.g. patched Firefox)?
3. Does it require custom drivers, or can it use Linux/Windows ones?
4. Does it support VT-d, and does it allow for the creation of untrusted driver domains?
5. Does it support S3 sleep?
6. Does it work on multiple CPUs/Chipsets?
7. What are the performance costs, more or less? (e.g. "XYZ prevents concurrent execution of two domains/processes on shared cores of a single processor", etc.)
8. Other special features? E.g. eliminates cooperative covert channels between VMs?
Here are the answers for Xen 4.1 (which we use as of 2014-04-28):
1. PV and HVM Virtual Machines (ring0/3 for PV domains, VT-x/AMD-v for HVMs).
2. Runs unmodified usermode apps (binaries).
3. Runs unmodified Linux drivers (dom0 and driver domains). PV VMs require special written pvdrivers.
4. Full VT-d support including untrusted driver domains.
5. S3 sleep supported well.
6. Works on most modern CPUs/Chipsets.
7. Biggest performance hit on disk operations (especially in Qubes when complex 2-layer mapping used for Linux qubes). No GPU virtualization.
8. Mostly Works<sup>TM</sup> :)
### What's so special about Qubes' GUI virtualization?
We have designed the GUI virtualization subsystem with two primary goals: security and performance. Our GUI infrastructure introduces only about 2,500 lines of C code (LOC) into the privileged domain (Dom0), which is very little, and thus leaves little space for bugs and potential attacks. At the same time, due to the smart use of Xen shared memory, our GUI implementation is very efficient, so most virtualized applications really feel as if they were executed natively.
### Can I watch YouTube videos in qubes?
Absolutely.
### Can I run applications, like games, which require 3D support?
Those won’t fly. We do not provide OpenGL virtualization for qubes. This is mostly a security decision, as implementing such a feature would most likely introduce a great deal of complexity into the GUI virtualization infrastructure. However, Qubes does allow for the use of accelerated graphics (OpenGL) in Dom0’s Window Manager, so all the fancy desktop effects should still work.
For further discussion about the potential for GPU passthorugh on Xen/Qubes, please see the following threads:
- [GPU passing to HVM](https://groups.google.com/group/qubes-devel/browse_frm/thread/31f1f2da39978573?scoring=d&q=GPU&)
- [Clarifications on GPU security](https://groups.google.com/group/qubes-devel/browse_frm/thread/31e2d8a47c8b4474?scoring=d&q=GPU&)
### Is Qubes a multi-user system?
No. Qubes does not pretend to be a multi-user system. Qubes assumes that the user who controls Dom0 controls the whole system. It would be very difficult to **securely** implement multi-user support. See [here](https://groups.google.com/group/qubes-devel/msg/899f6f3efc4d9a06) for details.
### Why passwordless sudo?
Please refer to [this page](https://www.qubes-os.org/doc/vm-sudo/).
### How should I report documentation issues?
Please see the [documentation guidelines](/doc/doc-guidelines).
### Will Qubes seek to get certified under the GNU Free System Distribution Guidelines (GNU FSDG)?
Not currently, for the same reasons that [Debian is not certified](https://www.gnu.org/distros/common-distros.en.html).
Installation & Hardware Compatibility
-------------------------------------
(See also: [System Requirements](/doc/system-requirements/), [Hardware Compatibility List](/hcl/), and [Certified Laptops](/doc/certified-laptops/).)
### How much disk space does each qube require?
Each qube is created from a TemplateVM and shares the root filesystem with this TemplateVM (in a read-only manner). This means that each qube needs only as much disk space as is necessary to store its own private data. This also means that it is possible to update the software for several qubes simultaneously by running a single update process in the TemplateVM upon which those qubes are based. (These qubes will then have to be restarted in order for the update to take effect in them.)
### How much memory is recommended for Qubes?
At least 4 GB. It is possible to install Qubes on a system with 2 GB of RAM, but the system would probably not be able to run more than three qubes at a time.
### Can I install Qubes on a system without VT-x?
Yes. Xen doesn't use VT-x (or AMD-v) for PV guest virtualization. (It uses ring0/3 separation instead.) However, without VT-x, you won't be able to use fully virtualized VMs (e.g., Windows-based qubes), which were introduced in Qubes 2. In addition, if your system lacks VT-x, then it also lacks VT-d. (See next question.)
### Can I install Qubes on a system without VT-d?
Yes. You can even run a NetVM, but you will not benefit from DMA protection for driver domains. On a system without VT-d, everything should work in the same way, except there will be no real security benefit to having a separate NetVM, as an attacker could always use a simple DMA attack to go from the NetVM to Dom0. **Nonetheless, all of Qubes' other security mechanisms, such as qube separation, work without VT-d. Therefore, a system running Qubes will still be significantly more secure than one running Windows, Mac, or Linux, even if it lacks VT-d.**
### 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?
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.
Errors suggesting this issue:
- in `xl dmesg` output:
(XEN) [VT-D] It's disallowed to assign 0000:00:1a.0 with shared RMRR at dbe9a000 for Dom19.
(XEN) XEN_DOMCTL_assign_device: assign 0000:00:1a.0 to dom19 failed (-1)
- during `qvm-start sys-usb`:
internal error: Unable to reset PCI device [...] no FLR, PM reset or bus reset available.
Another solution would be to set the pci_strictreset option using qvm-prefs in dom0:
`qvm-prefs usbVM -s pci_strictreset false`
This option allows the VM to ignore the error and the VM will start.
Please review the note on [this page](https://www.qubes-os.org/doc/Dom0Tools/QvmPrefs/) and be aware of the potential risk.
### I assigned a PCI device to a qube, then unassigned it/shut down the qube. Why isn't the device available in dom0?
This is an intended feature. A device which was previously assigned to a less trusted qube could attack dom0 if it were automatically reassigned there. In order to re-enable the device in dom0, either:
* Reboot the physical machine.
or
* Go to the sysfs (`/sys/bus/pci`), find the right device, detach it from the pciback driver and attach back to the original driver. Replace `<BDF>` with your device, for example `00:1c.2`:
echo 0000:<BDF> > /sys/bus/pci/drivers/pciback/unbind
MODALIAS=`cat /sys/bus/pci/devices/0000:<BDF>/modalias`
MOD=`modprobe -R $MODALIAS | head -n 1`
echo 0000:<BDF> > /sys/bus/pci/drivers/$MOD/bind
### How do I install Flash in a Debian qube?
The Debian way is to install the flashplugin-nonfree package. Do this in a Debian template. You will have to allow Full access in the firewall prior to installation. This will make Flash available to every qube using that template.
If you only want Flash available in one qube:
- download the Flash Player for linux (64 bit) .tar.gz from [Adobe](https://get.adobe.com/flashplayer/otherversions).
- untar the downloaded file ```tar xf install_flash_player_11_linux.x86_64.tar.gz```
- create ~/.mozilla/plugins if it does not exist
- move libflashhplayer.so to ~/.mozilla/plugins, and restart iceweasel.

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

@ -8,189 +8,435 @@ redirect_from:
- /wiki/BuildingArchlinuxTemplate/
---
Template building
=================
# Archlinux template building instructions
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:
**These are the instructions for Qubes 3.2. They will take you step by step through the entire process start to finish**
Download qubes-builder git code
-------------------------------
*Note: These instructions have not been tested for Qubes 3.1. However they could be working.*
Prefer the [marmarek git repository](https://github.com/marmarek/qubes-builder) as it is the most recent one.
*Note: No binary package for the archlinux template exists for Qubes 3.1.*
~~~
git clone https://github.com/marmarek/qubes-builder.git
~~~
## 1: Create and configure VM to use for template building
Change your builder.conf
------------------------
* The VM should be based on a Fedora template. It's best to use a standalone VM. I created a standalone VM based on
the Fedora 23 template. I named the VM “**development**”. These instructions assume a standalone VM based on a Fedora template is being used.
<br>
<br>
![arch-template-01](/attachment/wiki/ArchlinuxTemplate/arch-template-01.png)
<br>
<br>
* Ensure there is at least 25GB preferably 30GB of free space in the private storage. I made the private storage 30GB to be safe.
<br>
<br>
![arch-template-02](/attachment/wiki/ArchlinuxTemplate/arch-template-02.png)
<br>
<br>
Change the following variables / add the following lines (as appropriate):
*Note: Unless otherwise noted, all commands are from within the “development” VM or whatever you named your standalone VM used for building the template.*
~~~
BUILDER_PLUGINS += builder-archlinux
GIT_PREFIX := marmarek/qubes-
DISTS_VM += archlinux
~~~
## 2: Create GitHub Account (optional)
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).
* 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.
Get all required sources
------------------------
* Create user account here https://github.com
<br>
<br>
![arch-template-03](/attachment/wiki/ArchlinuxTemplate/arch-template-03.png)
<br>
<br>
~~~
make get-sources
~~~
## 3: Install necessary packages to 'development' VM for "Qubes Automated Build System"
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.
* Necessary packages to install:
You can ignore the repositories that are failing by adding the following line to your builder.conf:
* git
~~~
COMPONENTS:=$(filter-out desktop-linux-kde desktop-linux-xfce,$(COMPONENTS))
~~~
* createrepo
Just don't forget that you need to comment this line again if you want to build the whole Qubes-OS install CD.
* rpm-build
Make all required Qubes components
----------------------------------
* make
The first use of the builder can take several hours depending on your bandwidth as it will install an archlinux chroot:
* rpmdevtools
~~~
make qubes-vm
~~~
* python2-sh
Now build the template itself
-----------------------------
* dialog
This can take again several hours, especially the first time you built and archlinux template:
* rpm-sign
~~~
make linux-template-builder
~~~
* gnupg
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)
* The tools can usually be installed all together with the following terminal command string:
* * * * *
* **$ sudo dnf install git createrepo rpm-build make wget rpmdevtools python2-sh dialog rpm-sign gnupg**
<br>
<br>
![arch-template-04](/attachment/wiki/ArchlinuxTemplate/arch-template-04.png)
<br>
<br>
Known problems during building or when running the VM
=====================================================
## 4: Downloading and verifying the integrity of the "Qubes Automated Build System"
Build fails when fetching qubes-mgmt-salt
-----------------------------------------
* Import the Qubes master key
gpg --keyserver pgp.mit.edu --recv-keys 0xDDFA1A3E36879494
* Verify its fingerprint, set as 'trusted'. [This is described here](/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.)
# Execute the following commands in your home directory.
# It is assumed that the path to the repository is '~/qubes-builder'.
mkdir -p qubes-builder/keyrings/git
cp -t qubes-builder/keyrings/git/ .gnupg/pubring.gpg .gnupg/trustdb.gpg
* 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-configs/**
* **$ nano -W qubes-os-r3.2.conf** or **$ gedit qubes-os-r3.2.conf** or etc….
<br>
<br>
![arch-template-06](/attachment/wiki/ArchlinuxTemplate/arch-template-06.png)
<br>
<br>
* Go to the first line containing '**DISTS_VM ?= fc23**' it will be preceeded by line '**DIST_DOM0 ?= fc20**'. Remove '**fc23**' or whatever is listed there leaving only '**DISTS_VM ?=**'. Then save the file and close the text editor.
<br>
<br>
![arch-template-07](/attachment/wiki/ArchlinuxTemplate/arch-template-07.png)
<br>
<br>
<br>
## 6: Run the 'setup' script to build the builder.conf file
* Run the 'setup' script located in '**/home/user/qubes-builder/**' Make sure you are in directory '**qubes-builder**'
* **$ cd /home/user/qubes-builder/**
* **$ ./setup**
<br>
<br>
![arch-template-08](/attachment/wiki/ArchlinuxTemplate/arch-template-08.png)
<br>
<br>
* First screen will ask you to import 'Qubes-Master-Signing-key.asc'. The 'setup' script not only downloads but confirms the key to that of the key on Qubes-OS website.
* Select '**YES**'
* Select '**OK**' Press '**Enter**'
<br>
<br>
![arch-template-09](/attachment/wiki/ArchlinuxTemplate/arch-template-09.png)
<br>
<br>
* Next screen will ask you to import Marek Marczykowski-Goracki (Qubes OS signing key). Again 'setup' will confirm this key to the fingerprint.
* Select '**YES**'
* Select '**OK**' Press '**Enter**'
<br>
<br>
![arch-template-10](/attachment/wiki/ArchlinuxTemplate/arch-template-10.png)
<br>
<br>
* This screen will give you the choice of which Qubes Release to build the template for.
* Select '**Qubes Release 3.2**'
* Select '**OK**' Press '**Enter**'
<br>
<br>
![arch-template-11](/attachment/wiki/ArchlinuxTemplate/arch-template-11.png)
<br>
<br>
* Screen "**Choose Repos To Use To Build Packages**"
* Select 'QubesOS/qubes- Stable - Default Repo'
* Select '**OK**' Press '**Enter**'
<br>
<br>
![arch-template-12](/attachment/wiki/ArchlinuxTemplate/arch-template-12.png)
<br>
<br>
* Screen "**Build Template Only?**"
* Select '**Yes**' Press '**Enter**'
<br>
<br>
![arch-template-12](/attachment/wiki/ArchlinuxTemplate/arch-template-12a.png)
<br>
<br>
* Screen '**Builder Plugin Selection**' will give choices of builder plugins to use for the build.
* Deselect '**Fedora**'
* Deselect '**mgmt_salt**'
* Select '**builder-archlinux**'
* Select '**OK**' Press **Enter**
<br>
<br>
![arch-template-13](/attachment/wiki/ArchlinuxTemplate/arch-template-13.png)
<br>
<br>
* Screen '**Get sources**' wants to download additional packages needed for the choosen plugin/s.
* Select '**Yes**' Press '**Enter**'
<br>
<br>
![arch-template-14](/attachment/wiki/ArchlinuxTemplate/arch-template-14.png)
<br>
<br>
* Then wait for download to finish and press '**OK**'
<br>
<br>
![arch-template-14](/attachment/wiki/ArchlinuxTemplate/arch-template-15.png)
<br>
<br>
* Screen '**Template Distribution Selection**' allows you to choose the actual template/s you wish to build.
* Scroll Down to the very bottom (it is off the screen at first)
* Select '**archlinux**'
* Select '**OK**' Press '**Enter**'
<br>
<br>
![arch-template-16](/attachment/wiki/ArchlinuxTemplate/arch-template-16.png)
<br>
<br>
*Note: 'Setup' will close and will output the text of the created build.conf file as well as the needed **make** commands to build the template*
<br>
<br>
![arch-template-17](/attachment/wiki/ArchlinuxTemplate/arch-template-17.png)
<br>
<br>
## 7: Install all the dependencies
*Note: make sure you are in the “qubes-builder” directory to run the following cmds*
* **$ make install-deps**
<br>
<br>
![arch-template-18](/attachment/wiki/ArchlinuxTemplate/arch-template-18.png)
<br>
<br>
## 8: Get all the require sources for the build: (Note: this may take some time)
* **$ make get-sources**
<br>
<br>
![arch-template-19](/attachment/wiki/ArchlinuxTemplate/arch-template-19.png)
<br>
<br>
<br>
## 9: Make all the require Qubes Components
* **Note:** You can run a single command to build all the Qubes components or you can run them each individually.
Both ways below:
* Single command to build all Qubes components together: (this command can take a long time to process depending of your pc proccessing power)
* **$ make qubes-vm**
<br>
<br>
![arch-template-20](/attachment/wiki/ArchlinuxTemplate/arch-template-20.png)
<br>
<br>
* These are the indivual component 'make' commands:
* **$ make vmm-xen-vm**
* **$ make core-vchan-xen-vm**
* **$ make core-qubesdb-vm**
* **$ make linux-utils-vm**
* **$ make core-agent-linux-vm**
* **$ make gui-common-vm**
* **$ make gui-agent-linux-vm**
<br>
<br>
## 10: Make the actual Archlinux template
* **$ make template**
<br>
<br>
![arch-template-21](/attachment/wiki/ArchlinuxTemplate/arch-template-21.png)
<br>
<br>
## 11: Transfer Template into Dom0
* You need to ensure these two files are in the '**noarch**' directory
* **$ cd /home/user/qubes-builder/qubes-src/linux-template-builder/rpm/**
* **$ ls** *(confirm the below two files are there)*
* **install-templates.sh** (script to install template in dom0)
* **$ cd noarch**
* **$ ls**
* **qubes-template-archlinux-X.X.X-XXXXXXXXXXXX.noarch.rpm** (this is the template package 'X' replaces version and build digits)
<br>
<br>
![arch-template-22](/attachment/wiki/ArchlinuxTemplate/arch-template-22.png)
<br>
<br>
* **Transfer the install-templates.sh script file into Dom0**
*Note: as there is not a typical file transfer method for Dom0, for security reasons, this less than simple transfer function has to be used*
* Switch to Domo and open a terminal window.
**Note:** Take care when entering these cmd strings. They are very long and have a number of characters that are easy to mix '**-**' vs '**.**' '**<u>T</u>emplates** (correct) vs **<u>t</u>emplates** (wrong) or **Template_**'(also wrong) This script will also take care of transfering the actual template.rpm to Dom0 as well.
* **$ qvm-run --pass-io development 'cat /home/user/qubes-builder/qubes-src/linux-template-builder/rpm/install-templates.sh' > install-templates.sh**
* **$ chmod +x install-templates.sh**
* **$ ./install-templates.sh**
<br>
<br>
![arch-template-23](/attachment/wiki/ArchlinuxTemplate/arch-template-23.png)
<br>
<br>
![arch-template-24](/attachment/wiki/ArchlinuxTemplate/arch-template-24.png)
<br>
<br>
* If everything went correct there should be a Archlinux template listed in your Qubes VM Manager *
# Known problems in building with Qubes R3.X
## Build fails when fetching qubes-mgmt-salt
The `qubes-mgmt-salt` repo is not currently forked under the marmarek user on
GitHub, to whom the above instructions set the `GIT_PREFIX`. As Archlinux is
not yet supported by mgmt-salt, simply leave it out of the build (when building
the Archlinux template on it's own) by appending the following to your
`builder.conf`:
the Archlinux template on its own) by appending the following to your `override.conf` file:
~~~
BUILDER_PLUGINS := $(filter-out mgmt-salt,$(BUILDER_PLUGINS))
~~~
`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:
-----------------------------------------------------------------------------------------------
## The nm-applet (network manager icon) fails to start when archlinux is defined as a template-vm
In fact /etc/dbus-1/system.d/org.freedesktop.NetworkManager.conf does not allow a standard user to run network manager clients. To allow this, one need to change inside \<policy context="default"\>:
~~~
<deny send_destination="org.freedesktop.NetworkManager"/>
~~~
`<deny send_destination="org.freedesktop.NetworkManager"/>`
to
~~~
<allow send_destination="org.freedesktop.NetworkManager"/>
~~~
`<allow send_destination="org.freedesktop.NetworkManager"/>`
DispVM, Yum proxy and most Qubes addons (thunderbird ...) have not been tested at all.
--------------------------------------------------------------------------------------
## 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)
----------------------------------------------------------------------------------------------------------------------
## Error when building the gui-agent-linux with pulsecore error
This is apparently a bug in Archlinux between glibc and pulseaudio package 4.0-6. The packages pulseaudio-4.0-2 and libpulse-4.0-2 are known to work and can be downloaded and reinstalled manually.
Error when building the gui-agent-linux with pulsecore error
------------------------------------------------------------
~~~
```
module-vchan-sink.c:62:34: fatal error: pulsecore/core-error.h: No such file or directory
#include <pulsecore/core-error.h>
~~~
```
This error is because Archlinux update package too quickly. Probably, a new version of pulseaudio has been released, but the qubes team has not imported the new development headers yet.
You can create fake new headers just by copying the old headers:
~~~
```
cd qubes-builder/qubes-src/gui-agent-linux/pulse
ls
cp -r pulsecore-#lastversion pulsecore-#archlinuxversion
~~~
```
You can check the current archlinux pulseaudio version like this:
~~~
sudo chroot chroot-archlinux/ pacman -Qi pulseaudio
~~~
`sudo chroot chroot-archlinux/ pacman -Qi pulseaudio`
chroot-archlinux/dev/pts has not been unmounted
-----------------------------------------------
## 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
=============================
# Known problems in building with Qubes R2-B2
xen-vmm-vm fail to build with a PARSETUPLE related error (FIXED):
-----------------------------------------------------------------
## 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)
[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 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:
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}"
~~~
`extra="ro nomodeset 3 console=hvc0 rd_NO_PLYMOUTH {kernelopts}"`
to:
~~~
extra="ro nomodeset console=hvc0 rd_NO_PLYMOUTH {kernelopts}"
~~~
`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
----------------------------------------------------------------------------------------------------
## 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
@ -223,19 +469,23 @@ sudo sed 's:qubes-vm-updateable:qubes_vm_updateable:g' -i /usr/lib/qubes/qubes_t
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:
Do not forgot to unmount the VM:
~~~
umount /mnt/vm
~~~
`umount /mnt/vm`
Installing the template in dom0 fails because of a missing dependency (qubes-core-dom0-linux)
---------------------------------------------------------------------------------------------
## 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:
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
~~~
`sudo rpm -U --nodeps yourpackage.rpm`
# Qubes Mailing List Threads on the Archlinux build process
* [Qubes-Devel](https://groups.google.com/forum/#!forum/qubes-devel): [Qubes Builder failed Archlinux repository is missing](https://groups.google.com/forum/#!topic/qubes-devel/tIFkS-rPVx8)
* [Qubes-Users](https://groups.google.com/forum/#!forum/qubes-users): [Trying to compile archlinux template](https://groups.google.com/forum/#!topic/qubes-users/7wuwr3LgkQQ)
<br>

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

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

86
building/building-whonix-template.md Normal file
View File

@ -0,0 +1,86 @@
---
layout: doc
title: Building Whonix Templates
permalink: /doc/building-whonix-template/
redirect_from:
- /en/doc/building-whonix-template/
---
## Building Whonix Templates
The Whonix templates are easily downloaded and installed by following the [procedure here](https://www.whonix.org/wiki/Qubes/Install).
However, they are integrated into `qubes-builder` so they are straight-forward to build yourself if you prefer.
Many other Qubes templates can also be built by following this procedure.
Simply choose the appropriate builder(s) and template(s) you wish to build in the `./setup` procedure below.
Always include the `mgmt-salt` builder.
First, set up the [Build Environment](/doc/qubes-r3-building/#build-environment) (follow the build environment section only).
Next, configure the builder:
~~~
cd ~/qubes-builder
./setup
# Select Yes to add Qubes Master Signing Key
# Select Yes to add Qubes OS Signing Key
# Select 3.2 or 4.0 for version
# Stable
# Yes (we want to build only templates)
# Select builder-fedora, builder-debian, template-whonix, mgmt-salt (setup won't let you continue if you don't include builder-fedora, but we don't actually use it)
# Choose Yes to add adrelanos's third party key
# Yes (to download sources)
# Select whonix-gateway, whonix-workstation (for the currently shipping templates)
~~~
Continue the build process with:
~~~
make install-deps
make get-sources
~~~
You will often need to edit/update `qubes-src/template-whonix/builder.conf` at this stage to specify the currently shipping Tor Browser version.
Open it in your favorite editor, then look for "Extra Whonix Build Options" and add/edit the `WHONIX_TBB_VERSION` variable to specify the current version.
For example:
```
################################################################################
# Extra Whonix Build Options
################################################################################
# Whonix repository.
WHONIX_APT_REPOSITORY_OPTS ?= stable
#WHONIX_APT_REPOSITORY_OPTS = off
# Use turbo mode to build template
BUILDER_TURBO_MODE ?= 1
# Enable Tor by default (0: disable; 1: enable)
WHONIX_ENABLE_TOR ?= 0
WHONIX_TBB_VERSION ?= 7.5.2
```
You can add/edit the `WHONIX_TBB_VERSION` variable in `~/qubes-builder/builder.conf` instead of this file if preferred.
Finally, use:
~~~
make qubes-vm
make template
~~~
Once the build is complete, the install packages for your newly built templates will be located in `/qubes-builder/qubes-src/linux-template-builder/rpm/noarch`.
Copy them from there to dom0 and install:
~~~
qvm-run --pass-io <src-vm> 'cat ~/qubes-builder/qubes-src/linux-template-builder/rpm/noarch/qubes-template-whonix-gw-4.0.0-201802250036.noarch.rpm' > ~/qubes-template-whonix-gw-4.0.0-201802250036.noarch.rpm
qvm-run --pass-io <src-vm> 'cat ~/qubes-builder/qubes-src/linux-template-builder/rpm/noarch/qubes-template-whonix-ws-4.0.0-201802250145.noarch.rpm' > ~/qubes-template-whonix-ws-4.0.0-201802250145.noarch.rpm
sudo dnf install qubes-template-whonix-gw-4.0.0-201802250036.noarch.rpm
sudo dnf install qubes-template-whonix-ws-4.0.0-201802250145.noarch.rpm
~~~
And you are done!

4
building/development-workflow.md
View File

@ -419,7 +419,7 @@ Remember to also import gpg public key using `rpm --import`.
### Deb packages - Apt repo
Steps are mostly the same as in case of yum repo. Only details differs:
Steps are mostly the same as in the case of yum repo. The only details that differ:
- use [linux-deb] instead of [linux-yum] as a base - both in source and target VM
- use different `update_repo.sh` script in source VM (below)
@ -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/#port-forwarding-to-a-vm-from-the-outside-world
[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

57
building/kde-dom0.md
View File

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

34
building/pvusb.md
View File

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

4
building/qubes-builder-details.md
View File

@ -33,8 +33,8 @@ Variables for Windows build:
- `WIN_SIGN_CMD` Command used to sign resulting binaries. Note that default value is *sign.bat*. If you don't want to sign binaries, specify some placeholder here (eg. *true*). Check existing components (eg. vmm-xen-windows-pvdrivers) for example scripts. This command will be run with certain environment variables:
- `CERT_FILENAME` Path to key file (pfx format)
- `CERT_PASSWORD` Key password
- `CERT_PUBLIC_FILENAME` Certificate path in case of self-signed cert
- `CERT_CROSS_CERT_FILENAME` Certificate path in case of correct autheticode cert
- `CERT_PUBLIC_FILENAME` Certificate path in the case of self-signed cert
- `CERT_CROSS_CERT_FILENAME` Certificate path in the case of correct autheticode cert
- `SIGNTOOL` Path to signtool
- `WIN_PACKAGE_CMD` Command used to produce installation package (msi or msm). Default value is *wix.bat*, similar to above - use *true* if you don't want this command.
- `WIN_OUTPUT_HEADERS` Directory (relative to `WIN_SOURCE_SUBDIRS` element) with public headers of the package - for use in other components.

30
building/qubes-builder.md
View File

@ -8,6 +8,8 @@ redirect_from:
- /wiki/QubesBuilder/
---
**Note: The build system has been improved since this how-to was last updated. The [ISO building instructions](/doc/qubes-r3-building/) contain more up-to-date information on how to use the build system.**
Building Qubes from scratch
===========================
@ -15,39 +17,47 @@ We have a fully automated build system for Qubes, that downloads, builds and
packages all the Qubes components, and finally should spit out a ready-to-use
installation ISO.
In order to use it one should use an rpm-based distro, like Fedora :) and should ensure the following packages are installed:
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
- make
- wget
- rpmdevtools
- python-sh
- python2-sh
- dialog
- rpm-sign
- dpkg-dev
- debootstrap
- PyYAML
- devscripts
- perl-Digest-MD5
- perl-Digest-SHA
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 python2-sh dialog rpm-sign dpkg-dev debootstrap PyYAML devscripts perl-Digest-MD5 perl-Digest-SHA
The build system creates build environments in chroots and so no other packages are needed on the host. All files created by the build system are contained within the qubes-builder directory. The full build requires some 25GB of free space, so keep that in mind when deciding where to place this directory.
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 +99,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 +136,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:

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

@ -1,6 +1,6 @@
---
layout: doc
title: Qubes R3 Building
title: Qubes ISO Building
permalink: /doc/qubes-r3-building/
redirect_from:
- /en/doc/qubes-r3-building/
@ -8,52 +8,182 @@ redirect_from:
- /wiki/QubesR3Building/
---
Building Qubes OS 3.0 ISO
Building Qubes OS ISO
=========================
Ensure your system is rpm-based and that you have necessary dependencies installed (see [QubesBuilder](/doc/qubes-builder/) for more info):
Build Environment
-----------------
Fedora 26 has been successfully used to build Qubes R3.2 and R4.0 with the below steps.
Other rpm-based operating systems may also work.
Travis-CI also uses Ubuntu 14.04 to perform test builds, except it can not test the `./setup` script.
In `dom0`, install the Fedora 26 template if you don't already have it.
~~~
sudo yum install git createrepo rpm-build make wget rpmdevtools pandoc
sudo qubes-dom0-update qubes-template-fedora-26
~~~
Get the necessary keys to verify the sources:
Create a standalone appVM from the Fedora 26 template.
You may choose your own name, but this document will refer to it as `dev26`.
Set private storage to at least 60 GB if you will be building only the default templates; 100 GB or more if you plan on additional.
It's not required, but if you allocate additional CPU cores, the build process can utilize them at some steps such as the kernel build.
Likewise, more memory (up to 16 GB) can help.
Last, you may want to disable memory balancing on `dev26` but keep in mind the impact on your other qubes.
Once you've built `dev26`, open a Terminal window to it and install the necessary dependencies (see [QubesBuilder](/doc/qubes-builder/) for more info):
~~~
$ wget https://keys.qubes-os.org/keys/qubes-master-signing-key.asc
$ gpg --import qubes-master-signing-key.asc
$ gpg --edit-key 36879494
# Verify fingerprint!, set trust to *ultimate*
$ wget https://keys.qubes-os.org/keys/qubes-developers-keys.asc
$ gpg --import qubes-developers-keys.asc
$ sudo dnf install git createrepo rpm-build make wget rpmdevtools dialog rpm-sign gnupg dpkg-dev debootstrap python2-sh
~~~
Note we do *not* relay above on the security of our server (keys.qubes-os.org) nor the connection (ssl, cert) -- we only rely on you getting the Qubes Master Signing Key fingerprint *somehow* and ensure they match!
Now lets bootstrap the builder. Unfortunately the builder cannot verify itself (the classic Chicken and Egg problem), so we need to verify the signature manually:
Get the necessary keys to verify the sources (run these and other commands below as a regular user, not root):
~~~
$ git clone git://github.com/QubesOS/qubes-builder.git
$ cd qubes-builder
$ git describe --exact-match HEAD
<some tag>
$ git tag -v <some tag>
wget https://keys.qubes-os.org/keys/qubes-master-signing-key.asc
gpg --import qubes-master-signing-key.asc
gpg --edit-key 36879494
fpr
# Verify fingerprint! See Note below!
# Once verified, set trust to *ultimate*
# (Typical sequence is trust, 5, q)
wget https://keys.qubes-os.org/keys/qubes-developers-keys.asc
gpg --import qubes-developers-keys.asc
~~~
Assuming the verification went fine, we're good to go with all the rest without ever thinking more about verifying digital signatures on all the rest of the components, as the builder will do that for us, for each component, every time we, even for all aux files (e.g. Xen or Linux kernel sources).
**Note** In the above process, we do *not* rely on the security of our server (keys.qubes-os.org) nor the connection (ssl, cert) -- we only rely on you getting the Qubes Master Signing Key fingerprint *somehow* and ensuring they match!
See [Verifying Signatures](/security/verifying-signatures/#1-get-the-qubes-master-signing-key-and-verify-its-authenticity) for verification sources.
Let's configure the builder first (we can use one of the example configs, either for R2 or "master", which currently means pre-released R3):
Now let's bootstrap the builder. Unfortunately, the builder cannot verify itself (the classic Chicken and Egg problem), so we need to verify the signature manually:
~~~
cp example-configs/qubes-os-master.conf builder.conf
git clone git://github.com/QubesOS/qubes-builder.git
cd qubes-builder
git tag -v `git describe`
~~~
You can take a loot at the `builder.conf.default` for a description of all available options. Nevertheless, the default config should be enough for start:
**Note** It's very important to check if the verification message contains "Good signature from ..." and does not contain "WARNING: This key is not certified with a trusted signature!".
Assuming the verification went fine, we're good to go with all the rest without ever thinking more about verifying digital signatures on all the rest of the components, apart from an additional step if doing a non-scripted build.
The builder will do that for us for each component, every time we build, even for all auxiliary files (e.g. Xen or Linux kernel sources).
Build using setup script
-----------------
Let's configure the builder first (see [procedure](/doc/qubes-r3-building/#build-using-manual-steps) at bottom if you would prefer to manually configure):
~~~
$ make get-sources qubes
$ make sign-all # this requires setting SIGN_KEY in the builder.conf, can be skipped for test builds.
$ make iso
cd ~/qubes-builder
./setup
# Select Yes to add Qubes Master Signing Key
# Select Yes to add Qubes OS Signing Key
# Select 3.2 or 4.0 for version
# Stable
# No (we want a full build)
# Select builder-fedora, builder-debian, template-whonix, mgmt-salt
# Choose Yes to add adrelanos's third party key
# Yes (to download)
# Select fc26, stretch, whonix-gateway, whonix-workstation (for the currently shipping templates)
~~~
Continue the build process with:
~~~
make install-deps
make get-sources
~~~
When building the Whonix templates, you will often need to add/update the `WHONIX_TBB_VERSION` variable at this stage to specify the currently shipping Tor Browser version.
See the related note under [Extra Whonix Build Options](/doc/building-whonix-template/).
Finally, if you are making a test build, use:
~~~
make qubes
make iso
~~~
Or for a fully signed build (this requires setting `SIGN_KEY` in `builder.conf`):
~~~
make qubes
make sign-all
make iso
~~~
Enjoy your new ISO!
Build using manual steps
-----------------
Instead of using `./setup`, you can manually configure the build.
The script takes care of a lot of the keyring preparation for us, so we first need to set that up.
If you will be building Whonix templates:
~~~
cd ~
gpg --keyserver pgp.mit.edu --recv-keys 916B8D99C38EAF5E8ADC7A2A8D66066A2EEACCDA
gpg --fingerprint 916B8D99C38EAF5E8ADC7A2A8D66066A2EEACCDA
~~~
**Note:** It's very important to check the fingerprint displayed against multiple sources such as the [Whonix web site](https://www.whonix.org/wiki/Whonix_Signing_Key), etc.
It should look something like this:
~~~
pub 4096R/2EEACCDA 2014-01-16 [expires: 2021-04-17]
Key fingerprint = 916B 8D99 C38E AF5E 8ADC 7A2A 8D66 066A 2EEA CCDA
uid Patrick Schleizer <adrelanos@riseup.net>
sub 4096R/CE998547 2014-01-16 [expires: 2021-04-17]
sub 4096R/119B3FD6 2014-01-16 [expires: 2021-04-17]
sub 4096R/77BB3C48 2014-01-16 [expires: 2021-04-17]
~~~
Next, prepare the Git keyring directory and copy them in:
~~~
export GNUPGHOME=~/qubes-builder/keyrings/git
mkdir --parents "$GNUPGHOME"
cp ~/.gnupg/pubring.gpg "$GNUPGHOME"
cp ~/.gnupg/trustdb.gpg "$GNUPGHOME"
chmod --recursive 700 "$GNUPGHOME"
~~~
Copy one of the example configurations:
~~~
cd ~/qubes-builder
cp example-configs/qubes-os-master.conf builder.conf
~~~
Edit `builder.conf`, referring to `doc/Configuration.md` for a description of all available options.
Continue the build process with:
~~~
make install-deps
make get-sources
unset GNUPGHOME
~~~
When building the Whonix templates, you will often need to add/update the `WHONIX_TBB_VERSION` variable at this stage to specify the currently shipping Tor Browser version.
See the related note under [Extra Whonix Build Options](/doc/building-whonix-template/).
Finally, if you are making a test build, use:
~~~
make qubes
make iso
~~~
Or for a fully signed build (this requires setting `SIGN_KEY` in `builder.conf`):
~~~
make qubes
make sign-all
make iso
~~~
Enjoy your new ISO!

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

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

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

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

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

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

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

@ -11,96 +11,218 @@ redirect_from:
Qubes Backup, Restoration, and Migration
========================================
**Caution:** The Qubes backup system currently relies on a [weak key derivation scheme](https://github.com/QubesOS/qubes-issues/issues/971). It is *strongly recommended* that users select a *high-entropy* passphrase for use with Qubes backups.
**Caution:** The Qubes R3.2 backup system currently relies on a [weak key derivation scheme](https://github.com/QubesOS/qubes-issues/issues/971).
Although resolved in R4.0 and higher with the switch to scrypt, it is *strongly recommended* that users select a *high-entropy* passphrase for use with Qubes backups.
With Qubes, it's easy to back up and restore your whole system, as well as to migrate between two physical machines.
As of Qubes R2B3, these functions are integrated into the Qubes VM Manager GUI. There are also two command-line tools available which perform the same functions: [qvm-backup](/doc/dom0-tools/qvm-backup/) and [qvm-backup-restore](/doc/dom0-tools/qvm-backup-restore/).
As of Qubes R2B3, these functions are integrated into the Qubes VM Manager GUI.
There are also two command-line tools available which perform the same functions: [qvm-backup](/doc/dom0-tools/qvm-backup/) and [qvm-backup-restore](/doc/dom0-tools/qvm-backup-restore/).
Creating a Backup
Creating a Backup (R4.0 and later)
-----------------
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.
1. Go to **Applications menu -> System Tools -> Backup Qubes**.
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.
Once you have selected all desired AppVMs, click **Next**.
You may choose whether to compress backups by checking or unchecking the **Compress the backup** box.
Normally this should be left on unless you have a specific reason otherwise.
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/usb/), you can use the directory selection widget to mount a connected device (under "Other locations" item on the left); or 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 browse to it using the convenient directory selection dialog (`...`) at the right.
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.
**Note:** The supplied passphrase is used for **both** encryption/decryption and integrity verification.
At this point, you may also choose whether to save your settings by checking or unchecking the **Save settings as default backup profile** box.
**Warning: Saving the settings will result in your backup passphrase being saved in plaintext in dom0, so consider your threat model before checking this box.**
4. You will now see the summary of VMs to be backed up.
If there are any issues preventing the backup, they will be listed here and the **Next** button grayed out.
5. When you are ready, click **Next**.
Qubes will proceed to create your backup.
Once the progress bar has completed, you may click **Finish**.
Creating a Backup (R3.2 and earlier)
-----------------
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 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:** A VM must be shut down in order to be backed up.
Currently running VMs appear in red.
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 (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/usb/), you can use the directory selection widget to mount a connected device (under "Other locations" item on the left); or 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 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 browse to it using the convenient directory selection dialog (`...`) at the right.
If it does not exist, you must create it manually prior to backing up.
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.
**Note:** It is strongly recommended that you opt to encrypt all backups which will be sent to untrusted destinations!
**Note:** The supplied passphrase is used for **both** encryption/decryption and integrity verification. If you decide not to encrypt your backup (by unchecking the **Encrypt backup** box), the passphrase you supply will be used **only** for integrity verification. If you supply a passphrase but do not check the **Encrypt backup** box, your backup will **not** be encrypted!
**Note:** The supplied passphrase is used for **both** encryption/decryption and integrity verification.
If you decide not to encrypt your backup (by unchecking the **Encrypt backup** box), the passphrase you supply will be used **only** for integrity verification.
If you supply a passphrase but do not check the **Encrypt backup** box, your backup will **not** be encrypted!
4. When you are ready, click **Next**. Qubes will proceed to create your backup. Once the progress bar has completed, you may click **Finish**.
4. You will now see the summary of VMs to be backed up.
If there are any issues preventing the backup, they will be listed here and the **Next** button grayed out.
5. When you are ready, click **Next**.
Qubes will proceed to create your backup.
Once the progress bar has completed, you may click **Finish**.
Restoring from a Backup
Restoring from a Backup (R4.0 and later)
-----------------------
1. In **Qubes VM Manager**, click **System** on the menu bar, then click **Restore VMs from backup** in the drop-down list. This brings up the **Qubes Restore VMs** window.
1. Go to **Applications menu -> System Tools -> Restore Backup**.
This brings up the **Qubes Restore VMs** window.
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 on a [USB mass storage device](/doc/usb/), attach it first to another VM or select `sys-usb` in the next item.
- 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.
**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.
You must also specify the directory and filename of the backup (or a command to be executed in a VM) in the **Backup file** field.
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 browse to (using `...`) the `backups` folder.
Once you've located the backup file, double-click it or select it and hit **OK**.
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.
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.
1. **ignore missing templates and net VMs**: If any of the VMs in your backup depended upon a NetVM 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 and set them to use the default NetVM and system default template.
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. **Verify backup integrity, do not restore the data**: This will scan the backup file for corrupted data.
However, it does not currently detect if it is missing data as long as it is a correctly structured, non-corrupted backup file.
See [issue #3498](https://github.com/QubesOS/qubes-issues/issues/3498) for more details.
4. If your backup is encrypted, you must check the **Encrypted backup** box. If a passphrase was supplied during the creation of your backup (regardless of whether it is encrypted), then you must supply it here.
4. If your backup is encrypted, you must check the **Encrypted backup** box.
If a passphrase was supplied during the creation of your backup (regardless of whether it is encrypted), then you must supply it here.
**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:** 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.
All backups made from a Qubes R4.0 system will be encrypted.
**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.
5. You will now see the summary of VMs to be restored.
If there are any issues preventing the restore, they will be listed here and the **Next** button grayed out.
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**.
6. When you are ready, click **Next**.
Qubes will proceed to restore from your backup.
Once the progress bar has completed, you may click **Finish**.
Restoring from a Backup (R3.2 and earlier)
-----------------------
1. In **Qubes VM Manager**, click **System** on the menu bar, then click **Restore VMs from backup** in the drop-down list.
This brings up the **Qubes Restore VMs** window.
2. Select the source location of the backup to be restored:
- If your backup is located on a [USB mass storage device](/doc/usb/), attach it first to another VM or select `sys-usb` in the next item.
- 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 and filename of the backup (or a command to be executed in a VM) in the **Backup file** field.
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 browse to (using `...`) the `backups` folder.
Once you've located the backup file, double-click or select it and hit **OK**.
3. There are three options you may select when restoring from a backup:
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 and set them to use the default NetVM and system default template.
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. **Verify backup integrity, do not restore the data**: This will scan the backup file for corrupted data.
However, it does not currently detect if it is missing data as long as it is a correctly structured, non-corrupted backup file. See [issue #3498](https://github.com/QubesOS/qubes-issues/issues/3498) for more details.
4. If your backup is encrypted, you must check the **Encrypted backup** box.
If a passphrase was supplied during the creation of your backup (regardless of whether it is encrypted), then you must supply it here.
**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:** 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. You will now see the summary of VMs to be restored.
If there are any issues preventing the restore, they will be listed here and the **Next** button grayed out.
6. When you are ready, click **Next**.
Qubes will proceed to restore from your backup.
Once the progress bar has completed, you may click **Finish**.
Emergency Backup Recovery without Qubes
---------------------------------------
The Qubes backup system has been designed with emergency disaster recovery in mind. No special Qubes-specific tools are required to access data backed up by Qubes. In the event a Qubes system is unavailable, you can access your data on any GNU/Linux system with the following procedure.
The Qubes backup system has been designed with emergency disaster recovery in mind.
No special Qubes-specific tools are required to access data backed up by Qubes.
In the event a Qubes system is unavailable, you can access your data on any GNU/Linux system with the following procedure.
For emergency restore of backup created on Qubes R2 or newer take a look [here](/doc/backup-emergency-restore-v3/). For backups created on earlier Qubes version, take a look [here](/doc/backup-emergency-restore-v2/).
Refer to the following for emergency restore of a backup created on:
* [Qubes R4 or newer](/doc/backup-emergency-restore-v4/)
* [Qubes R3](/doc/backup-emergency-restore-v3/)
* [Qubes R2 or older](/doc/backup-emergency-restore-v2/)
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](/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 AppVM. 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.
* 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 other 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
-----
* The Qubes backup system relies on `openssl enc`, which is known to use a very weak key derivation scheme. The Qubes backup system also uses the same passphrase for authentication and for encryption, which is problematic from a security perspective. Users are advised to use a very high entropy passphrase for Qubes backups. For a full discussion, see [this ticket](https://github.com/QubesOS/qubes-issues/issues/971) and [this thread](https://groups.google.com/d/msg/qubes-devel/CZ7WRwLXcnk/u_rZPoVxL5IJ).
* The Qubes R3.2 and earlier backup system relies on `openssl enc`, which is known to use a very weak key derivation scheme.
The Qubes backup system also uses the same passphrase for authentication and for encryption, which is problematic from a security perspective.
Users are advised to use a very high entropy passphrase for Qubes backups.
For a full discussion, see [this ticket](https://github.com/QubesOS/qubes-issues/issues/971) and [this thread](https://groups.google.com/d/msg/qubes-devel/CZ7WRwLXcnk/u_rZPoVxL5IJ).
* For the technical details of the backup system, please refer to [this thread](https://groups.google.com/d/topic/qubes-devel/TQr_QcXIVww/discussion).
* If working with symlinks, note the issues described in [this thread](https://groups.google.com/d/topic/qubes-users/EITd1kBHD30/discussion).

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

@ -21,59 +21,49 @@ To copy a file from dom0 to a VM (domU), simply use `qvm-copy-to-vm`:
qvm-copy-to-vm <dest-vm> <file>
~~~
The file will arrive in your destination VM in the `~/QubesIncoming/dom0/`
directory.
The file will arrive in your destination VM in the `~/QubesIncoming/dom0/` directory.
### Copying logs from Dom0 ###
In order to easily copy/paste the contents of logs from dom0 to the inter-VM
clipboard, you can simply:
In order to easily copy/paste the contents of logs from dom0 to the inter-VM clipboard, you can simply:
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).
You may now paste the log contents to any VM as you normally would (i.e., 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. In Qubes 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 or Shift-Insert to paste the copied text into an AppVM as normal.
3. In other versions, write the data you wish to copy into `/var/run/qubes/qubes-clipboard.bin`, then `echo -n dom0 > /var/run/qubes/qubes-clipboard.bin.source`.
Then use Ctrl-Shift-V to paste the data to the desired VM.
Copying **to** Dom0
-------------------
There should normally be few reasons for the user to want to copy files from VMs
to Dom0, as Dom0 only acts as a "thin trusted terminal", and no user
applications run there. Copying untrusted files to Dom0 is not advised and may
compromise the security of your Qubes system. Because of this, we do not provide
a graphical user interface for it, unlike [copying files between
VMs](/doc/copying-files/).
There should normally be few reasons for the user to want to copy files from VMs to Dom0, as Dom0 only acts as a "thin trusted terminal", and no user applications run there.
Copying untrusted files to Dom0 is not advised and may compromise the security of your Qubes system.
Because of this, we do not provide a graphical user interface for it, unlike [copying files between VMs](/doc/copying-files/).
One common use-case for this is if we want to use a desktop wallpaper in Dom0 we
have located in one of our AppVMs (e.g. in the 'personal' AppVM where we got the
wallpaper from our camera or downloaded it from the Internet). While it's a
well-justified reason, imagine what would happen if the wallpaper (e.g. a JPEG
file) was somehow malformed or malicious and attempted to exploit a hypothetical
JPEG parser bug in Dom0 code (e.g. in the Dom0's Xorg/KDE code that parses the
wallpaper and displays it).
One common use-case for this is if we want to use a desktop wallpaper in Dom0 we have located in one of our AppVMs (e.g. in the 'personal' AppVM where we got the wallpaper from our camera or downloaded it from the Internet).
While it's a well-justified reason, imagine what would happen if the wallpaper (e.g. a JPEG file) was somehow malformed or malicious and attempted to exploit a hypothetical JPEG parser bug in Dom0 code (e.g. in the Dom0's Xorg/KDE code that parses the wallpaper and displays it).
If you are determined to copy some files to Dom0 anyway, you can use the
following method (run this command from Dom0's console):
If you are determined to copy some files to Dom0 anyway, you can use the following method (run this command from Dom0's console):
~~~
qvm-run --pass-io <src-vm> 'cat /path/to/file_in_src_domain' > /path/to/file_name_in_dom0
~~~
You can use the same method to copy files from Dom0 to VMs (if, for some reason,
you don't want to use `qvm-copy-to-vm`):
You can use the same method to copy files from Dom0 to VMs (if, for some reason, you don't want to use `qvm-copy-to-vm`):
~~~
cat /path/to/file_in_dom0 | qvm-run --pass-io <dest-vm> 'cat > /path/to/file_name_in_appvm'

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

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

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

@ -19,28 +19,45 @@ In order to copy file(s) from qube A to qube B, follow these steps:
GUI
---
1. Open file manager in the source qube (qube A), choose file(s) that you wish to copy, and right click on the selection, and choose `Copy to another AppVM`
1. Open file manager in the source qube (qube A), choose file(s) that you wish to copy, and right click on the selection, and choose `Copy to another AppVM`
1. A dialog box will appear asking for the name of the destination qube (qube B).
2. A dialog box will appear asking for the name of the destination qube (qube B).
1. A confirmation dialog box will appear(this will be displayed by Dom0, so none of the qubes can fake your consent). After you click ok, qube B will be started if it is not already running, the file copy operation will start, and the files will be copied into the following folder in qube B:
3. A confirmation dialog box will appear(this will be displayed by Dom0, so none of the qubes can fake your consent). After you click ok, qube B will be started if it is not already running, the file copy operation will start, and the files will be copied into the following folder in qube B:
- `/home/user/QubesIncoming/<source>`
`/home/user/QubesIncoming/<source>`
4. You can now move them whenever you like in the qube B filesystem using the file manager there.
1. You can now move them whenever you like in the qube B filesystem using the file manager there.
CLI
---
[qvm-copy-to-vm](/doc/vm-tools/qvm-copy-to-vm/)
```
qvm-copy-to-vm [--without-progress] dest_vmname file [file]+
```
Also see: [qvm-copy-to-vm](/doc/vm-tools/qvm-copy-to-vm/)
Qubes 4.0
---------
In Qubes 4.0, qvm-copy-to-vm and qvm-move-to-vm are deprecated (GUI behaviour is unchanged from Qubes 3.2). In the command line, use qvm-copy or qvm-move to avoid typing target qube name twice.
```
qvm-copy [--without-progress] file [file]+
```
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/qrexec3/#revoking-yes-to-all-authorization)

139
common-tasks/dispvm.md
View File

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

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

@ -24,15 +24,13 @@ If one allowed one of the VMs to "own" the full screen, e.g. to show a movie on
Secure use of full screen mode
------------------------------
However, it is possible to deal with full screen mode in a secure way assuming there are mechanisms that can be used at any time to show the full desktop, and which cannot be intercepted by the VM. An example of such q mechanism is the KDE's "Present Windows" and "Desktop Grid" effects, which are similar to Mac's "Expose" effect, and which can be used to immediately detect potential "GUI forgery", as they cannot be intercepted by any of the VM (as the GUID never passes down the key combinations that got consumed by KDE Window Manager), and so the VM cannot emulate those. Those effects are enabled by default in KDE once Compositing gets enabled in KDE (System Settings -\> Desktop -\> Enable Desktop Effects), which is recommended anyway. By default they are triggered by Ctrl-F8 and Ctrl-F9 key combinations, but can also be reassigned to other shortcuts.
However, it is possible to deal with full screen mode in a secure way assuming there are mechanisms that can be used at any time to show the full desktop, and which cannot be intercepted by the VM. An example of such a mechanism is the KDE's "Present Windows" and "Desktop Grid" effects, which are similar to Mac's "Expose" effect, and which can be used to immediately detect potential "GUI forgery", as they cannot be intercepted by any of the VM (as the GUID never passes down the key combinations that got consumed by KDE Window Manager), and so the VM cannot emulate those. Those effects are enabled by default in KDE once Compositing gets enabled in KDE (System Settings -\> Desktop -\> Enable Desktop Effects), which is recommended anyway. By default they are triggered by Ctrl-F8 and Ctrl-F9 key combinations, but can also be reassigned to other shortcuts.
Another option is to use Alt+Tab for switching windows. This shortcut is also handled by dom0.
Enabling full screen mode for select VMs
----------------------------------------
If you want to enable full screen mode for select VMs, you can do that by creating the following entry in the /etc/qubes/guid.conf file in Dom0:
**Note:** 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))
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:
~~~
VM: {
@ -44,6 +42,8 @@ VM: {
The string 'personal' above is an example only and should be replaced by the actual name of the VM for which you want to enable this functionality.
**Note:** There should be only one `VM: {}` block in the file (or you will [get into problems](https://groups.google.com/d/msg/qubes-users/-Yf9yNvTsVI/xXsEm8y2lrYJ))
One can also enable this functionality for all the VMs globally in the same file, by modifying the 'global' section:
~~~
@ -58,3 +58,13 @@ global: {
~~~
Be sure to restart the VM(s) after modifying this file, for the changes to take effect.
**Note:** Regardless of the settings above, you can always put a window into
fullscreen mode in Xfce4 using the trusted window manager by right-clicking on
a window's title bar and selecting "Fullscreen". This functionality should still
be considered safe, since a VM window still can't voluntarily enter fullscreen
mode. The user must select this option from the trusted window manager in dom0.
To exit fullscreen mode from here, press `alt` + `space` to bring up the title
bar menu again, then select "Leave Fullscreen".
For StandaloneHVMs, you should set the screen resolution in the qube to that of the host, (or larger), *before* setting fullscreen mode in Xfce4.

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

@ -11,33 +11,101 @@ redirect_from:
Managing shortcuts to applications in AppVMs
============================================
For ease of use Qubes aggregates shortcuts to applications that are installed in AppVMs and shows them in one "start menu" in dom0. Clicking on such shortcut runs the assigned application in its AppVM.
For ease of use Qubes aggregates shortcuts to applications that are installed in AppVMs and shows them in one "start menu" in dom0.
Clicking on such shortcut runs the assigned application in its AppVM.
![dom0-menu.png"](/attachment/wiki/ManagingAppVmShortcuts/dom0-menu.png)
To make newly installed applications show up in the menu, use the **qvm-sync-appmenus** command (Linux VMs does this automatically):
To make applications newly installed via the OS's package manager show up in the menu, use the `qvm-sync-appmenus` command (Linux VMs do this automatically):
`qvm-sync-appmenus vmname`
After that, select the *Add more shortcuts* entry in VM's submenu to customize which applications are shown:
After that, select the *Add more shortcuts* entry in the VM's submenu to customize which applications are shown:
![dom0-appmenu-select.png"](/attachment/wiki/ManagingAppVmShortcuts/dom0-appmenu-select.png)
The above image shows that Windows HVMs are also supported (provided that Qubes Tools are installed).
Behind the scenes
-----------------
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](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`.
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.
Some times applications may not have included a `.desktop` file and may not be detected by `qvm-sync-appmenus`.
Other times, you may want to make a web shortcut available from the Qubes start menu.
You can manually create new entries in the "available applications" list of shortcuts for all AppVMs based on a TemplateVM.
To do this:
1. Open a terminal window to the TemplateVM.
2. Create a custom `.desktop` file in `/usr/share/applications` (you may need to first create the subdirectory).
Look in `/usr/share/applications` for existing examples, or see the full [file specification](https://specifications.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html).
It will be something like:
```
[Desktop Entry]
Version=1.0
Type=Application
Terminal=false
Icon=/usr/share/icons/Adwaita/256x256/devices/scanner.png
Name=VueScan
GenericName=Scanner
Comment=Scan Documents
Categories=Office;Scanning;
Exec=vuescan
```
3. In dom0, run `qvm-sync-appmenus <TemplateVMName>`.
4. Go to VM Settings of the AppVM(s) to which you want to add the new shortcut, then the Applications tab.
Move the newly created shortcut to the right under selected.
If you only want to create a shortcut for a single AppVM, you can create a custom menu entry instead:
1. Open a terminal window to Dom0.
2. Create a custom `.desktop` file in `~/.local/share/applications`.
Look in the same directory for existing examples, or see the full [file specification](https://specifications.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html).
You may use `qvm-run` inside the `.desktop` file; see [Behind the scenes](/doc/managing-appvm-shortcuts/#behind-the-scenes) for more details.
3. Edit the `~/.config/menus/applications-merged/<vmname>-vm.menu` file for the AppVM.
4. Add a custom menu entry referring to your newly created `.desktop` file.
~~~
<Menu>
<Name>Webmail</Name>
<Include>
<Filename>custom.desktop</Filename>
</Include>
</Menu>
~~~
What about applications in DispVMs?
-----------------------------------
[See here](/doc/dispvm-customization/#adding-arbitrary-programs-to-disposable-vm-application-menu).
Behind the scenes
-----------------
`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.
* R4.0
The list of installed applications for each AppVM is stored in dom0's `~/.local/share/qubes-appmenus/<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 `~/.local/share/qubes-appmenus/<vmname>/apps`.
Actual command lines for the menu shortcuts involve `qvm-run` command which starts a process in another domain.
Examples: `qvm-run -q -a --service -- %VMNAME% qubes.StartApp+7-Zip-7-Zip_File_Manager` or `qvm-run -q -a --service -- %VMNAME% qubes.StartApp+firefox`
Note that you can create a shortcut that points to a .desktop file in your AppVM with e.g. `qvm-run -q -a --service -- personal qubes.StartApp+firefox`.
* R3.2
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.
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'`.

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

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

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

@ -11,44 +11,56 @@ 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.
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 default template is called **fedora-23** in Qubes R3.2 and **fedora-26** in Qubes R4.0.
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`, `/usr/local`, or `/rw` then it will disappear after the AppVM reboots (as the root filesystem for this AppVM will again be "taken" from the TemplateVM).
**This means one normally installs 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/fedora-template-upgrade-21/#compacting-the-upgraded-template) to recover space in dom0.
Unlike VM private filesystems, under R3.x the template VM root filesystem does not support discard by default, 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
In R4.0 and higher, the template root filesystem is created in a thin pool so manual trims are no longer needed.
See [here](/doc/disk-trim) for further discussion on enabling discards/trim support under all versions.
Installing (or updating) software in the TemplateVM
----------------------------------------------------
In order to permanently install new software, you should:
- Start the template VM and then start either console (e.g. `gnome-terminal`) or dedicated software management application, such as `gpk-application` (*Start-\>Applications-\>Template: fedora-XX-x64-\>Add/Remove software*),
- Start the template VM and then start either console (e.g. `gnome-terminal`) or dedicated software management application, such as `gpk-application` (*Start-\>Applications-\>Template: fedora-XX-\>Add/Remove software*),
- Install/update software as usual (e.g. using yum, or the dedicated GUI application). Then, shutdown the template VM,
- Install/update software as usual (e.g. using dnf, 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 can restart others whenever this will be convenient to you.
Testing repositories
--------------------
There are three Qubes VM testing repoistories (where `*` denotes the Release):
### Fedora ###
* `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
There are three Qubes VM testing repositories (where `*` denotes the Release):
To temporarily enable any of these repos, use the `--enablerepo=<repo-name>`
option. Example commands:
* `qubes-vm-*-current-testing` -- testing packages that will eventually land in the stable (`current`) repository
* `qubes-vm-*-security-testing` -- a subset of `qubes-vm-*-current-testing` that contains packages that qualify as security fixes
* `qubes-vm-*-unstable` -- packages that are not intended to land in the stable (`qubes-vm-*-current`) repository; mostly experimental debugging packages
To temporarily enable any of these repos, use the `--enablerepo=<repo-name>` option.
Example commands:
~~~
sudo dnf upgrade --enablerepo=qubes-vm-*-current-testing
@ -56,31 +68,55 @@ sudo dnf upgrade --enablerepo=qubes-vm-*-security-testing
sudo dnf upgrade --enablerepo=qubes-vm-*-unstable
~~~
To enable or disable any of these repos permanently, change the corresponding boolean in
`/etc/yum.repos.d/qubes-*.repo`.
To enable or disable any of these repos permanently, change the corresponding boolean in `/etc/yum.repos.d/qubes-*.repo`.
Reverting changes to a TemplateVM
### 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-r*.list`
Reverting changes to a TemplateVM (R4.0)
---------------------------------
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.
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 command appropriate to your version of Qubes.
**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!
**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-26` TemplateVM:
1. Shut down `fedora-26`.
If you've already just shut it down, do **not** start it again (see above).
2. In a dom0 terminal, type:
qvm-volume revert fedora-26:root
Reverting changes to a TemplateVM (R3.2)
---------------------------------
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 command appropriate to your version of Qubes.
**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).
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
@ -89,46 +125,89 @@ For example, to revert changes to the `fedora-23` TemplateVM:
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).
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 Template VM(s)
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 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.
- Use multiple templates (see below) for different classes of domains, e.g. a less trusted template, used for creation of less trusted AppVMs, would get various packages from somehow less trusted vendors, while the template used for more trusted AppVMs will only get packages from the standard Fedora repos.
- Use multiple templates (see below) for different classes of domains, e.g. a less trusted template, used for creation of less trusted AppVMs, would get various packages from less trusted vendors, while the template used for more trusted AppVMs will only get packages from the standard Fedora repos.
Some popular questions:
- So, why should we actually trust Fedora repos -- it also contains large amount of 3rd party software that might buggy, right?
- So, why should we actually trust Fedora repos -- it also contains large amount of third-party software that might be 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 far as the template's compromise is concerned, 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 `/usr/bin/firefox` and get 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?
- But why trust Fedora?
Because we chose to use Fedora as a vendor for the Qubes OS foundation (e.g. for Dom0 packages and for AppVM packages). We also chose to trust several other vendors, such as Xen.org, kernel.org, and a few others whose software we use in Dom0. We had to trust *somebody* as we are unable to write all the software from scratch ourselves. But there is a big difference in trusting all Fedora packages to be non-malicious (in terms of installation scripts) vs. trusting all those packages are non-buggy and non-exploitable. We certainly do not assume the latter.
Because we chose to use Fedora as a vendor for the Qubes OS foundation (e.g. for Dom0 packages and for AppVM packages).
We also chose to trust several other vendors, such as Xen.org, kernel.org, and a few others whose software we use in Dom0.
We had to trust *somebody* as we are unable to write all the software from scratch ourselves.
But there is a big difference in trusting all Fedora packages to be non-malicious (in terms of installation scripts) vs. trusting all those packages are non-buggy and non-exploitable.
We certainly do not assume the latter.
- So, are the template VMs as trusted as Dom0?
Not quite. Dom0 compromise is absolutely fatal, and it leads to Game Over<sup>TM</sup>. However, a compromise of a template affects only a subset of all your AppVMs (in case you use more than one template, or also some standalone VMs). Also, if your AppVMs are network disconnected, even though their filesystems might got compromised due to the corresponding template compromise, it still would be difficult for the attacker to actually leak out the data stolen in an AppVM. Not impossible (due to existence of cover channels between VMs on x86 architecture), but difficult and slow.
Not quite.
Dom0 compromise is absolutely fatal, and it leads to Game Over<sup>TM</sup>.
However, a compromise of a template affects only a subset of all your AppVMs (in case you use more than one template, or also some standalone VMs).
Also, if your AppVMs are network disconnected, even though their filesystems might get compromised due to the corresponding template compromise, it still would be difficult for the attacker to actually leak out the data stolen in an AppVM.
Not impossible (due to existence of cover channels between VMs on x86 architecture), but difficult and slow.
Standalone VMs
Standalone VMs (R4.0 and later)
--------------
Standalone VMs have their own copy of the whole filesystem, and thus can be updated and managed on their own.
But this means that they take a few GBs on disk, and also that centralized updates do not apply to them.
Sometimes it might be convenient to have a VM that has its own filesystem, where you can directly introduce changes, without the need to start/stop the template VM.
Such situations include e.g.:
- VMs used for development (devel environments require a lot of \*-devel packages and specific devel tools)
- VMs used for installing untrusted packages.
Normally you install digitally signed software from Red Hat/Fedora repositories, and it's reasonable that such software has non malicious *installation* scripts (rpm pre/post scripts).
However, when you would like to install some packages from less trusted sources, or unsigned, then using a dedicated (untrusted) standalone VM might be a better way.
In order to create a standalone VM you can use a command line like this (from console in Dom0):
```
qvm-create --class StandaloneVM --label <label> --property virt_mode=hvm <vmname>
```
... or click appropriate options in the Qubes Manager's Create VM window.
(Note: Technically, `virt_mode=hvm` is not necessary for every StandaloneVM. However, it makes sense if you want to use a kernel from within the VM.)
Standalone VMs (R3.2 and earlier)
--------------
Standalone VMs have their own copy of the whole filesystem, and thus can be updated and managed on its own. But this means that they take a few GBs on disk, and also that centralized updates do not apply to them.
Standalone VMs have their own copy of the whole filesystem, and thus can be updated and managed on their own.
But this means that they take a few GBs on disk, and also that centralized updates do not apply to them.
Sometime it might be convenient to have a VM that has its own filesystem, where you can directly introduce changes, without the need to start/stop the template VM. Such situations include e.g.:
Sometimes it might be convenient to have a VM that has its own filesystem, where you can directly introduce changes, without the need to start/stop the template VM.
Such situations include e.g.:
- VMs used for development (devel environments requires a lot of \*-devel packages and specific devel tools)
- VMs used for development (devel environments require a lot of \*-devel packages and specific devel tools)
- VMs used for installing untrusted packages. Normally you install digitally signed software from Red Hat/Fedora repositories, and it's reasonable that such software has non malicious *installation* scripts (rpm pre/post scripts). However, when you would like to install some packages form less trusted sources, or unsigned, then using a dedicated (untrusted) standalone VM might be a better way.
- VMs used for installing untrusted packages.
Normally you install digitally signed software from Red Hat/Fedora repositories, and it's reasonable that such software has non malicious *installation* scripts (rpm pre/post scripts).
However, when you would like to install some packages from less trusted sources, or unsigned, then using a dedicated (untrusted) standalone VM might be a better way.
In order to create a standalone VM you can use a command line like this (from console in Dom0):
@ -138,12 +217,18 @@ qvm-create <vmname> --standalone --label <label>
... or click appropriate options in the Qubes Manager's Create VM window.
Using more than one template
----------------------------
It's also possible to have more than one template VM in the system. E.g. one could clone the default template using the `qvm-clone` command in Dom0. This allows to have a customized template, e.g. with devel packages, or less trusted apps, shared by some subset of domains. It is important to note that the default template is "system managed" and therefore cannot be backed up using Qubes' built-in backup function. In order to ensure the preservation of your custom settings and the availability of a "known-good" backup template, you may wish to clone the default system template and use your clone as the default template for your AppVMs.
It's also possible to have more than one template VM in the system.
E.g. one could clone the default template using the `qvm-clone` command in Dom0.
This allows to have a customized template, e.g. with devel packages, or less trusted apps, shared by some subset of domains.
It is important to note that the default template is "system managed" and therefore cannot be backed up using Qubes' built-in backup function.
In order to ensure the preservation of your custom settings and the availability of a "known-good" backup template, you may wish to clone the default system template and use your clone as the default template for your AppVMs.
When you create a new domain you can choose which template this VM should be based on. If you use command line, you should use the `--template` switch:
When you create a new domain you can choose which template this VM should be based on.
If you use command line, you should use the `--template` switch:
~~~
qvm-create <vmname> --template <templatename> --label <label>
@ -152,52 +237,103 @@ qvm-create <vmname> --template <templatename> --label <label>
Temporarily allowing networking for software installation
---------------------------------------------------------
Some 3rd party applications cannot be installed using the standard yum repositories, and need to be manually downloaded and installed. When the installation requires internet connection to access 3rd party repositories, it will naturally fail when run in a Template VM because the default firewall rules for templates only allow connections to standard yum repositories. So it is necessary to modify firewall rules to allow less restrictive internet access for the time of the installation, if one really wants to install those applications into a template. As soon as software installation is completed, firewall rules should be returned back to the default state. The user should decided by themselves whether such 3rd party applications should be equally trusted as the ones that come from the standard Fedora signed repositories and whether their installation will not compromise the default Template VM, and potentially consider installing them into a separate template or a standalone VM (in which case the problem of limited networking access doesn't apply by default), as described above.
Some third-party applications cannot be installed using the standard yum repositories, and need to be manually downloaded and installed.
When the installation requires internet connection to access third-party repositories, it will naturally fail when run in a Template VM because the default firewall rules for templates only allow connections from package managers.
So it is necessary to modify firewall rules to allow less restrictive internet access for the time of the installation, if one really wants to install those applications into a template.
As soon as software installation is completed, firewall rules should be returned back to the default state.
The user should decide by themselves whether such third-party applications should be equally trusted as the ones that come from the standard Fedora signed repositories and whether their installation will not compromise the default Template VM, and potentially consider installing them into a separate template or a standalone VM (in which case the problem of limited networking access doesn't apply by default), as described above.
Updates proxy
-------------
Updates proxy is a service which filter http access to allow access to only something that looks like yum or apt repository. This is meant to mitigate user errors (like using browser in the template VM), rather than some real isolation. It is done with http proxy instead of simple firewall rules because it is hard to list all the repository mirrors (and keep that list up to date). The proxy is used only to filter the traffic, not to cache anything.
Updates proxy is a service which allows access only from package managers.
This is meant to mitigate user errors (like using browser in the template VM), rather than some real isolation.
It is done with http proxy (tinyproxy) instead of simple firewall rules because it is hard to list all the repository mirrors (and keep that list up to date).
The proxy is used only to filter the traffic, not to cache anything.
The proxy is running in selected VMs (by default all the NetVMs (1)) and intercept traffic directed to 10.137.255.254:8082. Thanks to such configuration all the VMs can use the same proxy address, and if there is a proxy on network path, it will handle the traffic (of course when firewall rules allows that). If the VM is configured to have access to the updates proxy (2), the startup scripts will automatically configure yum to really use the proxy (3). Also access to updates proxy is independent of any other firewall settings (VM will have access to updates proxy, even if policy is set to block all the traffic).
The proxy is running in selected VMs (by default all the NetVMs (1)) and intercepts traffic directed to 10.137.255.254:8082.
Thanks to such configuration all the VMs can use the same proxy address, and if there is a proxy on network path, it will handle the traffic (of course when firewall rules allow that).
If the VM is configured to have access to the updates proxy (2), the startup scripts will automatically configure dnf to really use the proxy (3).
Also access to updates proxy is independent of any other firewall settings (VM will have access to updates proxy, even if policy is set to block all the traffic).
(1) Services tab -\> "qubes-yum-proxy" entry; check qvm-service manual for details
There are two services ([qvm-service](https://www.qubes-os.org/doc/dom0-tools/qvm-service/), [service framework](https://www.qubes-os.org/doc/qubes-service/)):
(2) Firewall tab -\> Allow connections to Updates Proxy; this setting works immediately (once OK is clicked)
1. qubes-updates-proxy (and its deprecated name: qubes-yum-proxy) - a service providing a proxy for templates - by default enabled in NetVMs (especially: sys-net)
2. updates-proxy-setup (and its deprecated name: yum-proxy-setup) - use a proxy provided by another VM (instead of downloading updates directly), enabled by default in all templates
(3) Services tab -\> "yum-proxy-setup" entry; this setting works at next VM startup
This is generally the same in R3.2 and R4.0 - in both cases both the old and new names work.
And in both cases defaults listed above are applied if the service is not explicitly listed in services tab.
### Technical details
### Technical details (R4.0)
1. Updates proxy: It is running as "qubes-yum-proxy" service. Startup script of this service setup firewall rule to intercept proxy traffic:
Instead of using a network connection like in R3.2, R4.0 uses RPC/qrexec.
The proxy is configured in qrexec policy on dom0: `/etc/qubes-rpc/policy/qubes.UpdatesProxy`.
By default this is set to sys-net and/or sys-whonix, depending on firstboot choices.
This new design allows for templates to be updated even when they are not connected to any netvm.
Example policy file in R4.0 (with whonix installed, but not set as default updatevm for all templates):
```
# any VM with tag `whonix-updatevm` should use `sys-whonix`; this tag is added to `whonix-gw` and `whonix-ws` during installation and is preserved during template clone
$tag:whonix-updatevm $default allow,target=sys-whonix
$tag:whonix-updatevm $anyvm deny
# other templates use sys-net
$type:TemplateVM $default allow,target=sys-net
$anyvm $anyvm deny
```
### Technical details (R3.2)
The proxy is running in selected VMs (by default all the NetVMs).
Thanks to such configuration all VMs can use the same proxy address, and if there is a proxy on network path, it will handle the traffic (of course when firewall rules allow that).
The first proxy on the network path according to the template's netvm setting will be used.
If the VM is configured to have access to the updates proxy (1), the startup scripts will automatically configure dnf to use the proxy.
Also access to updates proxy is independent of any other firewall settings (VM will have access to updates proxy, even if the policy is set to block all the traffic).
(1) Firewall tab -\> Allow connections to Updates Proxy; this setting works immediately (once OK is clicked)
1. Updates proxy: It is running as "qubes-updates-proxy" service.
Startup script of this service sets up a firewall rule to intercept traffic directed to 10.137.255.254:8082:
~~~
iptables -t nat -A PR-QBS-SERVICES -d 10.137.255.254/32 -i vif+ -p tcp -m tcp --dport 8082 -j REDIRECT
~~~
1. VM using the proxy service Startup script (qubes-misc-post service) configure yum using /etc/yum.conf.d/qubes-proxy.conf file. It can either contain
2. VMs using the proxy service Startup script (updates-proxy-setup or qubes-misc-post service) configure
dnf using `/etc/yum.conf.d/qubes-proxy.conf` file.
It can either contain
~~~
proxy=http://10.137.255.254:8082/
~~~
line, or be empty. Note that this file is specifically included from main yum.conf, yum does not support real conf.d configuration style...
line, or be empty. Note that this file is specifically included from main yum.conf, dnf does not support real conf.d configuration style...
Note on treating AppVM's root filesystem non-persistency as a security feature
Note on treating AppVM's root filesystem non-persistence as a security feature
------------------------------------------------------------------------------
As explained above, any AppVM that is based on a Template VM (i.e. which is not a Standalone VM) has its root filesystem non-persistent across the VM reboots. In other words whatever changes the VM makes (or the malware running in this AppVM makes) to its root filesystem, are automatically discarded whenever one restarts the AppVM. This might seem like an excellent anti-malware mechanism to be used inside the AppVM...
As explained above, any AppVM that is based on a Template VM (i.e. which is not a Standalone VM) has its root filesystem non-persistent across the VM reboots.
In other words whatever changes the VM makes (or the malware running in this AppVM makes) to its root filesystem, are automatically discarded whenever one restarts the AppVM.
This might seem like an excellent anti-malware mechanism to be used inside the AppVM...
However, one should be careful with treating this property as a reliable way to keep the AppVM malware-free. This is because the non-persistency, in case of normal AppVMs, applies only to the root filesystem and not to the user filesystem (on which the `/home`, `/rw`, and `/usr/local` are stored) for obvious reasons. It is possible that malware, especially malware that could be specifically written to target a Qubes-based AppVMs, could install its hooks inside the user home directory files only. Examples of obvious places for such hooks could be: `.bashrc`, the Firefox profile directory which contains the extensions, or some PDF or DOC documents that are expected to be opened by the user frequently (assuming the malware found an exploitable bug in the PDF or DOC reader), and surely many others places, all in the user's home directory.
However, one should be careful with treating this property as a reliable way to keep the AppVM malware-free.
This is because the non-persistence, in the case of normal AppVMs, applies only to the root filesystem and not to the user filesystem (on which the `/home`, `/rw`, and `/usr/local` are stored) for obvious reasons.
It is possible that malware, especially malware that could be specifically written to target a Qubes-based AppVMs, could install its hooks inside the user home directory files only.
Examples of obvious places for such hooks could be: `.bashrc`, the Firefox profile directory which contains the extensions, or some PDF or DOC documents that are expected to be opened by the user frequently (assuming the malware found an exploitable bug in the PDF or DOC reader), and surely many others places, all in the user's home directory.
One advantage of the non-persistent rootfs though, is that the malware is still inactive before the user's filesystem gets mounted and "processed" by system/applications, which might theoretically allow for some scanning programs (or a skilled user) to reliably scan for signs of infections of the AppVM. But, of course, the problem of finding malware hooks in general is hard, so this would work likely only for some special cases (e.g. an AppVM which doesn't use Firefox, as otherwise it would be hard to scan the Firefox profile directory reliably to find malware hooks there). Also note that the user filesystem's metadata might got maliciously modified by malware in order to exploit a hypothetical bug in the AppVM kernel whenever it mounts the malformed filesystem. However, these exploits will automatically stop working (and so the infection might be cleared automatically) after the hypothetical bug got patched and the update applied (via template update), which is an exceptional feature of Qubes OS.
One advantage of the non-persistent rootfs though, is that the malware is still inactive before the user's filesystem gets mounted and "processed" by system/applications, which might theoretically allow for some scanning programs (or a skilled user) to reliably scan for signs of infections of the AppVM.
But, of course, the problem of finding malware hooks in general is hard, so this would work likely only for some special cases (e.g. an AppVM which doesn't use Firefox, as otherwise it would be hard to scan the Firefox profile directory reliably to find malware hooks there).
Also note that the user filesystem's metadata might got maliciously modified by malware in order to exploit a hypothetical bug in the AppVM kernel whenever it mounts the malformed filesystem.
However, these exploits will automatically stop working (and so the infection might be cleared automatically) after the hypothetical bug got patched and the update applied (via template update), which is an exceptional feature of Qubes OS.
Also note that Disposable VMs do not have persistent user filesystem, and so they start up completely "clean" every time. Note the word "clean" means in this context: the same as their template filesystem, of course.
Also note that Disposable VMs do not have persistent user filesystem, and so they start up completely "clean" every time.
Note the word "clean" means in this context: the same as their template filesystem, of course.
RPMFusion for a Fedora TemplateVM
---------------------------------
If you would like to enable the [RPM Fusion](http://rpmfusion.org/) repository: open a Terminal of the TemplateVM and type the following commands:
If you would like to enable the [RPM Fusion](http://rpmfusion.org/) repository, open a Terminal of the TemplateVM and type the following commands:
~~~
sudo dnf config-manager --set-enabled rpmfusion-free rpmfusion-nonfree

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

@ -0,0 +1,62 @@
---
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 create a .desktop file that advertises itself as a handler for http/https links, and then set 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 within a not so trusted enviroment - for example, a Windows VM - an application that tracks and reports its usage, or you simply want to protect your data.
Start the Windows TemplateVM (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)
Trim for standalone AppVMs
---------------------
The `qvm-trim-template` command is not available for a standalone AppVM.
It is still possible to trim the AppVM disks by using the `fstrim --all` command from the appvm.
You can also add the `discard` option to the mount line in `/etc/fstab` inside the standalone AppVM if you want trimming to be performed automatically, but there may be a performance impact on writes and deletes.

651
common-tasks/usb.md
View File

@ -7,6 +7,10 @@ redirect_from:
- /en/doc/stick-mounting/
- /doc/StickMounting/
- /wiki/StickMounting/
- /doc/external-device-mount-point/
- /en/doc/external-device-mount-point/
- /doc/ExternalDeviceMountPoint/
- /wiki/ExternalDeviceMountPoint/
- /doc/usbvm/
- /en/doc/usbvm/
- /doc/USBVM/
@ -18,280 +22,250 @@ Using and Managing USB Devices
==============================
How to attach USB drives
------------------------
----------
(**Note:** In the present context, the term "USB drive" denotes any
[USB mass storage device][mass-storage]. In addition to smaller flash memory
sticks, this includes things like USB external hard drives.)
(**Note:** In the present context, the term "USB drive" denotes any [USB mass storage device][mass-storage].
In addition to smaller flash memory sticks, this includes things like USB external hard drives.)
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
controller, see [here][usb-controller].)
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.
USB drive mounting is integrated into the Qubes VM Manager GUI. Simply insert
your USB drive, right-click on the desired qube in the Qubes VM Manager list,
click **Attach/detach block devices**, and select your desired action and
device. This, however, only works for the whole device. If you would like to
attach individual partitions, you must use the command-line tool.
### R4.0 ###
The command-line tool you may use to mount whole USB drives or their partitions
is `qvm-block`. This tool can be used to assign a USB drive to a qube as
follows:
USB drive mounting is integrated into the Devices Widget.
This is the tool tray icon with a yellow square located in the top right of your screen by default.
Simply insert your USB drive and click on the widget.
You will see multiple entries for your USB drive; typically, `sys-usb:sda`, `sys-usb:sda1`, and `sys-usb:2-1` for example.
The simplest (but slightly less secure, see note below about attaching individual partitions) option is to attach the entire block drive.
In our example, this is `sda`, so hover over it.
This will pop up a submenu showing running VMs to which the USB drive can be connected.
Click on one and your USB drive will be attached!
Note that attaching individual partitions can be slightly more secure because it doesn't force the target AppVM to parse the partition table.
However, it often means the AppVM won't detect the new partition and you will need to manually mount it inside the AppVM.
See below for more detailed steps.
The command-line tool you may use to mount whole USB drives or their partitions is `qvm-block`.
This tool can be used to assign a USB drive to a qube as follows:
1. Insert your USB drive.
2. In a dom0 console (running as a normal user), list all available block
devices:
2. In a dom0 console (running as a normal user), list all available block devices:
qvm-block -l
qvm-block
This will list all available block devices connected to any USB controller
in your system, no matter which qube hosts the controller. The name of the
qube hosting the USB controller is displayed before the colon in the device
name. The string after the colon is the name of the device used within the
qube, like so:
This will list all available block devices connected to any USB controller in your system, no matter which qube hosts the controller.
The name of the qube hosting the USB controller is displayed before the colon in the device name.
The string after the colon is the name of the device used within the qube, like so:
dom0:sdb1 Cruzer () 4GiB
usbVM:sdb1 Disk () 2GiB
**Note:** If your device is not listed here, you may refresh the list by
calling (from the qube to which the device is connected):
**Note:** If your device is not listed here, you may refresh the list by calling from the qube to which the device is connected (typically `sys-usb`):
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:
3. Assuming your USB drive is attached to `sys-usb` and is `sdb`, we attach the device to a qube with the name `personal` like so:
qvm-block -a personal dom0:sdb
qvm-block attach personal sys-usb: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.
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.
You may also mount one partition at a time by using the same command with
the partition number after `sdb`.
You may also mount one partition at a time by using the same command with the partition number after `sdb`.
**Warning:** when working with single partitions, it is possible to assign
the same partition to multiple qubes. For example, you could attach `sdb1`
to qube1 and then `sdb` to qube2. It is up to the user not to make this
mistake. The Xen block device framework currently does not provide an easy
way around this. Point 2 of [this comment on issue 1072][1072-comm2] gives
details about this.
4. The USB drive is now attached to the qube.
If using a default qube, you may open the Nautilus file manager in the qube, and your drive should be visible in the **Devices** panel on the left.
If you've attached a single partition, you may need to manually mount before it becomes visible:
```
cd ~
mkdir mnt
sudo mount /dev/xvdi mnt
```
4. The USB drive is now attached to the qube. If using a default qube, you may
open the Nautilus file manager in the qube, and your drive should be
visible in the **Devices** panel on the left.
5. When you finish using your USB drive, click the eject button or right-click and select **Unmount**.
If you've manually mounted a single partition in the above step, use:
`sudo umount mnt`
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 detach <vmname> <device>
qvm-block -d <device> <vmname>
7. You may now remove the device.
### R3.2 ###
USB drive mounting is integrated into the Qubes VM Manager GUI.
Simply insert your USB drive, right-click on the desired qube in the Qubes VM Manager list, click **Attach/detach block devices**, and select your desired action and device.
However, this only works for the whole device.
If you would like to attach individual partitions, you must use the command-line tool.
Note that attaching individual partitions can be slightly more secure because it doesn't force the target AppVM to parse the partition table.
However, it often means the AppVM won't detect the new partition and you will need to manually mount it inside the AppVM.
See below for more detailed steps.
The command-line tool you may use to mount whole USB drives or their partitions is `qvm-block`.
This tool can be used to assign a USB drive to a qube as follows:
1. Insert your USB drive.
2. In a dom0 console (running as a normal user), list all available block devices:
qvm-block
This will list all available block devices connected to any USB controller in your system, no matter which qube hosts the controller.
The name of the qube hosting the USB controller is displayed before the colon in the device name.
The string after the colon is the name of the device used within the qube, like so:
dom0:sdb1 Cruzer () 4GiB
usbVM:sdb1 Disk () 2GiB
**Note:** If your device is not listed here, you may refresh the list by calling from the qube to which the device is connected (typically `sys-usb`):
sudo udevadm trigger --action=change
3. Assuming your USB drive is attached to `sys-usb` and is `sdb`, we attach the device to a qube with the name `personal` like so:
qvm-block -a personal sys-usb: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.
You may also mount one partition at a time by using the same command with the partition number after `sdb`.
This is slightly more secure because it does not force the target AppVM to parse the partition table.
**Warning:** when working with single partitions, it is possible to assign the same partition to multiple qubes.
For example, you could attach `sdb1` to qube1 and then `sdb` to qube2.
It is up to the user not to make this mistake.
The Xen block device framework currently does not provide an easy way around this.
Point 2 of [this comment on issue 1072][1072-comm2] gives details about this.
4. The USB drive is now attached to the qube.
If using a default qube, you may open the Nautilus file manager in the qube, and your drive should be visible in the **Devices** panel on the left.
If you've attached a single partition, you may need to manually mount before it becomes visible:
```
cd ~
mkdir mnt
sudo mount /dev/xvdi mnt
```
5. When you finish using your USB drive, click the eject button or right-click and select **Unmount**.
If you've manually mounted a single partition in the above step, use:
`sudo umount mnt`
6. In a dom0 console, detach the stick
qvm-block -d <device>
or
qvm-block -d <vmname>
7. You may now remove the device.
**Warning:** Do not remove the device before detaching it from the VM!
Otherwise, you will not be able to attach it anywhere later. See issue [1082]
for details.
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
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).
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).
### What if I removed the device before detaching it from the VM? ###
### What if I removed the device before detaching it from the VM? (R3.2) ###
Currently (until issue [1082] gets implemented), if you remove the device
before detaching it from the qube, Qubes OS (more precisely, `libvirtd`) will
think that the device is still attached to the qube and will not allow attaching
further devices under the same name. The easiest way to recover from such a
situation is to reboot the qube to which the device was attached, but if this
isn't an option, you can manually recover from the situation by following these
steps:
Currently (until issue [1082] gets implemented), if you remove the device before detaching it from the qube, Qubes OS (more precisely, `libvirtd`) will think that the device is still attached to the qube and will not allow attaching further devices under the same name.
The easiest way to recover from such a situation is to reboot the qube to which the device was attached.
If this isn't an option, you can manually recover from the situation by following these steps:
1. Physically connect the device back. You can use any device as long as it
will be detected under the same name (for example, `sdb`).
1. Physically connect the device back.
You can use any device as long as it will be detected under the same name (for example, `sdb`).
2. Attach the device manually to the same VM using the `xl block-attach`
command. It is important to use the same "frontend" device name (by default,
`xvdi`). You can get it from the `qvm-block` listing:
2. Attach the device manually to the same VM using the `xl block-attach` command.
It is important to use the same "frontend" device name (by default, `xvdi`).
You can get it from the `qvm-block` listing:
[user@dom0 ~]$ qvm-block
sys-usb:sda DataTraveler_2.0 () 246 MiB (attached to 'testvm' as 'xvdi')
[user@dom0 ~]$ xl block-attach testvm phy:/dev/sda backend=sys-usb xvdi
[user@dom0 ~]$ sudo xl block-attach testvm phy:/dev/sda backend=sys-usb xvdi
In above example, all `xl block-attach` parameters can be deduced from the
output of `qvm-block`. In order:
In above example, all `xl block-attach` parameters can be deduced from the output of `qvm-block`.
In order:
* `testvm` - name of target qube to which device was attached - listed in
brackets by `qvm-block` command
* `phy:/dev/sda` - physical path at which device appears in source qube
(just after source qube name in `qvm-block` output)
* `backend=sys-usb` - name of source qube, can be omitted in case of dom0
* `xvdi` - "frontend" device name (listed at the end of line in `qvm-block`
output)
* `testvm` - name of target qube to which device was attached - listed in brackets by `qvm-block` command
* `phy:/dev/sda` - physical path at which device appears in source qube (just after source qube name in `qvm-block` output)
* `backend=sys-usb` - name of source qube, can be omitted in the case of dom0
* `xvdi` - "frontend" device name (listed at the end of line in `qvm-block` output)
3. Now properly detach the device, either using Qubes VM Manager or the
`qvm-block -d` command.
3. Now properly detach the device, either using Qubes VM Manager or the `qvm-block -d` command.
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. However,
Xen does not yet provide working PVUSB functionality, so only USB mass storage
devices can be passed to individual qubes.
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).
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.
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].
### Hide all USB controllers from dom0 ###
Even if you create a USB qube, 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.)
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.
Attaching a single USB device to a qube (USB passthrough)
------------------------------------------------
---------------------------------------------------------
Stating 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 use
method specific for particular device type (for example block devices described
above), instead of this generic one.
Starting with Qubes 3.2, it is possible to attach a single USB device to any Qube.
While this is a 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** to most of them.
If possible, use a method specific for particular device type (for example, block devices described above), instead of this generic one.
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).
### Installation of qubes-usb-proxy ###
[installation]: #installation-of-qubes-usb-proxy
Note, you cannot pass through devices from dom0 (in other words: a USB VM is required).
To use this feature, you need to have the [`qubes-usb-proxy`][qubes-usb-proxy] package installed in the template used for the USB qube and in the qube to which you want to connect USB devices. ( If the qube is TemplateBased then it should be installed in the relevant template as usual. )
If you do not have the package installed you will see this error: `ERROR: qubes-usb-proxy not installed in the VM`.
`qubes-usb-proxy` should be installed by default in the standard Fedora and Debian templates.
You install the `qubes-usb-proxy` package using the package manager as usual.
- Fedora: `sudo dnf install qubes-usb-proxy`
- Debian/Ubuntu: `sudo apt-get install qubes-usb-proxy`
### Usage of qubes-usb-proxy (R4.0) ###
This feature is also available from the Devices Widget.
This is the tool tray icon with a yellow square located in the top right of your screen by default.
Simply insert your USB device and click on the widget.
You will see an entry for your device such as `sys-usb:2-5 - 058f_USB_2.0_Camera` for example.
Hover over it.
This will pop up a submenu showing running VMs to which the USB device can be connected.
Click on one and your device will be attached!
You may also use the command line:
Listing available USB devices:
[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
Attaching selected USB device:
[user@dom0 ~]$ qvm-usb attach 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
Now, you can use your USB device (camera in this case) in the `conferences` qube.
If you see the error `ERROR: qubes-usb-proxy not installed in the VM` instead, please refer to the [Installation Section][installation].
When you finish, detach the device.
This can be done in the GUI by clicking on the Devices Widget.
You will see an entry in bold for your device such as **`sys-usb:2-5 - 058f_USB_2.0_Camera`**.
Hover over it.
This will pop up a submenu showing running VMs.
The one to which your device is connected will have an Eject button next to it.
Click that and your device will be detached.
You may also use the command line:
[user@dom0 ~]$ qvm-usb detach conferences 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
### Usage of qubes-usb-proxy (R3.2) ###
Listing available USB devices:
@ -309,7 +283,8 @@ Attaching selected USB device:
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
Now, you can use your USB device (camera in this case) in `conferences` qube.
Now, you can use your USB device (camera in this case) in the `conferences` qube.
If you see the error `ERROR: qubes-usb-proxy not installed in the VM` instead, please refer to the [Installation Section][installation].
When you finish, detach the device:
@ -319,8 +294,211 @@ When you finish, detach the device:
sys-usb:2-5 058f:3822 058f_USB_2.0_Camera
sys-usb:2-1 03f0:0641 PixArt_HP_X1200_USB_Optical_Mouse
This feature is not yet available in Qubes Manager.
This feature is not available in Qubes Manager.
Creating and Using a USB qube
-----------------------------
**Warning:** This has the potential to prevent you from connecting a keyboard to Qubes via USB.
There are problems with doing this in an encrypted install (LUKS).
If you find yourself in this situation, see this [issue][2270-comm23].
The connection of an untrusted USB device to dom0 is a security risk since dom0, like almost every OS, reads partition tables automatically.
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).
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 controller, see [here][usb-controller].
You can create a USB qube using the management stack by performing the following steps as root in dom0:
sudo qubesctl state.sls qvm.sys-usb
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 when 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:
* GRUB2
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.
* EFI
1. Open the file `/boot/efi/EFI/qubes/xen.cfg` in dom0.
2. Find the lines that begin with `kernel=`. There may be more than one.
3. Add `rd.qubes.hide_all_usb` to those lines.
4. Save and close the file.
5. 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:** A 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 the `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.
* GRUB2
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.
* EFI
1. Shut down the USB qube.
2. In Qubes Manager, right-click on the USB qube and select "Remove VM."
3. Open the file `/boot/efi/EFI/qubes/xen.cfg` in dom0.
4. Find the line(s) that begins with `kernel=`.
5. If `rd.qubes.hide_all_usb` appears anywhere in those lines, remove it.
6. Save and close the file.
7. 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 a 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.
If you use USB keyboard, automatic USB qube creation during installation is disabled.
Additional steps are required to avoid locking you out from the system.
Those steps are not performed by default, because of risk explained in [Security Warning about USB Input Devices].
### R4.0, using salt ###
To allow USB keyboard usage (including early boot for LUKS passphrase), make sure you have the latest `qubes-mgmt-salt-dom0-virtual-machines` package (simply [install dom0 updates][dom0-updates]) and execute in dom0:
sudo qubesctl state.sls qvm.usb-keyboard
The above command will take care of all required configuration, including creating USB qube if not present.
Note that it will expose dom0 to USB devices while entering LUKS passphrase.
Users are advised to physically disconnect other devices from the system for that time, to minimize the risk.
If you wish to perform only subset of this configuration (for example do not enable USB keyboard during boot), see manual instructions below.
### R3.2, manual ###
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 allow,user=root
(Change `sys-usb` to your desired USB qube.)
You can now use your USB keyboard.
For a confirmation dialog each time the USB keyboard is connected, change this line to:
```
sys-usb dom0 ask,default_target=dom0
```
Additionally, if you want to use USB keyboard to enter LUKS passphrase, it is incompatible with [hiding USB controllers from dom0][How to hide all USB controllers from dom0].
You need to revert that procedure (remove `rd.qubes.hide_all_usb` option from files mentioned there) and employ alternative protection during system boot - disconnect other devices during startup.
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.
The following steps are already done by default if you created the sys-usb qube with `qubesctl state.sls qvm.sys-usb` above, or let Qubes create it for you on first boot.
However, if you've created the USB qube manually:
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 top of the file:
sys-usb dom0 allow,user=root
(Change `sys-usb` to your desired USB qube.)
You can now use your USB mouse.
For a confirmation dialog each time the USB mouse is connected, change this line to:
```
sys-usb dom0 ask,default_target=dom0
```
[mass-storage]: https://en.wikipedia.org/wiki/USB_mass_storage_device_class
[Assigning Devices]: /doc/assigning-devices/
@ -328,9 +506,16 @@ This feature is not yet available in Qubes Manager.
[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
[2270-comm23]: https://github.com/QubesOS/qubes-issues/issues/2270#issuecomment-242900312
[1082]: https://github.com/QubesOS/qubes-issues/issues/1082
[faq-usbvm]: /doc/user-faq/#i-created-a-usbvm-and-assigned-usb-controllers-to-it-now-the-usbvm-wont-boot
[hide-usb]: #how-to-hide-all-usb-controllers-from-dom0
[faq-usbvm]: /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
[usb-challenges]: http://blog.invisiblethings.org/2011/05/31/usb-security-challenges.html
[create a USB qube]: #creating-and-using-a-usb-qube
[usb-challenges]: https://blog.invisiblethings.org/2011/05/31/usb-security-challenges.html
[YubiKey]: /doc/YubiKey/
[Security Warning about USB Input Devices]: #security-warning-about-usb-input-devices
[How to hide all USB controllers from dom0]: #how-to-hide-all-usb-controllers-from-dom0
[qubes-usb-proxy]: https://github.com/QubesOS/qubes-app-linux-usb-proxy
[dom0-updates]: /doc/software-update-dom0/#how-to-update-dom0

198
configuration/assigning-devices.md
View File

@ -11,72 +11,101 @@ redirect_from:
Assigning Devices to VMs
========================
In order to assign a whole PCI(e) device to a VM, one should use the `qvm-pci`
tool. First, list the available PCI devices:
Sometimes you may need to assign an entire PCI or PCI Express device directly to a qube.
This is also known as PCI pass-through.
The Qubes installer does this by default for `sys-net` (assigning all network class controllers), as well as `sys-usb` (assigning all USB controllers) if you chose to create the USB qube during install.
While this covers most use cases, there are some occasions when you may want to manually assign one NIC to `sys-net` and another to a custom NetVM, or have some other type of PCI controller you want to manually assign.
Note that one can only assign full PCI or PCI Express devices by default.
This limit is imposed by the PC and VT-d architectures.
This means if a PCI device has multiple functions, all instances of it need to be assigned to the same qube unless you have disabled the strict requirement for FLR with the `no-strict-reset` (R4.0) or `pci_strictreset` (R3.2) option.
In the steps below, you can tell if this is needed if you see the BDF for the same device listed multiple times with only the number after the "." changing.
While PCI device can only be used by one powered on VM at a time, it *is* possible to *assign* the same device to more than one VM at a time.
This means that you can use the device in one VM, shut that VM down, start up a different VM (to which the same device is also assigned), then use the device in that VM.
This can be useful if, for example, you have only one USB controller, but you have multiple security domains which all require the use of different USB devices.
R4.0
------------------------
In order to assign a whole PCI(e) device to a VM, one should use the `qvm-pci` tool.
First, list the available PCI devices:
~~~
qvm-pci
~~~
This will show you the `backend:BDF` address of each PCI device.
It will look something like `dom0:00_1a.0`.
Once you've found the address of the device you want to assign, then attach it like so:
~~~
qvm-pci attach --persistent <vmname> <backend>:<bdf>
~~~
For example, if `00_1a.0` is the BDF of the device you want to assign to the "personal" domain, you would do this:
~~~
qvm-pci attach --persistent personal dom0:00_1a.0
~~~
R3.2
------------------------
In order to assign a whole PCI(e) device to a VM, one should use the `qvm-pci` tool.
First, list the available PCI devices:
~~~
lspci
~~~
This will show you the BDF address of each PCI device. It will look something
like `00:1a.0`. Once you've found the BDF address of the device you want to
assign, then attach it like so:
This will show you the BDF address of each PCI device.
It will look something like `00:1a.0`.
Once you've found the BDF address of the device you want to assign, then attach it like so:
~~~
qvm-pci -a <vmname> <bdf>
~~~
For example, if `00:1a.0` is the BDF of the device I want to assign to the
"personal" domain, I would do this:
For example, if `00:1a.0` is the BDF of the device you want to assign to the "personal" domain, you would do this:
~~~
qvm-pci -a personal 00:1a.0
~~~
Note that one can only assign full PCI or PCI Express devices. This means one
cannot assign single USB devices -- only the whole USB controller with whatever
USB devices are connected to it. This limit is imposed by the PC and VT-d
architectures. More information on using and managing USB devices with qubes is
available on the [USB] page.
While a device can only be attached to one VM at a time, it *is* possible to
*assign* the same device to more than one VM at a time. This means that you can
use the device in one VM, shut that VM down, start up a different VM (to which
the same device is also assigned), then use the device in that VM. This can be
useful if, for example, you have only one USB controller, but you have multiple
security domains which all require the use of different USB devices.
Using Qubes Manager
-------------------
The above steps can also be done in Qubes Manager. Simply go into the VM
settings of your desired VM, then go to the "Devices" tab. This will show you a
list of available devices, which you can select to be assigned to that VM.
The above steps can also be done in Qubes Manager.
Simply go into the VM settings of your desired VM, then go to the "Devices" tab.
This will show you a list of available devices, which you can select to be assigned to that VM.
Finding the right USB controller
--------------------------------
If you want assign a certain [USB] device to a VM (by attaching the whole
USB controller), you need to figure out which PCI device is the right
controller. First, check to which USB bus the device is connected:
Some USB devices are not compatible with the USB pass-through method Qubes employs.
In situations like this, you can still often get the USB device to work by passing through the entire USB controller to a qube.
However, with this approach one cannot assign single USB devices, only the whole USB controller with whatever USB devices are connected to it.
More information on using and managing USB devices with qubes is available on the [USB] page.
If you want assign a certain USB device to a VM by attaching the whole USB controller, you need to figure out which PCI device is the right controller.
First, check to which USB bus the device is connected (note that these steps need to be run from a terminal inside `dom0`):
~~~
lsusb
~~~
For example, I want assign a broadband modem to the netvm. In the out put of
`lsusb` it can be listed as something like this. (In this case, the device isn't
fully identified):
For example, I want assign a broadband modem to the NetVM.
In the output of `lsusb` it can be listed as something like this.
(In this case, the device isn't fully identified):
~~~
Bus 003 Device 003: ID 413c:818d Dell Computer Corp.
~~~
The device is connected to USB bus \#3. Then check which other devices are
connected to the same bus, since *all* of them will be assigned to the same VM.
Now is the time to find right USB controller:
The device is connected to USB bus \#3.
Then check which other devices are connected to the same bus, since *all* of them will be assigned to the same VM.
Now is the time to find the right USB controller:
~~~
readlink /sys/bus/usb/devices/usb3
@ -88,37 +117,74 @@ This should output something like:
../../../devices/pci-0/pci0000:00/0000:00:1a.0/usb3
~~~
Now you see the BDF address in the path (right before final `usb3`). Strip the
leading `0000:` and pass the rest to the `qvm-pci` tool:
~~~
qvm-pci -a netvm 00:1a.0
~~~
Now you see the BDF address in the path (right before final `usb3`).
Strip the leading `0000:` and pass the rest to the `qvm-pci` tool to attach the controller with the version specific steps above.
Possible issues
---------------
### DMA buffer size
VMs with assigned PCI devices in Qubes have allocated a small buffer for DMA
operations (called swiotlb). By default it is 2MB, but some devices need a
larger buffer. To change this allocation, edit VM's kernel parameters (this is
expressed in 512B chunks):
VMs with assigned PCI devices in Qubes have allocated a small buffer for DMA operations (called swiotlb).
By default it is 2MB, but some devices need a larger buffer.
To change this allocation, edit VM's kernel parameters (this is expressed in 512B chunks):
~~~
# qvm-prefs netvm |grep kernelopts
kernelopts : iommu=soft swiotlb=2048 (default)
# qvm-prefs -s netvm kernelopts "iommu=soft swiotlb=4096"
# qvm-prefs -s netvm kernelopts "iommu=soft swiotlb=8192"
~~~
This is [known to be needed][ml1] for the Realtek RTL8111DL Gigabit Ethernet
Controller.
This is [known to be needed][ml1] for the Realtek RTL8111DL Gigabit Ethernet Controller.
### PCI passthrough issues
Sometimes PCI arbitrator is too strict. There is a way to enable permissive mode
for it. Create `/etc/systemd/system/qubes-pre-netvm.service`:
Sometimes the PCI arbitrator is too strict.
There is a way to enable permissive mode for it.
See also: [this thread][ml2] and the Xen wiki's [PCI passthrough] page.
**NOTE:** By setting the permissive flag for the PCI device, you're potentially weakening the device isolation, especially if your system is not equipped with a VT-d Interrupt Remapping unit.
See [Software Attacks on Intel VT-d] (page 7)
for more details.
At other times, you may instead need to disable the FLR requirement on a device.
This will also weaken device isolation; see the "I created a usbVM..." entry in the [FAQ](/doc/user-faq/) for more details.
R4.0
------------------------
Permissive mode and strict reset are options set as part of PCI device attachment.
If you've already attached the PCI device to a VM, detach it first either with Qube Manager or `qvm-pci`, then list the available PCI devices:
~~~
qvm-pci
~~~
This will show you the `backend:BDF` address of each PCI device.
It will look something like `dom0:00_1a.0`.
Once you've found the address of the device you want to assign, then attach it like so:
~~~
qvm-pci attach --persistent --option <option1> [--option <option2>] <vmname> <backend>:<bdf>
~~~
For example, if `00_1a.0` is the BDF of the device you want to assign to the "personal" domain, and it is particularly difficult to pass through you would do this:
~~~
qvm-pci attach --persistent --option permissive=true --option no-strict-reset=true personal dom0:00_1a.0
~~~
Running `qvm-pci` again should then show your PCI device attached with both the `permissive` and `no-strict-reset` options set.
**Note** again that in most cases you should not need either of these options set.
Only set one or more of them as required to get your device to function, or replace the device with one that functions properly with Qubes.
R3.2
------------------------
Permissive mode is enabled system wide per device.
Create `/etc/systemd/system/qubes-pre-netvm.service`:
~~~
[Unit]
@ -136,22 +202,21 @@ WantedBy=multi-user.target
Then enable it with `systemctl enable qubes-pre-netvm.service`
See also: [this thread][ml2] and the Xen wiki's [PCI passthrough] page.
The strict reset option is set for all devices attached to a VM with:
**NOTE:** By setting the permissive flag for the PCI device, you're potentially
weakening the device isolation, especially if your system is not equipped with
VT-d Interrupt Remapping unit. See [Software Attacks on Intel VT-d] (page 7)
for more details.
```
qvm-prefs usbVM -s pci_strictreset false
```
**Note** again that in most cases you should not need either of these options set.
Only set one or more of them as required to get your device to function, or replace the device with one that functions properly with Qubes.
Bringing PCI device back to dom0
--------------------------------
By default, when a device is detached from a VM (or when a VM with an attached
PCI device is shut down), the device is *not* automatically attached back to
dom0. This is an intended feature. A device which was previously assigned to a
VM less trusted than dom0 (which, in Qubes, is *all* of them) could attack dom0
if it were automatically reassigned there.
By default, when a device is detached from a VM (or when a VM with an attached PCI device is shut down), the device is *not* automatically attached back to dom0.
This is an intended feature.
A device which was previously assigned to a VM less trusted than dom0 (which, in Qubes, is *all* of them) could attack dom0 if it were automatically reassigned there.
In order to re-enable the device in dom0, either:
@ -159,13 +224,12 @@ In order to re-enable the device in dom0, either:
or
* Go to the sysfs (`/sys/bus/pci`), find the right device, detach it from the
pciback driver, and attach it back to the original driver. Replace `<BDF>`
with your device, for example `00:1c.2`:
* Go to the sysfs (`/sys/bus/pci`), find the right device, detach it from the pciback driver, and attach it back to the original driver.
Replace `<BDF>` with your full device, for example `0000:00:1c.2`:
~~~
echo 0000:<BDF> > /sys/bus/pci/drivers/pciback/unbind
MODALIAS=`cat /sys/bus/pci/devices/0000:<BDF>/modalias`
echo <BDF> > /sys/bus/pci/drivers/pciback/unbind
MODALIAS=`cat /sys/bus/pci/devices/<BDF>/modalias`
MOD=`modprobe -R $MODALIAS | head -n 1`
echo <BDF> > /sys/bus/pci/drivers/$MOD/bind
~~~
@ -173,7 +237,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

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

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

76
configuration/config-files.md
View File

@ -9,16 +9,19 @@ redirect_from:
- "/wiki/UserDoc/ConfigFiles/"
---
Qubes specific VM config files
==============================
Configuration 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).
Qubes-specific VM config files
------------------------------
These files are placed in /rw, which survives a VM restart.
That way, they can be used to customize a single VM instead of all VMs based on the same template.
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 runs 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
@ -26,29 +29,34 @@ in /rw/config etc. Example usage:
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-ip-change-hook` - script runs in NetVM after every external IP change and on "hardware" link status change.
- `/rw/config/qubes-firewall-user-script` - script run in ProxyVM
after each firewall update. Good place to write own custom firewall
rules
- (R4.0 only) in ProxyVMs (or AppVMs with `qubes-firewall` service enabled), scripts placed in the following directories will be executed in the listed order followed by `qubes-firewall-user-script` after each firewall update.
Good place to write own custom firewall rules.
- `/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.
~~~
/etc/qubes/qubes-firewall.d
/rw/config/qubes-firewall.d
/rw/config/qubes-firewall-user-script
~~~
- (R3.2 only) `/rw/config/qubes-firewall-user-script` - script runs in ProxyVM (or AppVM with `qubes-firewall` service enabled) after each firewall update.
Good place to write own custom firewall rules.
- `/rw/config/suspend-module-blacklist` - list of modules (one per line) to be unloaded before system goes to sleep.
The file is used only in a VM with PCI devices attached.
Intended for use with 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.
Also, take a look at [bind-dirs](/doc/bind-dirs) for instructions on how to easily modify arbitrary system files in an AppVM and have those changes persist.
GUI and audio configuration in dom0
===================================
-----------------------------------
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):
The GUI configuration file `/etc/qubes/guid.conf` in one of a few not managed by qubes-prefs or the Qubes Manager tool.
Sample config (included in default installation):
~~~
# Sample configuration file for Qubes GUI daemon
@ -78,19 +86,19 @@ 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_fullscreen` - allow VM to request its windows to go fullscreen (without any colorful frame).
- `allow_utf8_titles` - allow to use UTF-8 in window titles,
otherwise non-ASCII characters are replaced by underscore.
**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".
- `secure_copy_sequence` and `secure_paste_sequence` - key sequences
used to trigger secure copy and paste
- `allow_utf8_titles` - allow the use of UTF-8 in window titles; otherwise, non-ASCII characters are replaced by an underscore.
- `windows_count_limit` - limit on concurrent windows count.
- `secure_copy_sequence` and `secure_paste_sequence` - key sequences used to trigger secure copy and paste.
- `windows_count_limit` - limit on concurrent windows.
- `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.
- `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.

102
configuration/disk-trim.md
View File

@ -8,31 +8,105 @@ 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.
Disk Trim
----------
To enable TRIM in dom0 you need:
Disk trimming is the procedure by which the operating system informs the underlying storage device of which storage blocks are no longer in use.
It does this by issuing an `ATA_TRIM` command for the block. This is also known as a `discard`.
In this way, the storage device can perform garbage collection of the unused blocks and internally prepare them for reuse. SSDs in general benefit from this, while HDDs do not.
1. Get your LUKS device UUID:
In a Linux system running on bare metal, this is relatively straight-forward.
When instructed by the operating system, discards are issued by the file-system driver directly to the storage driver and then to the SSD.
In Qubes, this gets more complex due to virtualization, LUKS, and LVM (and thin pools on R4.0 and up).
If you run `fstrim --all` inside a TemplateVM, in a worst case the `discard` can follow a path like:
OS -> File-system Driver -> Virtual Storage Driver -> Backend Storage Driver -> LVM Storage Driver -> LUKS Driver -> Physical Storage Driver -> Physical Storage Device
If discards are not supported at any one of those layers, it will not make it to the underlying physical device.
There are some security implications to permitting TRIM (read for example [this article](https://asalor.blogspot.com/2011/08/trim-dm-crypt-problems.html)), but in most cases not exploitable.
Conversely, TRIM can improve security against local forensics when using SSDs, because with TRIM enabled deleting data (usually) results in the actual data being erased quickly, rather than remaining in unallocated space indefinitely.
However deletion is not guaranteed, and can fail to happen without warning for a variety of reasons.
Configuration
----------
In all versions of Qubes, you may want to set up a periodic job in `dom0` to trim the disk.
This can be done with either systemd (weekly only) or cron (daily or weekly).
* **Systemd**
From a terminal as a regular user:
```
systemctl enable fstrim.timer
systemctl start fstrim.timer
```
* **Cron**
This can be done from a terminal as root, by creating a `trim` file in `/etc/cron.daily` (or `/etc/cron.weekly`).
Add the following contents:
```
#!/bin/bash
/sbin/fstrim --all
```
And mark it as executable with `chmod 755 /etc/cron.daily/trim`.
**Note** Although discards can be issued on every delete inside `dom0` by adding the `discard` mount option to `/etc/fstab`, this option can hurt performance so the above procedure is recommended instead.
However, inside App and Template qubes, the `discard` mount option is on by default to notify the LVM thin pool driver (R4.0) or sparse file driver (R3.2) that the space is no longer needed and can be zeroed and re-used.
If you are using Qubes with LVM, you may also want to set `issue_discards = 1` in `/etc/lvm/lvm.conf`.
Setting this option will permit LVM to issue discards to the SSD when logical volumes are shrunk or deleted.
In R4.x, LVM Logical volumes are frequently deleted (every time a disposable VM is shut down, for example) so you may want to set `issue_discards = 1` if using an SSD, but see the article linked in the first section of this page.
However, this is relatively rare in R3.x.
LUKS
----------
If you have enabled LUKS in dom0, discards will not get passed down to the storage device.
To enable TRIM support in dom0 with LUKS you need to:
1. Get your LUKS device UUID:
~~~
ls /dev/mapper/luks-*
~~~
2. Add entry to `/etc/crypttab` (replace luks-\<UUID\> with the device name and the \<UUID\> with UUID alone):
2. Add entry to `/etc/crypttab` (replace luks-\<UUID\> with the device name and the \<UUID\> with UUID alone):
~~~
luks-<UUID> UUID=<UUID> none allow-discards
luks-<UUID> UUID=<UUID> none discard
~~~
3. Add `rd.luks.allow-discards=1` to kernel cmdline (`/etc/default/grub`, GRUB\_CMDLINE\_LINUX line)
4. Rebuild grub config (`grub2-mkconfig -o /boot/grub2/grub.cfg`)
5. Rebuild initrd **in hostonly mode**:
3. Add `rd.luks.options=discard` to kernel cmdline (follow either GRUB2 or EFI, not both):
* GRUB2: `/etc/default/grub`, `GRUB_CMDLINE_LINUX` line and
Rebuild grub config (`grub2-mkconfig -o /boot/grub2/grub.cfg`), then
Rebuild initrd (`dracut -f`)
* EFI: `/boot/efi/EFI/qubes/xen.cfg`, `kernel=` line(s), then
Rebuild initrd (`dracut -f /boot/efi/EFI/qubes/initramfs-$(uname -r).img $(uname -r)`)
~~~
dracut -H -f
~~~
4. Reboot the system.
6. Add "discard" option to `/etc/fstab` for root device
7. Reboot the system, verify that allow-discards is really enabled (`dmsetup table`)
5. To verify if discards are enabled you may use `dmsetup table` (confirm the line for your device mentions "discards") or just run `fstrim -av` (you should see a `/` followed by the number of bytes trimmed).
There is a [bug affecting allow-discards option](https://bugzilla.redhat.com/show_bug.cgi?id=890533), once it will be fixed, first two steps will be no longer needed.
Swap Space
----------
By default TRIM is not enabled for swap.
To enable it add the `discard` flag to the options for the swap entry in `/etc/fstab`.
This may or may not actually improve performance.
If you only want the security against local forensics benefit of TRIM, you can use the `discard=once` option instead to only perform the TRIM operation once during at boot.
To verify that TRIM is enabled, check `dmesg` for what flags were enabled when the swap space was activated.
You should see something like the following:
Adding 32391164k swap on /dev/mapper/qubes_dom0-swap. Priority:-2 extents:1 across:32391164k SSDscFS
The `s` indicates that the entire swap device will be trimmed at boot, and `c` indicates that individual pages are trimmed after they are no longer being used.

16
configuration/external-audio.md
View File

@ -14,19 +14,24 @@ Using External Audio Devices
Why you want to use external audio devices
------------------------------------------
Qubes audio virtualization protocol does not implement latency reporting for security reasons, keeping the protocol as simple as possible. Also, in a compromise between low latency and low CPU usage, latency may be around 200 ms. So applications demanding higher audio quality (even Skype) need a better environment. But Qubes flexibility fully allows that using external audio devices. These are mostly USB audio cards, but firewire devices also might be used.
Qubes audio virtualization protocol does not implement latency reporting for security reasons, keeping the protocol as simple as possible.
Also, in a compromise between low latency and low CPU usage, latency may be around 200 ms.
So applications demanding higher audio quality (even Skype) need a better environment.
But Qubes flexibility fully allows that using external audio devices.
These are mostly USB audio cards, but firewire devices also might be used.
Implementing external audio devices
-----------------------------------
First you need to identify an user VM dedicated to audio and [assign a device](/doc/AssigningDevices) to it. In the most common case the assigned device is the USB controller to which your USB audio card will be connected.
First you need to identify an user VM dedicated to audio and [assign a device](/doc/AssigningDevices) to it.
In the most common case the assigned device is the USB controller to which your USB audio card will be connected.
### Fedora VMs
In a terminal of the template from which you user VM depends, install pavucontrol with:
~~~
sudo yum install pavucontrol
sudo dnf install pavucontrol
~~~
Close the template and start or restart your user VM, insert your external audio device, open a terminal and prepare pulseaudio to use it with:
@ -38,9 +43,10 @@ pactl load-module module-udev-detect
Start the audio application that is going to use the external audio device.
Launch pavucontrol, for example using "run command in VM" of Qubes Manager and select you external audio card in pavucontrol. You need to do that only the first time you use a new external audio device, then pulse audio will remember you selection.
Launch pavucontrol, for example using "run command in VM" of Qubes Manager and select your external audio card in pavucontrol.
You need to do that only the first time you use a new external audio device, then pulse audio will remember your selection.
If you detach your external audio device, then want to insert it again, or change it with another one, you need to repeat the previous commands in terminal, adding an other line at the beginning:
If you detach your external audio device, then want to insert it again (or want to change it with another one), you need to repeat the previous commands in terminal adding another line at the beginning:
~~~
pactl unload-module module-udev-detect

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

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

20
configuration/fetchmail.md
View File

@ -16,14 +16,14 @@ Fetchmail is standalone MRA (Mail Retrieval Agent) aka "IMAP/POP3 client". Its s
Installation
------------
`yum install fetchmail`
`dnf install fetchmail`
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
~~~

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

@ -1,196 +0,0 @@
---
layout: doc
title: HTTP Filtering Proxy
permalink: /doc/config/http-filtering-proxy/
---
How to run an HTTP filtering proxy in a FirwallVM
=================================================
Introduction
------------
By default Qubes uses a special firewall VM that sits between the
networking VM and each AppVM. This VM controls the traffic for AppVMs
and can be used to restrict what AppVMs can send or receive. The
traffic rules can be setup using filtering rules GUI in Qubes VM
manager. The manager translates user-defined setup into iptables rules
for the kernel of firewall VM.
The primary goal of the filtering rule setup in firewall VM is to
allow for the user to protect either from own mistakes (like accessing
an arbitrary website from a browser running in a banking VM) or from
mistakes of websites (like a banking website that loads JS code from a
social network operator when the user logs in into the bank).
As the rules in the firewall are IP-based, it has drawbacks. First the
rules cannot be used if one has to use a HTTP proxy to connect for
websites (a common setup on corporate networks). Second the Qubes
resolves DNS names from the firewall rules when the AppVM loads. This
prevents websites that use DNS-based load balancers from working
unless the user reloads the firewall rules (which re-resolve the DNS
names) whenever the balancer transfer her session to another IP. Third
the initial setup of the rules is complicated as the firewall drops
the connection silently. As a workaround on can use browser's network
console to see what is blocked, but this is time-consuming and one can
trivially miss some important cases like including in the firewall
white list sites for OCSP SSL certificate verification.
These drawbacks can be mitigated if one replaces iptable-based rules
with a filtering HTTP proxy. The following describes how to setup
tinyproxy-based proxy in the firewall VM to archive such filtering.
Warning
-------
Running a HTTP proxy in your firewall VM increases the attack surface
against that VM from a compromised AppVM. tinyproxy has a relatively
simple code and a reasonable track record to allow to certain level of
trust. But one cannot exclude bugs especially in the case of a hostile
proxy clients as this is less tested scenario. So it is not advisable
to use the proxy in a shared firewall VM against untrusted AppVM to
black-list some unwanted connection like advertisement sites.
Less problematic setup is to white-list possible connections for
several trusted and semi-trusted AppVMs within one firewall VM. Still
for maximum safety one should consider running a separated firewall VM
per each important AppVMs and run the proxy there.
As a counterweight to this warning it is important to point out that
HTTP proxy decreases attack surface against AppVM. For example, with a
proxy the AppVM does not need DNS connections so a bug in the kernel
or in the browser in that area would not affect the AppVM. Also
browsers typically avoid many latest and greatest HTTP features when
connection through proxies minimizing exposure of new and unproven
networking code.
Setup
-----
1. Copy this [archive] with the proxy control script, default
tinyproxy config and a sample firewall filtering file into the
firewall VM and unpack it in `/rw/config` folder there as root:
cd /rw/config
sudo tar xzf .../proxy.tar.xz
2. If necessary adjust `/rw/config/tinyproxy/config` according to the
man page for `tinyproxy.conf`. The included config file refuses the
connection unless the host is white-listed in the filtering file, so
this can be altered if one wants rather to black-list connection. One
may also specify upstream proxies there. The file is a template file
and the control script will replace `{name}` constructs in the file with
actual parameters. In general lines with `{}` should be preserved as is.
3. For each AppVM that one wants to run through the proxy create an
the corresponding filtering file in the `/rw/config/tinyproxy`
directory. With the default config the filtering file should contain
regular expressions to match white-listed hosts with one regular
expression per line, see the man page for tinyproxy.conf for details.
The file should be named:
name.ip-address-of-app-vm
The name part before the dot can be arbitrary. For convenience one can
use AppVm name here, but this is not required. It is important to get
ip address part right as this is what the control script uses to
determine for which AppVM to apply the proxy rules. One can check the
IP address of AppVM in Qubes VM manager in the VM settings dialog, see
the Networking session under the Basic tab.
The attached archive includes `tinyproxy/social.10.137.2.13` file with a
rules for a AppVM allowing connection to google, facebook, linkedin,
livejournal, youtube and few other other sites. One can use it as an
example after changing the the IP address accordingly.
When editing the rules remember to include `$` at the end of the host
name and to prefix each dot in the host name with the backslash. This
way the pattern matches the whole host and not just some prefix and
the dot is not interpreted as an instruction to match an arbitrary
character according to regular expression syntax.
4. Check that `proxyctl.py` script can properly recognize the rule
files. For that run:
sudo /rw/config/tinyproxy/proxyctl.py show
For each rule file it should print the name, ip address, network
interface of the running AppVM if AppVM runs and the id of the
tinyproxy process that proxies that AppVM. The first time each pid
should be `--`.
5. Now run some AppVM with proxy and then run:
sudo /rw/config/tinyproxy/proxyctl.py update
The update command starts proxy processes and adjusts the iptable
rules to allow for proxy traffic for each running AppVM from the
filtering files list. For each stopped AppVM the proxy is killed.
Check that proxy is started so the `pid` field of the show command is a
number:
sudo /rw/config/tinyproxy/proxyctl.py show
6. Run the browser in the started AppVM and configure it to use the
proxy on the port 8100 running at the IP address of the firewall VM
gateway interface. In Qubes VM manager the address is given after the
Gateway label in the Setting dialog for the firewall VM.
In Firefox go to the Preferences dialog, select Advanced->Network,
click Settings for the Connection section. In the Connection Settings
dialog select Manual proxy configuration. For HTTP Proxy field use the
IP address of the firewall gateway interface. Enter 8100 as the port
and the select the checkbox "Use this proxy server for all protocols".
Go to some site. The browser should either load it if it was
white-listed in the filtering file or show a page generated by
tinyproxy that the page was filtered out.
In the firewall VM see `/run/tinyproxy/name/log` file. For each filtered
out website it contains an entry and one can adjust the filtering file
to include the corresponding host. After changing the file run either:
sudo /rw/config/tinyproxy/proxyctl.py restart name
to restart proxy with the updated rules file only for the given VM or
sudo /rw/config/tinyproxy/proxyctl.py kill-all-and-restart
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
following line:
/rw/config/tinyproxy/proxyctl.py update
If the file does not exist, create it so it looks like this:
#!/usr/bin/bash
/rw/config/tinyproxy/proxyctl.py update
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
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
outside connections, simply select "Deny network access except...," make
sure that the address list is empty and then unselect "Allow ICMP," "DNS"
and "Update proxy" checkboxes.
There is no need to add any special entries for the proxy in the GUI
as `proxyctl.py` adds rules for the proxy traffic itself.
--------------------------------------------------------------------------------
This guide was initially written by Igor Bukanov in a [message] to the
`qubes-devel` [mailing list].
[archive]: https://groups.google.com/group/qubes-devel/attach/39c95d63fccca12b/proxy.tar.gz?part=0.1
[message]: https://groups.google.com/d/msg/qubes-devel/UlK8P27UtD4/K6HM_GNdyTkJ
[mailing list]: /mailing-lists/

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

@ -9,17 +9,19 @@ redirect_from:
VM kernel managed by dom0
=========================
By default VMs kernels are provided by dom0. This means that:
By default, VMs kernels are provided by dom0. This means that:
1. You can select kernel version in VM settings;
1. You can select the kernel version in VM settings;
2. You can modify kernel options in VM settings;
3. You can **not** modify any of above from inside of VM;
3. You can **not** modify any of the above from inside a VM;
4. Installing additional kernel modules is cumbersome.
To select which kernel a given VM will use, you can use either use Qubes Manager (VM settings, advanced tab), or `qvm-prefs` tool:
*Note* In the examples below, although the specific version numbers might be old, the commands have been verified on R3.2 and R4.0 with debian-9 and fedora-26 templates.
To select which kernel a given VM will use, you can either use Qubes Manager (VM settings, advanced tab), or the `qvm-prefs` tool:
~~~
[user@dom0 ~]$ qvm-prefs my-appvm -s kernel
[user@dom0 ~]$ qvm-prefs -s my-appvm kernel
Missing kernel version argument!
Possible values:
1) default
@ -29,11 +31,11 @@ Possible values:
- 3.18.17-4
- 3.19.fc20
- 3.18.10-2
[user@dom0 ~]$ qvm-prefs my-appvm -s kernel 3.18.17-4
[user@dom0 ~]$ qvm-prefs my-appvm -s kernel default
[user@dom0 ~]$ qvm-prefs -s my-appvm kernel 3.18.17-4
[user@dom0 ~]$ qvm-prefs -s my-appvm kernel default
~~~
To check/change the default kernel you can go either to "Global settings" in Qubes Manager, or use `qubes-prefs` tool:
To check/change the default kernel you can either go to "Global settings" in Qubes Manager, or use the `qubes-prefs` tool:
~~~
[user@dom0 ~]$ qubes-prefs
@ -49,7 +51,9 @@ 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:
VM kernels are packages by Qubes team in `kernel-qubes-vm` packages.
Generally, the system will keep the three newest available versions.
You can list them with the `rpm` command:
~~~
[user@dom0 ~]$ rpm -qa 'kernel-qubes-vm*'
@ -58,10 +62,11 @@ kernel-qubes-vm-3.18.16-3.pvops.qubes.x86_64
kernel-qubes-vm-3.18.17-4.pvops.qubes.x86_64
~~~
If you want more recent version, you can check `qubes-dom0-unstable` repository. As the name suggest, keep in
mind that those packages may be less stable than the default ones.
If you want a more recent version, you can check the `qubes-dom0-unstable` repository.
There is also the `kernel-latest-qubes-vm` package which should provide a more recent (non-LTS) kernel, but has received much less testing.
As the names suggest, keep in mind that those packages may be less stable than the default ones.
Checking available versions in `qubes-dom0-unstable` repository:
To check available versions in the `qubes-dom0-unstable` repository:
~~~
[user@dom0 ~]$ sudo qubes-dom0-update --enablerepo=qubes-dom0-unstable --action=list kernel-qubes-vm
@ -82,7 +87,7 @@ kernel-qubes-vm.x86_64 1000:3.18.17-4.pvops.qubes @qubes-dom0-cached
~~~
Installing new version from `qubes-dom0-unstable` repository:
Installing a new version from `qubes-dom0-unstable` repository:
~~~
[user@dom0 ~]$ sudo qubes-dom0-update --enablerepo=qubes-dom0-unstable kernel-qubes-vm
@ -127,24 +132,25 @@ Failed:
kernel-qubes-vm.x86_64 1000:3.18.10-2.pvops.qubes
Complete!
[marmarek@dom0 ~]$
[user@dom0 ~]$
~~~
In the above example, it tries to remove 3.18.10-2.pvops.qubes kernel (to keep only 3 installed), but since some VM uses it, it fails. Installation of new package is unaffected by this event.
In the above example, it tries to remove the 3.18.10-2.pvops.qubes kernel (to keep only three installed), but since some VM uses it, it fails.
Installation of the new package is unaffected by this event.
The newly installed package is set as default VM kernel.
The newly installed package is set as the 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:
* using Fedora kernel package
* using manually compiled kernel
It is possible to package a kernel installed in dom0 as a VM kernel.
This makes it possible to use a VM kernel which is not packaged by Qubes team.
This includes:
* using a Fedora kernel package
* using a manually compiled kernel
To prepare such VM kernel, you need to install `qubes-kernel-vm-support`
package in dom0 and also have matching kernel headers installed (`kernel-devel`
package in case of Fedora kernel package). You can install required stuff using `qubes-dom0-update`:
To prepare such a VM kernel, you need to install the `qubes-kernel-vm-support` package in dom0 and also have matching kernel headers installed (`kernel-devel` package in the case of a Fedora kernel package).
You can install requirements using `qubes-dom0-update`:
~~~
[user@dom0 ~]$ sudo qubes-dom0-update qubes-kernel-vm-support kernel-devel
@ -187,10 +193,9 @@ Installed:
Complete!
~~~
Then you can call `qubes-prepare-vm-kernel` tool to actually package the
kernel. The first parameter is kernel version (exactly as seen by the kernel),
the second one (optional) is short name being visible in Qubes Manager and
`qvm-prefs` tool.
Then you can call the `qubes-prepare-vm-kernel` tool to actually package the kernel.
The first parameter is kernel version (exactly as seen by the kernel), the second one (optional) is short name.
This is visible in Qubes Manager and the `qvm-prefs` tool.
~~~
[user@dom0 ~]$ sudo qubes-prepare-vm-kernel 4.1.9-6.pvops.qubes.x86_64 4.1.qubes
@ -202,52 +207,37 @@ mke2fs 1.42.12 (29-Aug-2014)
--> Done.
~~~
Using kernel installed in the VM
Using kernel installed in the VM (R4.0)
--------------------------------
**This option is available only in Qubes R3.1 or newer**
It is possible to use kernel installed in the VM (in most cases - TemplateVM).
This is possible thanks to PV GRUB2 - GRUB2 running in the VM. To make it happen, you need to:
1. Install PV GRUB2 in dom0 - package is named `grub2-xen`.
2. Install kernel in the VM. As with all VM software installation - this needs to be done in TemplateVM (of StandaloneVM if you are using one).
3. Set VM kernel to `pvgrub2` value. You can use `pvgrub2` in selected VMs, not necessary all of them, even when it's template has kernel installed. You can still use dom0-provided kernel for selected VMs.
**WARNING: When using kernel from within VM, `kernelopts` parameter is ignored.**
### Installing PV GRUB2
Simply execute:
Both debian-9 and fedora-26 templates already have grub and related tools preinstalled so if you want to use one of the distribution kernels, all you need to do is clone either template to a new one, then:
~~~
sudo qubes-dom0-update grub2-xen
qvm-prefs <clonetemplatename> virt_mode hvm
qvm-prefs <clonetemplatename> kernel ''
~~~
### Installing kernel in Fedora VM
If you'd like to use a different kernel than default, continue reading.
In Fedora based VM, you need to install `qubes-kernel-vm-support` package. This
package include required additional kernel module and initramfs addition
required to start Qubes VM (for details see
[template implementation](/doc/template-implementation/)). Additionally you
need some GRUB tools to create it's configuration. Note: you don't need actual
grub bootloader as it is provided by dom0. But having one also shouldn't harm.
### Installing kernel in Fedora VM (R4.0)
Install whatever kernel you want.
You need to also ensure you have the `kernel-devel` package for the same kernel version installed.
If you are using a distribution kernel package (`kernel` package), the initramfs and kernel modules may be handled automatically.
If you are using a manually built kernel, you need to handle this on your own.
Take a look at the `dkms` documentation, especially the `dkms autoinstall` command may be useful.
If you did not see the `kernel` install rebuild your initramfs, or are using a manually built kernel, you will need to rebuild it yourself.
Replace the version numbers in the example below with the ones appropriate to the kernel you are installing:
~~~
sudo yum install qubes-kernel-vm-support grub2-tools
sudo dracut -f /boot/initramfs-4.15.14-200.fc26.x86_64.img 4.15.14-200.fc26.x86_64
~~~
Then install whatever kernel you want. If you are using distribution kernel
package (`kernel` package), initramfs and kernel module should be handled
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
`GRUB_TIMEOUT` to speed up VM startup. Then you need to generate actual configuration:
In Fedora it can be done using `grub2-mkconfig` tool:
Once the kernel is installed, you need to create a GRUB configuration.
You may want to adjust some settings in `/etc/default/grub`; for example, lower `GRUB_TIMEOUT` to speed up VM startup.
Then, you need to generate the actual configuration:
In Fedora it can be done using the `grub2-mkconfig` tool:
~~~
sudo grub2-mkconfig -o /boot/grub2/grub.cfg
@ -259,29 +249,17 @@ You can safely ignore this error message:
grub2-probe: error: cannot find a GRUB drive for /dev/mapper/dmroot. Check your device.map
~~~
Then shutdown the VM. From now you can set `pvgrub2` as VM kernel and it will
start kernel configured within VM.
Then shutdown the VM.
### Installing kernel in Debian VM
**Note:** You may also use `PV` mode instead of `HVM` but this is not recommended for security purposes.
If you require `PV` mode, install `grub2-xen` in dom0 and change the template's kernel to `pvgrub2`.
Booting to a kernel inside the template is not supported under `PVH`.
In Debian based VM, you need to install `qubes-kernel-vm-support` package. This
package include required additional kernel module and initramfs addition
required to start Qubes VM (for details see
[template implementation](/doc/template-implementation/)). Additionally you
need some GRUB tools to create it's configuration. Note: you don't need actual
grub bootloader as it is provided by dom0. But having one also shouldn't harm.
### Installing kernel in Debian VM (R4.0)
~~~
sudo apt-get update
sudo apt-get install qubes-kernel-vm-support grub2-common
~~~
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 not, or you are building kernel manually, do this on
using `dkms` and `initramfs-tools`:
Install whatever kernel you want, making sure to include the headers.
If you are using a distribution kernel package (`linux-image-amd64` package), the initramfs and kernel modules should be handled automatically.
If not, or you are building the kernel manually, do this using `dkms` and `initramfs-tools`:
sudo dkms autoinstall -k <kernel-version> # replace this <kernel-version> with actual kernel version
sudo update-initramfs -u
@ -303,10 +281,9 @@ The output should look like this:
$ 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
`GRUB_TIMEOUT` to speed up VM startup. Then you need to generate actual configuration:
In Fedora it can be done using `update-grub2` tool:
When the kernel is installed, you need to create a GRUB configuration.
You may want to adjust some settings in `/etc/default/grub`; for example, lower `GRUB_TIMEOUT` to speed up VM startup.
Then, you need to generate the actual configuration with the `update-grub2` tool:
~~~
sudo mkdir /boot/grub
@ -319,15 +296,156 @@ You can safely ignore this error message:
grub2-probe: error: cannot find a GRUB drive for /dev/mapper/dmroot. Check your device.map
~~~
Then shutdown the VM. From now you can set `pvgrub2` as VM kernel and it will
start kernel configured within VM.
Then shutdown the VM.
**Note:** You may also use `PV` mode instead of `HVM` but this is not recommended for security purposes.
If you require `PV` mode, install `grub2-xen` in dom0 and change the template's kernel to `pvgrub2`.
Booting to a kernel inside the template is not supported under `PVH`.
Using kernel installed in the VM (R3.2)
--------------------------------
**This option is available only in Qubes R3.1 or newer**
It is possible to use a kernel installed in the VM (in most cases - TemplateVM).
This is possible thanks to PV GRUB2 - GRUB2 running in the VM.
To make it happen, at a high level you need to:
1. Install PV GRUB2 (`grub2-xen`) in dom0.
2. Install kernel in the VM (see below for Fedora and Debian steps).
As with all VM software installation - this needs to be done in a TemplateVM (or StandaloneVM if you are using one).
3. Set VM kernel to `pvgrub2` value.
You can use `pvgrub2` in selected VMs, but it's not necessary in all of them, even if its template has a kernel installed.
You can still use a dom0-provided kernel for selected VMs.
**WARNING: When using a kernel from within a VM, the `kernelopts` parameter is ignored.**
### Installing PV GRUB2 (R3.2)
Simply execute:
~~~
sudo qubes-dom0-update grub2-xen
~~~
### Installing kernel in Fedora VM (R3.2)
In a Fedora based VM, you need to install the `qubes-kernel-vm-support` package.
This package includes the additional kernel module and initramfs addition required to start a Qubes VM (for details see [template implementation](/doc/template-implementation/)).
Additionally, you need some GRUB tools to create its configuration.
Note: You don't need an actual grub bootloader as it is provided by dom0, but having one shouldn't hurt.
~~~
sudo dnf install qubes-kernel-vm-support grub2-tools
~~~
Then install whatever kernel you want.
You need to also ensure you have the `kernel-devel` package for the same kernel version installed.
If you are using a distribution kernel package (`kernel` package), the initramfs and kernel modules may be handled automatically.
If you are using a manually built kernel, you need to handle this on your own.
Take a look at the `dkms` documentation, especially the `dkms autoinstall` command may be useful.
If you did not see the `kernel` install rebuild your initramfs, or are using a manually built kernel, you will need to rebuild it yourself.
Replace the version numbers in the example below with the ones appropriate to the kernel you are installing:
~~~
sudo dracut -f /boot/initramfs-4.15.14-200.fc26.x86_64.img 4.15.14-200.fc26.x86_64
~~~
Once the kernel is installed, you need to create a GRUB configuration.
You may want to adjust some settings in `/etc/default/grub`; for example, lower `GRUB_TIMEOUT` to speed up VM startup.
Then, you need to generate the actual configuration:
In Fedora it can be done using the `grub2-mkconfig` tool:
~~~
sudo grub2-mkconfig -o /boot/grub2/grub.cfg
~~~
You can safely ignore this error message:
~~~
grub2-probe: error: cannot find a GRUB drive for /dev/mapper/dmroot. Check your device.map
~~~
Then shutdown the VM.
Now you can set `pvgrub2` as the VM kernel and it will start the kernel configured within your VM.
**Note:** On first boot the VM will automatically allocate swap space.
This can take a while to complete- longer than your `qrexec_timeout` setting, which will make the VM appear to have hung on boot.
To confirm this is the case, see [Troubleshooting](/doc/managing-vm-kernel/#troubleshooting) below or just wait for five minutes and shutdown the VM.
It should respond normally on future boots.
### Installing kernel in Debian VM (R3.2)
In a Debian based VM, you need to install the `qubes-kernel-vm-support` package.
This package includes the additional kernel module and initramfs addition required to start a Qubes VM (for details see [template implementation](/doc/template-implementation/)).
Additionally, you need some GRUB tools to create its configuration.
Note: You don't need an actual grub bootloader as it is provided by dom0, but having one shouldn't hurt.
~~~
sudo apt update
sudo apt install qubes-kernel-vm-support grub2-common
~~~
If prompted for a GRUB install device, choose `/dev/mapper/dmroot`.
You will receive an error about GRUB failed to install to it, but just continue anyways.
Ignore warnings about `version '...' has bad syntax`.
Then install whatever kernel you want.
If you are using a distribution kernel package (`linux-image-amd64` package), the initramfs and kernel modules should be handled automatically.
If not, or you are building the kernel manually, do this using `dkms` and `initramfs-tools`:
sudo dkms autoinstall -k <kernel-version> # replace this <kernel-version> with actual kernel version
sudo update-initramfs -u
The output should look like this:
$ sudo dkms autoinstall -k 3.16.0-4-amd64
u2mfn:
Running module version sanity check.
- Original module
- No original module exists within this kernel
- Installation
- Installing to /lib/modules/3.16.0-4-amd64/updates/dkms/
depmod....
DKMS: install completed.
$ sudo update-initramfs -u
update-initramfs: Generating /boot/initrd.img-3.16.0-4-amd64
When the kernel is installed, you need to create a GRUB configuration.
You may want to adjust some settings in `/etc/default/grub`; for example, lower `GRUB_TIMEOUT` to speed up VM startup.
Then, you need to generate the actual configuration with the `update-grub2` tool:
~~~
sudo mkdir /boot/grub
sudo update-grub2
~~~
You can safely ignore this error message:
~~~
grub2-probe: error: cannot find a GRUB drive for /dev/mapper/dmroot. Check your device.map
~~~
Then shutdown the VM.
Now you can set `pvgrub2` as the VM kernel and it will start the kernel configured within your VM.
When starting the VM you can safely ignore any warnings about a missing module 'dummy-hcd'.
**Note:** on first boot the VM will automatically allocate swap space.
This can take a while to complete- longer than your `qrexec_timeout` setting, which will make the VM appear to have hung on boot.
To confirm this is the case, see [Troubleshooting](/doc/managing-vm-kernel/#troubleshooting) below or just wait for five minutes and shutdown the VM.
It should respond normally on future boots.
### Troubleshooting
In case of problems, you can access VM console (using `sudo xl console VMNAME` in dom0) to access
GRUB menu. You need to call it just after starting VM (until `GRUB_TIMEOUT`
expires) - for example in separate dom0 terminal window.
In case of problems, you can access the VM console using `sudo xl console VMNAME` in dom0, then access the GRUB menu.
You need to call it just after starting the VM (until `GRUB_TIMEOUT` expires); for example, in a separate dom0 terminal window.
In any case you can later access VM logs (especially VM console log (`guest-VMNAME.log`).
In any case you can later access the VM's logs (especially the VM console log `guest-VMNAME.log`).
You can always set kernel back to some dom0-provided value to fix VM kernel installation.
You can always set the kernel back to some dom0-provided value to fix a VM kernel installation.

30
configuration/multiboot.md
View File

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

240
configuration/multimedia.md Normal file
View File

@ -0,0 +1,240 @@
---
layout: doc
title: How to Make a Multimedia TemplateVM
permalink: /doc/multimedia/
redirect_from:
- /en/doc/multimedia/
- /doc/Multimedia/
- /wiki/Multimedia/
---
How to Make a Multimedia TemplateVM
===================================
Note: This Howto has been written and was tested under Qubes 4rc4
You can consolidate most of your media streaming tasks into one "multimedia" App-VM. This howto explains how to create a multimedia template which can be used to play multimedia content.
This includes:
- Spotify
- Amazon Prime
- Netflix
- DVDs
Installation
------------
Start by cloning the default debian template in dom0.
Hint:
t-multimedia is just the template VM where we will install all packages.
In the last step we will create an AppVM from this template.
`qvm-clone debian-9 t-multimedia`
Launch a Terminal in the new template VM:
`qvm-run --auto t-multimedia gnome-terminal`
Important:
Enter all the following commands in the terminal of the template VM
Become the root user to run all following command without the need to use sudo in the multimedia template VM
`sudo -i`
This howto assumes that you have xclip available in the AppVM where you download the Repository Signing keys.
xclip will be used to paste the content of the clipboard to a file.
You can install xclip via:
`apt-get install xclip` on Debian
`dnf install xclip` on Fedora
You can of course install xclip just into the AppVM where you download the signing keys to have it available for this howto and it will be deleted if you reboot the AppVM. To have xclip available also after a reboot you need to install it in the Template VM on which your Internet AppVM is based (make sure to reboot the AppVM after you've installed any package in its template)
Installation of Spotify
-----------------------
Import GPG-Key for spotify
As the template VM can't connect to internet you need to get the public key file from another AppVM and copy it to the template VM. The easiest way is to use the Qubes Clipboard to copy the keys from the AppVM where you get the key to the Template VM.
In an AppVM which has Internet access:
- Open <https://keyserver.ubuntu.com/pks/lookup?op=get&search=0xEFDC8610341D9410>
- Copy content of page to the Clipboard (Ctrl+A and Ctrl+C)
- open a Terminal in this AppVM and copy the content of the clipboard to a file
`xclip -o > spotify.pubkey`
Copy the public signing key over to the multimedia template VM
- copy the file via `qvm-copy-to-vm t-multimedia spotify.pubkey`
- or create a new file on the Template VM and copy the content of the clipboard (the public key)
Copy content of page to the Qubes Clipboard (Ctrl+C and then Shift+Ctrl+C)
Switch to the gnome terminal in the Multimedia Template VM
`nano spotify.pubkey`
Paste the content from the Qubes Clipboard into nano (Shift+Ctrl+V and then Paste)
Save the file (Ctrl+O <Enter> Ctrl+X)
Check the signature of the signing key (in the multimedia Template VM).
Hint: depending on your installed version of GnuPG the command to show a public might slightly be different.
See [this StackExchange question](https://unix.stackexchange.com/questions/391344/gnupg-command-to-show-key-info-from-file) for more information.
If this command doesn't show a fingerprint choose one of the other commands mentioned in the above link.
`gpg --with-fingerprint spotify.pubkey`
This should look like:
[user@t-multimedia ~]$ `gpg --with-fingerprint spotify.pubkey`
pub 4096R/341D9410 2017-07-25 Spotify Public Repository Signing Key <tux@spotify.com>
Key fingerprint = 0DF7 31E4 5CE2 4F27 EEEB 1450 EFDC 8610 341D 9410
You can (and should) lookup the fingerprint on at least one (or more) keyservers as the above information might be outdated.
<https://keyserver.ubuntu.com/pks/lookup?op=vindex&search=0xefdc8610341d9410&fingerprint=on>
Add the public key to the repository keyring
`apt-key add spotify.pubkey`
Add the Spotify repository to your list of package sources:
`echo deb http://repository.spotify.com stable non-free > /etc/apt/sources.list.d/spotify.list`
Update the list of all known packages
`apt-get update`
Install Spotify
`apt-get install -y spotify-client`
Create a spotify desktop-entry
`cp -p /usr/share/spotify/spotify.desktop /usr/share/applications/`
`cp /usr/share/spotify/icons/spotify-linux-16.png /usr/share/icons/hicolor/16x16/apps/spotify.png`
Installation of VLC
-------------------
To play DVDs you can install VLC with the needed Codecs
Download the public key which signs the VLC package repositories
In an AppVM which has Internet access:
- Open <https://keyserver.ubuntu.com/pks/lookup?op=get&search=0x6BCA5E4DB84288D9>
- Repeat all steps to save the public signing key on the AppVM (see above / Spotify example)
`xclip -o > videolan.pubkey`
Copy the public signing key over to the multimedia template VM
- copy the file via `qvm-copy-to-vm t-multimedia videolan.pubkey`
- or create a new file on the Template VM and copy the content of the clipboard (the public key)
Copy content of page to the Qubes Clipboard (Ctrl+C and then Shift+Ctrl+C)
Switch to the gnome terminal in the Multimedia Template VM
`nano videolan.pubkey`
Paste the content from the Qubes Clipboard into nano (Shift+Ctrl+V and then Paste)
Save the file (Ctrl+O <Enter> Ctrl+X)
Check the signature of the signing key
`gpg --with-fingerprint videolan.pubkey`
This should look like:
[user@t-multimedia ~]$ `gpg --with-fingerprint videolan.pubkey`
pub 2048R/B84288D9 2013-08-27 VideoLAN APT Signing Key <videolan@videolan.org>
Key fingerprint = 8F08 45FE 77B1 6294 429A 7934 6BCA 5E4D B842 88D9
sub 2048R/288D4A2C 2013-08-27
You can (and should) lookup the fingerprint on at least one (or more) keyservers as the above information might be outdated.
<https://keyserver.ubuntu.com/pks/lookup?op=vindex&search=0x6BCA5E4DB84288D9&fingerprint=on>
Add the public key to the repository keyring
`apt-key add videolan.pubkey`
Add the new VLC package repositories to your list of sources
`echo "deb http://download.videolan.org/pub/debian/stable/ /" > /etc/apt/sources.list.d/vlc.list`
`echo "deb-src http://download.videolan.org/pub/debian/stable/ /" >> /etc/apt/sources.list.d/vlc.list`
Update package repositories
`apt-get update`
Install libdvdcss and VLC
`apt-get install -y libdvdcss2 vlc`
Installation Google Chrome
--------------------------
To play Videos with Netflix, Amazon Prime & Co using Chrome is a good option as it has all needed codecs included.
Hint: Using Chromium will not work for some reasons.
Download the public key which signs the Google package repositories
In an AppVM which has Internet access:
- Open <https://keyserver.ubuntu.com/pks/lookup?op=get&search=0x7721F63BD38B4796>
- Repeat all steps to save the public signing key on the AppVM (see above / Spotify example)
`xclip -o > google.pubkey`
Copy the public signing key over to the multimedia template VM
- copy the file via `qvm-copy-to-vm t-multimedia google.pubkey`
- or create a new file on the Template VM and copy the content of the clipboard (the public key)
Copy content of page to the Qubes Clipboard (Ctrl+C and then Shift+Ctrl+C)
Switch to the gnome terminal in the Multimedia Template VM
`nano google.pubkey`
Paste the content from the Qubes Clipboard into nano (Shift+Ctrl+V and then Paste)
Save the file (Ctrl+O <Enter> Ctrl+X)
Check the signature of the signing key (still in the AppVM where you downloaded the key)
`gpg --with-fingerprint google.pubkey`
This should look like:
[user@t-multimedia ~]$ `gpg --with-fingerprint google.pubkey`
pub 4096R/D38B4796 2016-04-12 Google Inc. (Linux Packages Signing Authority)
<linux-packages-keymaster@google.com>
Key fingerprint = EB4C 1BFD 4F04 2F6D DDCC EC91 7721 F63B D38B 4796
sub 4096R/640DB551 2016-04-12 [expires: 2019-04-12]
sub 4096R/997C215E 2017-01-24 [expires: 2020-01-24]
You can (and should) lookup the fingerprint on at least one (or more) keyservers as the above information might be outdated.
<https://keyserver.ubuntu.com/pks/lookup?op=vindex&search=0x7721F63BD38B4796&fingerprint=on>
or
<https://www.google.com/linuxrepositories/>
Add the public key to the repository keyring
`apt-key add google.pubkey`
Add the Google package repositories to your list of sources
`echo "deb http://dl.google.com/linux/chrome/deb/ stable main"> /etc/apt/sources.list.d/google.list`
Update package repositories
`apt-get update`
Install Chrome
`apt-get install google-chrome-stable`
Create a Multimedia AppVM
-------------------------
The last step is to create a multimedia AppVM (named "my-multimedia" here) based on the new multimedia template.
`qvm-create --template t-multimedia --label orange my-multimedia`

6
configuration/mutt.md
View File

@ -25,7 +25,9 @@ not very convenient.
Installation
------------
`yum install mutt`
`dnf install mutt cyrus-sasl-plain`
`cyrus-sasl-plain` package is necessary for SMTP authentication to work.
Configuration
-------------
@ -56,7 +58,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

8
configuration/network-bridge-support.md
View File

@ -42,12 +42,12 @@ First, retrieve the attachment of this Wifi article in dom0. Then apply the thre
Finally restart the qubes manager GUI.
A new option is now available in the AppVM Settings to enable set the NetVM in bridge mode. For a bridged AppVM, you should the select a netvm instead of a firewall vm, enabled the Bridge option and restart your AppVM.
An option is available in the AppVM Settings to enable setting the NetVM in bridge mode. For a bridged AppVM, you should then select a NetVM instead of a FirewallVM/ ProxyVM, enable the Bridge option, and restart your AppVM.
NetVM patch (Qubes R2B2)
------------------------
You need to modify manually the NetVM iptable script inside the NetVM. The reason is that by default the NetVM only accept traffic coming from network interfaces called vif\* (in our case, we will use an additional interface called bridge0. The second reason is that all trafic is NATed by default. In our case, we want to forward traffic from the bridge interface without modifying it, while NATing traffic coming from vif\* interfaces.
You need to modify manually the NetVM iptable script inside the NetVM. The reason is that by default the NetVM only accepts traffic coming from network interfaces called vif\* (in our case, we will use an additional interface called bridge0. The second reason is that all trafic is NATed by default. In our case, we want to forward traffic from the bridge interface without modifying it, while NATing traffic coming from vif\* interfaces.
Modify manually the Template you use for your NetVM (not the NetVM itself). This is by default fedora-x86\_64. Edit the file /etc/sysconfig/iptables. You need to modify two parts of the file.
@ -95,7 +95,7 @@ This requires:
Note: A wireless interface cannot be bridged.
The bridge edition GUI is somehow buggy as it does not remember all the parameter you setup. You can fix it by editing manually the files in /etc/NetworkManager/system-connections/. Here is one example for these files:
The bridge edition GUI is somewhat buggy as it does not remember all the parameters you set up. You can fix it by editing manually the files in /etc/NetworkManager/system-connections/. Here is one example for these files:
- Bridge-DHCP
@ -137,7 +137,7 @@ Note: Do not forget to put stp=false if you bridge only eth0 because sending BPD
slave-type=bridge
~~~
If you do not manager to start your bridge, you can start it manually from a NetVM terminal:
If you do not manage to start your bridge, you can start it manually from a NetVM terminal:
~~~
$ nmcli con up id bridge0-eth0

29
configuration/network-printer.md
View File

@ -14,27 +14,42 @@ Configuring a network printer for Qubes AppVMs
Where to configure printers and install drivers?
------------------------------------------------
One would normally want to configure a printer in a template VM, rather than in particular AppVMs. This is because all the global settings made to AppVMs (those stored in its /etc, as well as binaries installed in /usr) would be discarded upon AppVM shutdown. When printer is added and configured in a template VM, then all the AppVMs based on this template should automatically be able to use it (without the need for the template VM to be running, of course).
One would normally want to configure a printer in a template VM, rather than in particular AppVMs.
This is because all the global settings made to AppVMs (those stored in its /etc, as well as binaries installed in /usr) would be discarded upon AppVM shutdown.
When printer is added and configured in a template VM, then all the AppVMs based on this template should automatically be able to use it (without the need for the template VM to be running, of course).
Alternatively one can add a printer in a standalone VM, but this would limit the printer usage to this particular VM.
Security considerations for network printers and drivers
--------------------------------------------------------
Some printers require 3rd party drivers, typically downloadable from the vendor's website. Such drivers are typically distributed in a form of ready to install RPM packages. However, they are often unsigned, and additionally the downloads are available via HTTP connections only. As a result, installation of such 3rd party RPMs in a default template VM exposes a risk of compromise of this template VM, which, in turn, leads automatically to compromise of all the AppVMs based on the template. (Again, it's not buggy or malicious drivers that we fear here, but rather malicious installation scripts for those drivers).
Some printers require third-party drivers, typically downloadable from the vendor's website.
Such drivers are typically distributed in a form of ready to install RPM packages.
However, they are often unsigned, and additionally the downloads are available via HTTP connections only.
As a result, installation of such third-party RPMs in a default template VM exposes a risk of compromise of this template VM, which, in turn, leads automatically to compromise of all the AppVMs based on the template.
(Again, it's not buggy or malicious drivers that we fear here, but rather malicious installation scripts for those drivers).
In order to mitigate this risk, one might consider creating a custom template (i.e. clone the original template) and then install the 3rd party, unverified drivers there. Such template might then be made the default template for [Disposable VM creation](/doc/dispvm/), which should allow one to print any document by right-clicking on it, choosing "Open in Disposable VM" and print from there. This would allow to print documents from more trusted AppVMs (based on a trusted default template, that is not poisoned by 3rd party printer drivers).
In order to mitigate this risk, one might consider creating a custom template (i.e. clone the original template) and then install the third-party, unverified drivers there.
Such template might then be made a DVM template for [Disposable VM creation](/doc/dispvm/), which should allow one to print any document by right-clicking on it, choosing "Open in Disposable VM" and print from there.
This would allow to print documents from more trusted AppVMs (based on a trusted default template that is not poisoned by third-party printer drivers).
However, one should be aware that most (all?) network printing protocols are insecure, unencrypted protocols. This means, that an attacker who is able to sniff the local network, or who is controlling the (normally untrusted) Qubes NetVM, will likely to be able to see the documents being printed. This is a limitation of today's printers and printing protocols, something that cannot be solved by Qubes or any other OS.
However, one should be aware that most (all?) network printing protocols are insecure, unencrypted protocols.
This means, that an attacker who is able to sniff the local network, or who is controlling the (normally untrusted) Qubes NetVM, will likely to be able to see the documents being printed.
This is a limitation of today's printers and printing protocols, something that cannot be solved by Qubes or any other OS.
Additionally, the printer drivers as well as CUPS application itself, might be buggy and might got exploited when talking to a compromised printer (or by an attacker who controls the local network, or the default NetVM). Consider not using printing from your more trusted AppVMs for this reason.
Additionally, the printer drivers as well as CUPS application itself, might be buggy and might get exploited when talking to a compromised printer (or by an attacker who controls the local network, or the default NetVM).
Consider not using printing from your more trusted AppVMs for this reason.
Steps to configure a network printer in a template VM
----------------------------------------------------------
1. Start the "Printer Settings" App in a template VM (either via Qubes "Start Menu", or by launching the `system-config-printer` in the template).
2. Add/Configure the printer in the same way as one would do on any normal Linux. Be sure to allow network access from the template VM to your printer, as normally the template VM is not allowed any network access, except to the Qubes proxy for software installation. One can use Qubes Manager to modify firewall rules for particular VMs.
2. Add/Configure the printer in the same way as one would do on any normal Linux.
You may need to allow network access from the template VM to your printer to complete configuration, as normally the template VM is not allowed any network access except to the Qubes proxy for software installation.
One can use Qubes Manager to modify firewall rules for particular VMs.
3. Optional: Test the printer by printing a test page. If it works, shut down the template VM.
4. Open an AppVM (make sure it's based on the template where you just installed the printer, normally all AppVMs are based on the default template), and test if printing works. If it doesn't then probably the AppVM doesn't have networking access to the printer -- in that case adjust the firewall settings for that AppVM in Qubes Manager. Also, make sure that the AppVM gets restarted after the template was shutdown.
4. Open an AppVM (make sure it's based on the template where you just installed the printer, normally all AppVMs are based on the default template), and test if printing works.
If it doesn't then probably the AppVM doesn't have networking access to the printer -- in that case adjust the firewall settings for that AppVM in Qubes Manager.
Also, make sure that the AppVM gets restarted after the template was shutdown.
5. Alternatively if you do not want to modify the firewall rules of the template VM (that have security scope) you can simply shut down the template VM without trying to print the test page (which will not work), start or restart an AppVM based on the template and test printing there.

12
configuration/postfix.md
View File

@ -16,11 +16,11 @@ Postfix is full featured MTA (Message Transfer Agent). Here we will configure it
Installation
------------
`yum install postfix procmail make cyrus-sasl cyrus-sasl-plain`
`dnf install postfix procmail make cyrus-sasl cyrus-sasl-plain`
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
You should also check `alternatives` command, to see if it is the default `mta`. It probably is not. You may need to `dnf remove ssmtp` or something
Configuration
-------------
@ -35,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
@ -99,14 +99,14 @@ alias_maps = hash:/etc/aliases
@localhost your.mail@example.com
~~~
`/usr/local/etc/postfix/sender_relay`. This is important file. Put there all your SMTP servers. Pay attention to port (smtp/submission). Square brackets have their special meaning, they are almost certainly needed. For more info consult Postfix manual.
`/usr/local/etc/postfix/sender_relay`. This is an important file. Put all your SMTP servers there. Pay attention to port (smtp/submission). Square brackets have their special meaning, they are almost certainly needed. For more info consult Postfix manual.
~~~
your.mail@exmaple.com [mail.example.com]:submission
your.other@mail.com [smtp.mail.com]:smtp
~~~
`/usr/local/etc/postfix/saslpass`. Here you put passwords to above mentioned servers. It depends on provider if you need to put whole email as username or just the part before `@`.
`/usr/local/etc/postfix/saslpass`. Here you put passwords to above mentioned servers. It depends on your provider if you need to put whole email as username or just the part before `@`.
~~~
[mail.example.com]:submission your.mail:y0urP4ssw0rd
@ -152,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.

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

@ -4,103 +4,98 @@ title: Resize Disk Image
permalink: /doc/resize-disk-image/
redirect_from:
- /en/doc/resize-disk-image/
- /en/doc/resize-root-disk-image/
- /doc/ResizeDiskImage/
- /doc/ResizeRootDiskImage/
- /wiki/ResizeDiskImage/
- /wiki/ResizeRootDiskImage/
---
Resize Disk Image
-----------------
There are several disk images which can be easily extended. But pay attention to the overall consumed space of your sparse disk images.
There are several disk images which can be easily extended, but pay attention to the overall consumed space of your sparse/thin disk images.
See also [OS Specific Follow-up Instructions](/doc/resize-disk-image/#os-specific-follow-up-instructions) at the end of this page.
### Private disk image
1048576 MB is the maximum size which can be assigned to a private storage through qubes-manager.
### Template disk image (R4.0)
To grow the private disk image of a AppVM beyond this limit [qubes-grow-private](/doc/dom0-tools/qvm-grow-private/) can be used:
If you want install a lot of software in your TemplateVM, you may need to increase the amount of disk space your TemplateVM can use.
*Make sure changes in the TemplateVM between reboots don't exceed 10G.*
1. Resize the *root image* using Qubes version specific procedure below.
2. Start the template.
3. Resize the filesystem using OS appropriate tools (Qubes will handle this automatically under Linux).
4. Verify available space in the template using `df -h` or OS specific tools.
5. Shutdown the template.
### Template disk image (R3.2)
If you want install a lot of software in your TemplateVM, you may need to increase the amount of disk space your TemplateVM can use.
*Make sure changes in the TemplateVM between reboots don't exceed 10G.*
1. Make sure that all the VMs based on this template are shut down (including netvms etc).
2. Resize the *root image* using Qubes version specific procedure below.
3. If any netvm/proxyvm used by this template is based on it, set template's netvm to none.
4. Start the template.
5. Resize the filesystem using OS appropriate tools (Linux is `sudo resize2fs /dev/mapper/dmroot`).
6. Verify available space in the template using `df -h` or OS specific tools.
7. Shutdown the template.
8. Restore original netvm setting (if changed), and check firewall settings (setting netvm to none causes the firewall to reset to "block all")
### Expand disk image (R4.0)
1048576 MiB is the maximum size which can be assigned to storage through Qube Manager.
To grow the root or private disk image of an AppVM beyond this limit, `qvm-volume` can be used:
~~~
qvm-grow-private <vm-name> <size>
qvm-volume extend <vm_name>:root <size>
~~~
OR
~~~
qvm-volume extend <vm_name>:private <size>
~~~
Note: Size is the target size (i.e. 4096MB or 16GB, ...), not the size to add to the existing disk.
### Shrinking private disk image (Linux VM)
### Expand disk image (R3.2)
**This operation is dangerous and this is why it isn't available in standard Qubes tools. If you have enough disk space, it is safer to create new VM with smaller disk and move the data.**
1048576 MB is the maximum size which can be assigned to storage through Qubes Manager.
The basic idea is to:
1. Shrink filesystem on the private disk image.
2. Then shrink the image.
Ext4 does not support online shrinking, so can't be done as convenient as image grown. Note that we don't want to touch the VM filesystem directly in dom0 for security reasons. First you need to start VM without `/rw` mounted. One of the possibility is to interrupt its normal startup by adding `rd.break` kernel option:
To grow the private disk image of an AppVM beyond this limit, `qvm-grow-root` or [qvm-grow-private](/doc/dom0-tools/qvm-grow-private/) can be used:
~~~
qvm-prefs -s <vm-name> kernelopts rd.break
qvm-start --no-guid <vm-name>
qvm-grow-root <vm-name> <size>
~~~
OR
~~~
qvm-grow-private <vm-name> <size>
~~~
And wait for qrexec connect timeout (or simply press Ctrl-C). Then you can connect to VM console and shrink the filesystem:
Note: Size is the target size (i.e. 4096MB or 16GB, ...), not the size to add to the existing disk.
~~~
sudo xl console <vm-name>
# you should get dracut emergency shell here
mount --bind /dev /sysroot/dev
chroot /sysroot
mount /proc
e2fsck -f /dev/xvdb
resize2fs /dev/xvdb <new-desired-size>
umount /proc
exit
umount /sysroot/dev
poweroff
~~~
### Resize a StandaloneVM Root Image
Now you can resize the image:
For more flexibility, you may also turn your TemplateVM into a StandaloneVM.
Doing this means it will have its own root filesystem *(StandaloneVMs use a copy of the template, instead of smart sharing)*.
To do this run `qvm-create --standalone` from `dom0` console, then perform the [OS Specific Follow-up Instructions](/doc/resize-disk-image/#os-specific-follow-up-instructions) below.
~~~
truncate -s <new-desired-size> /var/lib/qubes/appvms/<vm-name>/private.img
~~~
### Shrinking a disk image
**It is critical to use the same (or bigger for some safety margin) size in truncate call compared to resize2fs call. Otherwise you will loose your data!** Then reset kernel options back to default:
Ext4 and most other filesystems do not support online shrinking, so it can't be done as conveniently as growing the image.
Note that we don't want to touch the VM filesystem directly in dom0 for security reasons.
~~~
qvm-prefs -s <vm-name> kernelopts default
~~~
1. Create a new qube with smaller disk using Qube Manager or `qvm-create`
2. Move data to the new qube using `qvm-copy`, backup & restore, or OS utilities
3. Delete old qube using Qube Manager or `qvm-remove`
Done.
OS Specific Follow-up Instructions
-----------------
### Template disk image
If you want install a lot of software in your TemplateVM, you may need to increase the amount of disk space your TemplateVM can use.
1. Make sure that all the VMs based on this template are shut off (including netvms etc).
2. Sanity check: verify that none of loop device are pointing at this template root.img: `sudo losetup -a`
3. Resize root.img file using `truncate -s <desired size>` (the root.img path can be obtained from qvm-prefs).
4. If any netvm/proxyvm used by this template is based on it, set template netvm to none.
5. Start the template.
6. Execute `sudo resize2fs /dev/mapper/dmroot` in the template.
7. Verify available space in the template using `df -h`
8. Shutdown the template.
9. Restore original netvm setting (if changed), check firewall settings (setting netvm to none causes firewall reset to "block all")
### HVM disk image
In this example we will grow the disk image of an HVM to 30GB.
First, stop/shutdown the HVM.
Then, from a Dom0 terminal (in KDE: System Tools -\> Terminal Emulator) do the following:
~~~
cd /var/lib/qubes/appvms/<yourHVM>/
ls -lh root.img (<--verify current size of disk image)
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:
After expanding volumes, the partition table and file-system may need to be adjusted.
Use tools appropriate to the OS in your qube.
Brief instructions for Windows 7, FreeBSD, and Linux are provided below.
#### Windows 7
@ -119,3 +114,9 @@ sysctl kern.geom.debugflags=0x10
gpart resize -i index ada0
zpool online -e poolname ada0
~~~
#### Linux
Qubes will automatically grow the filesystem for you on AppVMs but not HVMs (or Template root images on R3.2).
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 `resize2fs` to make this space available.

54
configuration/resize-root-disk-image.md
View File

@ -1,54 +0,0 @@
---
layout: doc
title: Resize Root Disk Image
permalink: /doc/resize-root-disk-image/
redirect_from:
- /en/doc/resize-root-disk-image/
- /doc/ResizeRootDiskImage/
- /wiki/ResizeRootDiskImage/
---
Resize Root Disk Image
----------------------
The safest way to increase the size of `root.img` is to turn your TemplateVM into a StandaloneVM. Doing this means it will have it's own root filesystem *(StandaloneVMs use a copy of template, instead of smart sharing)*. To do this run `qvm-create --standalone` from `dom0` Konsole.
### Resize a StandaloneVM Root Image
In `dom0` Konsole run the following command (replace the size and path):
~~~
truncate -s 20G /var/lib/qubes/appvms/standalonevm/root.img
~~~
Then start Terminal for this StandaloneVM and run:
~~~
sudo resize2fs /dev/mapper/dmroot
~~~
Shutdown the StandaloneVM and you will have extended the size of it's `root.img`
### Resize a TemplateVM Root Image
Shut down the TemplateVM, as well as all VMs based on that template (since they
share `root.img`).
In `dom0` Konsole run the following command (replace the size and path):
*Make sure changes in the TemplateVM between reboots didn't exceed 10G.*
~~~
truncate -s 20G /var/lib/qubes/vm-templates/fedora-21/root.img
~~~
Then start only the TemplateVM and run the following. Note that if you are
resizing the TemplateVM used by, e.g., your NetVM, you may need to disable
networking so when the TemplateVM is started, it does not autostart other VMs
based on the same `root.img`. Otherwise you will get an error message `Nothing
to do!`.
~~~
sudo resize2fs /dev/mapper/dmroot
~~~
Shutdown the TemplateVM and you will have extended the size of it's `root.img`.

58
configuration/rpc-policy.md Normal file
View File

@ -0,0 +1,58 @@
---
layout: doc
title: RPC Policies
permalink: /doc/rpc-policy/
---
RPC Policies
============
This document explains the basics of RPC policies in Qubes.
For more information, see [Qrexec: command execution in VMs][qrexec3].
Here's an example of an RPC policy file in dom0:
```
[user@dom0 user ~]$ cat /etc/qubes-rpc/policy/qubes.FileCopy
(...)
$tag:work $tag:work allow
$tag:work $anyvm deny
$anyvm $tag:work deny
$anyvm $anyvm ask
```
It has three columns (from left to right): source, destination, and permission.
Each row is a rule.
For example, the first row says that we're **allowed** (third column) to copy a file (since this is the policy file for `qubes.FileCopy`) **from** (first column) any VM tagged with "work" **to** (second column) any VM tagged with "work".
In other words, all the VMs tagged with "work" are allowed to copy files to each other without any prompts.
(If the third column were "ask" instead of "allow", there would be prompts.
I.e., we would be **asked** to approve the action, instead of it always being **allowed**.)
Now, the whole policy file is parsed from top to bottom.
As soon as a rule is found that matches the action being evaluated, parsing stops.
We can see what this means by looking at the second row.
It says that we're **denied** from attempting to copy a file **from** any VM tagged with "work" **to** any VM whatsoever.
(That's what the `$anyvm` keyword means -- literally any VM in the system).
But, wait a minute, didn't we just say (in the first row) that all the VMs tagged with work are **allowed** to copy files to each other?
That's exactly right.
The first and second rows contradict each other, but that's intentional.
Since we know that parsing goes from top to bottom (and stops at the first match), we intentionally put the first row above the second row so that it would take precedence.
This is how we create a policy that says: "VMs tagged with 'work' are allowed to copy files to each other but not to any *other* VMs (i.e., not to VMs that *aren't* tagged with 'work')."
The third row says that we're **denied** from copying files **from** any VM in the system **to** any VM tagged with "work".
Again, since parsing goes from top to bottom, this doesn't mean that no files can ever be copied from *any* VM to a VM tagged with "work".
Rather, it means that only VMs that match an earlier rule can do so (in this case, only VMs tagged with "work").
The fourth and final row says that we're **asked** (i.e., prompted) to copy files **from** any VM in the system **to** any VM in the system.
(This rule was already in the policy file by default.
We added the first three.)
Note that it wouldn't make sense to add any rules after this one, since every possible pair of VMs will match the `$anyvm $anyvm` pattern.
Therefore, parsing will always stop at this rule, and no rules below it will ever be evaluated.
All together, the three rules we added say that all VMs tagged with "work" are allowed to copy files to each other; however, they're denied from copying files to other VMs (without the "work" tag), and other VMs (without the "work" tag) are denied from copying files to them.
The fourth rule means that the user gets prompted for any situation not already covered.
Further details about how this system works can be found in [Qrexec: command execution in VMs][qrexec3].
[qrexec3]: /doc/qrexec3/

18
configuration/rxvt.md
View File

@ -16,12 +16,16 @@ Rxvt
Installation
------------
`yum install rxvt-unicode-256color-ml` will bring both base `rxvt-unicode` and extension. Let me also recommend excellent Terminus font: `yum install terminus-fonts`.
`dnf install rxvt-unicode-256color-ml` will bring both base `rxvt-unicode` and extension.
Let me also recommend excellent Terminus font: `dnf install terminus-fonts`.
Xresources
----------
In TemplateVM create file `/etc/X11/Xresources.urxvt` and paste config below. `!`-lines are comments and may be left out. `#`-lines are directives to CPP (C preprocessor) and are necessary. This shouldn't go to `/etc/X11/Xresources`, because that file is not preprocessed by default.
In TemplateVM create file `/etc/X11/Xresources.urxvt` and paste config below.
`!`-lines are comments and may be left out.
`#`-lines are directives to CPP (C preprocessor) and are necessary.
This shouldn't go to `/etc/X11/Xresources`, because that file is not preprocessed by default.
~~~
! CGA colour palette
@ -122,13 +126,18 @@ 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'
!URxvt.termName: rxvt-256color
~~~
Then create script to automatically merge those to xrdb. File `/etc/X11/xinit/xinitrc.d/urxvt.sh`:
Then create script to automatically merge those to xrdb.
File `/etc/X11/xinit/xinitrc.d/urxvt.sh`:
~~~
#!/bin/sh
@ -139,4 +148,5 @@ Then create script to automatically merge those to xrdb. File `/etc/X11/xinit/xi
Shortcuts
---------
For each AppVM, go to *Qubes Manager \> VM Settings \> Applications*. Find `rxvt-unicode` (or `rxvt-unicode (256-color) multi-language`) and add.
For each AppVM, go to *Qubes Manager \> VM Settings \> Applications*.
Find `rxvt-unicode` (or `rxvt-unicode (256-color) multi-language`) and add.

522
configuration/salt.md
View File

@ -3,113 +3,248 @@ layout: doc
title: Management stack
permalink: /doc/salt/
---
# Management infrastructure
Since Qubes R3.1 release we have included `salt` (also called SaltStack)
management engine in dom0 as default with some states already configured. salt
allows administrators to easily configure their systems. In this guide we will
show how it is set up and how you can modify it for your own purpose.
# Management Infrastructure
Since the Qubes R3.1 release we have included the Salt (also called SaltStack)
management engine in dom0 as default (with some states already configured).
Salt allows administrators to easily configure their systems.
In this guide we will show how it is set up and how you can modify it for your
own purpose.
In the current form the **API is provisional** and subject to change between
*minor* releases.
## Understanding `salt`
## Understanding Salt
This document is not meant to be comprehensive salt documentation, however
This document is not meant to be comprehensive Salt documentation; however,
before writing anything it is required you have at least *some* understanding of
basic salt-related vocabulary. For more exhaustive documentation, visit
[official site][salt-doc], though we must warn you that it is not easy to read
if you just start working with salt and know nothing.
basic Salt-related vocabulary.
For more exhaustive documentation, visit [official site][salt-doc], though we
must warn you that it is not easy to read if you just start working with Salt
and know nothing.
Salt has client-server architecture, where server (called *master*) manages its
clients (called *minions*). In typical situation it is intended that
administrator interacts only with master and keeps the configuration there. In
Qubes OS we don't have master though, since we have only one minion, which
resides in `dom0` and manages domains from there. This is also supported by
salt.
### The Salt Architecture
Salt is a management engine, that enforces particular state of the system, where
minion runs. A *state* is an end effect *declaratively* expressed by the
administrator. This is the most important concept in the whole package. All
configuration (ie. the states) are written in YAML.
Salt is a client-server model, where the server (called *master*) manages
its clients (called *minions*).
In typical situations, it is intended that the administrator interacts only
with the master and keeps the configurations there.
In Qubes, we don't have a master.
Instead we have one minion which resides in `dom0` and manages domains from
there.
This setup is also supported by Salt.
A *pillar* is a data backend declared by administrator. When states became
repetitive, instead of pure YAML they can be written with help of some template
engine (preferably jinja2), which can use data structures specified in pillars.
Salt is a management engine (similar to Ansible, Puppet, and Chef), that
enforces a particular state of a minion system.
A *state* is an end effect *declaratively* expressed by the administrator.
This is the most important concept in the entire engine.
All configurations (i.e., the states) are written in YAML.
A *formula* is a ready to use, packaged solution that combines state and pillar,
possibly with some file templates and other auxiliary files. There are many of
those made by helpful people all over the Internet.
A *pillar* is a data back-end declared by the administrator.
When states become repetitive, instead of pure YAML they can be written using a
template engine (preferably Jinja2); which can use data structures specified in
pillars.
A *formula* is a ready to use, packaged solution that combines a state and a
pillar (possibly with some file templates and other auxiliary files).
There are many formulas made by helpful people all over the Internet.
A *grain* is some data that is also available in templates, but its value is not
directly specified by administrator. For example the distribution (like
`"Debian"` or `"Gentoo"`) is a value of the grain `"os"`. It also contains other
info about kernel, hardware etc.
directly specified by administrator.
For example, the distribution (e.g., `"Debian"` or `"Gentoo"`) is a value of
the grain `"os"`. It also contains other information about the kernel,
hardware, etc.
A *module* is a Python extension to salt that is responsible for actually
enforcing the state in a particular area. It exposes some *imperative* functions
for administrator. For example there is `system` module that has `system.halt`
function that, when issued, will immediately halt the computer. There is another
function called `state.highstate` which will synchronize the state of the system
with the administrator's will.
A *module* is a Python extension to Salt that is responsible for actually
enforcing the state in a particular area.
It exposes some *imperative* functions for the administrator.
For example, there is a `system` module that has a `system.halt` function that,
when issued, will immediately halt a domain.
There is another function called `state.highstate` which will synchronize the
state of the system with the administrator's configuration/desires.
### Configuration
## Salt configuration, Qubes OS layout
#### States
All salt configuration in `/srv/` directory, as usual. The main directory is
`/srv/salt/` where all state files reside. States are contained in `*.sls`
files. However the states that are part of standard Qubes distribution are
mostly templates and the configuration is done in pillars from formulas.
The smallest unit of configuration is a state.
A state is written in YAML and looks like this:
The formulas are in `/srv/formulas`, including stock formula for domains in
stateid:
cmd.run: #this is the execution module. in this case it will execute a command on the shell
- name: echo 'hello world' #this is a parameter of the state.
The stateid has to be unique throughout all states running for a minion and can
be used to order the execution of the references state.
`cmd.run` is an execution module.
It executes a command on behalf of the administrator.
`name: echo 'hello world'` is a parameter for the execution module `cmd.run`.
The module used defines which parameters can be passed to it.
There is a list of [officially available states][salt-doc-states].
There are many very useful states:
* For [managing files][salt-doc-states-file]: Use this to create files or
directories and change them (append lines, replace text, set their content etc.)
* For [installing and uninstalling][salt-doc-states-pkg] packages.
* For [executing shell commands][salt-doc-states-cmd].
With these three states you can define most of the configuration of a VM.
You can also [order the execution][salt-doc-states-order] of your states:
D:
cmd.run:
- name: echo 1
- order: last
C:
cmd.run:
- name: echo 1
B:
cmd.run:
- name: echo 1
- require:
- cmd: A
- require_in:
- cmd:C
A:
cmd.run:
- name: echo 1
- order: 1
The order of execution will be `A, B, C, D`.
The official documentation has more details on the
[require][salt-doc-states-req] and [order][salt-doc-states-ord] arguments.
#### State Files
When configuring a system you will write one or more state files (`*.sls`) and
put (or symlink) them into the main Salt directory `/srv/salt/`.
Each state file contains multiple states and should describe some unit of
configuration (e.g., a state file `mail.sls` could setup a VM for e-mail).
#### Top Files
After you have several state files, you need something to assign them to a VM.
This is done by `*.top` files ([official documentation][salt-doc-top]).
Their structure looks like this:
environment:
target_matching_clause:
- statefile1
- folder2.statefile2
In most cases, the environment will be called `base`.
The `target_matching_clause` will be used to select your minions (VMs).
It can be either the name of a VM or a regular expression.
If you are using a regular expressions, you need to give Salt a hint you are
doing so:
environment:
^app-(work|(?!mail).*)$:
- match: pcre
- statefile
For each target you can write a list of state files.
Each line is a path to a state file (without the `.sls` extension) relative to
the main directory.
Each `/` is exchanged with a `.`, so you can't reference files or directories
with a `.` in their name.
### Enabling Top Files and Applying the States
Now, because we use custom extensions to manage top files (instead of just
enabling them all), to enable a particular top file you should issue command:
$ qubesctl top.enable my-new-vm
To list all enabled top files:
$ qubesctl top.enabled
And to disable one:
$ qubesctl top.disable my-new-vm
To apply the states to dom0 and all VMs:
$ qubesctl --all state.highstate
(More information on the `qubesctl` command further down.)
### Template Files
You will sometimes find yourself writing repetitive states.
To solve this, there is the ability to template files or states.
This is most commonly done with [Jinja][jinja].
Jinja is similar to Python and in many cases behaves in a similar fashion, but
there are sometimes differences when, for example, you set some variable inside
a loop: the variable outside will not get changed.
Instead, to get this behavior, you would use a `do` statement.
So you should take a look at the [Jinja API documentation][jinja-tmp].
Documentation about using Jinja to directly call Salt functions and get data
about your system can be found in the official
[Salt documentation][jinja-call-salt-functions].
## Salt Configuration, QubesOS layout
All Salt configuration files are in the `/srv/` directory, as usual.
The main directory is `/srv/salt/` where all state files reside.
States are contained in `*.sls` files.
However, the states that are part of the standard Qubes distribution are mostly
templates and the configuration is done in pillars from formulas.
The formulas are in `/srv/formulas`, including stock formulas for domains in
`/srv/formulas/dom0/virtual-machines-formula/qvm`, which are used by firstboot.
Because we use some code that is not found in older versions of salt, there is
a tool called `qubesctl` that should be run instead of `salt-call --local`. It
accepts all arguments of the vanilla tool.
Because we use some code that is not found in older versions of Salt, there is
a tool called `qubesctl` that should be run instead of `salt-call --local`.
It accepts all the same arguments of the vanilla tool.
## Configuring a VM's System from Dom0
## Configuring system inside of VMs
Starting with Qubes 3.2, Salt in Qubes can be used to configure VMs. Salt
formulas can be used normal way. Simply set VM name as target minion name in
top file. You can also use `qubes` pillar module to select VMs with a
particular property (see below). Then you need to pass additional arguments to
`qubesctl` tool:
Starting with Qubes R3.2, Salt in Qubes can be used to configure VMs from dom0.
Simply set the VM name as the target minion name in the top file.
You can also use the `qubes` pillar module to select VMs with a particular
property (see below).
If you do so, then you need to pass additional arguments to the `qubesctl` tool:
usage: qubesctl [-h] [--show-output] [--force-color] [--skip-dom0]
[--targets TARGETS | --templates | --app | --all]
...
positional arguments:
command Salt command to execute (for example: state.highstate)
command Salt command to execute (e.g., state.highstate)
optional arguments:
-h, --help show this help message and exit
--show-output Show output of management commands
--force-color Force color output, allow control characters from VM,
UNSAFE
--skip-dom0 Skip dom0 condifuration (VM creation etc)
--skip-dom0 Skip dom0 configuration (VM creation etc)
--targets TARGETS Coma separated list of VMs to target
--templates Target all templates
--app Target all AppVMs
--all Target all non-disposable VMs (TemplateVMs and AppVMs)
To apply the configuration to all the templates, call `qubesctl --templates
state.highstate`.
To apply a state to all templates, call `qubesctl --templates state.highstate`.
Actual configuration is applied using `salt-ssh` (running over `qrexec` instead
of `ssh`). Which means you don't need to install anything special in a VM you
want to manage. Additionally for each target VM, `salt-ssh` is started from a
temporary VM. This way dom0 doesn't directly interact with potentially
malicious target VM.
The actual configuration is applied using `salt-ssh` (running over `qrexec`
instead of `ssh`).
Which means you don't need to install anything special in a VM you want to
manage.
Additionally, for each target VM, `salt-ssh` is started from a temporary VM.
This way dom0 doesn't directly interact with potentially malicious target VMs;
and in the case of a compromised Salt VM, because they are temporary, the
compromise cannot spread from one VM to another.
## Writing your own configuration
## Writing Your Own Configurations
Let's start with quick example:
Let's start with a quick 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,195 @@ 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
Additional pillar data is available to ease targeting configuration (for
example all the templates). List here may be subject to changes in future
releases.
## Virtual Machine Formulae
### qubes:type
You can use these formulae to download, install, and configure VMs in Qubes.
These formulae use pillar data to define default VM names and configuration details.
The default settings can be overridden in the pillar data located in:
```
/srv/pillar/base/qvm/init.sls
```
In dom0, you can apply a single state with `sudo qubesctl state.sls STATE_NAME`.
For example, `sudo qubesctl state.sls qvm.personal` will create a `personal` VM (if it does not already exist) with all its dependencies (TemplateVM, `sys-firewall`, and `sys-net`).
### Available states
#### `qvm.sys-net`
System NetVM
#### `qvm.sys-usb`
System UsbVM
#### `qvm.sys-net-with-usb`
System UsbVM bundled into NetVM. Do not enable together with `qvm.sys-usb`.
#### `qvm.usb-keyboard`
Enable USB keyboard together with USBVM, including for early system boot (for LUKS passhprase).
This state implicitly creates a USBVM (`qvm.sys-usb` state), if not already done.
#### `qvm.sys-firewall`
System firewall ProxyVM
#### `qvm.sys-whonix`
Whonix gateway ProxyVM
#### `qvm.personal`
Personal AppVM
#### `qvm.work`
Work AppVM
#### `qvm.untrusted`
Untrusted AppVM
#### `qvm.vault`
Vault AppVM with no NetVM enabled.
#### `qvm.default-dispvm`
Default Disposable VM template - fedora-26-dvm AppVM
#### `qvm.anon-whonix`
Whonix workstation AppVM.
#### `qvm.whonix-ws-dvm`
Whonix workstation AppVM for Whonix Disposable VMs.
#### `qvm.updates-via-whonix`
Setup UpdatesProxy to route all templates updates through Tor (sys-whonix here).
#### `qvm.template-fedora-21`
Fedora-21 TemplateVM
#### `qvm.template-fedora-21-minimal`
Fedora-21 minimal TemplateVM
#### `qvm.template-debian-7`
Debian 7 (wheezy) TemplateVM
#### `qvm.template-debian-8`
Debian 8 (jessie) TemplateVM
#### `qvm.template-whonix-gw`
Whonix Gateway TemplateVM
#### `qvm.template-whonix-ws`
Whonix Workstation TemplateVM
## The `qubes` Pillar Module
Additional pillar data is available to ease targeting configurations (for example all templates).
**Note:** This list is subject to change in future releases.
### `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-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

114
configuration/secondary-storage.md
View File

@ -11,34 +11,104 @@ redirect_from:
Storing AppVMs on Secondary Drives
==================================
Suppose you have a fast but small primary SSD and a large but slow secondary
HDD. You want to store a subset of your AppVMs on the HDD. In dom0:
Suppose you have a fast but small primary SSD and a large but slow secondary HDD.
You want to store a subset of your AppVMs on the HDD.
1. `# mv /var/lib/qubes/appvms/my-new-appvm
/path/to/secondary/drive/my-new-appvm`
### R4.0 ###
2. `# ln -s /path/to/secondary/drive/my-new-appvm /var/lib/qubes/appvms/`
Qubes 4.0 is more flexible than earlier versions about placing different VMs on different disks.
For example, you can keep templates on one disk and AppVMs on another, without messy symlinks.
Now, `my-new-appvm` will behave as if it were still stored on the primary SSD
(except that it will probably be slower, since it's actually stored on the
secondary HDD).
These steps assume you have already created a separate [volume group](https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/6/html/logical_volume_manager_administration/vg_admin#VG_create) and [thin pool](https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/6/html/logical_volume_manager_administration/thinly_provisioned_volume_creation) (not thin volume) for your HDD.
See also [this example](https://www.linux.com/blog/how-full-encrypt-your-linux-system-lvm-luks) if you would like to create an encrypted LVM pool (but note you can use a single logical volume if preferred, and to use the `-T` option on `lvcreate` to specify it is thin). You can find the commands for this example applied to Qubes at the bottom of this R4.0 section.
Known Issues
------------
First, collect some information in a dom0 terminal:
* The above procedure does **not** interfere with [Qubes Backup][]. However,
attempting to symlink a `private.img` file (rather than the whole AppVM
directory) is known to prevent the `private.img` file from being backed up.
The same problem may occur if the above procedure is attempted on a
[TemplateVM][]. [[1]]
sudo pvs
sudo lvs
* 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
detached when you shut down the AppVM.) [[2]]
Take note of the VG and thin pool names for your HDD, then register it with Qubes:
[Qubes Backup]: https://www.qubes-os.org/doc/BackupRestore/
[TemplateVM]: https://www.qubes-os.org/doc/Templates/
# <pool_name> is a freely chosen pool name
# <vg_name> is LVM volume group name
# <thin_pool_name> is LVM thin pool name
qvm-pool --add <pool_name> lvm_thin -o volume_group=<vg_name>,thin_pool=<thin_pool_name>,revisions_to_keep=2
Now, you can create qubes in that pool:
qvm-create -P <pool_name> --label red <vmname>
It isn't possible to directly migrate an existing qube to the new pool, but you can clone it there, then remove the old one:
qvm-clone -P <pool_name> <sourceVMname> <cloneVMname>
qvm-remove <sourceVMname>
If that was a template, or other qube referenced elsewhere (NetVM or such), you will need to adjust those references manually after moving.
For example:
qvm-prefs <appvmname_based_on_old_template> template <new_template_name>
In theory, you can still use file-based disk images ("file" pool driver), but it lacks some features such as you won't be able to do backups without shutting down the qube.
#### Example HDD setup ####
Assuming the secondary hard disk is at /dev/sdb (it will be completely erased), you can set it up for encryption by doing in a dom0 terminal (use the same passphrase as the main Qubes disk to avoid a second password prompt at boot):
sudo cryptsetup luksFormat --hash=sha512 --key-size=512 --cipher=aes-xts-plain64 --verify-passphrase /dev/sdb
sudo blkid /dev/sdb
Note the device's UUID (in this example "b209..."), we will use it as its luks name for auto-mounting at boot, by doing:
sudo nano /etc/crypttab
And adding this line (change both "b209..." for your device's UUID from blkid) to crypttab:
luks-b20975aa-8318-433d-8508-6c23982c6cde UUID=b20975aa-8318-433d-8508-6c23982c6cde none
Reboot the computer so the new luks device appears at /dev/mapper/luks-b209... and we can then create its pool, by doing this on a dom0 terminal (substitute the b209... UUIDs with yours):
First create the physical volume
sudo pvcreate /dev/mapper/luks-b20975aa-8318-433d-8508-6c23982c6cde
Then create the LVM volume group, we will use for example "qubes" as the <vg_name>:
sudo vgcreate qubes /dev/mapper/luks-b20975aa-8318-433d-8508-6c23982c6cde
And then use "poolhd0" as the <thin_pool_name> (LVM thin pool name):
sudo lvcreate -T -n poolhd0 -l +100%FREE qubes
Finally we will tell Qubes to add a new pool on the just created thin pool
qvm-pool --add poolhd0_qubes lvm_thin -o volume_group=qubes,thin_pool=poolhd0,revisions_to_keep=2
By default VMs will be created on the main Qubes disk (i.e. a small SSD), to create them on this secondary HDD do the following on a dom0 terminal:
qvm-create -P poolhd0_qubes --label red unstrusted-hdd
### R3.2 ###
In dom0:
mv /var/lib/qubes/appvms/<my-new-appvm> /path/to/secondary/drive/<my-new-appvm>
ln -s /path/to/secondary/drive/<my-new-appvm> /var/lib/qubes/appvms/
Now, `my-new-appvm` will behave as if it were still stored on the primary SSD (except that it will probably be slower, since it's actually stored on the secondary HDD).
* The above procedure does **not** interfere with [Qubes Backup][].
However, attempting to symlink a `private.img` file (rather than the whole AppVM directory) is known to prevent the `private.img` file from being backed up.
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 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 detached when you shut down the AppVM.) [[2]]
[Qubes Backup]: /doc/BackupRestore/
[TemplateVM]: /doc/Templates/
[1]: https://groups.google.com/d/topic/qubes-users/EITd1kBHD30/discussion
[2]: https://groups.google.com/d/topic/qubes-users/nDrOM7dzLNE/discussion

361
configuration/vpn.md
View File

@ -12,16 +12,16 @@ redirect_from:
How To make a VPN Gateway in Qubes
==================================
Although setting up a VPN connection is not by itself Qubes specific, there are a number of Qubes-related details that can make using the connection 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.
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.
Please refer to 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)
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
The simplest case is to set up a VPN connection using the NetworkManager service inside your NetVM. Because the NetworkManager service is already started, you are ready to set up your VPN connection. However this has some disadvantages:
- You have to place (and probably save) your VPN credentials inside the NetVM, which is directly connected to the outside world
- All your AppVMs which are connected to the NetVM will be connected to the VPN (by default)
- You have to place (and probably save) your VPN credentials inside the NetVM, which is directly connected to the outside world
- All your AppVMs which are connected to the NetVM will be connected to the VPN (by default)
### AppVM
@ -29,171 +29,271 @@ While the NetworkManager service is not started here (for a good reason), you ca
### ProxyVM
One of the best things in Qubes is that you can use a 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.
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.
- Easily control which of your AppVMs are connected to your VPN by simply setting it as a NetVM of the desired AppVM.
- 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.
Set up a ProxyVM as a VPN gateway using NetworkManager
------------------------------------------------------
1. Create a new VM: Name it, click the ProxyVM radio button then choose a color and template.
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)
![Create\_New\_VM.png](/attachment/wiki/VPN/Create_New_VM.png)
2. Add the `network-manager` service to this new VM.
2. Add the `network-manager` service to this new VM.
![Settings-services.png](/attachment/wiki/VPN/Settings-services.png)
![Settings-services.png](/attachment/wiki/VPN/Settings-services.png)
3. Set up your VPN as described in the NetworkManager documentation linked above.
3. Set up your VPN as described in the NetworkManager documentation linked above.
4. Configure your AppVMs to use the new VM as a NetVM.
4. (Optional) Make your VPN start automatically.
![Settings-NetVM.png](/attachment/wiki/VPN/Settings-NetVM.png)
Edit `/rw/config/rc.local` and add these lines:
```bash
# Automatically connect to the VPN once Internet is up
while ! ping -c 1 -W 1.1.1.1; do
sleep 1
done
PWDFILE="/rw/config/NM-system-connections/secrets/passwd-file.txt"
nmcli connection up file-vpn-conn passwd-file $PWDFILE
```
You can find the actual "file-vpn-conn" in `/rw/config/NM-system-connections/`.
Create directory `/rw/config/NM-system-connections/secrets/` (You can put your `*.crt` and `*.pem` files here too).
Create a new file `/rw/config/NM-system-connections/secrets/passwd-file.txt`:
```
vpn.secrets.password:XXXXXXXXXXXXXX
```
And substitute "XXXXXXXXXXXXXX" for the actual password.
The contents of `passwd-file.txt` may differ depending on your VPN settings. See the [documentation for `nmcli up`](https://www.mankier.com/1/nmcli#up).
5. (Optional) Make the network fail-close for the AppVMs if the connection to the VPN breaks.
5. Optionally, you can install some [custom icons](https://github.com/Zrubi/qubes-artwork-proxy-vpn) for your VPN
Edit `/rw/config/qubes-firewall-user-script` and add these lines:
```bash
# Block forwarding of connections through upstream network device
# (in case the vpn tunnel breaks)
iptables -I FORWARD -o eth0 -j DROP
iptables -I FORWARD -i eth0 -j DROP
```
6. Configure your AppVMs to use the new VM as a NetVM.
![Settings-NetVM.png](/attachment/wiki/VPN/Settings-NetVM.png)
7. Optionally, you can install some [custom icons](https://github.com/Zrubi/qubes-artwork-proxy-vpn) for your VPN
Set up a ProxyVM as a VPN gateway using iptables and CLI scripts
----------------------------------------------------------------
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.
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 then choose a color and template.
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)
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.
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`.
You may also wish to install `nano` or other simple text editor for entering the scripts below.
![Create\_New\_VM.png](/attachment/wiki/VPN/Create_New_VM.png)
2. Set up and initial test of the VPN client.
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.
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/...'.
Notes about VPN config options: The VPN scripts here are intended to work with commonly used `tun` interfaces, whereas `tap` mode is untested. Also, the config should route all traffic through your VPN's interface after a connection is created; For openvpn the directive for this is `redirect-gateway def1`. Lastly, the VPN client may not be able to prompt you for credentials when connecting to the server: Creating a file in the 'vpn' folder with your credentials and using a directive such as openvpn's `auth-user-pass <filename>` is recommended.
__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.
If your choice of TemplateVM 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 for OpenVPN.
3. Create the DNS-handling script.
Use `sudo nano /rw/config/vpn/qubes-vpn-handler.sh` to edit and add:
sudo systemctl disable openvpn.service
~~~
#!/bin/bash
set -e
export PATH="$PATH:/usr/sbin:/sbin"
You may also wish to install `nano` or another simple text editor for entering the scripts below.
case "$1" in
2. Set up and test the VPN client.
Make sure the VPN VM and its TemplateVM is not running.
Run a terminal (CLI) in the VPN VM -- this will start the VM.
Then create a new `/rw/config/vpn` folder with.
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
sudo mkdir /rw/config/vpn
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
Copy your VPN config files to `/rw/config/vpn`.
Your VPN config file should be named `openvpn-client.ovpn`) so you can use the scripts below as is without modification.
Otherwise you would have to replace the file name.
`openvpn-client.ovpn` contents:
;;
down)
su - -c 'notify-send "$(hostname): LINK IS DOWN !" --icon=dialog-error' user
;;
esac
~~~
* Files accompanying the main config such as `*.crt` and `*.pem` should also go to `/rw/config/vpn` folder.
* Files referenced in `openvpn-client.ovpn` should not use absolute paths such as `/etc/...`.
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:
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`.
~~~
script-security 2
up 'qubes-vpn-handler.sh up'
down 'qubes-vpn-handler.sh down'
~~~
sudo nano /rw/config/vpn/openvpn-client.ovpn
**Restart the client and test the connection again** ...this time from an AppVM!
Make sure it already includes or add:
5. Set up iptables anti-leak rules.
redirect-gateway def1
Edit the firewall script with `sudo nano /rw/config/qubes-firewall-user-script` then clear out the existing lines and add:
The VPN client may not be able to prompt you for credentials when connecting to the server.
Create a file in the `/rw/config/vpn` folder with your credentials and using a directive.
For example for OpenVPN, 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
auth-user-pass pass.txt
# Add the `qvpn` group to system, if it doesn't already exist
if ! grep -q "^qvpn:" /etc/group ; then
Save file `/rw/config/vpn/openvpn-client.ovpn`.
Make sure a `/rw/config/vpn/pass.txt` file actually exists.
sudo nano /rw/config/vpn/pass.txt
Add:
username
password
Replace `username` and `password` with your actual username and password.
**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`.
ping 8.8.8.8
`ping` can be aborted by pressing the two keys `ctrl` + `c` at the same time.
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.
sudo nano /rw/config/vpn/qubes-vpn-handler.sh
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
~~~
Save the script.
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.
sudo nano /rw/config/vpn/openvpn-client.ovpn
Add the following.
script-security 2
up 'qubes-vpn-handler.sh up'
down 'qubes-vpn-handler.sh down'
Remove other instances of lines starting with `script-security`, `up` or `down` should there be any others.
Save the script.
**Restart the client and test the connection again** ...this time from an AppVM!
5. Set up iptables anti-leak rules.
Edit the firewall script.
sudo nano /rw/config/qubes-firewall-user-script
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
ip6tables -I FORWARD -o eth0 -j DROP
ip6tables -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
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
~~~
# 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
~~~
Save the script.
Make it executable.
Now save the script and make it executable:
`sudo chmod +x /rw/config/qubes-firewall-user-script`
sudo chmod +x /rw/config/qubes-firewall-user-script
5. Set up the VPN's autostart.
5. Set up the VPN's autostart.
Use `sudo nano /rw/config/rc.local` to clear out the existing lines and add:
sudo nano /rw/config/rc.local
~~~
#!/bin/bash
VPN_CLIENT='openvpn'
VPN_OPTIONS='--cd /rw/config/vpn/ --config openvpn-client.ovpn --daemon'
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.
Clear out the existing lines and add:
~~~
#!/bin/bash
VPN_CLIENT='openvpn'
VPN_OPTIONS='--cd /rw/config/vpn/ --config openvpn-client.ovpn --daemon'
su - -c 'notify-send "$(hostname): Starting $VPN_CLIENT..." --icon=network-idle' user
groupadd -rf qvpn ; sleep 2s
sg qvpn -c "$VPN_CLIENT $VPN_OPTIONS"
~~~
If you are using anything other than OpenVPN, change the `VPN_CLIENT` and `VPN_OPTIONS` variables to match your VPN software.
Save the script.
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.
Now save the script and make it executable:
`sudo chmod +x /rw/config/rc.local`
6. Restart the new VM! The link should then be established automatically with a popup notification to that effect.
Usage
-----
@ -202,6 +302,17 @@ Configure your AppVMs to use the VPN VM as a NetVM...
![Settings-NetVM.png](/attachment/wiki/VPN/Settings-NetVM.png)
If you want to be able to use the [Qubes firewall](/doc/firewall), create a new FirewallVM (as a ProxyVM) and set it to use the VPN VM as its NetVM.
Then, configure AppVMs to use your new FirewallVM as their NetVM.
If you want to update your TemplateVMs through the VPN, enable the `qubes-updates-proxy` service in your new FirewallVM.
You can do this in the Services tab in Qubes VM Manager or on the command-line:
qvm-service -e <name> qubes-updates-proxy
Then, configure your templates to use your new FirewallVM as their NetVM.
Troubleshooting
---------------

40
configuration/w3m.md Normal file
View File

@ -0,0 +1,40 @@
---
layout: doc
title: Reducing the fingerprint of the text-based web browser w3m
permalink: /doc/w3m/
redirect_from:
- /en/doc/mutt/
- /doc/W3m/
- /wiki/W3m/
---
Reducing the fingerprint of the text-based web browser w3m
====
TL;DR: You can reduce the amount of information w3m gives about itself and the environment it is running in (and, by extension, you). **It will not make you anonymous; your fingerprint will still be unique.** But it may improve your privacy.
[w3m](http://w3m.sourceforge.net/) 'is a text-based web browser as well as a pager like `more` or `less`. With w3m you can browse web pages through a terminal emulator window (xterm, rxvt or something like that). Moreover, w3m can be used as a text formatting tool which typesets HTML into plain text.'
You can reduce the [browser fingerprint](https://panopticlick.eff.org/about#browser-fingerprinting) by applying the following changes to `~/.w3m/config` in any AppVM you want to use w3m in. (If you have not run w3m yet, you might need to copy the config file from elsewhere.) You can also apply the same changes to `/etc/w3m/config` in the relevant TemplateVM(s) to have them apply to multiple AppVMs; but make sure they are not reversed by the contents of `~/.w3m/config` in any of the AppVMs. (w3m reads `~/.w3m/config` after `/etc/w3m/config`).
* Set `user_agent` to `user_agent Mozilla/5.0 (Windows NT 6.1; rv:45.0) Gecko/20100101 Firefox/45.0`.
By default w3m identifies itself as `w3m/` + version number. The user agent `Mozilla/5.0 (Windows NT 6.1; rv:45.0) Gecko/20100101 Firefox/45.0` is the most common and the one used by the Tor Browser Bundle (TBB). One in fourteen browsers fingerprinted by Panopticlick has this value.
* Make w3m use the same HTTP_ACCEPT headers the TBB by adding the following lines at the end of the file:
accept_language en-US,en;q=0.5
accept_encoding gzip, deflate
accept_media text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8
These changes will hide your computer's locale and some other information that may or may not be unique to the VM in which it is running. With the modifications above w3m will have the same headers as about one in fifteen browsers fingerprinted by Panopticlick.
Testing these settings on <https://browserprint.info> returns a fingerprint that is distinguishable from that of the TBB (with JavaScript disabled) only by 'Screen Size (CSS)' and 'Browser supports HSTS?'.\* (<https://panopticlick.eff.org> does not work with w3m.) Due to the low number of w3m users it is highly likely that you will have an unique browser fingerprint among the visitors of a website using somewhat sophisticated browser fingerprinting technology. But at least your browser fingerprint will not reveal your computer's locale settings or other specifics about it in the HTTP_ACCEPT headers. And while it may be inferred from your fingerprint that you use w3m, it is not be explicitly stated in the User-Agent header.
**Reminder: Do not rely on these settings for anonymity. Using w3m is all but guaranteed to make you stand out in the crowd.**
PS: You still need to delete cookies manually (`~/.w3m/cookie`) if you are not running w3m in a DispVM anyway. If you set w3m to not accept cookies, its fingerprint will change. (You can configure w3m to not use store cookies or accept new ones (or both), but the setting `use_cookie` seems to really mean `accept_cookie` and vice-versa, so maybe it is best to delete them manually for now.)
* * *
\* Does someone know how to fix this?

187
customization/awesome.md Normal file
View File

@ -0,0 +1,187 @@
---
layout: doc
title: awesome
permalink: /doc/awesome/
redirect_from:
- /en/doc/awesome/
- /doc/awesome/
---
# Using awesome in dom0
## Qubes-specific features
* support for the Qubes OS window colors
* rudimentary support for the Qubes application menu entries following the freedesktop standard
* support for custom filters and menu entries
## Installation
awesome can be installed with the standard dom0 installation mechanisms.
$ sudo qubes-dom0-update awesome
That's it. After logging out, you can select awesome in the login manager.
## Development
To [contribute code](/doc/contributing/) you may clone the awesome repository as follows:
$ git clone https://github.com/QubesOS/qubes-desktop-linux-awesome
For build instructions please check the repository _README_.
The repository attempts to follow the upstream Fedora repository.
## Common customizations
This section focuses on Qubes-specific customizations. For generic awesome customizations you might want to have a look at the [awesome website](https://awesomewm.org).
Customizations for awesome are usually done at `~/.config/awesome/rc.lua`. The default file can be found at `/etc/xdg/awesome/rc.lua`.
### Application menu
Starting from Qubes 4.0 application menu entries specific to awesome can be put into `~/.config/awesome/xdg-menu/` following the freedesktop standard. The folder might have to be created.
### Focus steal hardening
The default Qubes OS awesome installation comes with the defaults set by the awesome developers for focus changes. Some users may want more tight control over window focus changes - especially since focus changes can have security implications when sensitive data is provided to an incorrect application or even qube.
#### Definition
For the below example we'll define _wanted focus changes_ as one of the below:
* mouse move & click afterwards
* workspace/tag change
* pre-defined key combinations for focus changes (e.g. Mod-j & Mod-k)
* tag assignments and unassignments
Everything else is considered an unwanted _focus steal_.
In particular the following events are not meant to cause a focus change:
* new window created
* a window was closed
* application request
* mouse move without click (sloppy focus)
For the below example other requests from applications to the window manager are meant to be ignored in general as well, e.g.:
* windows shouldn't be able to maximize themselves without the user giving a respective command to the WM (simple test: Firefox F11 next to another window)
* windows shouldn't be able to change their size themselves
* windows shouldn't be able to modify their borders in any way
Users may want to adjust their definitions and respective implementations according to their needs.
#### Implementation
The implementation may be specific to the awesome version you're running. This guide refers to awesome version 3.5.9 which is available to Qubes 3.2 and Qubes 4.0 users.
Please keep in mind that this guide may not be conclusive. Your mileage may vary.
##### Change the autofocus implementation
The line `require("awful.autofocus")` in your _rc.lua_ implements various focus-related features for your awesome instance.
In order to customise these, you can copy the file `/usr/share/awesome/lib/awful/autofocus.lua` to e.g. `~/.config/awesome/autofocus_custom.lua` and replace the line above with `require("autofocus_custom")`.
Then you can customise the focus behavior. According to our above definitions it would look as follows:
```lua
---autofocus_custom.lua
local client = client
local screen = screen
local aclient = require("awful.client")
local atag = require("awful.tag")
--- When loaded, this module makes sure that there's always a client that will have focus
-- on events such as tag switching, client unmanaging, etc.
-- awful.autofocus
-- Give focus when clients appear/disappear and no one else has focus.
-- @param obj An object that should have a .screen property.
function check_focus(obj)
-- When no visible client has the focus...
if not client.focus or not client.focus:isvisible() then
local c = aclient.focus.history.get(obj.screen, 0)
if c then client.focus = c end
end
end
-- Give focus on tag selection change.
-- @param tag A tag object
function check_focus_tag(t)
local s = atag.getscreen(t)
if not s then return end
check_focus({ screen = s })
if client.focus and client.focus.screen ~= s then
local c = aclient.focus.history.get(s, 0)
if c then client.focus = c end
end
end
--made above functions global & removed some focus switches below (user interaction required instead)
--clear any focus
function clear_focus()
--unfortunately this doesn't work at the moment
--cf. https://github.com/awesomeWM/awesome/issues/164
--(Qubes uses an older awesome version that doesn't have the fix yet)
--client.focus = nil
end
atag.attached_connect_signal(nil, "property::selected", check_focus_tag)
client.connect_signal("unmanage", clear_focus)
client.connect_signal("tagged", check_focus)
client.connect_signal("untagged", check_focus)
client.connect_signal("property::hidden", clear_focus)
client.connect_signal("property::minimized", clear_focus)
```
##### Remove unwanted focus changing key bindings
The mouse bindings
```lua
awful.button({ }, 4, awful.tag.viewnext),
awful.button({ }, 5, awful.tag.viewprev)
```
in the default _rc.lua_ may cause tag and thus focus changes without keyboard interaction and tend to happen accidentally. This doesn't suit our definition from above and should therefore be removed or commented out.
##### Adjust client rules
The default client rule allows certain focus changes via `focus = awful.client.focus.filter`. These changes can be prevented entirely by setting `focus = false`.
Alternatively users may provide their own focus filter functions.
##### Disable sloppy focus
In your _rc.lua_ you'll find a section such as
```lua
-- Enable sloppy focus
c:connect_signal("mouse::enter", function(c)
if awful.layout.get(c.screen) ~= awful.layout.suit.magnifier
and awful.client.focus.filter(c) then
client.focus = c
end
end)
```
These enable _sloppy focus_ aka focus changes on mouse movements (without clicking) and should be removed or commented out to disable that behaviour.
##### Ignore requests from applications to the window manager
Handling of such requests is currently mostly implemented by awesome in the file `/usr/share/awesome/lib/awful/ewmh.lua`. You can either comment out the respective `client.connect_singal()` lines in that file (it will change back after each awesome update though) or disconnect the signals in your _rc.lua_.
As of awesome 3.5.9 this however is apparently only possible for signals connected to global functions, i.e. currently only the below signals can be disconnected in the _rc.lua_:
```lua
local ewmh = require("awful.ewmh")
client.disconnect_signal("request::activate", ewmh.activate)
client.disconnect_signal("request::tag", ewmh.tag)
```
The signal names may change across awesome versions.

60
customization/bind-dirs.md
View File

@ -8,14 +8,19 @@ redirect_from:
# How to make any file in a TemplateBasedVM persistent using bind-dirs #
## What is bind-dirs.sh? ##
## What are bind-dirs? ##
With [bind-dirs.sh](https://github.com/QubesOS/qubes-core-agent-linux/blob/master/vm-systemd/bind-dirs.sh)
you can make arbitrary files or folders persistent in TemplateBasedVMs.
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? ##
For example, it is useful for Whonix, sys-whonix, where [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). So sys-whonix does not require to be a StandaloneVM. And therefore can benefit from the Tor anonymity feature 'persistent Tor entry guards' without the overhead of a StandaloneVM.
In a TemplateBasedVM all of the file system comes from the template except `/home`, `/usr/local`, and `/rw`.
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 ##
@ -23,17 +28,27 @@ bind-dirs.sh works with Qubes R3.2 and above.
## How to use bind-dirs.sh? ##
1. Create a file `/rw/config/qubes-bind-dirs.d/50_user.conf` with root rights inside a VM.
Inside your TemplateBasedVM.
2. Append a folder or file to the `binds` variable. In the following example we are using folder `/var/lib/tor`. You can replace that folder with a folder or file of your choice.
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' )
3. Save.
Multiple entries are possible, each on a separate line.
4. Reboot the VM.
4. Save.
5. Done.
5. Reboot the TemplateBasedVM.
6. Done.
If you added for example folder `/var/lib/tor` to the `binds` variable, from now on any files within that folder will persist reboots. If you added for example file `/etc/tor/torrc` to the `binds` variable, from now on any modifications to that file will persist reboots.
## Other Configuration Folders ##
@ -41,16 +56,31 @@ bind-dirs.sh works with Qubes R3.2 and above.
* `/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 TempalteVM root image cannot be made deleted in the TemlateBasedVMs root image using bind-dirs.sh.
* Does not work if the file / folder in question does not already exist in the root image. I.e. a file that does not exist in the root image cannot be bind mounted in the TemplateBasedVM.
* Re-running `sudo /usr/lib/qubes/bind-dirs.sh` without 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.
* 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.
`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`
@ -58,7 +88,7 @@ bind-dirs.sh works with Qubes R3.2 and above.
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.)
(Editing `/usr/lib/qubes-bind-dirs.d/40_qubes-whonix.conf` directly is strongly discouraged, since such changes get lost when that file is changed in the package on upgrades.)
## Discussion ##

14
customization/dark-theme.md
View File

@ -70,7 +70,7 @@ This is the result after applying the steps described here.
![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.
**Note:** Changing 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 therefore hard to read.
Dark XCFE in Dom0
-----------------
@ -109,7 +109,7 @@ This is the result after applying the steps described here.
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.
Almost all Qubes VMs use default applications based on the GTK toolkit. Therefore the description below is focused on tools from the Gnome Desktop Environment.
Using "Gnome-Tweak-Tool"
------------------------
@ -120,7 +120,7 @@ The advantage of creating a dark themed Template VM is, that each AppVM which is
1. Start VM
**Note:** In case of App VM start the Template on which the AppVM is based on.
**Note:** Remember that if you want to make the change persistent, the change needs to be made in the TemplateVM, not the AppVM.
2. Install `Gnome-Tweak-Tool`
@ -157,11 +157,7 @@ The advantage of creating a dark themed Template VM is, that each AppVM which is
6. *(Optional)* Modify Firefox
**Note:** Firefox uses GTK style settings by default. This can create side effects such as unusable forms or search fields. There are two different ways to avoid this. Either by using a add-on or by overwriting the defaults.
- use the theme [GTK+ Dark Theme Global Fixes](https://userstyles.org/styles/111694/gtk-dark-theme-global-fixes) and the [Stylish](https://addons.mozilla.org/en-US/firefox/addon/stylish/) addon
- or add the following line to `/rw/config/rc.local`
**Note:** Firefox uses GTK style settings by default. This can create side effects such as unusable forms or search fields. One way to avoid this is to add the following line to `/rw/config/rc.local`:
sed -i.bak "s/Exec=firefox %u/Exec=bash -c 'GTK_THEME=Adwaita:light firefox %u'/g" /usr/share/applications/firefox.desktop
@ -174,7 +170,7 @@ 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.
**Note:** Remember that if you want to make the change persistent, the change needs to be made in the TemplateVM, not the AppVM.
2. Enable `Global Dark Theme`

335
customization/dispvm-customization.md
View File

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

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

@ -13,11 +13,14 @@ FEDORA Packages Recommendations
Template installation
------------------------------
> [dom0]#qubes-dom0-update qubes-template-fedora-21-minimal
> [dom0]#qubes-dom0-update qubes-template-fedora-26-minimal
*Note*: the template may not start in Qubes R3 when using kernel 3.19 (unstable). In this case, switch the AppVM or TemplateVM to the kernel 3.18.
*Note*: If you have doubts about a set of tool or package you want to install, start installing and testing it in an AppVM. You can then reproduce it later in your TemplateVM if you are satisfied. That the (QubesOS?) template philosophy.
*Note*: If you have doubts about a set of tools or package you want to install, start installing and testing it in an AppVM.
You can then reproduce it later in your TemplateVM if you are satisfied.
That is the template philosophy in QubesOS.
For more information on the uses of a minimal template read [this page][Minimal].
Standard tools installation
================
@ -25,28 +28,32 @@ Standard tools installation
Administration (documented)
---------------------------------------------
sudo pciutils vim-minimal less tcpdump telnet psmisc nmap nmap-ncat usbutils
> sudo pciutils vim-minimal less tcpdump telnet psmisc nmap nmap-ncat usbutils
*Notes*: nmap can be used to discover a network (nmap -sP [network]), especially if you are inside a Microsoft network, because your AppVM will be protected/NATted behind Qubes firewall (microsoft / home network are heavily using autodiscovery technologies which require to be in the same local network (no firewall/no NAT), eg: your printer.
*Notes*: nmap can be used to discover hosts on a network (nmap -sP [network]), especially if you are inside a Microsoft network, because your AppVM will be protected/NATted behind the Qubes firewall.
(Microsoft / home networks make heavy use of autodiscovery technologies which require clients to be in the same local network (no firewall/no NAT), eg: your printer.)
Some recommendation here: check your current network using the Network manager applet (eg: 192.168.1.65). Then run nmap in your current AppVM/TemplateVM to search for the selected printer/equipement: nmap -sP 192.168.1.-. Don't forget to allow temporarily the Qubes Firewall if you are inside a TemplateVM.
Some recommendations here: check your current network using the Network manager applet (eg: 192.168.1.65).
Then run nmap in your current AppVM/TemplateVM to search for the selected printer/equipment:
nmap -sP 192.168.1.-.
Don't forget to temporarily allow traffic via the Qubes Firewall if you are doing this in a TemplateVM.
Administration (undocumented)
-------------------------------------------------
openssh keepassx openssl gnome-keyring man
> openssh keepassx openssl gnome-keyring man
Dependency note: keepassx rely on qt which takes ~30MB
Network VM (documented)
----------------------------------------
NetworkManager NetworkManager-wifi network-manager-applet wireless-tools dbus-x11 tar tinyproxy
> NetworkManager NetworkManager-wifi network-manager-applet wireless-tools dbus-x11 tar tinyproxy iptables
Network VM (undocumented)
--------------------------------------------
which dconf dconf-editor
> which dconf dconf-editor
*Notes*: which is required for autostart scripts
@ -55,36 +62,35 @@ which dconf dconf-editor
Network VM (manual operations - documented)
------------------------------------------------------------------------
Search for a wireless firmware matching your wireless card (to be launched in network VM)
Search for wireless firmware matching your wireless card (to be launched in network VM)
> lspci; yum search firmware
> lspci; dnf search firmware
ProxyVM/NetworkVM for 3G Modems
=====================
--------------------------------------------
ModemManager NetworkManager-wwan usb_modeswitch modem-manager-gui
> ModemManager NetworkManager-wwan usb_modeswitch modem-manager-gui
Dependency note: modem-manager-gui rely on webkit-gtk and is optional (NetworkManager can handle the modem alone)
Dependency note: modem-manager-gui relies on webkit-gtk and is optional (NetworkManager can handle the modem alone)
Source: [3GMODEM]
ProxyVM for VPNs
==========
--------------------------------------------
Search for a VPN package for your particular vpn solution
Search for a VPN package for your particular vpn solution then [configure][VPNNM] NetworkManager
> yum search NetworkManager [openconnect|openswat|...]
> dnf search NetworkManager [openvpn\|openconnect\|openswat\|...]
OR
For manual handling of VPN (and because NetworkManager is not available in proxyVMs, check the Qubes-users mail threads on google group
Refer to [this guide][VPN] which includes instructions for failsafe anti-leak VPN configuration using CLI scripts. (An early discussion about OpenVPN configuration can be viewed [here][OPENVPNSETUP].) Required packages will be `iptables` in addition to VPN software such as `openvpn`.
(cprise started a good one on openvpn: [OPENVPNSETUP] "[qubes-users] OpenVPN Setup, Revisited Again!")
Printer Setup
========
--------------------------------------------
system-config-printer system-config-printer-applet cups
> system-config-printer system-config-printer-applet cups
Dependency Note: depends on python3 + python3 additional libraries which takes more than 40 M once installed.
@ -95,33 +101,32 @@ Manual operations
- Don't forget to restart your TemplateVM or only the cups service when you installed cups (systemctl start cups)
- First you need to search for your printer. If you don't know its name or IP, search for it using nmap: check your current network using the Network manager applet (eg: 192.168.1.65). Then run nmap in your current AppVM/TemplateVM to search for the selected printer/equipement: nmap -sP 192.168.1.-. Don't forget to allow temporarily the Qubes Firewall if you are inside a TemplateVM.
- First you need to search for your printer. If you don't know its name or IP, search for it using nmap: check your current network using the Network manager applet (eg: 192.168.1.65). Then run nmap in your current AppVM/TemplateVM to search for the selected printer/equipement: nmap -sP 192.168.1.-. Don't forget to temporarily allow traffic via the Qubes Firewall if you are inside a TemplateVM.
- Once you identified your printer, run system-config-printer GUI to install your printer
- You man need to cancel the operation to install more adapted printer drivers (eg: if the driver cannot be found automatically). Use yum search printername to find potential drivers (eg yum search photosmart)
- You may need to cancel the operation to install more adapted printer drivers (eg: if the driver cannot be found automatically). Use dnf search printername to find potential drivers (eg dnf search photosmart)
GUI recommendations
=============
======================
Lightweight packages recommendations
---------------------------------------------------------------
lxterminal dejavu-sans-mono-fonts dejavu-sans-fonts gnome-settings-daemon
> lxterminal dejavu-sans-mono-fonts dejavu-sans-fonts gnome-settings-daemon
*Note*: You need to install sans-mono fonts for the terminal or it will be unreadable (overlapping characters....), while the sans fonts are just to get nicer GUI menus.
*Scite* is a nice notepad that can also highlight scripts with very light dependencies
> scite
scite
*Meld* allows easy comparison of two text files/ two configuration files.
*Meld* allow comparing two text files/ two configuration files easily.
meld
> meld
*Thunar* is a light file manager usually used by xfce
thunar thunar-volman ntfs-3g
> thunar thunar-volman ntfs-3g
Dependency Note: xfce4 dependencies (but still quite light ~1.4M downloads)
@ -130,32 +135,34 @@ Miscellaneous packages
*pycairo* package is needed for file's contextual menu "Send to VM" to function (to actually popup dialog box and enter VM's name where the file will be sent to).
*pinentry-gtk* package is responsible for pop-up dialog window where you enter password for your password protected gpg key. Install this package in machine holding your password protected gpg keys. If you do not use password protected gpg keys, there is no need to install this package.
*pinentry-gtk* package is responsible for pop-up dialog window where you enter password for your password protected gpg key.
Install this package in the qube holding your password protected gpg keys.
If you do not use password protected gpg keys, there is no need to install this package.
GUI themes
-----------------
Managing GUI theme / appearance is often complex because when you do not want to depends on a specific desktop system.
Managing GUI theme / appearance is often complex because when you do not want to depend on a specific desktop system.
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.
The appearance of Windows can only be changed in dom0, however, the appearance of all buttons, menus, icons, widgets are specific to each AppVM.
### Packages
Choose theme packages for each framework. I recommend the following documentation [THEMEPACKAGES]
clearlooks-phenix-gtk2-theme clearlooks-phenix-gtk3-theme
> clearlooks-phenix-gtk2-theme clearlooks-phenix-gtk3-theme
You can search for other themes using yum search theme gtk
You can search for other themes using dnf search theme gtk
You can check your currently installed theme packages (to eventually remove them) using rpm -qa | grep theme
### Tweaking theme and appearance
First you can get an insight of installed Gtk theme and see how it will appears using lxappearance.
First you can get an insight of installed Gtk theme and see how it will appear using lxappearance.
I recommend not applying settings using lxappearance (do not click on apply) because it will create multiple configuration files.
@ -176,12 +183,12 @@ Cleaning the whole dconf settings is also possible by removing the following fil
rm ~/.config/dconf/user
~~~
*Note*: lxappearance only have effect on gtk3 theme so it won't work to change gtk2 themes (used by Firefox, Thunderbird ...).
*Note*: lxappearance only has an effect on gtk3 themes so it won't work to change gtk2 themes (used by Firefox, Thunderbird ...).
However, it is very lightweight and can be used to identify the name and look of themes you are interested in.
Once you have the name, you can apply it using gsetting command line or gconf-editor.
*Note*: if you really want a GUI theme editor, you can install gnome-tweak-tools, but this tool have a lot
of gnome dependencies (~150MB of dependencies). Eventually install it and uninstall it as soon as you changed your theme.
*Note*: if you really want a GUI theme editor, you can install gnome-tweak-tools, but this tool has a lot
of gnome dependencies (~150MB of dependencies). You can install it and uninstall it as soon as you change your theme.
#### Testing notes
@ -189,7 +196,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,21 +258,21 @@ 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:
1. You installed packages of the theme you selected both for Qt, GTK2 and GTK3.
(eg: Adwaita which is the default theme. I did not found another cross framework theme on fedora default packages).
(eg: Adwaita which is the default theme. I have not found another cross framework theme on fedora default packages).
2. You want to use the GTK theme you selected for Qt but there is no qt package.
In this case QGtkStyle will take precedence and convert the style automatically.
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
@ -279,3 +286,9 @@ Two case:
[DCONF2]: https://wiki.gnome.org/Projects/dconf/SystemAdministrators
[UNIFORMTHEME]: https://wiki.archlinux.org/index.php/Uniform_look_for_Qt_and_GTK_applications
[Minimal]: ../templates/fedora-minimal/
[VPNNM]: ../vpn/#set-up-a-proxyvm-as-a-vpn-gateway-using-networkmanager
[VPN]: ../vpn/#set-up-a-proxyvm-as-a-vpn-gateway-using-iptables-and-cli-scripts

4
customization/kde.md
View File

@ -12,7 +12,7 @@ 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://github.com/QubesOS/qubes-issues/issues/2119). Nonetheless, it is
R3.2, however, [XFCE is the new default desktop environment](/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
@ -40,6 +40,8 @@ You can also change your default login manager (lightdm) to the new KDE default:
* reboot
If you encounter performance issues with KDE, try switching back to LightDM.
Window Management
-----------------

41
customization/language-localization.md
View File

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

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

@ -25,15 +25,14 @@ 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
*Note*: Unselecting windows media, .Net and Internet Explorer will uninstall these components. On a new install they are generally old versions anyway and it will be quicker to install directly the new versions later.
Windows services
---------------------------
Disable the following services that are not required or have no sense in a VM context:
* Base Filtering Engine (only required if your want to use Microsoft IPSEC)
* Base Filtering Engine (only required if you want to use Microsoft IPSEC)
* DHCP Client
* Function Discovery Provider Host
@ -48,14 +47,13 @@ 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.
Windows update
--------------------------
I recommend disabling windows update (Never Check for Update) because checking for updates will start every time you start an AppVM if you don't started your template after some days.
I recommend disabling windows update (Never Check for Update) because checking for updates will start every time you start an AppVM if you haven't started your template in a while.
Running windows update is also apparently IO hungry.
@ -64,10 +62,10 @@ Of course I recommend starting the template regularly and checking manually for
System properties
---------------------------
Right click on computer and go to Properties > Advanced > Performances:
Right click on computer and go to Properties > Advanced > Performance:
* If your don't care about visual effect, in Visual Effect select "Adjust for best performance"
* I personally tweak the page file size to win some place on my root.
* If you don't care about visual effect, in Visual Effect select "Adjust for best performance"
* I personally tweak the page file size to gain some space on my root.
In Advanced>Performances>Advanced tab, change Virtual memory:
@ -77,16 +75,16 @@ Right click on computer and go to Properties > Advanced > Performances:
4. click on set
5. click on drive d:
6. select customer size
7. use an initial size of 500 and a max size of 1000. If the page file is too small, you will notify a low memory pop up when working on windows. In this case, it often means that you should extend your AppVM RAM.
7. use an initial size of 500 and a max size of 1000. If the page file is too small, you will notice a low memory pop up when working on windows. In this case, it often means that you should extend your AppVM RAM.
* System Protection
Here you can disable Shadow Folder because it has little sense in case of Qubes because
Here you can disable Shadow Folder because it has little sense in the case of Qubes because
* we do backup regularly of AppVMs/TemplateVMs;
* we do regular backups of AppVMs/TemplateVMs;
* we can revert at least one template change if we break something.
Select drives where system protection is enabled and click Configure. "Turn of system protection" "Delete all restore points"
Select drives where system protection is enabled and click Configure. "Turn off system protection" "Delete all restore points"
* Remote
@ -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
@ -155,7 +157,7 @@ Manual tasks that can/should be started in the template
> mv root.img.clean root.img
* If don't managed to fill the free space with zeros, you can follow the following *unsafe* undocumented procedure
* If it doesn't manage to fill the free space with zeros, you can follow the following *unsafe* undocumented procedure
1. from dom0, go to /var/lib/templates-vm/yourtemplate
2. check the partitioning to identify the filesystem offset of root.img

6
customization/xfce.md
View File

@ -12,7 +12,11 @@ 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.**
Prior to R3.2, KDE was the default desktop environment in Qubes. Beginning with
R3.2 [XFCE is the new default desktop environment](/doc/releases/3.2/release-notes/) and does not require manual installation.
Installation:

98
debugging/automated-tests.md
View File

@ -7,31 +7,28 @@ redirect_from:
- /doc/AutomatedTests/
---
Automatic tests
Automated 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.
Unit and Integration Tests
--------------------------
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).
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.
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:
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 the [core-admin repository](https://github.com/QubesOS/qubes-core-admin/tree/master/qubes/tests) in the `tests` directory.
To start them you can use standard python unittest runner:
python -m unittest -v qubes.tests
Or our custom one:
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 +70,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
@ -102,25 +99,45 @@ 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:
### Qubes 4.0
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)
Tests on Qubes 4.0 require stopping `qubesd` service first, because special instance of it is started as part of the test run.
Additionally, tests needs to be started as root. The full command to run the tests is:
### 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`
sudo systemctl stop qubesd; sudo -E python3 -m qubes.tests.run -v ; sudo systemctl start qubesd
On Qubes 4.0 tests are also compatible with nose2 test runner, so you can use this instead:
sudo systemctl stop qubesd; sudo -E nose2 -v --plugin nose2.plugins.loader.loadtests qubes.tests; sudo systemctl start qubesd
This may be especially useful together with various nose2 plugins to store tests results (for example `nose2.plugins.junitxml`), to ease presenting results. This is what we use on [OpenQA].
### Tests configuration
Test run can be altered using environment variables:
- `DEFAULT_LVM_POOL` - LVM thin pool to use for tests, in `VolumeGroup/ThinPool` format
- `QUBES_TEST_PCIDEV` - PCI device to be used in PCI passthrough tests (for example sound card)
- `QUBES_TEST_TEMPLATES` - space separated list of templates to run tests on; if not set, all installed templates are tested
- `QUBES_TEST_LOAD_ALL` - load all tests (including tests for all templates) when relevant test modules are imported; this needs to be set for test runners not supporting [load_tests protocol](https://docs.python.org/3/library/unittest.html#load-tests-protocol)
### Adding a new test to core-admin
After adding a new unit test to [core-admin/tests](https://github.com/QubesOS/qubes-core-admin/tree/master/tests) you'll have to make sure of two things:
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
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`.
#### Editing `__init__.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 (
@ -135,4 +152,25 @@ Add at the bottom of the file in the method `def load_tests` to the variable
):
~~~
Installation Tests with openQA
------------------------------
**URL:** <https://openqa.qubes-os.org/>
**Tests:** <https://github.com/marmarek/openqa-tests-qubesos>
Manually testing the installation of Qubes OS is a time-consuming process.
We use [openQA] to automate this process.
It works by installing Qubes in KVM and interacting with it as a user would, including simulating mouse clicks and keyboard presses.
Then, it checks the output to see whether various tests were passed, e.g., by comparing the virtual screen output to screenshots of a successful installation.
Using openQA to automatically test the Qubes installation process works as of Qubes 4.0-rc4 on 2018-01-26, provided that the versions of KVM and QEMU are new enough and the hardware has VT-x and EPT.
KVM also supports nested virtualization, so HVM should theoretically work.
In practice, however, either Xen or QEMU crashes when this is attempted.
Nonetheless, PV works well, which is sufficient for automated installation testing.
Thanks to an anonymous donor, our openQA system is hosted in a datacenter on hardware that meets these requirements.
[unittest]: https://docs.python.org/2/library/unittest.html
[OpenQA]: http://open.qa/

2
debugging/profiling.md
View File

@ -30,7 +30,7 @@ mkdir -p ~/profiling
qvm-run -p qubes-dev 'cat ~/profiling/Upload.sh' > ~/profiling/Upload.sh
~~~
- WARNING: this will obviously be running third party code which is not signed by ITL nor Fedora. You have been warned.
- WARNING: this will obviously be running third-party code which is not signed by ITL nor Fedora. You have been warned.
Workflow
--------

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

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

39
debugging/vm-interface.md
View File

@ -32,7 +32,7 @@ QubesDB
- `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-debug-mode` - flag whether VM has 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)
@ -50,7 +50,7 @@ QubesDB
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` - control entry - dom0 writing `reload` here signals `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
@ -59,7 +59,7 @@ 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.
communicating problems - like a popup.
#### Firewall rules in 4.x ####
@ -80,14 +80,13 @@ update, so VM can setup a watch here to trigger rules reload.
retrieving them). The first rule has number `0000`.
Each rule is a single QubesDB entry, consisting of pairs `key=value` separated
by space. Order of those pairs in a single rule is undefined. QubesDB enforces
a limit on a single entry length - 3072 bytes.
by space. QubesDB enforces limit on a single entry length - 3072 bytes.
Possible options for a single rule:
- `action`, values: `accept`, `drop`; this is present it every rule
- `action`, values: `accept`, `drop`; this is present in every rule
- `dst4`, value: destination IPv4 address with a mask; for example: `192.168.0.0/24`
- `dst6`, value: destination IPv6 address with a mask; for example: `2000::/3`
- `dstname`, value: DNS hostname of destination host
- `dsthost`, value: DNS hostname of destination host
- `proto`, values: `tcp`, `udp`, `icmp`
- `specialtarget`, value: One of predefined target, currently defined values:
- `dns` - such option should match DNS traffic to default DNS server (but
@ -96,20 +95,24 @@ Possible options for a single rule:
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.
Options must appear in the rule in the order listed above. Duplicated options
are forbidden.
If tool applying firewall encounter any parse error (unknown option, invalid
value etc), it should drop all the traffic coming from that `SOURCE_IP`,
A rule matches only when all predicates match. Only one of `dst4`, `dst6` or
`dsthost` can be used in a single rule.
If tool applying firewall encounters any parse error (unknown option, invalid
value, duplicated option, etc), it should drop all the traffic coming from that `SOURCE_IP`,
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=accept specialtarget=dns`
- `action=drop proto=tcp specialtarget=dns` - drop DNS queries sent using TCP
- `action=drop`
### Keys set by VM for passing info to dom0 ###
@ -117,7 +120,7 @@ Example valid rules:
- `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:
- `/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 these entries:
- `desc` - device description (ASCII text)
- `size` - device size in bytes
- `mode` - default connection mode; `r` for read-only, `w` for read-write
@ -130,7 +133,7 @@ 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.SetMonitorLayout` - provide list of monitors, one per 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:
@ -172,10 +175,10 @@ Other Qrexec services installed by default:
- `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
`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
containing selected path, or nothing in the 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
@ -199,7 +202,7 @@ abstraction. This will change in the future. Those tools are:
- `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.
Additionally, automatic tests extensively run various commands directly in VMs. We do not plan to change that.
GUI protocol
------------

2
debugging/windows-debugging.md
View File

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

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