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

Fix conflicts introduced from new changes in master branch

Browse Source
This commit is contained in:
Miguel Jacq 2017-11-01 14:00:00 +11:00
commit 408aef3941
No known key found for this signature in database
GPG Key ID: EEA4341C6D97A0B6
76 changed files with 4053 additions and 762 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
.travis.yml
View File

@ -4,3 +4,9 @@ rvm:
- 2.1
install: git clone https://github.com/${TRAVIS_REPO_SLUG%%/*}/qubesos.github.io ~/qubesos.github.io
script: ~/qubesos.github.io/_utils/travis.sh
addons:
apt:
packages:
- hunspell
- pandoc
- jq

177
_dev/Makefile Normal file
View File

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

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

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

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

193
_dev/conf.py Normal file
View File

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

15
_dev/index.rst Normal file
View File

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

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

@ -0,0 +1,54 @@
---
layout: default
title: Code of Conduct
permalink: /code-of-conduct/
---
## 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](http://citizencodeofconduct.org/)
- 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](https://www.qubes-os.org/mailing-lists/#discussion-list-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
This Code of Conduct is adapted from the [Contributor Covenant, version 1.4](http://contributor-covenant.org/version/1/4) and the [Rust Code of Conduct](https://www.rust-lang.org/en-US/conduct.html).

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-thumbs-o-up"></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>

117
about/join.md Normal file
View File

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

385
about/mailing-lists.md Normal file
View File

@ -0,0 +1,385 @@
---
layout: sidebar
title: Mailing Lists
permalink: /mailing-lists/
redirect_from:
- /doc/mailing-lists/
- /en/doc/mailing-lists/
- /en/doc/qubes-lists/
- /doc/qubes-lists/
- /doc/QubesLists/
- /wiki/QubesLists/
---
Qubes Mailing Lists
===================
Discussion list guidelines
--------------------------
Qubes discussions 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.
### Specific rules and notes ###
* Send your message to the correct list. Read the sections below to determine
which list is correct for your message.
* Do not [top-post].
* Include a precise and informative subject line. This will allow others to
easily find your thread in the future and use it as a reference. (Bad: "Help!
Qubes problems!" Good: "R2B2 Installation problem: Apple keyboard not working
in installer.")
* If your message is not successfully sent to the list, it probably got caught
in the spam filter. We check the spam filter regularly, so please be patient,
and your message should be approved (and your email address added to the
whitelist) within a few days.
* Keep the mailing list CCed throughout the conversation unless there's a
special need for privacy (in which case, use PGP encryption). This increases
the likelihood that a greater quantity of useful information will be
available to everyone in the future.
* Quote appropriately. If you're replying to a thread (whether your own or
someone else's), you should make sure to quote enough from previous messages
in the thread so that people reading your message can understand the context
without having to find and read earlier messages from that thread. Each reply
should continue the conversation and, ideally, be readable as a conversation
in itself. Do not quote advertisements in signatures or inline PGP signature
blocks. (Quoting the latter interferes with the ability of programs like
Enigmail to properly quote replies thereafter).
* If you do not speak English, you should feel free to post in your own
language. However, bear in mind that most members of the list can only read
English. You may wish to include an automated translation in your message out
of consideration for those readers. If you choose to write in English, please
do not apologize for doing so poorly, as it is unnecessary. We understand and
will ask for clarification if needed.
* While we're generally open to hearing suggestions for new features, please
note that we already have a pretty well defined [roadmap], and it's rather
unlikely that we will change our schedule in order to accommodate your
request. If there's a particular feature you'd like to see in Qubes, a much
more effective way to make it happen is to contribute a patch that implements
it. We happily accept such contributions, provided they meet our standards.
Please note, however, that it's always a good idea to field a discussion of
your idea on the `qubes-devel` list before putting in a lot of hard work on
something that we may not be able or willing to accept.
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.
#### Gmane
The mailing list is also available via Gmane, a service that provides mailing
lists in the form of newsgroups. This makes it possible for you to subscribe
and read all mails sent to the list without having them all sent to your normal
mail account. To use Gmane, you need a newsreader such as Mozilla Thunderbird.
To add Gmane's server to Thunderbird, follow the instructions in
[Mozilla Thunderbird's documentation for how to add
newsgroups][thunderbird-newsgroup].
In the fourth step replace `news.mozilla.org` with `news.gmane.org`.
* To subscribe to the list, click on **Subscribe...** and search for the
newsgroup [`gmane.os.qubes.user`]. Click on the checkbox besides the name
and **OK**.
* You send and reply to mails the same way you would normally.
* To unsubscribe from the list, click on **Subscribe...**
search for the newsgroup [`gmane.os.qubes.user`], uncheck the checkbox, and
click on **OK**. Thunderbird will automatically remove the newsgroup.
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-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.
#### Gmane
The mailing list is also available via Gmane, a service that provides mailing
lists in the form of newsgroups. This makes it possible for you to subscribe
and read all mails sent to the list without having them all sent to your normal
mail account. To use Gmane, you need a newsreader such as Mozilla Thunderbird.
To add Gmane's server to Thunderbird, follow the instructions in
[Mozilla Thunderbird's documentation for how to add
newsgroups][thunderbird-newsgroup].
In the fourth step replace `news.mozilla.org` with `news.gmane.org`.
* To subscribe to the list, click on **Subscribe...** and search for the
newsgroup [`gmane.os.qubes.devel`]. Click on the checkbox besides the name
and **OK**.
* You send and reply to mails the same way you would normally.
* To unsubscribe from the list, click on **Subscribe...**
search for the newsgroup [`gmane.os.qubes.devel`], uncheck the checkbox, and
click on **OK**. Thunderbird will automatically remove the newsgroup.
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 Mozilla Thunderbird.
To add Gmane's server to Thunderbird, follow the instructions in
[Mozilla Thunderbird's documentation for how to add
newsgroups][thunderbird-newsgroup].
In the fourth step replace `news.mozilla.org` with `news.gmane.org`.
* To subscribe to the list, click on **Subscribe...** and search for the
newsgroup [`gmane.os.qubes.project`]. Click on the checkbox besides the name
and **OK**.
* You send and reply to mails the same way you would normally.
* To unsubscribe from the list, click on **Subscribe...**
search for the newsgroup [`gmane.os.qubes.project`], uncheck the checkbox, and
click on **OK**. Thunderbird will automatically remove the newsgroup.
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.
[qsb]: /security/bulletins/
[qubes-announce-web]: https://groups.google.com/group/qubes-announce
[top-post]: https://en.wikipedia.org/wiki/Posting_style
[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]: /doc/user-faq/
[documentation]: /doc/
[thunderbird-newsgroup]: https://support.mozilla.org/en-US/kb/creating-newsgroup-account
[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/

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)

19
about/statistics.md Normal file
View File

@ -0,0 +1,19 @@
---
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>
The graph is updated daily.
Raw data is available at
[https://tools.qubes-os.org/counter/stats.json](https://tools.qubes-os.org/counter/stats.json).
Format is not documented and may change any time should the developers feel the
need to include something else. Source code is available at
[https://github.com/woju/qubes-stats](https://github.com/woju/qubes-stats).

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

@ -0,0 +1,79 @@
---
layout: default
title: Video Tours of Qubes OS
permalink: /video-tours/
---
<div id="tour">
<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>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">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>

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:
- [https://www.amazon.com/Definitive-Guide-Xen-Hypervisor/dp/013234971X](https://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:
- [https://www.amazon.com/Linux-Kernel-Development-Robert-Love/dp/0672329468](https://www.amazon.com/Linux-Kernel-Development-Robert-Love/dp/0672329468)
- [https://www.amazon.com/Linux-Device-Drivers-Jonathan-Corbet/dp/0596005903](https://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):
- [https://www.amazon.com/Dynamics-Trusted-Platform-Buildin-Grawrock/dp/1934053082](https://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.)

580
basics_dev/gsoc.md Normal file
View File

@ -0,0 +1,580 @@
---
layout: sidebar
title: Google Summer of Code
permalink: /gsoc/
redirect_from: /GSoC/
---
2017 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.
### 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.
```
### Qubes MIME handlers
**Project**: Qubes MIME handlers
**Brief explanation**: [#441](https://github.com/QubesOS/qubes-issues/issues/441) (including remembering decision whether some file
should be opened in DispVM or locally)
**Expected results**:
- Design mechanism for recognising which files should be opened locally and which in Disposable VM. This mechanism should:
- Respect default action like "by default open files in Disposable VM" (this
may be about files downloaded from the internet, transferred from
other VM etc).
- Allow setting persistent flag for a file that should be opened in specific
way ("locally"); this flag should local to the VM - it shouldn't be possible
to preserve (or even fabricate) the flag while transferring the file from/to
VM.
- See linked ticket for simple ideas.
- Implement generic file handler to apply this mechanism; it should work
regardless of file type, and if file is chosen to be opened locally, normal
(XDG) rules of choosing application should apply.
- Setting/unsetting the flag should be easy - like if once file is chosen to
be opened locally, it should remember that decision.
- Preferably use generic mechanism to integrate it into file managers (XDG
standards). If not possible - integrate with Nautilus and Dolphin.
- Optionally implement the same for Windows.
- Document the mechanism (how the flag is stored, how mechanism is plugged
into file managers etc).
- Write unit tests and integration tests.
**Knowledge prerequisite**:
- XDG standards
- Bash or Python scripting
- Basic knowledge of configuration/extension for file managers
**Mentor**: [Marek Marczykowski-Górecki](/team/)
### 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/)
### 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/)
### IPv6 support
**Project**: IPv6 support
**Brief explanation**: Add support for native IPv6 in Qubes VMs. This should
include IPv6 routing (+NAT...), IPv6-aware firewall, DNS configuration, dealing
with IPv6 being available or not in directly connected network. See
[#718](https://github.com/QubesOS/qubes-issues/issues/718) for more details.
**Expected results**:
- Add IPv6 handling to network configuration scripts in VMs
- Add support for IPv6 in Qubes firewall (including CLI/GUI tools to configure it)
- Design and implement simple mechanism to propagate information about IPv6
being available at all (if necessary). This should be aware of ProxyVMs
potentially adding/removing IPv6 support - like VPN, Tor etc.
- Add unit tests and integration tests for both configuration scripts and UI
enhancements.
- Update documentation.
**Knowledge prerequisite**:
- network protocols, especially IPv6, TCP, DNS, DHCPv6, ICMPv6 (including
autoconfiguration)
- ip(6)tables, nftables, NAT
- Python and Bash scripting
- network configuration on Linux: ip tool, configuration files on Debian and
Fedora, NetworkManager
**Mentor**: [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**: [Jean-Philippe Ouellet](mailto:jpo@vt.edu)
### 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**: [Jean-Philippe Ouellet](mailto:jpo@vt.edu)
### GUI improvements
**Project**: GUI improvements
**Brief explanation**:
* GUI for enabling USB keyboard: [#2329](https://github.com/QubesOS/qubes-issues/issues/2329)
* GUI for enabling USB passthrough: [#2328](https://github.com/QubesOS/qubes-issues/issues/2328)
* GUI interface for /etc/qubes/guid.conf: [#2304](https://github.com/QubesOS/qubes-issues/issues/2304)
* Improving inter-VM file copy / move UX master ticket: [#1839](https://github.com/QubesOS/qubes-issues/issues/1839)
* and comprehensive list of GUI issues: [#1117](https://github.com/QubesOS/qubes-issues/issues/1117)
**Expected results**:
- Add/enhance GUI tools to configure/do things mentioned in description above.
Reasonable subset of those things is acceptable.
- Write tests for added elements.
**Knowledge prerequisite**:
- Python, PyGTK
**Mentor**: [Jean-Philippe Ouellet](mailto:jpo@vt.edu)
### 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-gw-firewall to nftables
- port whonix-ws-firewall to nftables
- make connections to IPv6 Tor relays work
- make connections to IPv6 destinations work
**Knowledge prerequisite**:
**Mentor**: [Patrick Schleizer](/team/)
### Standalone connection wizard for Tor pluggable transports
**Project**: Standalone connection wizard for Tor pluggable transports
**Brief explanation**: [#1938](https://github.com/QubesOS/qubes-issues/issues/1938), https://www.whonix.org/blog/connection-bridge-wizard, https://github.com/Whonix/anon-connection-wizard
**Expected results**:
Users are presented with a GUI where they can select different bridges to use to connect to Tor if it is censored in their country/region, just like with the Tor Browser.
**Knowledge prerequisite**:
**Mentor**: [Patrick Schleizer](/team/)
### Leverage modern static & dynamic analysis
**Project**: Leverage modern static & dynamic analysis
**Brief explanation**:
**Expected results**: Stand up tooling to automatically run various tools against the Qubes code base, and address as many found issues as possible.
**Knowledge prerequisite**: Familiarity with various analysis tools & techniques, including but not limited to: valgrind, coverity, clang's sanitizers, guided fuzzing.
**Mentor**: [Jean-Philippe Ouellet](mailto:jpo@vt.edu)
### Formally analyze how untrusted inputs propagate through the Qubes code base
**Project**: Formally analyze how untrusted inputs propagate through the Qubes code base
**Brief explanation**: It would be useful to have a rigorous understanding of what code paths are reachable and which state can be affected via input from untrusted domains. Such analysis would likely involve building a model of the system with a combination of taint tracking and static and symbolic analysis.
**Expected results**: A rigorous model of the scope of code paths and state reachable or affectable from other (Xen) domains.
**Knoledge prerequisite**: Frama-C, pytaint, angr, others.
**Mentor**: [Jean-Philippe Ouellet](mailto:jpo@vt.edu)
### 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/)
### Make Anti Evil Maid resistant against shoulder surfing and video surveillance
**Project**: Observing the user during early boot should not be sufficient to defeat the protection offered by Anti Evil Maid.
**Brief explanation**:
1. Implement optional support for time-based one-time-password seed secrets. Instead of verifying a static text or picture (which the attacker can record and replay later on a compromised system), the user would verify an ephemeral six-digit code displayed on another device, e.g. a smartphone running any Google Authenticator compatible code generator app.
2. Implement optional support for storing a passphrase-encrypted LUKS disk decryption key on a secondary AEM device. The attacker would then have to seize this device in order to decrypt the user's data; just recording the passphrase as it is entered would no longer be enough.
**Expected results**: AEM package updates implementing both features, with fallback support in case the user does not have their smartphone or secondary AEM device at hand. Good UX and documentation for enrolling or upgrading users.
**Knowledge prerequisite**:
- Bash scripting
- The AEM threat model
- GRUB2, dracut, systemd, LUKS
**Mentor**: [Rusty Bird](mailto:rustybird@openmailbox.org)
### GNOME support in dom0
**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/)
### 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**:
### 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](https://www.qubes-os.org/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]](https://www.qubes-os.org/doc/qubes-builder/) [[2]](https://www.qubes-os.org/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**:
### 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**:
----
We adapted some of the language here about GSoC from the [KDE GSoC page](https://community.kde.org/GSoC).
[gsoc-qubes]: https://summerofcode.withgoogle.com/organizations/6239659689508864/
[gsoc]: https://summerofcode.withgoogle.com/
[team]: https://www.qubes-os.org/team/
[gsoc-faq]: https://developers.google.com/open-source/gsoc/faq
[contributing]: https://www.qubes-os.org/doc/contributing/#contributing-code
[patches]: https://www.qubes-os.org/doc/source-code/#how-to-send-patches
[code-signing]: https://www.qubes-os.org/doc/code-signing/
[ml-devel]: https://www.qubes-os.org/mailing-lists/#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]: https://www.qubes-os.org/mailing-lists/
[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]: https://www.qubes-os.org/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 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](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.

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

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

2
basics_user/contributing.md
View File

@ -25,6 +25,7 @@ ways in which you can help:
* [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]
@ -75,4 +76,5 @@ be grateful to [receive your patch][patch].
[GitHub issues]: https://github.com/QubesOS/qubes-issues/issues
[qubes-devel]: /mailing-lists/#qubes-devel
[Community-Developed Feature Tracker]: https://www.qubes-os.org/qubes-issues/
[Qubes download mirror]: /downloads/mirrors/

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

@ -0,0 +1,190 @@
---
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>Now that you've installed Qubes, 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.
To open a console window in dom0, either go to Start-\>System Tools-\>Konsole or 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/dom0-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.
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.
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.
However, if the user makes use of an "expose-like" desktop switcher, such as the "Desktop Grid" effect that is enabled by default under KDE (default activation command: Ctrl-F8), then we can safely allow qubes to enter full screen mode, as we have assurance that we can always "preempt" them by hitting the magic key combination (e.g., Ctrl-F8), which will be consumed by the trusted window manager and not passed down to the fullscreen qube.
This means that the qube has no way of effectively "faking" the fullscreen view of the system, as the user can easily identify it as "just another qube."
Theoretically, this could be achieved even with primitive Alt-Tab like switching, which should be available on simpler Window Managers (such as Xfce4, which we also support as an alternative dom0 Desktop Environment), but this might be less obvious to the user.
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]: /doc/user-faq/
[system-doc]: /doc/system-doc/
[devel-faq]: /doc/devel-faq/
[downloads]: /downloads/
[getting started]: /getting-started/

25
basics_user/user-faq.md
View File

@ -44,12 +44,13 @@ Qubes Users' FAQ
* [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)
* [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)
-----------------------------------
* [Which version of Qubes am I running?](#which-version-of-qubes-am-i-running)
* [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)
@ -159,7 +160,7 @@ 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:
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&)
@ -272,14 +273,14 @@ 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.
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?
See [this message](http://groups.google.com/group/qubes-devel/msg/6412170cfbcb4cc5).
### Can I install Qubes in a virtual machine (e.g., on VMWare)?
### 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!)
@ -291,18 +292,22 @@ Open a terminal and run `sudo yum install linux-firmware` in the TemplateVM upon
### 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 starts with explaining what is wrong with using such a setup.
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.
Common Problems
---------------
### 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).
(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?
@ -341,7 +346,7 @@ 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.
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.
@ -464,6 +469,6 @@ Press `F11` twice.
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"
- 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.

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

@ -332,7 +332,7 @@ redirect_from:
* **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*
* Swtich to Domo and open a terminal window.
* 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.

12
building/qubes-builder.md
View File

@ -34,27 +34,27 @@ In order to use it one should use an rpm-based distro, like Fedora :) and should
- debootstrap
- PyYAML
Unusually one can install those packages by just issuing:
Usually one can install those packages by just issuing:
sudo dnf install gpg git createrepo rpm-build make wget rpmdevtools python-sh dialog rpm-sign dpkg-dev debootstrap PyYAML
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:
@ -96,7 +96,7 @@ You can also build selected component separately. Eg. to compile only gui virtua
make gui-daemon
Full list you can get from make help. For advanced use and preparing sources
You can get a full list from make help. For advanced use and preparing sources
for use with [QubesBuilder](/doc/qubes-builder/) take a look at [doc directory
in QubesBuilder](https://github.com/marmarek/qubes-builder/tree/master/doc) or
[QubesBuilderDetails](/doc/qubes-builder-details/) page.

6
common-tasks/dispvm.md
View File

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

7
common-tasks/tips-and-tricks.md
View File

@ -52,3 +52,10 @@ Start the Windows TemplateVM (which has no user data), install/upgrade apps; the
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

26
common-tasks/usb.md
View File

@ -24,6 +24,8 @@ Using and Managing USB Devices
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 with a 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 and since the whole
USB stack is put to work to parse the data presented by the USB device in order
@ -110,7 +112,7 @@ 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
**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 `lsusb` command) or that you have a PS/2 keyboard at hand
@ -325,9 +327,21 @@ passthrough will **expose your target qube** for 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
### Installation of qubes-usb-proxy ###
[installation]: #installation-of-qubes-usb-proxy
To use this feature, you need to install [`qubes-usb-proxy`][qubes-usb-proxy] package in the
templates used for the USB qube and qubes you want to connect USB devices to. Note
you cannot pass through devices from dom0 (in other words: USB VM is required).
`qubes-usb-proxy` should be installed by default in the template VM.
However, if you receive this error: `ERROR: qubes-usb-proxy not installed in the VM`,
you can install the `qubes-usb-proxy` with the package manager in the VM
you want to attach the USB device to.
- Fedora: `sudo dnf install qubes-usb-proxy`
- Debian/Ubuntu: `sudo apt-get install qubes-usb-proxy`
### Usage of qubes-usb-proxy ###
Listing available USB devices:
@ -345,7 +359,9 @@ 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:
@ -364,6 +380,7 @@ This feature is not yet available in Qubes Manager however, if you would like to
[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
[hide-usb]: #how-to-hide-all-usb-controllers-from-dom0
[faq-usbvm]: /doc/user-faq/#i-created-a-usbvm-and-assigned-usb-controllers-to-it-now-the-usbvm-wont-boot
@ -375,3 +392,4 @@ This feature is not yet available in Qubes Manager however, if you would like to
[gsoc-page]: https://summerofcode.withgoogle.com/organizations/6239659689508864/
[YubiKey]: /doc/YubiKey/
[Security Warning about USB Input Devices]: #security-warning-about-usb-input-devices
[qubes-usb-proxy]: https://github.com/QubesOS/qubes-app-linux-usb-proxy

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

@ -4,7 +4,7 @@ title: HTTP Filtering Proxy
permalink: /doc/config/http-filtering-proxy/
---
How to run an HTTP filtering proxy in a FirwallVM
How to run an HTTP filtering proxy in a FirewallVM
=================================================
Introduction

4
configuration/postfix.md
View File

@ -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
@ -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.

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

@ -73,11 +73,11 @@ Done.
### 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.
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. See also additional information and caveats about [resizing the root disk image].
1. Make sure that all the VMs based on this template are shut down (including netvms etc).
2. Sanity check: verify that none of the loop devices 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).
2. Sanity check: verify that none of the loop devices are pointing at this template root.img. Run this in dom0: `sudo losetup -a`
3. Resize root.img file. Run this in dom0: `truncate -s <desired size> <path to root.img>` (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.
@ -126,3 +126,6 @@ zpool online -e poolname ada0
You will see that there is unallocated free space at the end of your primary disk.
You can use standard linux tools like fdisk and mkfs to make this space available.
[resizing the root disk image]: https://www.qubes-os.org/doc/resize-root-disk-image/

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/

376
configuration/salt.md
View File

@ -3,86 +3,96 @@ 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.
### The architecture
### The Salt Architecture
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.
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.
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 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 *pillar* is a data back-end 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.
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 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 *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
#### States
The smallest unit of configuration is a state.
A state is written in yaml and looks like this:
A state is written in YAML and looks like this:
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 over all states running for a minion and can be used
to order the execution of states.
`cmd.run` is the execution module. It decides which action will be executed.
`name: echo 'hello world'` is a parameter for the execution module. It depends on
the module which parameters are accepted.
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 list of [officially available states][salt-doc-states].
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.
* To [execute shell commands][salt-doc-states-cmd].
* For [executing shell commands][salt-doc-states-cmd].
With these three states you can do most of the configuration inside of a vm.
With these three states you can define most of the configuration of a VM.
You also can [order the execution][salt-doc-states-order] of your states:
You can also [order the execution][salt-doc-states-order] of your states:
D:
cmd.run:
@ -104,20 +114,20 @@ You also can [order the execution][salt-doc-states-order] of your states:
- 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.
The official documentation has more details on the
[require][salt-doc-states-req] and [order][salt-doc-states-ord] arguments.
#### State files
#### State Files
When configuring a system you will write one or several state files (`*.sls`) and
put (or symlink) them in the salt main directory `/srv/salt/`.
Each state file contains one multiple states and should describe some unit of
configuration (e.g.: A state file `mail.sls` could setup a vm for mailing).
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
#### Top Files
After you have state several state files, you need something to assign them to a
vm. This is done by `*.top` files ([official documentation][salt-doc-top]).
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:
@ -125,11 +135,11 @@ Their structure looks like this:
- statefile1
- folder2.statefile2
The environment will be in most cases `base`.
The `target_matching_clause` will be used to select your minions (vms).
It can be just the name of a vm or a regular expression.
If you are using a regular expression, you need to give salt a hint you are doing
so:
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).*)$:
@ -137,99 +147,104 @@ so:
- statefile
For each target you can write a list of state files.
Each line is a path to a state file (without the `.sls`) relative to the main
directory. Each `/` is exchanged by a dot, so you can't reference files or
directories with a dot in their name.
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 configuration
### Enabling Top Files and Applying the States
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:
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
$ qubesctl top.enable my-new-vm
To list all enabled tops:
To list all enabled top files:
qubesctl top.enabled
$ qubesctl top.enabled
And to disable one:
qubesctl top.disable my-new-vm
$ qubesctl top.disable my-new-vm
To actually apply the states to dom0 and all vms:
To apply the states to dom0 and all VMs:
qubesctl --all state.highstate
$ qubesctl --all state.highstate
(More information on the command is further down.)
(More information on the `qubesctl` command further down.)
### Templating files
### Template Files
You will sometimes find your self writing repetitive states. To solve this,
there is the ability to template files or states.
This can be done with [jinja][jinja].
Jinja is similar to python and behaves in many cases similar, but there
sometimes are differences (e.g. If you set some variable inside a loop,
the variable outside will not get changed. Unless you use a do statement).
So you should take a look at the [jinja api documentation][jinja-tmp].
How you can use jinja to directly call salt functions and get data about
your system is documented in the [salt documentation][jinja-call-salt-functions].
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, Qubes OS layout
## Salt Configuration, QubesOS layout
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.
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 formula for domains in
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 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
@ -239,75 +254,82 @@ Let's start with a 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.
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 actually apply the state:
To apply the state:
qubesctl state.highstate
$ qubesctl state.highstate
### Example of Configuring a VM's System from Dom0
### 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:
- 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`
As in the example above, it creates a domain and sets its properties.
### qvm.present
### `qvm.prefs`
As in example above, it creates domain and sets its properties.
### 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`. This 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:
@ -321,83 +343,79 @@ domains this way.
- default:
- service5
This enables, disables, or sets to default, the services as in qvm-service.
This enables, disables, or sets to default, services as in `qvm-service`.
### qvm.running
### `qvm.running`
Ensures the domain is running:
Ensures the specified domain is running:
domain is running:
qvm.running:
- name: salt-test4
## qubes pillar module
## The `qubes` Pillar Module
Additional pillar data is available to ease targeting configuration (for
example all the templates). List here may be subject to changes in future
releases.
Additional pillar data is available to ease targeting configurations (for
example all templates).
***Note*** List here may be subject to changes in future releases.
### qubes:type
### `qubes:type`
VM type. Possible values:
- `admin` - administration domain (`dom0`)
- `admin` - Administration domain (`dom0`)
- `template` - Template VM
- `standalone` - Standalone VM
- `app` - template based AppVM
- `app` - Template based AppVM
### qubes:template
### `qubes:template`
Template name on which given VM is based (if any).
Template name on which a given VM is based (if any).
### qubes:netvm
### `qubes:netvm`
VM which provides network to the given VM
## Debugging
The output for each vm is logged in `/var/log/qubes/mgmt-VM_NAME.log`.
If the log does not contain useful information, you can stop `qubesctl` by
pressing `ctrl+z`.
The output for each VM is logged in `/var/log/qubes/mgmt-VM_NAME.log`.
You need to:
1. run `sudo qubesctl --skip-dom0 --target=VM_NAME state.highstate`
2. When your vm is being started (yellow) press Ctrl-Z on qubesctl.
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.
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
$ 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
## Known Pitfalls
### Using fedora-24-minimal
The fedora-24-minimal package is missing the sudo package.
The fedora-24-minimal package is missing the `sudo` package.
You can install it via:
qvm-run -p vmname 'dnf install -y sudo'
$ qvm-run -p -u root fedora-24-minimal-template 'dnf install -y sudo'
The `-p` is will cause the execution to wait until the package is installed.
This is important when using a state with `cmd.run`.
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)
### 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.
E.g.:
The solution is to shut down the updateVM between each install:
{% raw %}
install template and shutdown updatevm:
install template and shutdown updateVM:
cmd.run:
- name: sudo qubes-dom0-update -y fedora-24; qvm-shutdown {{salt.cmd.run(qubes-prefs updatevm) }}
{% endraw %}
- name: sudo qubes-dom0-update -y fedora-24; qvm-shutdown {% raw %}{{ salt.cmd.run(qubes-prefs updateVM) }}{% endraw %}
## Further reading
## Further Reading
* [Salt documentation][salt-doc]
* [Salt states][salt-doc-states] ([files][salt-doc-states-file], [commands][salt-doc-states-cmd],
@ -405,7 +423,7 @@ E.g.:
* [Top files][salt-doc-top]
* [Jinja templates][jinja]
* [Qubes specific modules][salt-qvm-doc]
* [Formula for default Qubes VMs][salt-virtual-machines-doc] ([and actual states][salt-virtual-machines-states])
* [Formulas for default Qubes VMs][salt-virtual-machines-doc] ([and actual states][salt-virtual-machines-states])
[salt-doc]: https://docs.saltstack.com/en/latest/
[salt-qvm-doc]: https://github.com/QubesOS/qubes-mgmt-salt-dom0-qvm/blob/master/README.rst

7
customization/dispvm-customization.md
View File

@ -21,8 +21,9 @@ In order to regenerate the Disposable VM "snapshot" (called 'savefile' on Qubes)
[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):
@ -77,7 +78,7 @@ For added convenience, arbitrary programs can be added to the Application Menu o
[Desktop Entry]
Version=1.0
Type=Application
Exec=sh -c 'echo arbitrary | /usr/lib/qubes/qfile-daemon-dvm qubes.VMShell dom0 DEFAULT red
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

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](https://www.qubes-os.org/doc/releases/3.2/release-notes/) and does not require manual installation.
Installation:

1
debugging/vm-interface.md
View File

@ -96,6 +96,7 @@ 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.

13
doc.md
View File

@ -40,14 +40,13 @@ Security Information
Choosing Your Hardware
----------------------
* [System Requirements](/doc/system-requirements/)
* [Certified Hardware](/doc/certified-hardware/)
* [Hardware Compatibility List (HCL)](/hcl/)
* [Qubes-Certified Laptops](/doc/certified-laptops/)
* [Hardware Certification](/hardware-certification/)
Installing & Upgrading Qubes
----------------------------
* [Qubes Downloads](/downloads/)
* [Qubes Download Mirrors](/downloads/mirrors/)
* [Installation Guide](/doc/installation-guide/)
* [Upgrade Guides](/doc/upgrade/)
* [Why and How to Verify Signatures](/security/verifying-signatures/)
@ -91,6 +90,7 @@ Managing Operating Systems within Qubes
* [Windows: Advanced options and troubleshooting of Qubes Tools for Windows (R3)](/doc/windows-tools-3/)
* [Windows: Advanced options and troubleshooting of Qubes Tools for Windows (R2)](/doc/windows-tools-2/)
* [Windows: Uninstalling Qubes Tools for Windows 2.x](/doc/uninstalling-windows-tools-2/)
* [Fedora: Upgrading the Fedora 24 Template to Fedora 25](/doc/template/fedora/upgrade-24-to-25/)
* [Fedora: Upgrading the Fedora 23 Template to Fedora 24](/doc/template/fedora/upgrade-23-to-24/)
* [Fedora: Upgrading the Fedora 21 Template to Fedora 23](/doc/template/fedora/upgrade-21-to-23/)
* [Fedora: Upgrading the Fedora 20 Template to Fedora 21](/doc/template/fedora/upgrade-20-to-21/)
@ -134,6 +134,7 @@ Configuration Guides
* [Multibooting](/doc/multiboot/)
* [Resizing AppVM and HVM Disk Images](/doc/resize-disk-image/)
* [Extending `root.img` Size](/doc/resize-root-disk-image/)
* [RPC Policies](/doc/rpc-policy/)
* [Installing ZFS in Qubes](/doc/zfs/)
* [Mutt Guide](/doc/mutt/)
* [Postfix Guide](/doc/postfix/)
@ -178,6 +179,7 @@ Troubleshooting
* [Troubleshooting UEFI related problems](/doc/uefi-troubleshooting/)
* [Fixing wireless on suspend & resume](/doc/wireless-troubleshooting/)
* [How to remove VMs manually](/doc/remove-vm-manually/)
* [Intel Integrated Graphics Troubleshooting](/doc/intel-igfx-troubleshooting/)
Reference Pages
@ -194,6 +196,7 @@ Presentation Slides
* [[PDF] LinuxCon 2014 -- Qubes OS R2 Tutorial](/attachment/wiki/slides/LinuxCon_2014_Qubes_Tutorial.pdf)
* [[PDF] LinuxCon 2014 -- Qubes OS Keynote](/attachment/wiki/slides/LinuxCon_2014_Qubes_Keynote.pdf)
* [[PDF] RMLL 2016 -- Improving client systems security with Qubes OS](/attachment/wiki/slides/RMLL_2016_Improving-client-systems-security.pdf)
* [[PDF] Golem and Friends 2017 -- Towards Reasonably Secure Computing in the Decentralized World](/attachment/wiki/slides/Secure_Computing_in_Decentralized_World.pdf)
Developer Documentation
=======================
@ -233,6 +236,8 @@ System
* [Qubes OS Architecture Overview](/doc/architecture/)
* [Qubes OS Architecture Spec v0.3 [PDF]](/attachment/wiki/QubesArchitecture/arch-spec-0.3.pdf)
* [Security-critical elements of Qubes OS](/doc/security-critical-code/)
* [Qubes Core Admin](https://dev.qubes-os.org/projects/core-admin/en/latest/)
* [Qubes Core Admin Client](https://dev.qubes-os.org/projects/core-admin-client/en/latest/)
* [Qrexec: command execution in VMs](/doc/qrexec3/)
* [Qubes GUI virtualization protocol](/doc/gui/)
* [Networking in Qubes](/doc/networking/)
@ -278,4 +283,6 @@ Releases
* [Qubes R3.1 release schedule](/doc/releases/3.1/schedule/)
* [Qubes R3.2 release notes](/doc/releases/3.2/release-notes/)
* [Qubes R3.2 release schedule](/doc/releases/3.2/schedule/)
* [Qubes R4.0 release notes](/doc/releases/4.0/release-notes/)
* [Qubes R4.0 release schedule](/doc/releases/4.0/schedule/)

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

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

65
hardware/certified-laptops.md
View File

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

172
hardware/hcl.html Normal file
View File

@ -0,0 +1,172 @@
---
layout: full
title: Hardware Compatibility List (HCL)
permalink: /hcl/
model: all
redirect_from: /compatible-hardware/
---
<div id="hcl">
<div class="row">
<div class="col-lg-3 col-md-3">
<h4>Hardware Type</h4>
<p>
<a href="#hardware-laptops" class="btn btn-primary btn-block" href=""><i class="fa fa-laptop"></i> Laptop Devices</a>
</p>
<p>
<a href="#hardware-desktops" class="btn btn-primary btn-block" href=""><i class="fa fa-desktop"></i> Desktop, Workstation &amp; Servers</a>
</p>
<p>
<a href="#hardware-motherboards" class="btn btn-primary btn-block" href=""><i class="fa fa-server"></i> Motherboards</a>
</p>
<hr>
<p>
<a href="/doc/hcl/#generating-and-submitting-new-reports" class="btn btn-default btn-block" href=""><i class="fa fa-plus"></i> Add Your Device</a>
</p>
<h4>Information</h4>
<ul>
<li><a href="/doc/hcl/">What is the Hardware Compatibility List (HCL)?</a></li>
<li><a href="/doc/hcl/#generating-and-submitting-new-reports">How do I Submit a Report?</a></li>
<li><a href="/doc/system-requirements/">Qubes OS System Requirements</a></li>
<li><a href="/doc/certified-hardware/">Certified Hardware</a></li>
</ul>
</div>
<div class="col-lg-9 col-md-9">
<h4>Marks &amp; Colours</h4>
<table class="table table-bordered">
<tr>
<td width="25%" class="success text-center"><strong>yes</strong><br> feature is working correctly</td>
<td wdith="25%" class="info text-center"><strong>unknown</strong><br>a blank cell indicates we lack information</td>
<td width="25%" class="warning text-center"><strong>partial</strong><br>some tweaking is needed, see remarks for more information</td>
<td width="25%" class="danger text-center"><strong>no</strong><br>does not work or is not present</td>
</tr>
</table>
<h4>List Columns</h4>
<table class="table table-bordered table-responsive">
<tr>
<td><strong>Model</strong></td>
<td>Manufacturer and Devicename (Socket/CPU, Chipset/Southbridge, Graphics)</td>
</tr>
<tr>
<td><strong>BIOS</strong></td>
<td>Reported BIOS version</td>
</tr>
<tr>
<td><a class='ext-link' href='https://en.wikipedia.org/wiki/Hardware_virtual_machine'>HVM</a></td>
<td>
<a class='ext-link' href='https://en.wikipedia.org/wiki/Intel_VT-x#Intel-VT-x'>Intel VT-x</a> or <a class='ext-link' href='https://en.wikipedia.org/wiki/AMD-V#AMD_virtualization_.28AMD-V.29'>AMD-v</a> technology (required for running HVM domains, such as <a class='ext-link' href='/doc/WindowsAppVms/'>Windows-based AppVMs</a>)
</td>
</tr>
<tr>
<td>
<a class='ext-link' href='https://en.wikipedia.org/wiki/IOMMU'>IOMMU</a>
</td>
<td>
Intel VT-d or AMD IOMMU technology (required for effective isolation of network VMs and <a class='ext-link' href='https://wiki.xen.org/wiki/Xen_PCI_Passthrough'>PCI passthrough</a>)
</td>
</tr>
<tr>
<td>
<a class='ext-link' href='https://en.wikipedia.org/wiki/Second_Level_Address_Translation'>SLAT</a>
</td>
<td>
Second Level Address Translation (SLAT): Intel VT-x support for Extended Page Tables (EPT) or AMD-V support for Rapid Virtualization Indexing (RVI).
</td>
</tr>
<tr>
<td><a class='ext-link' href='https://en.wikipedia.org/wiki/Trusted_Platform_Module'>TPM</a></td>
<td>
TPM with proper BIOS support (required for <a class='ext-link' href='/doc/AntiEvilMaid/'>Anti Evil Maid</a>)
</td>
</tr>
<tr>
<td><strong>Qubes</strong></td>
<td>Reported Qubes version (R=Release, rc=release candidate, B=Beta, i.e.: R1, R2B1, R2rc1)</td>
</tr>
<tr>
<td>
<a class='ext-link' href='https://en.wikipedia.org/wiki/Linux_kernel#Maintenance'>Kernel</a>
</td>
<td>
Reported <a class='ext-link' href='https://en.wikipedia.org/wiki/Dom0'>dom0</a> kernel version (numbers in uname -r), can be selected during installation and boot in Troubleshooting menu
</td>
</tr>
<tr>
<td><strong>Remark</strong></td>
<td>Further information field. Qubes, Kernel and this field is coloured in conjunction to reflect general machine compatibility
</td>
</tr>
<tr>
<td><strong>Credit</strong></td>
<td>Name linked to report in <a class='ext-link' href='https://groups.google.com/forum/#!forum/qubes-users'>qubes-users</a></td>
</tr>
</table>
</div>
</div>
<h2 id="hardware-laptops" class="add-left"><i class="fa fa-laptop"></i> Laptop Devices</h2>
<table class="table table-hover table-bordered table-responsive more-bottom" align="center">
<tr>
<th style="width=23%">Model</th>
<th style="width=42px">BIOS</th>
<th style="width=32px">HVM</th>
<th style="width=32px">IOMMU</th>
<th style="width=32px">SLAT</th>
<th style="width=32px">TPM</th>
<th style="width=42px">Qubes</th>
<th style="width=42px">Xen</th>
<th style="width=42px">Kernel</th>
<th>Remark</th>
<th style="width=20%">Credit</th>
</tr>
{% for device in site.hcl %}
{% if device.type == 'laptop' or device.type == 'notebook' %}
{% include hcl-device.html %}
{% endif %}
{% endfor %}
</table>
<h2 id="hardware-desktops" class="add-left"><i class="fa fa-desktop"></i> Desktop, Workstation &amp; Server</h2>
<table class="table table-hover table-bordered table-responsive more-bottom" align="center">
<tr>
<th style="width=23%">Model</th>
<th style="width=42px">BIOS</th>
<th style="width=32px">HVM</th>
<th style="width=32px">IOMMU</th>
<th style="width=32px">SLAT</th>
<th style="width=32px">TPM</th>
<th style="width=42px">Qubes</th>
<th style="width=42px">Xen</th>
<th style="width=42px">Kernel</th>
<th>Remark</th>
<th style="width=20%">Credit</th>
</tr>
{% for device in site.hcl %}
{% if device.type == 'desktop' or device.type == 'workstation' or device.type == 'server' %}
{% include hcl-device.html %}
{% endif %}
{% endfor %}
</table>
<h2 id="hardware-motherboards" class="add-left"><i class="fa fa-server"></i> Motherboards</h2>
<table class="table table-hover table-bordered table-responsive " align="center">
<tr>
<th style="width=23%">Model</th>
<th style="width=42px">BIOS</th>
<th style="width=32px">HVM</th>
<th style="width=32px">IOMMU</th>
<th style="width=32px">SLAT</th>
<th style="width=32px">TPM</th>
<th style="width=42px">Qubes</th>
<th style="width=42px">Xen</th>
<th style="width=42px">Kernel</th>
<th>Remark</th>
<th style="width=20%">Credit</th>
</tr>
{% for device in site.hcl %}
{% if device.type == 'motherboard' %}
{% include hcl-device.html %}
{% endif %}
{% endfor %}
</table>
</div>

68
hardware/system-requirements.md
View File

@ -10,6 +10,14 @@ redirect_from:
# System Requirements #
<div class="alert alert-warning" role="alert">
<i class="fa fa-exclamation-triangle"></i>
<b>Notice:</b>
The system requirements on this page are <em>necessary, but not sufficient,</em> for Qubes compatibility at a minimal or recommended level.
In other words, just because a computer satisfies these requirements doesn't mean that Qubes will successfully install and run on it.
We strongly recommend consulting the <a href="/hcl/">Hardware Compatibility List</a> to verify that Qubes can install and run on your specific model in the ways you need it to.
</div>
## Qubes Release 3.x ##
### Minimum ###
@ -17,20 +25,16 @@ redirect_from:
* 64-bit Intel or AMD processor (x86\_64 aka x64 aka AMD64)
* 4 GB RAM
* 32 GB disk space
* Legacy boot mode (required for R3.0 and earlier; UEFI is supported beginning
with R3.1)
* Legacy boot mode (required for R3.0 and earlier; UEFI is supported beginning with R3.1)
### Recommended ###
* Fast SSD (strongly recommended)
* Intel IGP (strongly preferred)
* Nvidia GPUs may require significant [troubleshooting][nvidia].
* ATI GPUs have not been formally tested (but see the [Hardware Compatibility
List]).
* [Intel VT-x] or [AMD-V] (required for running HVM domains, such as
Windows-based AppVMs)
* [Intel VT-d] or [AMD-Vi (aka AMD IOMMU)] (required for effective isolation of
network VMs)
* ATI GPUs have not been formally tested (but see the [Hardware Compatibility List]).
* [Intel VT-x] or [AMD-V] (required for running HVM domains, such as Windows-based AppVMs)
* [Intel VT-d] or [AMD-Vi (aka AMD IOMMU)] (required for effective isolation of network VMs)
* TPM with proper BIOS support (required for [Anti Evil Maid])
## Qubes Release 4.x ##
@ -48,45 +52,30 @@ redirect_from:
* Fast SSD (strongly recommended)
* Intel IGP (strongly preferred)
* Nvidia GPUs may require significant [troubleshooting][nvidia].
* ATI GPUs have not been formally tested (but see the [Hardware Compatibility
List]).
* ATI GPUs have not been formally tested (but see the [Hardware Compatibility List]).
* TPM with proper BIOS support (required for [Anti Evil Maid])
* A non-USB keyboard or multiple USB controllers
* Also consider the [hardware certification requirements for Qubes 4.x].
## Choosing Hardware ##
* Please see the [Hardware Compatibility List] for a compilation of
hardware reports generated and submitted by users across various Qubes
versions. (For more information about the HCL itself, see [here][hcl-doc]).
* For more certain hardware compatibility, you may wish to consider a
[Qubes-certified laptop]. (For information about how a computer becomes
Qubes-certified, see [Hardware Certification].)
* Please see the [Hardware Compatibility List] for a compilation of hardware reports generated and submitted by users across various Qubes versions.
(For more information about the HCL itself, see [here][hcl-doc].)
* See the [Certified Hardware] page.
## Important Notes ##
* Qubes **can** be installed on systems which do not meet the recommended
requirements. Such systems will still offer significant security
improvements over traditional operating systems, since things like GUI
isolation and kernel protection do not require special hardware.
* Qubes **can** be installed on a USB flash drive or external disk, and testing
has shown that this works very well. A fast USB 3.0 flash drive is
recommended for this. (As a reminder, its capacity must be at least 32 GB.)
Simply plug the flash drive into the computer before booting into the Qubes
installer from a separate installation medium, choose the flash drive as the
target installation disk, and proceed with the installation normally. After
Qubes has been installed on the flash drive, it can then be plugged into
other computers in order to boot into Qubes. In addition to the convenience
of having a portable copy of Qubes, this allows users to test for hardware
compatibility on multiple machines (e.g., at a brick-and-mortar computer
store) before deciding on which computer to purchase. (See [hcl-report] for
advice on hardware compatibility testing.) Keep in mind to also change
assigned devices for your netvm and usbvm, if you move between different
machines.
* There is also a [live USB] option available, which may be even easier for
testing.
* Installing Qubes in a virtual machine is not recommended, as it uses its own
bare-metal hypervisor (Xen).
* Qubes **can** be installed on systems which do not meet the recommended requirements.
Such systems will still offer significant security improvements over traditional operating systems, since things like GUI isolation and kernel protection do not require special hardware.
* Qubes **can** be installed on a USB flash drive or external disk, and testing has shown that this works very well. A fast USB 3.0 flash drive is recommended for this.
(As a reminder, its capacity must be at least 32 GB.)
Simply plug the flash drive into the computer before booting into the Qubes installer from a separate installation medium, choose the flash drive as the target installation disk, and proceed with the installation normally.
After Qubes has been installed on the flash drive, it can then be plugged into other computers in order to boot into Qubes.
In addition to the convenience of having a portable copy of Qubes, this allows users to test for hardware compatibility on multiple machines (e.g., at a brick-and-mortar computer
store) before deciding on which computer to purchase.
(See [hcl-report] for advice on hardware compatibility testing.)
Remember to change the devices assigned to your NetVM and USBVM if you move between different machines.
* Installing Qubes in a virtual machine is not recommended, as it uses its own bare-metal hypervisor (Xen).
* Macintosh PCs are not currently supported due to keyboard and mouse problems.
(See [#230] for details. Patches welcome!)
* [Advice on finding a VT-d capable notebook][vt-d-notebook].
@ -94,12 +83,11 @@ redirect_from:
[nvidia]: /doc/install-nvidia-driver/
[hardware certification requirements for Qubes 4.x]: /news/2016/07/21/new-hw-certification-for-q4/
[Hardware Certification]: /hardware-certification/
[Certified Hardware]: /doc/certified-hardware/
[Hardware Compatibility List]: /hcl/
[hcl-doc]: /doc/hcl/
[hcl-report]: /doc/hcl/#generating-and-submitting-new-reports
[Anti Evil Maid]: /doc/anti-evil-maid/
[Qubes-certified laptop]: /doc/certified-laptops/
[live USB]: /doc/live-usb/
[#230]: https://github.com/QubesOS/qubes-issues/issues/230
[vt-d-notebook]: https://groups.google.com/d/msg/qubes-users/Sz0Nuhi4N0o/ZtpJdoc0OY8J

16
installing/installation-guide.md
View File

@ -19,6 +19,16 @@ redirect_from:
Installation Guide
==================
Warning
-------
There is a set of known upstream bugs in the Fedora installer that affect Qubes 3.2 ([Bug 1170803], [Bug 1374983], and [Bug 1268700]; tracked in Qubes issue [#2835]).
This issue is fixed in Qubes 4.0.
On Qubes 3.2, because of these bugs, the installer will try to access all existing disk partitions, run fsck on them, and mount them.
Therefore, we *strongly* recommended that, prior to starting the Qubes installer, you physically disconnect all disks that you do not want to be modified.
Furthermore, if you are installing Qubes on a potentially compromised system, we *strongly* recommended that you wipe your target installation disk before starting the installer.
Hardware Requirements
---------------------
@ -55,7 +65,7 @@ an installation medium.)
If you prefer to use a USB drive, then you just need to copy the ISO onto the
USB device, e.g. using `dd`:
dd if=Qubes-R3-x86_64.iso of=/dev/sdX
dd if=Qubes-R3-x86_64.iso of=/dev/sdX bs=1M
Change `Qubes-R3-x86_64.iso` to the filename of the version you're installing,
and change `/dev/sdX` to the correct target device (e.g., `/dev/sda`).
@ -117,6 +127,10 @@ Getting Help
questions to the appropriate mailing list.
[Bug 1170803]: https://bugzilla.redhat.com/show_bug.cgi?id=1170803
[Bug 1374983]: https://bugzilla.redhat.com/show_bug.cgi?id=1374983
[Bug 1268700]: https://bugzilla.redhat.com/show_bug.cgi?id=1268700
[#2835]: https://github.com/QubesOS/qubes-issues/issues/2835
[system requirements]: /doc/system-requirements/
[Hardware Compatibility List]: /hcl/
[live USB]: /doc/live-usb/

9
installing/supported-versions.md
View File

@ -21,7 +21,8 @@ past minor releases, are available from our [download mirrors].
| Release 3.0 | 2015-10-01 | 2016-09-09 | Old, unsupported |
| Release 3.1 | 2016-03-09 | 2017-03-29 | Old, unsupported |
| Release 3.2 | 2016-09-29 | TBA | Current, [extended support] |
| Release 4.0 | TBA | TBA | In development |
| Release 3.2.1 | TBA | TBA | In development |
| Release 4.0 | TBA | TBA | In development (prerelease) |
Dom0
@ -35,7 +36,8 @@ The table below shows the OS used for dom0 in each Qubes OS release.
| Release 3.0 | Fedora 20 |
| Release 3.1 | Fedora 20 |
| Release 3.2 | Fedora 23 |
| Release 4.0 | TBA |
| Release 3.2.1 | Fedora 23 |
| Release 4.0 | Fedora 25 |
**Note:** Dom0 is isolated from domUs. DomUs can access only a few interfaces,
such as Xen, device backends (in the dom0 kernel and in other VMs, such as the
@ -56,7 +58,8 @@ release. Currently, only Fedora and Debian TemplateVMs are officially supported.
| Release 2 | 21 | None |
| Release 3.0 | 21, 22\*, 23 | 7 ("wheezy")\*, 8 ("jessie") |
| Release 3.1 | 21, 22\*, 23 | 7 ("wheezy")\*, 8 ("jessie"), 9 ("stretch")\* |
| Release 3.2 | 23, 24\* | 8 ("jessie"), 9 ("stretch")\* |
| Release 3.2 | 23, 24\*, 25\* | 8 ("jessie"), 9 ("stretch")\* |
| Release 3.2.1 | TBA | TBA |
| Release 4.0 | TBA | TBA |
\* Denotes versions for which we have published the packages but have not done

2
managing-os/hvm.md
View File

@ -50,6 +50,8 @@ qvm-start win7 --cdrom=/dev/cdrom
Next the VM will start booting from the attached CDROM device (which in the example above just happens to be a Windows 7 installation disk). Depending on the OS that is being installed in the VM one might be required to start the VM several times (as is the case with Windows 7 installations), because whenever the installer wants to "reboot the system" it actually shuts down the VM and Qubes won't automatically start it. Several invocations of qvm-start command (as shown above) might be needed.
**Note:** If your Windows installation gets stuck at the glowing Windows logo, you might want to read [Issue 2488](https://github.com/QubesOS/qubes-issues/issues/2488) for a solution.
[![r2b1-win7-installing.png](/attachment/wiki/HvmCreate/r2b1-win7-installing.png)](/attachment/wiki/HvmCreate/r2b1-win7-installing.png)
Using Installation ISOs located in other VMs

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

@ -6,7 +6,7 @@ redirect_from:
- /doc/kali/
---
**General Remainder:**
**General reminder:**
- The installation scripts and provided tools may have bugs, be vulnerable to Man in the Middle (MitM) attacks or other vulnerabilities.
@ -27,15 +27,10 @@ There are multiple ways to create a Kali Linux VM:
2. Clone the Qubes OS Debian image and turn it into a Kali Linux distribution using [katoolin]. Explained [here](#katoolin).
3. Clone the Qubes OS 'jessie' Debian template, upgrade it to 'stretch'
(Debian 9.0) and turn it into a Kali linux template. Explained
[here](#debian-upgrade).
[here](#templatevm-from-debian).
## Alternative Options to Kali
- [BlackArch][qubes-blackarch]
- [PenTester Framework (PTF)][qubes-ptf]
- [Pentesting][qubes-pentesting]
## Kali Linux HVM <a name="hvm"/>
Kali Linux HVM <a name="hvm"/>
--------------
1. Download the Kali installation DVD
@ -45,11 +40,12 @@ There are multiple ways to create a Kali Linux VM:
qvm-start <hvm-name> --cdrom <vm-name>:/home/user/Downloads/<iso-name>.iso
## Create Debian Based Kali Template <a name="katoolin"/>
Debian based Kali Template with Katoolin <a name="katoolin"/>
----------------------------------------
Katoolin is a script (written in Python) which helps you to install Kali tools.
1. *(Optional)* Install `debian-8` template (if not already installed)
1. (Optional) Install `debian-8` template (if not already installed)
2. Update your `debian-8` template
@ -74,7 +70,7 @@ Katoolin is a script (written in Python) which helps you to install Kali tools.
sudo apt-get dist-upgrade
sudo apt-get autoremove
6. Install Katoolin and add Kali Linux repositories
5. Install Katoolin and add Kali Linux repositories
1. Install Katoolin
@ -127,12 +123,12 @@ Katoolin is a script (written in Python) which helps you to install Kali tools.
What do you want to do ?> ^CShutdown requested...Goodbye...
7. Clean up and update `kali` template
6. Clean up and update `kali` template
sudo apt-get dist-upgrade
sudo apt-get autoremove
8. Shutdown and trim `kali` template
7. Shutdown and trim `kali` template
- Shutdown `kali` template
@ -142,9 +138,9 @@ Katoolin is a script (written in Python) which helps you to install Kali tools.
qvm-trim-template kali
9. Start image
8. Start image
11. Install tools
9. Install tools
1. View Categories
@ -160,15 +156,17 @@ Katoolin is a script (written in Python) which helps you to install Kali tools.
- **Note:** The `all` option does not work for `Information Gathering`, `Web Apps`, `Forensic Tools`, `Reverse Engineering` and `Extra`.
12. Create a AppVMs based on the `kali` template
10. Create a AppVMs based on the `kali` template
- (Optional) Attach necessary devices
## Installing Kali from a Debian template <a name="debian-upgrade"/>
Kali Linux TemplateVM from a Debian template <a name="debian-upgrade"/><a name="templatevm-from-debian"/>
--------------------------------------------
This section will explain how to create your own [Kali] Linux VM as a VM
template. The basic idea is to personalize the template with the tools you need
and then spin up isolated AppVMs based on the template.
This section will explain how to create your own [Kali] Linux TemplateVM based
on a Debian 9.0 (Stretch) TemplateVM. The basic idea is to personalize the
template with all the tools needed, and then spin up isolated AppVMs based on
the template.
This has been tested on Qubes OS 3.2.
@ -176,133 +174,122 @@ The steps can be summarised as:
1. Install Qubes' Debian 8.0 (Jessie) template
2. Upgrade the template to Debian 9.0 (Stretch)
3. Install kali through the ``kali-linux-full`` package
4. Use the template to build appVM so that you can maintain isolation between
3. Install Kali Linux through the ``kali-linux-full`` package
4. Use the template to build AppVM so that you can maintain isolation between
e.g. pentesting jobs
### Get Kali Linux GPG key ###
Steps to build a Kali template
------------------------------
**CAUTION:** Before proceeding, please carefully read [On Digital Signatures and Key Verification][qubes-verifying-signatures].
This website cannot guarantee that any PGP key you download from the Internet is authentic.
Always obtain a trusted key fingerprint via other channels, and always check any key you download against your trusted copy of the fingerprint.
### Get the GPG key
This step is required since by (security) default a TemplateVM do not have a
direct Internet connectivity. Users understanding the risks of enabling such
access can change this configuration in firewall settings for the TemplateVM.
1. You'll need to fetch the Kali GPG key from a dispVM as the template you'll
build won't have direct internet connectivity unless you enable it from the
firewall:
1. Retrive the Kali Linux GPG key using a DispVM.
# in a dispVM
gpg --keyserver hkp://keys.gnupg.net --recv-key 7D8D0BF6
gpg --list-keys --with-fingerprint 7D8D0BF6
gpg --export --armor 7D8D0BF6 > kali.asc
[user@xxxx-dvm ~]$ gpg --keyserver hkp://keys.gnupg.net --recv-key 7D8D0BF6
[user@xxxx-dvm ~]$ gpg --list-keys --with-fingerprint 7D8D0BF6
[user@xxxx-dvm ~]$ gpg --export --armor 7D8D0BF6 > kali-key.asc
2. **DO NOT TURN OFF** the dispVM
2. **DO NOT TURN OFF** the DispVM, the `kali-key.asc` file will be copied to
the Kali Linux template in a further step.
3. Make sure the key ID is the valid one listed on the [Kali website]. Ideally,
verify the fingerprint through other channels as recommended on that link.
3. Make sure the key is the authentic Kali key.
See the [Kali website] for further advice and instructions on verification.
Once you have the key, keep the dispVM on as you'll need to copy the key over
to the Kali template.
### Create a Kali Linux (rolling) template ###
### Customize the template
These instructions will show you how to upgrade a Debian 9 TemplateVM to Kali Linux.
1. Install [the debian-8 template] if not already installed
**Note:** The prompt on each line indicates where each command should be entered
(`@dom0`, `@kali-rolling` or `@xxxx-dvm`).
2. Clone the debian template and start a terminal in it:
1. Ensure the base template is not running.
# in dom0:
qvm-clone debian-8 debian-9
qvm-run -a debian-9 gnome-terminal
[user@dom0 ~]$ qvm-shutdown debian-9
# in the debian-9 template terminal:
# substitute jessie for stretch in
sudo -s
sensible-editor /etc/apt/sources.list
sensible-editor /etc/apt/sources.list.d/qubes-r3.list
apt-get update && apt-get dist-upgrade
# (hat tip: [the Debian wiki])
2. Clone the base template and start a terminal in the new template.
Restart the template when done and make sure you can open a terminal.
[user@dom0 ~]$ qvm-clone debian-9 kali-rolling
[user@dom0 ~]$ qvm-run -a kali-rolling gnome-terminal
3. Prepare the kali template:
3. Copy the Kali GPG key from the DispVM to the new template:
# in dom0:
qvm-shutdown debian-9
qvm-clone debian-9 kali-tpl
qvm-run -a kali-tpl gnome-terminal
[user@xxxx-dvm ~]$ qvm-copy-to-vm kali-rolling kali-key.asc
The DispVM can now be turned off.
3. Add the sources to install Kali linux to the `kali-tpl` template:
4. Add the Kali GPG key to the list of keys trusted to authenticate packages:
# in kali-tpl:
sudo -s
echo 'deb http://http.kali.org/kali kali-rolling main non-free contrib' >> /etc/apt/sources.list
[user@kali-rolling ~]$ /home/user/QubesIncoming/dispXXX/kali-key.asc | sudo apt-key add -
4. Copy the Kali key from the dispVM into the template:
This command should return `OK` on a line by itself.
# in the dispVM:
qvm-copy-to-vm kali-tpl kali.asc
5. Attempt the upgrade process in the new template.
# in kali-tpl:
cat /home/user/QubesIncoming/dispXXX/kali-key.asc | sudo apt-key add -
[user@kali-rolling ~]$ sudo cat <<EOF > /etc/apt/sources.list.d/kali.list
# Kali Linux repository
deb http://http.kali.org/kali kali-rolling main non-free contrib
EOF
[user@kali-rolling ~]$ sudo apt-get update
[user@kali-rolling ~]$ sudo apt-get dist-upgrade
[user@kali-rolling ~]$ sudo apt-get autoremove
6. Shut down and trim the new template.
The last command should return `OK` on a line by itself.
[user@dom0 ~]$ qvm-shutdown kali-rolling
[user@dom0 ~]$ qvm-trim-template kali-rolling
5. Update the system:
7. Ensure a terminal can be opened in the new template.
# in kali-tpl:
sudo -s
apt-get update && apt-get dist-upgrade
[user@dom0 ~]$ qvm-run -a kali-rolling gnome-terminal
6. Shut down the `kali-tpl` template:
# in dom0:
qvm-shutdown kali-tpl
### Install the Kali tools
### Install the Kali tools ###
At this point you should have a working template and you can install the tools you need.
1. [resize the template] if you plan on installing the full Kali distribution. For example to install `kali-linux-full` you must **grow** the size of the VM system from 10Gb to at least 20Gb.
1. [resize the template disk image][qubes-resize-disk-image] if you plan on installing the full Kali distribution. For example to install `kali-linux-full` you must **grow** the size of the VM system from 10GB to at least 20GB.
1. Install Kali linux:
2. Install Kali Linux tools:
# in kali-tpl:
sudo apt-get install kali-linux-full
[user@kali-rolling ~]$ sudo apt-get install kali-linux-full
2. [optional] Customise the template's home directory (e.g. install your licensed copy of Burp Suite Professional)
3. (Optional) Customise the template's home directory (e.g. install your licensed copy of Burp Suite Professional)
### Use the template
### Use the template ###
The template is ready to be used. You can now spin up AppVMs based on the `kali-tpl` template.
The template is ready to be used. You can now spin up AppVMs based on the `kali-rolling` template.
Alternative Options to Kali
===========================
Alternative Options to Kali Linux
---------------------------------
* PenTester Framework: [PTF] ([PTF Qubes OS guide])
* Black Arch with [BA Qubes OS guide])
* [KATOOLIN]
* [PenTester Framework][PTF], with [PTF Qubes OS guide][qubes-ptf]
* BlackArch Linux, with [BA Qubes OS guide][qubes-blackarch]
* [KATOOLIN][katoolin-howto]
* more on the [Penetration Testing page][qubes-pentesting]
Notes
-----
Thanks to the people in [the discussion thread].
Thanks to the people in [the discussion thread](https://github.com/QubesOS/qubes-issues/issues/1981).
[qubes-verifying-signatures]: /security/verifying-signatures/
[qubes-pentesting]: /doc/pentesting/
[qubes-blackarch]: /doc/pentesting/blackarch/
[qubes-ptf]: /doc/pentesting/ptf/
[qubes-pentesting]: /doc/pentesting/
[qubes-template-debian-install]: /doc/templates/debian/#install
[qubes-resize-disk-image]: /doc/resize-disk-image/
[kali-vbox]: https://www.offensive-security.com/kali-linux-vmware-virtualbox-image-download/
[kali]: https://www.kali.org/
[kali website]: https://docs.kali.org/introduction/download-official-kali-linux-images.
[KATOOLIN]: http://www.tecmint.com/install-kali-linux-tools-using-katoolin-on-ubuntu-debian/
[the debian-8 template]: https://www.qubes-os.org/doc/templates/debian/#install
[kali-vbox]: https://www.offensive-security.com/kali-linux-vmware-virtualbox-image-download/
[kali website]: https://docs.kali.org/introduction/download-official-kali-linux-images
[PTF]: https://www.trustedsec.com/may-2015/new-tool-the-pentesters-framework-ptf-released/
[audio CDs]: https://www.reddit.com/r/Nirvana/comments/3hmra1/the_main_character_in_the_tv_show_mr_robot_has_a/
[resize the template]: https://www.qubes-os.org/doc/resize-disk-image/
[the Debian wiki]: https://wiki.debian.org/Qubes#Install_Debian_Templates
[the discussion thread]: https://github.com/QubesOS/qubes-issues/issues/1981
[PTF Qubes OS guide]: https://www.qubes-os.org/doc/pentesting/ptf/
[BA Qubes OS guide]: https://www.qubes-os.org/doc/pentesting/blackarch/
[katoolin]: https://github.com/LionSec/katoolin
[katoolin-howto]: http://www.tecmint.com/install-kali-linux-tools-using-katoolin-on-ubuntu-debian/

10
managing-os/reinstall-template.md
View File

@ -19,10 +19,16 @@ First, copy any files that you wish to keep from the TemplateVM's `/home` and
$ sudo qubes-dom0-update --action=reinstall qubes-template-package-name
Replace `qubes-template-package-name` with the name of the *package* of the
template you wish to reinstall. For example, use `qubes-template-fedora-24` if
you wish to reinstall the `fedora-24` template. Only one template can be
template you wish to reinstall. For example, use `qubes-template-fedora-25` if
you wish to reinstall the `fedora-25` template. Only one template can be
reinstalled at a time.
Note that Qubes may initially refuse to perform the reinstall if the exact revision of
the template package on your system is no longer in the Qubes online repository. In
this case, you can specify `upgrade` as the action instead and the newer version will be
used. The other `dnf` package actions that are now supported in addition to `reinstall`
and `upgrade` are `upgrade-to` and `downgrade`.
**Reminder:** If you're trying to reinstall a template that is not in an enabled
repo, you must enable that repo. For example:

8
managing-os/templates.md
View File

@ -71,7 +71,7 @@ Important Notes
update a template from dom0 (and thereby lose any user modifications in the
existing template), you must first uninstall the existing template from dom0:
$ sudo yum remove qubes-template-fedora-24
$ sudo yum remove qubes-template-fedora-25
* Standalone VMs using Template VMs as a basis can be created easily. These
VMs receive a *copy* of the operating system and do not get automatically
@ -86,10 +86,10 @@ Important Notes
* On XFCE based Dom0, a manual action may be required to remove the "Start Menu"
sub-menu of the removed TemplateVM. For example, to remove a dangling sub-menu
for a removed "fedora-24" template, open a Dom0 Terminal and type:
for a removed "fedora-25" template, open a Dom0 Terminal and type:
$ rm ~/.local/share/applications/fedora-24-*
$ rm ~/.local/share/applications/fedora-25-*
Just make sure there are no other TemplateVMs whose names start with "fedora-24"
Just make sure there are no other TemplateVMs whose names start with "fedora-25"
or else their menu items will be removed too.

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

@ -30,15 +30,15 @@ Install
Templates can be installed with the following command:
Debian 7 (wheezy) - old stable:
Debian 7 (wheezy) - obsolete/archive:
[user@dom0 ~]$ sudo qubes-dom0-update qubes-template-debian-7
Debian 8 (jessie) - stable:
Debian 8 (jessie) - oldstable:
[user@dom0 ~]$ sudo qubes-dom0-update qubes-template-debian-8
Debian 9 (stretch) - testing:
Debian 9 (stretch) - stable:
A prebuilt template is not yet available, but there are two options for
achieving a stretch template:

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

@ -12,8 +12,6 @@ redirect_from:
Upgrading the Debian 8 Template
===============================
Disclaimer: Debian 9 (Stretch) is marked testing for a reason. You may notice stability problems when using it.
Please note that if you installed packages from one of the testing repositories you must make sure that the repository is enabled in `/etc/apt/sources.list.d/qubes-r3.list` before attempting the upgrade. Otherwise, your upgrade will [break](https://github.com/QubesOS/qubes-issues/issues/2418).
Summary: Upgrading a Debian 8 Template to Debian 9
@ -115,10 +113,6 @@ TemplateVM's max size + the actually used space there) free space in dom0.
Additional Information
----------------------
It should be noted that Debian 9 (Stretch) is currently marked testing and
should be treated as such. For projects that need absolute stability, upgrading
may not be the best option.
Debian Stretch packages were first made available in the Qubes R3.1 repositories.
If sound is not working, you may need to enable the Qubes testing repository to get the testing version of qubes-gui-agent. This can be done by editing the /etc/apt/sources.list.d/qubes-r3.list file and uncommenting the Qubes Updates Candidates repo.

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

@ -21,7 +21,7 @@ Installation
The Fedora minimal template can be installed with the following command:
~~~
[user@dom0 ~]$ sudo qubes-dom0-update qubes-template-fedora-24-minimal
[user@dom0 ~]$ sudo qubes-dom0-update qubes-template-fedora-25-minimal
~~~
The download may take a while depending on your connection speed.
@ -32,7 +32,7 @@ Duplication and first steps
It is highly recommended to clone the original template, and make any changes in the clone instead of the original template. The following command clones the template. Replace `your-new-clone` with your desired name.
~~~
[user@dom0 ~]$ qvm-clone fedora-24-minimal your-new-clone
[user@dom0 ~]$ qvm-clone fedora-25-minimal your-new-clone
~~~
You must start the template in order to customize it.

241
managing-os/templates/fedora/upgrade-24-to-25.md Normal file
View File

@ -0,0 +1,241 @@
---
layout: doc
title: Upgrading the Fedora 24 Template to Fedora 25
permalink: /doc/template/fedora/upgrade-24-to-25/
redirect_from:
- /doc/fedora-template-upgrade-24/
- /en/doc/fedora-template-upgrade-24/
- /doc/FedoraTemplateUpgrade24/
- /wiki/FedoraTemplateUpgrade24/
---
Upgrading the Fedora 24 Template
================================
This instruction is about upgrading Fedora 24 to Fedora 25 template. The same
instruction can be used to upgrade Fedora 23 to Fedora 25 - simply start with
cloning fedora-23 instead of fedora-24.
Summary: Upgrading the Standard Fedora 24 Template to Fedora 25
---------------------------------------------------------------
**Note:** The prompt on each line indicates where each command should be entered
(`@dom0` or `@fedora-25`).
[user@dom0 ~]$ qvm-clone fedora-24 fedora-25
[user@dom0 ~]$ truncate -s 5GB /var/tmp/template-upgrade-cache.img
[user@dom0 ~]$ qvm-run -a fedora-25 gnome-terminal
[user@dom0 ~]$ qvm-block -A fedora-25 dom0:/var/tmp/template-upgrade-cache.img
[user@fedora-25 ~]$ sudo mkfs.ext4 /dev/xvdi
[user@fedora-25 ~]$ sudo mount /dev/xvdi /mnt/removable
[user@fedora-25 ~]$ sudo dnf clean all
[user@fedora-25 ~]$ sudo dnf --releasever=25 --setopt=cachedir=/mnt/removable distro-sync
(Shut down TemplateVM by any normal means.)
[user@dom0 ~]$ rm /var/tmp/template-upgrade-cache.img
[user@dom0 ~]$ qvm-trim-template fedora-25
(Optional cleanup: Switch everything over to the new template and delete the old
one. See instructions below for details.)
Detailed: Upgrading the Standard Fedora 24 Template to Fedora 25
----------------------------------------------------------------
These instructions will show you how to upgrade the standard Fedora 24
TemplateVM to Fedora 25. The same general procedure may be used to upgrade any
template based on the standard Fedora 24 template.
**Note:** The command-line prompt on each line indicates where each command
should be entered (`@dom0` or `@fedora-25`).
1. Ensure the existing template is not running.
[user@dom0 ~]$ qvm-shutdown fedora-24
2. Clone the existing template and start a terminal in the new template.
[user@dom0 ~]$ qvm-clone fedora-24 fedora-25
[user@dom0 ~]$ qvm-run -a fedora-25 gnome-terminal
3. Attempt the upgrade process in the new template.
[user@fedora-25 ~]$ sudo dnf clean all
[user@fedora-25 ~]$ sudo dnf --releasever=25 distro-sync
**Note:** `dnf` might ask you to approve importing a new package signing
key. For example, you might see a prompt like this one:
warning: /var/cache/dnf/fedora-d02ca361e1b58501/packages/python2-babel-2.3.4-1.fc25.noarch.rpm: Header V3 RSA/SHA256 Signature, key ID 8fdb19c98: NOKEY
Importing GPG key 0x81B46521:
Userid : "Fedora (25) <fedora-25-primary@fedoraproject.org>"
Fingerprint: C437 DCCD 558A 66A3 7D6F 4372 4089 D8F2 FDB1 9C98
From : /etc/pki/rpm-gpg/RPM-GPG-KEY-fedora-25-x86_64
Is this ok [y/N]:
This key was already checked when it was installed (notice that the "From"
line refers to a location on your local disk), so you can safely say yes to
this prompt.
**Note:** If you encounter no errors, proceed to step 4. If you do encounter
errors, see the next two points first.
* If `dnf` reports that you do not have enough free disk space to proceed
with the upgrade process, create an empty file in dom0 to use as a cache
and attach it to the template as a virtual disk.
[user@dom0 ~]$ truncate -s 5GB /var/tmp/template-upgrade-cache.img
[user@dom0 ~]$ qvm-block -A fedora-25 dom0:/var/tmp/template-upgrade-cache.img
Then reattempt the upgrade process, but this time use the virtual disk
as a cache.
[user@fedora-25 ~]$ sudo mkfs.ext4 /dev/xvdi
[user@fedora-25 ~]$ sudo mount /dev/xvdi /mnt/removable
[user@fedora-25 ~]$ sudo dnf clean all
[user@fedora-25 ~]$ sudo dnf --releasever=25 --setopt=cachedir=/mnt/removable distro-sync
If this attempt is successful, proceed to step 4.
* `dnf` may complain:
At least X MB more space needed on the / filesystem.
In this case, one option is to [resize the TemplateVM's disk
image][resize-disk-image] before reattempting the upgrade process.
(See [Additional Information] below for other options.)
4. Shut down the new TemplateVM (from the command-line or Qubes VM Manager).
[user@dom0 ~]$ qvm-shutdown fedora-25
5. Remove the cache file, if you created one.
[user@dom0 ~]$ rm /var/tmp/template-upgrade-cache.img
6. Trim the new template (see [Compacting the Upgraded Template] for details
and other options).
[user@dom0 ~]$ qvm-trim-template fedora-25
7. (Recommended) Switch everything that was set to the old template to the new
template, e.g.:
1. Make the new template the default template:
Qubes Manager --> Global settings --> Default template
2. Base AppVMs on the new template. In Qubes Manager, for each VM that is
currently based on `fedora-24` that you would like to base on
`fedora-25`, enter its VM settings and change the Template selection:
Qubes Manager --> (Select a VM) --> VM settings --> Template
3. Base the [DispVM] template on the new template.
If you have set the new template as your default template:
[user@dom0 ~]$ qvm-create-default-dvm --default-template
Otherwise:
[user@dom0 ~]$ qvm-create-default-dvm fedora-25
8. (Optional) Remove the old template. (Make sure to type `fedora-24`, not
`fedora-25`.)
[user@dom0 ~]$ sudo dnf remove qubes-template-fedora-24
Summary: Upgrading the Minimal Fedora 24 Template to Fedora 25
--------------------------------------------------------------
**Note:** The prompt on each line indicates where each command should be entered
(`@dom0` or `@fedora-25`).
[user@dom0 ~]$ qvm-clone fedora-24-minimal fedora-25-minimal
[user@dom0 ~]$ qvm-run -a fedora-25-minimal xterm
[user@fedora-25-minimal ~]$ su -
[root@fedora-25-minimal ~]# dnf clean all
[user@fedora-25-minimal ~]# dnf --releasever=25 distro-sync
(Shut down TemplateVM by any normal means.)
[user@dom0 ~]$ qvm-trim-template fedora-25-minimal
(If you encounter insufficient space issues, you may need to use the methods
described for the standard template above.)
Differences Between the Standard and Minimal Upgrade Procedures
---------------------------------------------------------------
The procedure for upgrading the minimal template (or any template based on the
minimal template) is the same as the procedure for the standard template above,
**with the following exceptions**:
1. `gnome-terminal` is not installed by default. Unless you've installed it
(or another terminal emulator), use `xterm`. (Of course, you can also use
`xterm` for the standard template, if you prefer.)
2. `sudo` is not installed by default. Unless you've installed it, use `su` as
demonstrated above. (Of course, you can also use `su` for the standard
template, if you prefer.)
Compacting the Upgraded Template
--------------------------------
Neither `fstrim` nor the `discard` mount option works on the TemplateVM's root
filesystem, so when a file is removed in the template, space is not freed in
dom0. This means that the template will use about twice as much space as is
really necessary after upgrading.
You can use the `qvm-trim-template` tool:
[user@dom0 ~]$ qvm-trim-template fedora-25
Upgrading StandaloneVMs
-----------------------
The procedure for upgrading a StandaloneVM from Fedora 24 to Fedora 25 is the
same as for a TemplateVM, except that `qvm-trim-template` does not work on
StandaloneVMs. Instead, you should run the following command inside the
StandaloneVM in order to compact it:
$ sudo fstrim -v -a
Additional Information
----------------------
As mentioned above, you may encounter the following `dnf` error:
At least X MB more space needed on the / filesystem.
In this case, you have several options:
1. [Increase the TemplateVM's disk image size][resize-disk-image].
This is the solution mentioned in the main instructions above.
2. Delete files in order to free up space. One way to do this is by
uninstalling packages. You may then reinstalling them again after you
finish the upgrade process, if desired). However, you may end up having to
increase the disk image size anyway (see previous option).
3. Increase the `root.img` size with `qvm-grow-root`.
4. Do the upgrade in parts, e.g., by using package groups. (First upgrade
`@core` packages, then the rest.)
5. Do not perform an in-place upgrade. Instead, simply download and install a
new template package, then redo all desired template modifications.
With regard to the last option, here are some useful messages from the
mailing list which also apply to TemplateVM management and migration in
general:
* [Marek](https://groups.google.com/d/msg/qubes-users/mCXkxlACILQ/dS1jbLRP9n8J)
* [Jason M](https://groups.google.com/d/msg/qubes-users/mCXkxlACILQ/5PxDfI-RKAsJ)
[resize-disk-image]: /doc/resize-disk-image/
[Additional Information]: #additional-information
[Compacting the Upgraded Template]: #compacting-the-upgraded-template
[DispVM]: /doc/dispvm/

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

@ -32,7 +32,7 @@ Qubes Windows Tools (QWT for short) contain several components than can be enabl
**In testing VMs only** it's probably a good idea to install a VNC server before installing QWT. If something goes very wrong with the Qubes gui agent, a VNC server should still allow access to the OS.
**NOTE**: Xen PV disk drivers are not installed by default. This is because they seem to cause problems (BSOD). We're working with upstream devs to fix this. *However*, the BSOD seems to only occur after the first boot and everything works fine after that. **Enable the drivers at your own risk** of course, but we welcome reports of success/failure in any case (backup your VM first!). With disk PV drivers absent `qvm-block` will not work for the VM, but you can still use standard Qubes inter-VM file copying mechanisms.
**NOTE**: Xen PV disk drivers are not installed by default. This is because they seem to cause problems (BSOD = Blue Screen Of Death). We're working with upstream devs to fix this. *However*, the BSOD seems to only occur after the first boot and everything works fine after that. **Enable the drivers at your own risk** of course, but we welcome reports of success/failure in any case (backup your VM first!). With disk PV drivers absent `qvm-block` will not work for the VM, but you can still use standard Qubes inter-VM file copying mechanisms.
Xen PV driver components may display a message box asking for reboot during installation -- it's safe to ignore them and defer the reboot.

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

@ -16,9 +16,9 @@ privacy](https://tails.boum.org/contribute/design/MAC_address/#index1h1). Curren
Newer versions of Network Manager have a robust set of options for randomizing MAC addresses, and can handle the entire process across reboots, sleep/wake cycles and different connection states. In particular, versions 1.4.2 and later should be well suited for Qubes.
NM 1.4.2 is currently available from the Debian 9 (testing) repository, and has been tested in Qubes using a Debian template [upgraded to version 9.](https://www.qubes-os.org/doc/debian-template-upgrade-8/)
Network Manager 1.4.2 or later is available from the Fedora 25 repository as well as the Debian 9 repository, which you can install by [upgrading a Debian 8 template to version 9.](https://www.qubes-os.org/doc/debian-template-upgrade-8/)
In the Debian 9 template you intend to use as a NetVM, check that Network Manager version is now at least 1.4.2:
In the Debian 9 or Fedora 25 template you intend to use as a NetVM, check that Network Manager version is now at least 1.4.2:
~~~
$ sudo NetworkManager -V

26
privacy/signal.md
View File

@ -76,6 +76,32 @@ You can now launch the Signal messenger inside its own dedicated AppVM directly
The same steps should work for any Chrome app.
Creating a shortcut in the applications menu for a StandaloneVM
---------------------------------------------------------------
If you want to add to the standalone VM rather than a template, then follow below.
The following part will also assume that the .desktop file has been correctly made.
This can also be used to add a application portable application/script from a tar archive, also this part of the guide is assuming that the StandaloneVM is called `Signal`.
1. First you will need to copy/move the .desktop file: `/home/user/Desktop/chrome-bikioccmkafdpakkkcpdbhpfkkhcmohk-Default.desktop`to the applications folder on the StandaloneVM: `/usr/share/applications/`
[user@Signal ~]$ sudo mv /home/user/Desktop/chrome-bikioccmkafdpakkkcpdbhpfkkhcmohk-Default.desktop /usr/share/applications/
2. Now copy/move over the icon file to make it look all nice and pretty.
[user@Signal ~]$ sudo mv /home/user/Desktop/chrome-bikioccmkafdpakkkcpdbhpfkkhcmohk-Default.desktop /usr/share/icons/hicolor/48x48/apps/
3. Now fire up the `dom0` Terminal Emulator from `Q` Menu -> `Terminal Emulator`. All you need to do now is run the command to sync the app menus `qvm-sync-appmenus` along with the Standalone VM name `Signal`.
[user@dom0 ~]$ qvm-sync-appmenus Signal
4. Now stop the StandaloneVM: `Signal`.
5. With your mouse select the `Q` menu -> `Domain: Signal` -> `Signal: Add more shortcuts`. Select `Signal Private Messenger` from the left `Available` column, move it to the right `Selected` column by clicking the `>` button and then `OK` to apply the changes and close the window.
6. (optional, only on KDE:) Follow the `Q` menu once more, right-click on the new `Signal: Signal Private Messenger` menu item and select `Add to Panel`.
-----
[Signal]: https://whispersystems.org/

17
privacy/whonix.md
View File

@ -23,31 +23,26 @@ by using the gateway as a ProxyVM to route all network traffic through Tor,
while the workstation is used for making AppVMs.
## Getting Started with Whonix
To install Whonix, you must have a working Qubes machine already.
* [Install Whonix in Qubes](/doc/whonix/install/)
* Note: To install Whonix in Qubes, you must already have a working Qubes machine.
* [Installing Whonix in Qubes](/doc/whonix/install/)
* [Updating Whonix in Qubes](/doc/whonix/update/)
## Customizing, Reinstalling, & Uninstalling Whonix
* [Customizing Whonix](/doc/whonix/customize/)
* [Uninstall Whonix from Qubes](/doc/whonix/uninstall/)
* [Uninstalling Whonix from Qubes](/doc/whonix/uninstall/)
*The following links are on Whonix's website and may be technical.*
*The following pages are written by the Whonix developers and are located on their website.*
* [Using Whonix with DisposableVMs](https://www.whonix.org/blog/qubes-whonix-dispvm)
* [Security Advice for after installing Whonix on Qubes](https://www.whonix.org/wiki/Post_Install_Advice)
* [Post-Installation Security Advice](https://www.whonix.org/wiki/Post_Install_Advice)
* [How to set up Tor Bridges in Whonix on Qubes](https://www.whonix.org/wiki/Bridges#How_to_use_bridges_in_Whonix)
* [Using Multiple Whonix-Workstations with Whonix on Qubes](https://www.whonix.org/wiki/Multiple_Whonix-Workstations#Qubes-Whonix)
* [How to use Corridor (a Tor traffic whitelisting gateway) with Whonix](https://www.whonix.org/wiki/Corridor)
## Support for Whonix
*The following links are on Whonix's site.*
*The following pages are written by the Whonix developers and are located on their website.*
* [Whonix Support](https://www.whonix.org/wiki/Support) - General Whonix, Debian, Tor, etc... related issues
* [Whonix Qubes Forum](https://forums.whonix.org/c/qubes) - Whonix specific issues
You can also use [Qubes support](/help/), but not all Qubes users run Whonix.

4
reference/qubes-service.md
View File

@ -12,7 +12,7 @@ Usage documentation is on [qvm-service manual page](/doc/dom0-tools/qvm-service/
Under the hood enabled service in VM is signaled by file in /var/run/qubes-service. This can be used to implement almost enable/disable **per-VM** switch controlled by dom0. Adding support for systemd services is pretty simple:
Create `/etc/systemd/system/<service name>.service.d/30_qubes.conf` file
In the VM, create `/etc/systemd/system/<service name>.service.d/30_qubes.conf` file
containing (you may need to create a directory for this file first):
~~~
@ -20,4 +20,4 @@ containing (you may need to create a directory for this file first):
ConditionPathExists=/var/run/qubes-service/<service name>
~~~
This will cause service to be started only when you enable it with qvm-service for given VM.
This will cause service to be started only when you enable it with qvm-service for this VM.

79
releases/4.0/release-notes.md Normal file
View File

@ -0,0 +1,79 @@
---
layout: doc
title: Qubes R4.0 release notes
permalink: /doc/releases/4.0/release-notes/
---
Qubes R4.0 release notes
========================
New features since 3.2
----------------------
* Core management scripts rewrite with better structure and extensibility, [API documentation][api-doc]
* [Admin API][admin-api] allowing strictly controlled managing from non-dom0
* All `qvm-*` command-line tools rewritten, some options have changed
* Renaming VM directly is prohibited, there is GUI to clone under new name and remove old VM
* [Use HVM by default][hvm-switch] to lower [attack surface on Xen][qsb-24]
* Create USB VM by default
* [Multiple Disposable VMs templates support][dispvm-ticket]
* New [backup format][backup-format] using scrypt key-derivation function
* Non-encrypted backups no longer supported
* [split VM packages][packages-split], for better support minimal, specialized templates
* [Qubes Manager decomposition][manager-ticket] - domains and devices widgets instead of full Qubes Manager; devices widget support also USB
* [More flexible firewall interface][vm-interface] for ease unikernel integration
* Template VMs do not have network interface by default, [qrexec-based updates proxy][qrexec-proxy] is used instead
* More flexible IP addressing for VMs - [custom IP][custom-ip], [hidden from the IP][hide-ip]
* More flexible Qubes RPC policy - [related ticket][qrexec-policy-keywords], [documentation][qrexec-doc]
* [New Qubes RPC confirmation window][qrexec-confirm], including option to specify destination VM
* Dom0 update to Fedora 25 for better hardware support
* Kernel 4.9.x
You can get detailed description in [completed github issues][github-release-notes]
Known issues
------------
* On some laptops (for example Librem 15v2), touchpad do not work directly after installation. Reboot the system to fix the issue.
* List of USB devices may contain device identifiers instead of name
* For other known issues take a look at [our tickets](https://github.com/QubesOS/qubes-issues/issues?q=is%3Aopen+is%3Aissue+milestone%3A%22Release+4.0%22+label%3Abug)
It is advised to install updates just after system installation to apply bug fixes for (some of) the above problems.
Downloads
---------
See [Qubes Downloads](/downloads/).
Installation instructions
-------------------------
See [Installation Guide](/doc/installation-guide/).
Upgrading
---------
There is no in-place upgrade path from earlier Qubes versions. The only
supported option to upgrade to Qubes R4.0 is to install it from scratch and use
[qubes backup and restore tools][backup] for migrating of all of the user VMs.
[backup]: /doc/backup-restore/
[github-release-notes]: https://github.com/QubesOS/qubes-issues/issues?q=is%3Aissue+sort%3Aupdated-desc+milestone%3A%22Release+4.0%22+label%3Arelease-notes+is%3Aclosed
[custom-ip]: https://github.com/QubesOS/qubes-issues/issues/1477
[hide-ip]: https://github.com/QubesOS/qubes-issues/issues/1143
[packages-split]: https://github.com/QubesOS/qubes-issues/issues/2771
[hvm-switch]: https://github.com/QubesOS/qubes-issues/issues/2185
[manager-ticket]: https://github.com/QubesOS/qubes-issues/issues/2132
[dispvm-ticket]: https://github.com/QubesOS/qubes-issues/issues/2253
[qrexec-proxy]: https://github.com/QubesOS/qubes-issues/issues/1854
[qrexec-policy-keywords]: https://github.com/QubesOS/qubes-issues/issues/865
[qrexec-confirm]: https://github.com/QubesOS/qubes-issues/issues/910
[qrexec-doc]: /doc/qrexec3/#extra-keywords-available-in-qubes-40-and-later
[vm-interface]: /doc/vm-interface/
[admin-api]: /news/2017/06/27/qubes-admin-api/
[qsb-24]: https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-024-2016.txt
[backup-format]: /doc/backup-emergency-restore-v4/
[api-doc]: https://dev.qubes-os.org/projects/qubes-core-admin/en/latest/

19
releases/4.0/schedule.md Normal file
View File

@ -0,0 +1,19 @@
---
layout: doc
title: Qubes R4.0 Release Schedule
permalink: /doc/releases/4.0/schedule/
redirect_from:
- /en/doc/releases/4.0/schedule/
---
Qubes R4.0 Release Schedule
===========================
This schedule is based on [Version Scheme](/doc/version-scheme/#release-schedule).
| Date | Stage |
| -----------:| --------------------------------------- |
| 31 Jul 2017 | 4.0-rc1 release |
| <strike>28 Aug 2017</strike><br/><strike>11 Sep 2017</strike><br/><strike>9 Oct 2017</strike><br/>18 Oct 2017 | current-testing freeze before 4.0-rc2 |
| <strike> 4 Sep 2017</strike><br/><strike>18 Sep 2017</strike><br/><strike>16 Oct 2017</strike><br/>23 Oct 2017 | 4.0-rc2 release |
| 6 Nov 2017 | decide whether 4.0-rc2 is the final 4.0 |

2
security-info/canaries.md
View File

@ -32,4 +32,6 @@ Qubes Canaries are published through the [Qubes Security Pack](/security/pack/).
----
- [Qubes Canary \#11](https://github.com/QubesOS/qubes-secpack/blob/master/canaries/canary-011-2017.txt)
- [Qubes Canary \#12](https://github.com/QubesOS/qubes-secpack/blob/master/canaries/canary-012-2017.txt)
- [Qubes Canary \#13](https://github.com/QubesOS/qubes-secpack/blob/master/canaries/canary-013-2017.txt)

5
security-info/security-bulletins-template.md
View File

@ -9,9 +9,10 @@ Security Bulletin Template
==========================
~~~
Dear Qubes community,
Dear Qubes Community,
We have just published Qubes Security Bulletin (QSB) #<number>: <title>.
We have just published Qubes Security Bulletin (QSB) #<number>:
<title>.
The text of this QSB is reproduced below. This QSB and its accompanying
signatures will always be available in the Qubes Security Pack (qubes-secpack).

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

@ -77,4 +77,9 @@ Qubes Security Bulletins are published through the [Qubes Security Pack](/securi
- [Qubes Security Bulletin \#29](https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-029-2017.txt) (Critical Xen bug in PV memory virtualization code (XSA-212))
- [Qubes Security Bulletin \#30](https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-030-2017.txt) (Critical Xen bugs related to PV memory virtualization (XSA-213, XSA-214))
- [Qubes Security Bulletin \#31](https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-031-2017.txt) (Xen hypervisor vulnerabilities with unresearched impact (XSA 216-224))
- [Qubes Security Bulletin \#32](https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-032-2017.txt) (Xen hypervisor and Linux kernel vulnerabilities (XSA-226 through XSA-230))
- [Qubes Security Bulletin \#33](https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-033-2017.txt) (Xen hypervisor (XSA-231 through XSA-234))
- [Qubes Security Bulletin \#34](https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-034-2017.txt) (GUI issue and Xen vulnerabilities (XSA-237 through XSA-244))
- [Qubes Security Bulletin \#34](https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-035-2017.txt) (Xen hypervisor issue related to grant tables (XSA-236))

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

@ -92,10 +92,29 @@ There should also be a copy of this key at the project's main website, in the
Once you have obtained the Qubes Master Signing Key,
you should verify the fingerprint of this key very carefully by obtaining
copies of the fingerprint from trustworthy independent sources and comparing
them to the downloaded key's fingerprint to ensure they match. Then set its
trust level to "ultimate" (oh, well), so that it can be used to automatically
verify all the keys signed by the Qubes Master Signing Key:
copies of the fingerprint from multiple independent sources and comparing
them to the downloaded key's fingerprint to ensure they match. Here are some
ideas:
* Use the PGP Web of Trust.
* Check the key against different keyservers.
* Use different search engines to search for the fingerprint.
* Use Tor to view and search for the fingerprint on various websites.
* Use various VPNs and proxy servers.
* Use different Wi-Fi networks (work, school, internet cafe, etc.).
* Ask people to post the fingerprint in various forums and chat rooms.
* Check against PDFs and photographs in which the fingerprint appears
(e.g., slides from a talk or on a T-shirt).
* Repeat all of the above from different computers and devices.
In addition, some operating systems have built-in keyrings containing keys
capable of validating the Qubes Master Signing Key. For example, if you have
a Debian system, then your debian-keyring may already contain the necessary
keys.
Once you're confident that you have the legitimate Qubes Master Signing Key,
set its trust level to "ultimate" (oh, well), so that it can be used to
automatically verify all the keys signed by the Qubes Master Signing Key:
$ gpg --edit-key 0x36879494

12
security/data-leaks.md
View File

@ -16,9 +16,9 @@ The Role of the Firewall
**[Firewalling in Qubes](/doc/firewall/) is not intended to be a leak-prevention mechanism.**
There are several reasons for this, which will be explained below. However, the main reason is that Qubes cannot prevent an attacker who has compromised one AppVM (with restrictive firewall rules) from leaking data via cooperative covert channels through a different AppVM (with sufficiently nonrestrictive firewall rules, if any) which the attacker has also compromised.
There are several reasons for this, which will be explained below. However, the main reason is that Qubes cannot prevent an attacker who has compromised one AppVM with restrictive firewall rules from leaking data via cooperative covert channels through another compromised AppVM with nonrestrictive firewall rules.
For example, suppose you have an `email` AppVM. You have set the firewall rules for `email` such that it can communicate only with your email server. Now suppose that an attacker sends you a GPG-encrypted message which exploits a hypothetical bug in the GnuPG process. There are now multiple ways the attacker could proceed to leak data (such as confidential email messages) from `email`. The most obvious way is by simply emailing the data to himself. Another possibility is that the attacker has also compromised another one of your AppVMs, such as your `netvm`, which is normally assumed to be untrusted and has unrestricted access to the network. In this case, the attacker might move data from `email` to the `netvm` via a covert channel, such as the CPU cache. Such covert channels through the CPU cache have been described and even implemented in some "lab environments" and might allow for bandwidths of even a few tens of bits/sec. It is unclear whether such channels could be implemented in a real world system, where multiple VMs execute at the same time, each running tens or hundreds of processes, all using the same cache memory, but it is worth keeping in mind. Of course, this would require special malware written specifically to attack Qubes OS, and perhaps even a specific Qubes OS version and perhaps a specific Qubes OS configuration. Nevertheless, it might be possible.
For example, suppose you have an `email` AppVM. You have set the firewall rules for `email` such that it can communicate only with your email server. Now suppose that an attacker sends you a GPG-encrypted message which exploits a hypothetical bug in the GnuPG process. There are now multiple ways the attacker could proceed to leak data (such as confidential email messages) from `email`. The most obvious way is by simply emailing the data to himself. Another possibility is that the attacker has also compromised another one of your AppVMs, such as your `netvm`, which is normally assumed to be untrusted and has unrestricted access to the network. In this case, the attacker might move data from `email` to the `netvm` via a covert channel, such as the CPU cache. Such covert channels have been described and even implemented in some "lab environments" and might allow for bandwidths of even a few tens of bits/sec. It is unclear whether such channels could be implemented in a real world system, where multiple VMs are running at the same time, each handling tens or hundreds of processes, all using the same cache memory, but it is worth keeping in mind. Of course, this would require special malware written specifically to attack Qubes OS, and perhaps even a specific Qubes OS version and/or configuration. Nevertheless, it might be possible.
Note that physically air-gapped machines are not necessarily immune to this problem. Covert channels can potentially take many forms (e.g., sneakernet thumb drive, bluetooth, or even microphone and speakers).
@ -29,12 +29,12 @@ Types of Data Leaks
In order to understand and attempt to prevent data leaks in Qubes, we must distinguish among three different types of relevant data leaks:
1. **Intentional leaks.** Malicious software which actively tries to leak data out of an AppVM, perhaps via cooperative covert channels established with other malicious software in another AppVM (or on some server via networking, if networking, even limited, is allowed for the AppVM).
1. **Intentional leaks.** Malicious software which actively tries to leak data out of an AppVM, perhaps via cooperative covert channels established with other malicious software in another AppVM or on some server via networking, if networking, even limited, is allowed for the AppVM.
1. **Intentional sniffing.** Malicious software trying to use side channels to, e.g., actively guess some key material used in another VM by some non-malicious software there (e.g., non-leak-proof GPG accidentally leaking out bits of the private key by generating some timing patterns when using this key for some crypto operation). Such attacks have been described in the academic literature, but it is doubtful that they would succeed in practice in a moderately busy general purpose system like Qubes OS (where the attacker normally has no way to trigger the target crypto operation explicitly, and it is normally required that the attacker trigger many such operations).
2. **Intentional sniffing.** Malicious software trying to use side channels to, e.g., actively guess some key material used in another VM by some non-malicious software there (e.g., non-leak-proof GPG accidentally leaking out bits of the private key by generating some timing patterns when using this key for some crypto operation). Such attacks have been described in the academic literature, but it is doubtful that they would succeed in practice in a moderately busy general purpose system like Qubes OS where the attacker normally has no way to trigger the target crypto operation explicitly and it is normally required that the attacker trigger many such operations.
1. **Unintentional leaks.** Non-malicious software which is either buggy or doesn't maintain the privacy of user data (whether by design or accident). For example, software which automatically sends error reports to a remote server, where these reports contain details about the system which the user did not want to share.
3. **Unintentional leaks.** Non-malicious software which is either buggy or doesn't maintain the privacy of user data, whether by design or accident. For example, software which automatically sends error reports to a remote server, where these reports contain details about the system which the user did not want to share.
Both Qubes firewall and an empty NetVM (i.e., setting the NetVM of an AppVM to "none") can fully protect against leaks of type 3. However, neither Qubes firewall nor an empty NetVM are guaranteed to protect against leaks of types 1 and 2. It is likely that the only way to fully protect against leaks of type 1 and 2 is to either pause or shut down all other VMs while performing sensitive operations in the target VM(s) (such as key generation).
Both Qubes firewall and an empty NetVM (i.e., setting the NetVM of an AppVM to "none") can fully protect against leaks of type 3. However, neither Qubes firewall nor an empty NetVM are guaranteed to protect against leaks of types 1 and 2. There are few effective, practical policy measures available to end-users today to stop the leaks of type 1. It is likely that the only way to fully protect against leaks of type 2 is to either pause or shut down all other VMs while performing sensitive operations in the target VM(s) (such as key generation).
For further discussion, see [this thread](https://groups.google.com/d/topic/qubes-users/t0cmNfuVduw/discussion).

4
security/firewall.md
View File

@ -3,8 +3,8 @@ layout: doc
title: The Qubes Firewall
permalink: /doc/firewall/
redirect_from:
- /doc/firewall/
- /en/doc/firewall/
- /doc/qubes-firewall/
- /en/doc/qubes-firewall/
- /doc/QubesFirewall/
- /wiki/QubesFirewall/
---

12
security/multifactor-authentication.md
View File

@ -67,24 +67,24 @@ Optional Preparation Steps
[minimal Fedora template][FedoraMinimal]. Get it if you haven't already done
so:
[user@dom0 ~]$ sudo qubes-dom0-update qubes-template-fedora-24-minimal
[user@dom0 ~]$ sudo qubes-dom0-update qubes-template-fedora-25-minimal
2. Since we'll be making some modifications, you may want to clone the minimal
template:
[user@dom0 ~]$ qvm-clone fedora-24-minimal fedora-24-min-mfa
[user@dom0 ~]$ qvm-clone fedora-25-minimal fedora-25-min-mfa
3. Since this is going to be a minimal environment in which we run `oathtool`
from the command line, we'll install only a couple of packages:
[user@fedora-24-min-mfa ~]$ su -
[user@fedora-24-min-mfa ~]# yum install oathtool vim-minimal
[user@fedora-24-min-mfa ~]$ poweroff
[user@fedora-25-min-mfa ~]$ su -
[user@fedora-25-min-mfa ~]# yum install oathtool vim-minimal
[user@fedora-25-min-mfa ~]$ poweroff
4. Create an AppVM and set it to use the TemplateVM we just created:
[user@dom0 ~]$ qvm-create -l black mfa
[user@dom0 ~]$ qvm-prefs -s mfa template fedora-24-min-mfa
[user@dom0 ~]$ qvm-prefs -s mfa template fedora-25-min-mfa
5. Isolate the new AppVM from the network:

30
security/split-bitcoin.md
View File

@ -17,30 +17,26 @@ A "split" bitcoin wallet is a strategy of protecting your bitcoin by having your
A "Watching" Wallet and a "Cold" Wallet
---------------------------------------
1. Create a Debian 8 backports template using the Qubes VM Manager or running
`qvm-clone debian-8 debian-8-backports` in dom0.
1. Create a fedora-25-electrum template using the Qubes VM Manager or running
`qvm-clone fedora-25 fedora-25-electrum` in dom0.
2. Add backports to the sources for the new template by opening a terminal in
the new template, run `sudo vi /etc/apt/sources.list` and add
`deb http://http.debian.net/debian jessie-backports main`.
2. Start the new template:
`qvm-start fedora-25-electrum`
`qvm-run fedora-25-electrum xterm`
(If you are new to `vi` text editing, type `i` to be able to edit, and when
done editing press `ESC` then type `:x` and press `ENTER`.)
3. Install `electrum` to fedora-25-electrum template VM. From fedora-25-electrum terminal enter:
`sudo dnf update`.
`sudo dnf install electrum`.
3. Update source list: `sudo apt-get update`.
4. Shut down your `fedora-25-electrum` template
4. Install `electrum` from backports:
`sudo apt-get -t jessie-backports install electrum`.
5. Create an `offline-bitcoin` qube based on `fedora-25-electrum` using the Qubes VM Manager or running `qvm-create -t fedora-25-electrum -l black offline-bitcoin` and `qvm-prefs -s offline-bitcoin netvm none` in dom0.
5. shut down your `debian-8-backports` template
6. Follow the [electrum documentation in creating an offline wallet](http://docs.electrum.org/en/latest/coldstorage.html#create-an-offline-wallet)
6. create an `offline-bitcoin` qube based on `debian-8-backports` using the Qubes VM Manager or running `qvm-create -t debian-8-backports -l black offline-bitcoin` and `qvm-prefs -s offline-bitcoin netvm none` in dom0.
7. Create a `watching-bitcoin` qubes based on `fedora-25-electrum` connecting to the internet how ever you prefer using the Qubes VM Manager or running for example `qvm-create -t fedora-25-electrum -l green watching-bitcoin` and `qvm-prefs -s watching-bitcoin netvm sys-whonix` in dom0.
7. follow the [electrum documentation in creating an offline wallet](http://docs.electrum.org/en/latest/coldstorage.html#create-an-offline-wallet)
8. create a `watching-bitcoin` qubes based on `debian-8-backports` connecting to the internet how ever you prefer using the Qubes VM Manager or running for example `qvm-create -t debian-8-backports -l green watching-bitcoin` and `qvm-prefs -s watching-bitcoin netvm sys-whonix` in dom0.
9. follow the [electrum documentation in creating an online watching-only wallet](http://docs.electrum.org/en/latest/coldstorage.html#create-a-watching-only-version-of-your-wallet)
8. Follow the [electrum documentation in creating an online watching-only wallet](http://docs.electrum.org/en/latest/coldstorage.html#create-a-watching-only-version-of-your-wallet)
Important Notes
---------------

4
security/split-gpg.md
View File

@ -90,7 +90,7 @@ package installed.
For Fedora.
[user@fedora-24 ~]$ sudo yum install qubes-gpg-split
[user@fedora-25 ~]$ sudo yum install qubes-gpg-split
Start with creating a dedicated AppVM for storing your keys (the GPG backend
domain). It is recommended that this domain be network disconnected (set its
@ -161,7 +161,7 @@ the content of the file `/rw/config/gpg-split-domain`, which should be set to
the name of the GPG backend VM. This file survives the AppVM reboot, of course.
[user@work ~]$ sudo bash
[user@work ~]$ echo "work-gpg" > /rw/config/gpg-split-domain
[root@work ~]$ echo "work-gpg" > /rw/config/gpg-split-domain
A note on passphrases:

12
security/vm-sudo.md
View File

@ -110,9 +110,11 @@ this for extra security.**
(Note: any VMs you would like still to have password-less root access (e.g. TemplateVMs) can be specified in the second file with "\<vmname\> dom0 allow")
2. Configuring Fedora TemplateVM to prompt Dom0 for any authorization request:
- In /etc/pam.d/system-auth, replace all lines beginning with "auth" with one line:
- In /etc/pam.d/system-auth, replace all lines beginning with "auth" with these lines:
auth [success=done default=die] pam_exec.so seteuid /usr/lib/qubes/qrexec-client-vm dom0 qubes.VMAuth /usr/bin/grep -q ^1$
auth [success=1 default=ignore] pam_exec.so seteuid /usr/lib/qubes/qrexec-client-vm dom0 qubes.VMAuth /bin/grep -q ^1$
auth requisite pam_deny.so
auth required pam_permit.so
- Require authentication for sudo. Replace the first line of /etc/sudoers.d/qubes with:
@ -124,9 +126,11 @@ this for extra security.**
[root@fedora-20-x64]# rm /etc/polkit-1/localauthority/50-local.d/qubes-allow-all.pkla
3. Configuring Debian/Whonix TemplateVM to prompt Dom0 for any authorization request:
- In /etc/pam.d/common-auth, replace all lines beginning with "auth" with one line:
- In /etc/pam.d/common-auth, replace all lines beginning with "auth" with these lines:
auth [success=done default=die] pam_exec.so seteuid /usr/lib/qubes/qrexec-client-vm dom0 qubes.VMAuth /bin/grep -q ^1$
auth [success=1 default=ignore] pam_exec.so seteuid /usr/lib/qubes/qrexec-client-vm dom0 qubes.VMAuth /bin/grep -q ^1$
auth requisite pam_deny.so
auth required pam_permit.so
- Require authentication for sudo. Replace the first line of /etc/sudoers.d/qubes with:

321
services/admin-api.md Normal file
View File

@ -0,0 +1,321 @@
---
layout: doc-full
title: Admin API
permalink: /doc/admin-api/
redirect_from:
- /doc/mgmt/
- /doc/mgmt1/
- /doc/mgmt-architecture/
- /doc/admin-api-architecture/
---
# Qubes OS Admin API
*(This page is the current draft of the proposal. It is not implemented yet.)*
## Goals
The goals of the Admin API system is to provide a way for the user to manage
the domains without direct access to dom0.
Foreseen benefits include:
- Ability to remotely manage the Qubes OS.
- Possibility to create multi-user system, where different users are able to use
different sets of domains, possibly overlapping. This would also require to
have separate GUI domain.
The API would be used by:
- Qubes OS Manager (or any tools that would replace it)
- CLI tools, when run from another VM (and possibly also from dom0)
- remote management tools
- any custom tools
## Threat model
TBD
## Components
![Admin API Architecture][admin-api-architecture]
A central entity in the Qubes Admin API system is a `qubesd` daemon, which
holds information about all domains in the system and mediates all actions (like
starting and stopping a qube) with `libvirtd`. The `qubesd` daemon also manages
the `qubes.xml` file, which stores all persistent state information and
dispatches events to extensions. Last but not least, `qubesd` is responsible for
querying the RPC policy for qrexec daemon.
The `qubesd` daemon may be accessed from other domains through a set of qrexec
API calls called the "Admin API". This API is the intended
management interface supported by the Qubes OS. The API is stable. When called,
the RPC handler performs basic validation and forwards the request to the
`qubesd` via UNIX domain socket. The socket API is private and unstable. It is
documented [FIXME currently it isn't -- woju 20161221] in the developer's
documentation of the source code.
## The calls
The API should be implemented as a set of qrexec calls. This is to make it easy
to set the policy using current mechanism.
| call | dest | argument | inside | return | note |
| ------------------------------------- | --------- | --------- | ----------------------------------------- | --------------------------------------------------------- | ---- |
| `admin.vmclass.List` | `dom0` | - | - | `<class>\n` |
| `admin.vm.List` | `dom0|<vm>` | - | - | `<name> class=<class> state=<state>\n` |
| `admin.vm.Create.<class>` | `dom0` | template | `name=<name> label=<label>` | - |
| `admin.vm.CreateInPool.<class>` | `dom0` | template | `name=<name> label=<label> `<br/>`pool=<pool> pool:<volume>=<pool>` | - | either use `pool=` to put all volumes there, <br/>or `pool:<volume>=` for individual volumes - both forms are not allowed at the same time
| `admin.vm.CreateDisposable` | template | - | - | name | Create new DisposableVM, `template` is any AppVM with `dispvm_allowed` set to True, or `dom0` to use default defined in `default_dispvm` property of calling VM; VM created with this call will be automatically removed after its shutdown; the main difference from `admin.vm.Create.DispVM` is automatic (random) name generation.
| `admin.vm.Remove` | vm | - | - | - |
| `admin.label.List` | `dom0` | - | - | `<property>\n` |
| `admin.label.Create` | `dom0` | label | `0xRRGGBB` | - |
| `admin.label.Get` | `dom0` | label | - | `0xRRGGBB` |
| `admin.label.Index` | `dom0` | label | - | `<label-index>` |
| `admin.label.Remove` | `dom0` | label | - | - |
| `admin.property.List` | `dom0` | - | - | `<property>\n` |
| `admin.property.Get` | `dom0` | property | - | `default={True|False} `<br/>`type={str|int|bool|vm|label} <value>` |
| `admin.property.GetDefault` | `dom0` | property | - | `type={str|int|bool|vm|label} <value>` |
| `admin.property.Help` | `dom0` | property | - | `help` |
| `admin.property.HelpRst` | `dom0` | property | - | `help.rst` |
| `admin.property.Reset` | `dom0` | property | - | - |
| `admin.property.Set` | `dom0` | property | value | - |
| `admin.vm.property.List` | vm | - | - | `<property>\n` |
| `admin.vm.property.Get` | vm | property | - | `default={True|False} `<br/>`type={str|int|bool|vm|label} <value>` |
| `admin.vm.property.GetDefault` | vm | property | - | `type={str|int|bool|vm|label} <value>` |
| `admin.vm.property.Help` | vm | property | - | `help` |
| `admin.vm.property.HelpRst` | vm | property | - | `help.rst` |
| `admin.vm.property.Reset` | vm | property | - | - |
| `admin.vm.property.Set` | vm | property | value | - |
| `admin.vm.feature.List` | vm | - | - | `<feature>\n` |
| `admin.vm.feature.Get` | vm | feature | - | value |
| `admin.vm.feature.CheckWithTemplate` | vm | feature | - | value |
| `admin.vm.feature.Remove` | vm | feature | - | - |
| `admin.vm.feature.Set` | vm | feature | value | - |
| `admin.vm.tag.List` | vm | - | - | `<tag>\n` |
| `admin.vm.tag.Get` | vm | tag | - | `0` or `1` | retcode? |
| `admin.vm.tag.Remove` | vm | tag | - | - |
| `admin.vm.tag.Set` | vm | tag | - | - |
| `admin.vm.firewall.Get` | vm | - | - | `<rule>\n` | rules syntax as in [firewall interface](/doc/vm-interface/#firewall-rules-in-4x) with addition of `expire=` and `comment=` options; `comment=` (if present) must be the last option
| `admin.vm.firewall.Set` | vm | - | `<rule>\n` | - | set firewall rules, see `admin.vm.firewall.Get` for syntax
| `admin.vm.firewall.Reload` | vm | - | - | - | force reload firewall without changing any rule
| `admin.vm.device.<class>.Attach` | vm | device | options | - | `device` is in form `<backend-name>+<device-ident>` <br/>optional options given in `key=value` format, separated with spaces; <br/>options can include `persistent=True` to "persistently" attach the device (default is temporary)
| `admin.vm.device.<class>.Detach` | vm | device | - | - | `device` is in form `<backend-name>+<device-ident>`
| `admin.vm.device.<class>.Set.persistent`| vm | device | `True`|`False` | - | `device` is in form `<backend-name>+<device-ident>`
| `admin.vm.device.<class>.List` | vm | - | - | `<device> <options>\n` | options can include `persistent=True` for "persistently" attached devices (default is temporary)
| `admin.vm.device.<class>.Available` | vm | device-ident | - | `<device-ident> <properties> description=<desc>\n` | optional service argument may be used to get info about a single device, <br/>optional (device class specific) properties are in `key=value` form, <br/>`description` must be the last one and is the only one allowed to contain spaces
| `admin.pool.List` | `dom0` | - | - | `<pool>\n` |
| `admin.pool.ListDrivers` | `dom0` | - | - | `<pool-driver> <property> ...\n` | Properties allowed in `admin.pool.Add`
| `admin.pool.Info` | `dom0` | pool | - | `<property>=<value>\n` |
| `admin.pool.Add` | `dom0` | driver | `<property>=<value>\n` | - |
| `admin.pool.Set.revisions_to_keep` | `dom0` | pool | `<value>` | - |
| `admin.pool.Remove` | `dom0` | pool | - | - |
| `admin.pool.volume.List` | `dom0` | pool | - | volume id |
| `admin.pool.volume.Info` | `dom0` | pool | vid | `<property>=<value>\n` |
| `admin.pool.volume.Set.revisions_to_keep`| `dom0` | pool | `<vid> <value>` | - |
| `admin.pool.volume.ListSnapshots` | `dom0` | pool | vid | `<snapshot>\n` |
| `admin.pool.volume.Snapshot` | `dom0` | pool | vid | snapshot |
| `admin.pool.volume.Revert` | `dom0` | pool | `<vid> <snapshot>` | - |
| `admin.pool.volume.Resize` | `dom0` | pool | `<vid> <size_in_bytes>` | - |
| `admin.pool.volume.Import` | `dom0` | pool | `<vid>\n<raw volume data>` | - |
| `admin.pool.volume.CloneFrom` | `dom0` | pool | vid | token, to be used in `admin.pool.volume.CloneTo` | obtain a token to copy volume `vid` in `pool`;<br/>the token is one time use only, it's invalidated by `admin.pool.volume.CloneTo`, even if the operation fails |
| `admin.pool.volume.CloneTo` | `dom0` | pool | `<vid> <token>` | - | copy volume pointed by a token to volume `vid` in `pool` |
| `admin.vm.volume.List` | vm | - | - | `<volume>\n` | `<volume>` is per-VM volume name (`root`, `private`, etc), `<vid>` is pool-unique volume id
| `admin.vm.volume.Info` | vm | volume | - | `<property>=<value>\n` |
| `admin.vm.volume.Set.revisions_to_keep`| vm | volume | value | - |
| `admin.vm.volume.ListSnapshots` | vm | volume | - | snapshot | duplicate of `admin.pool.volume.`, but with other call params |
| `admin.vm.volume.Snapshot` | vm | volume | - | snapshot | id. |
| `admin.vm.volume.Revert` | vm | volume | snapshot | - | id. |
| `admin.vm.volume.Resize` | vm | volume | size_in_bytes | - | id. |
| `admin.vm.volume.Import` | vm | volume | raw volume data | - | id. |
| `admin.vm.volume.CloneFrom` | vm | volume | - | token, to be used in `admin.vm.volume.CloneTo` | obtain a token to copy `volume` of `vm`;<br/>the token is one time use only, it's invalidated by `admin.vm.volume.CloneTo`, even if the operation fails |
| `admin.vm.volume.CloneTo` | vm | volume | token, obtained with `admin.vm.volume.CloneFrom` | - | copy volume pointed by a token to `volume` of `vm` |
| `admin.vm.Start` | vm | - | - | - |
| `admin.vm.Shutdown` | vm | - | - | - |
| `admin.vm.Pause` | vm | - | - | - |
| `admin.vm.Unpause` | vm | - | - | - |
| `admin.vm.Kill` | vm | - | - | - |
| `admin.backup.Execute` | `dom0` | config id | - | - | config in `/etc/qubes/backup/<id>.conf`, only one backup operation of given `config id` can be running at once |
| `admin.backup.Info` | `dom0` | config id | - | backup info | info what would be included in the backup
| `admin.backup.Cancel` | `dom0` | config id | - | - | cancel running backup operation
| `admin.Events` | `dom0|vm` | - | - | events |
| `admin.vm.Stats` | `dom0|vm` | - | - | `vm-stats` events, see below | emit VM statistics (CPU, memory usage) in form of events
Volume properties:
- `pool`
- `vid`
- `size`
- `usage`
- `rw`
- `source`
- `save_on_stop`
- `snap_on_start`
Method `admin.vm.Stats` returns `vm-stats` events every `stats_interval` seconds, for every running VM. Parameters of `vm-stats` events:
- `memory_kb` - memory usage in kB
- `cpu_time` - absolute CPU time (in milliseconds) spent by the VM since its startup, normalized for one CPU
- `cpu_usage` - CPU usage in percents
## Returned messages
First byte of a message is a message type. This is 8 bit non-zero integer.
Values start at 0x30 (48, `'0'`, zero digit in ASCII) for readability in hexdump.
Next byte must be 0x00 (a separator).
This alternatively can be thought of as zero-terminated string containing
single ASCII digit.
### OK (0)
```
30 00 <content>
```
Server will close the connection after delivering single message.
### EVENT (1)
```
31 00 <subject> 00 <event> 00 ( <key> 00 <value> 00 )* 00
```
Events are returned as stream of messages in selected API calls. Normally server
will not close the connection.
A method yielding events will not ever return a `OK` or `EXCEPTION` message.
When calling such method, it will produce an artificial event
`connection-established` just after connection, to help avoiding race
conditions during event handler registration.
### EXCEPTION (2)
```
32 00 <type> 00 ( <traceback> )? 00 <format string> 00 ( <field> 00 )*
```
Server will close the connection.
Traceback may be empty, can be enabled server-side as part of debug mode.
Delimiting zero-byte is always present.
Fields are should substituted into `%`-style format string, possibly after
client-side translation, to form final message to be displayed unto user. Server
does not by itself support translation.
## Tags
The tags provided can be used to write custom policies. They are not used in
a&nbsp;default Qubes OS installation. However, they are created anyway.
- `created-by-<vm>` &mdash;&nbsp;Created in an extension to qubesd at the
moment of creation of the VM. Cannot be changed via API, which is also
enforced by this extension.
- `managed-by-<vm>` &mdash;&nbsp;Can be used for the same purpose, but it is
not created automatically, nor is it forbidden to set or reset this tag.
## Backup profile
Backup-related calls do not allow (yet) to specify what should be included in
the backup. This needs to be configured separately in dom0, with a backup
profile, stored in `/etc/qubes/backup/<profile>.conf`. The file use yaml syntax
and have following settings:
- `include` - list of VMs to include, can also contains tags using
`$tag:some-tag` syntax or all VMs of given type using `$type:AppVM`, known
from qrexec policy
- `exclude` - list of VMs to exclude, after evaluating `include` setting
- `destination_vm` - VM to which the backup should be send
- `destination_path` - path to which backup should be written in
`destination_vm`. This setting is given to `qubes.Backup` service and
technically it's up to it how to interpret it. In current implementation it is
interpreted as a directory where a new file should be written (with a name
based on the current timestamp), or a command where the backup should
be piped to
- `compression` - should the backup be compressed (default: True)? The value can be either
`False` or `True` for default compression, or a compression command (needs to
accept `-d` argument for decompression)
- `passphrase_text` - passphrase used to encrypt and integrity protect the backup
- `passphrase_vm` - VM which should be asked what backup passphrase should be
used. The asking is performed using `qubes.BackupPassphrase+profile_name`
service, which is expected to output chosen passphrase to its stdout. Empty
output cancel the backup operation. This service can be used either to ask
the user interactively, or to have some automated passphrase handling (for
example: generate randomly, then encrypt with a public key and send
somewhere)
Not all settings needs to be set.
Example backup profile:
```yaml
# Backup only selected VMs
include:
- work
- personal
- vault
- banking
# Store the backup on external disk
destination_vm: sys-usb
destination_path: /media/my-backup-disk
# Use static passphrase
passphrase_text: "My$Very!@Strong23Passphrase"
```
And slightly more advanced one:
```yaml
# Include all VMs with a few exceptions
include:
- $type:AppVM
- $type:TemplateVM
- $type:StandaloneVM
exclude:
- untrusted
- $tag:do-not-backup
# parallel gzip for faster backup
compression: pigz
# ask 'vault' VM for the backup passphrase
passphrase_vm: vault
# send the (encrypted) backup directly to remote server
destination_vm: sys-net
destination_path: ncftpput -u my-ftp-username -p my-ftp-pass -c my-ftp-server /directory/for/backups
```
## General notes
- there is no provision for `qvm-run`, but there already exists `qubes.VMShell` call
- generally actions `*.List` return a list of objects and have "object
identifier" as first word in a row. Such action can be also called with "object
identifier" in argument to get only a single entry (in the same format).
- closing qrexec connection normally does _not_ interrupt running operation; this is important to avoid leaving the system in inconsistent state
- actual operation starts only after caller send all the parameters (including a payload), signaled by sending EOF mark; there is no support for interactive protocols, to keep the protocol reasonable simple
## TODO
- something to configure/update policy
- notifications
- how to constrain the events?
- how to pass the parameters? maybe XML, since this is trusted anyway and
parser may be complicated
- how to constrain the possible values for `admin.vm.property.Set` etc, like
"you can change `netvm`, but you have to pick from this set"; this currently
can be done by writing an extension
- a call for executing `*.desktop` file from `/usr/share/applications`, for use
with appmenus without giving access to `qubes.VMShell`; currently this can be
done by writing custom qrexec calls
- maybe some generator for `.desktop` for appmenus, which would wrap calls in
`qrexec-client-vm`
<!-- vim: set ts=4 sts=4 sw=4 et : -->
[admin-api-architecture]: /attachment/wiki/AdminAPI/admin-api-architecture.svg

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

@ -14,7 +14,7 @@ Qubes Dom0 secure update procedure
Reasons for Dom0 updates
------------------------
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 will be discovered e.g. in the Dom0 Desktop Manager, this really is not a problem for Qubes, because all the 3rd party software running in Dom0 is not accessible from VMs or network in any way. Some exceptions to the above include: Qubes GUI daemon, Xen store daemon, and disk back-ends (we plan move the disk backends to 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 updating software in Dom0. This is because there is no networking in Dom0, which means that even if some bugs will be discovered e.g. in the Dom0 Desktop Manager, this really is not a problem for Qubes, because all the 3rd party software running in Dom0 is not accessible from VMs or network in any way. Some exceptions to the above include: Qubes GUI daemon, Xen store daemon, and disk back-ends (we plan to move the disk backends to untrusted domain in Qubes 2.0). Of course we believe this software is reasonably secure and we hope it will not need patching.
However, we anticipate some other situations when updating Dom0 software might be required:
@ -25,20 +25,20 @@ However, we anticipate some other situations when updating Dom0 software might b
Problems with traditional network-based update mechanisms
---------------------------------------------------------
Dom0 is the most trusted domain on Qubes OS, and for this reason we decided to design Qubes in such a way that Dom0 is not connected to any network. In fact only select domains can be connected to a network via so called network domains. There could also be more than one network domain, e.g. in case the user is connected to more than one physically or logically separated networks.
Dom0 is the most trusted domain on Qubes OS, and for this reason we decided to design Qubes in such a way that Dom0 is not connected to any network. In fact only certain domains can be connected to a network via so-called network domains. There can also be more than one network domain, e.g. in case the user is connected to more than one physically or logically separated networks.
Secure update mechanism we use in Qubes (starting from Beta 2
Secure update mechanism we use in Qubes (starting from Beta 2)
-------------------------------------------------------------
Keeping Dom0 not connected to any network makes it hard, however, to provide updates for software in Dom0. For this reason we have come up with the following mechanism for Dom0 updates, which minimizes the amount of untrusted input processed by Dom0 software:
The update process is initiated by [qvm-dom0-update script](https://github.com/QubesOS/qubes-core-admin-linux/blob/release2/dom0-updates/qubes-dom0-update), running in Dom0.
Updates (\*.rpm files) are checked and downloaded by UpdateVM, which by default is the same as the firewall VM, but can be configured to be any other, network-connected VM. This is done by [qubes-download-dom0-updates.sh script](https://github.com/QubesOS/qubes-core-agent-linux/blob/release2/misc/qubes-download-dom0-updates.sh) (this script is executed using qrexec by the previously mentioned qvm-dom0-update). Note that we assume that this script might get compromised and might download a maliciously compromised downloads -- this is not a problem as Dom0 verifies digital signatures on updates later. The downloaded rpm files are placed in a ~~~/var/lib/qubes/dom0-updates~~~ directory on UpdateVM filesystem (again, they might get compromised while being kept there, still this isn't a problem). This directory is passed to yum using the ~~~--installroot=~~~ option.
Updates (\*.rpm files) are checked and downloaded by UpdateVM, which by default is the same as the firewall VM, but can be configured to be any other, network-connected VM. This is done by [qubes-download-dom0-updates.sh script](https://github.com/QubesOS/qubes-core-agent-linux/blob/release2/misc/qubes-download-dom0-updates.sh) (this script is executed using qrexec by the previously mentioned qvm-dom0-update). Note that we assume that this script might get compromised and fetch maliciously compromised downloads -- this is not a problem as Dom0 verifies digital signatures on updates later. The downloaded rpm files are placed in a ~~~/var/lib/qubes/dom0-updates~~~ directory on UpdateVM filesystem (again, they might get compromised while being kept there, still this isn't a problem). This directory is passed to yum using the ~~~--installroot=~~~ option.
Once updates are downloaded, the update script that runs in UpdateVM requests an RPM service [qubes.ReceiveUpdates](https://github.com/QubesOS/qubes-core-admin-linux/blob/release2/dom0-updates/qubes.ReceiveUpdates) to be executed in Dom0. This service is implemented by [qubes-receive-updates script](https://github.com/QubesOS/qubes-core-admin-linux/blob/release2/dom0-updates/qubes-receive-updates) running in Dom0. The Dom0's qvm-dom0-update script (which originally initiated the whole update process) waits until qubes-receive-updates finished.
The qubes-receive-updates script processes the untrusted input from Update VM: it first extracts the received \*.rpm files (that are sent over qrexec data connection) and then verifies digital signature on each file. The qubes-receive-updates script is a security-critical component of the Dom0 update process (as is the [qfile-dom0-unpacker.c](https://github.com/QubesOS/qubes-core-admin-linux/blob/release2/dom0-updates/qfile-dom0-unpacker.c) and the rpm utility, both used by the qubes-receive-updates for processing the untrusted input.
The qubes-receive-updates script processes the untrusted input from Update VM: it first extracts the received \*.rpm files (that are sent over qrexec data connection) and then verifies digital signature on each file. The qubes-receive-updates script is a security-critical component of the Dom0 update process (as is the [qfile-dom0-unpacker.c](https://github.com/QubesOS/qubes-core-admin-linux/blob/release2/dom0-updates/qfile-dom0-unpacker.c) and the rpm utility, both used by the qubes-receive-updates for processing the untrusted input).
Once qubes-receive-updates finished unpacking and verifying the updates, the updates are placed in ``qubes-receive-updates`` directory in Dom0 filesystem. Those updates are now trusted. Dom0 is configured (see /etc/yum.conf in Dom0) to use this directory as a default (and only) [yum repository](https://github.com/QubesOS/qubes-core-admin-linux/blob/release2/dom0-updates/qubes-cached.repo).

55
services/mgmt-design.md
View File

@ -1,55 +0,0 @@
---
layout: doc-full
title: Management API
permalink: /doc/mgmt-architecture/
---
# Qubes OS Management Architecture
*(This page is the current draft of the proposal. It is not implemented yet.)*
## Goals
The goals of the management system is to provide a way for the user to manage
the domains without direct access to dom0.
Foreseen benefits include:
- Ability to remotely manage the Qubes OS.
- Possibility to create multi-user system, where different users are able to use
different sets of domains, possibly overlapping. This would also require to
have separate GUI domain.
The API would be used by:
- Qubes OS Manager (or any tools that would replace it)
- CLI tools, when run from another VM (and possibly also from dom0)
- remote management tools
- any custom tools
## Threat model
TBD
## Components
![Management Architecture][mgmt-architecture]
A central entity in the Qubes management system is a `qubesd` daemon, which
holds information about all domains in the system and mediates all actions (like
starting and stopping a qube) with `libvirtd`. The `qubesd` daemon also manages
the `qubes.xml` file, which stores all persistent state information and
dispatches events to extensions. Last but not least, `qubesd` is responsible for
querying the RPC policy for qrexec daemon.
The `qubesd` daemon may be accessed from other domains through a set of qrexec
API calls called the [management API][mgmt1]. This API is the intended
management interface supported by the Qubes OS. The API is stable. When called,
the RPC handler performs basic validation and forwards the request to the
`qubesd` via UNIX domain socket. The socket API is private and unstable. It is
documented [FIXME currently it isn't -- woju 20161221] in the developer's
documentation of the source code.
[mgmt1]: ../mgmt1/
[mgmt-architecture]: /attachment/wiki/mgmt/mgmt-architecture.svg

186
services/mgmt1.md
View File

@ -1,186 +0,0 @@
---
layout: doc-full
title: Management API
permalink: /doc/mgmt1/
redirect_from:
- /doc/mgmt/
---
# Management API
*(This page is the current draft of the proposal. It is not implemented yet.)*
The API should be implemented as a set of qrexec calls. This is to make it easy
to set the policy using current mechanism.
## The calls
| call | dest | argument | inside | return | note |
| ------------------------------------- | --------- | --------- | ----------------------------------------- | --------------------------------------------------------- | ---- |
| `mgmt.vmclass.List` | `dom0` | - | - | `<class>\n` |
| `mgmt.vm.List` | `dom0|<vm>` | - | - | `<name> class=<class> state=<state>\n` |
| `mgmt.vm.Create.<class>` | `dom0` | template | `name=<name> label=<label>` | - |
| `mgmt.vm.CreateInPool.<class>` | `dom0` | template | `name=<name> label=<label> `<br/>`pool=<pool> pool:<volume>=<pool>` | - | either use `pool=` to put all volumes there, <br/>or `pool:<volume>=` for individual volumes - both forms are not allowed at the same time
| `mgmt.vm.CreateTemplate` | `dom0` | name | `root.img` | - |
| `mgmt.vm.Clone` | vm | - | `name=<name>` | - |
| `mgmt.vm.CloneInPool` | vm | - | `name=<name> `<br/>`pool=<pool> pool:<volume>=<pool>` | - | same as for `mgmt.vm.CreateInPool`
| `mgmt.vm.Remove` | vm | - | - | - |
| `mgmt.label.List` | `dom0` | - | - | `<property>\n` |
| `mgmt.label.Create` | `dom0` | label | `0xRRGGBB` | - |
| `mgmt.label.Get` | `dom0` | label | - | `0xRRGGBB` |
| `mgmt.label.Index` | `dom0` | label | - | `<label-index>` |
| `mgmt.label.Remove` | `dom0` | label | - | - |
| `mgmt.property.List` | `dom0` | - | - | `<property>\n` |
| `mgmt.property.Get` | `dom0` | property | - | `default={yes|no} `<br/>`type={str|int|bool|vm|label} <value>` |
| `mgmt.property.Help` | `dom0` | property | - | `help` |
| `mgmt.property.HelpRst` | `dom0` | property | - | `help.rst` |
| `mgmt.property.Reset` | `dom0` | property | - | - |
| `mgmt.property.Set` | `dom0` | property | value | - |
| `mgmt.vm.property.List` | vm | - | - | `<property>\n` |
| `mgmt.vm.property.Get` | vm | property | - | `default={yes|no} <value>` |
| `mgmt.vm.property.Help` | vm | property | - | `help` |
| `mgmt.vm.property.HelpRst` | vm | property | - | `help.rst` |
| `mgmt.vm.property.Reset` | vm | property | - | - |
| `mgmt.vm.property.Set` | vm | property | value | - |
| `mgmt.vm.feature.List` | vm | - | - | `<feature>\n` |
| `mgmt.vm.feature.Get` | vm | feature | - | value |
| `mgmt.vm.feature.CheckWithTemplate` | vm | feature | - | value |
| `mgmt.vm.feature.Remove` | vm | feature | - | - |
| `mgmt.vm.feature.Set` | vm | feature | value | - |
| `mgmt.vm.tag.List` | vm | - | - | `<tag>\n` |
| `mgmt.vm.tag.Get` | vm | tag | - | `0` or `1` | retcode? |
| `mgmt.vm.tag.Remove` | vm | tag | - | - |
| `mgmt.vm.tag.Set` | vm | tag | - | - |
| `mgmt.vm.firewall.Get` | vm | - | - | `<rule>\n` | rules syntax as in [firewall interface](/doc/vm-interface/#firewall-rules-in-4x) with addition of `expire=` and `comment=` options; `comment=` (if present) must be the last option
| `mgmt.vm.firewall.Set` | vm | - | `<rule>\n` | - | set firewall rules, see `mgmt.vm.firewall.Get` for syntax
| `mgmt.vm.firewall.Flush` | vm | - | - | - |
| `mgmt.vm.firewall.SetPolicy` | vm | - | `accept|drop` | - |
| `mgmt.vm.firewall.GetPolicy` | vm | - | - | `accept|drop` |
| `mgmt.vm.firewall.Reload` | vm | - | - | - | force reload firewall without changing any rule
| `mgmt.vm.device.<class>.Attach` | vm | device | options | - | `device` is in form `<backend-name>+<device-ident>` <br/>optional options given in `key=value` format, separated with spaces; <br/>options can include `persistent=yes` to "persistently" attach the device (default is temporary)
| `mgmt.vm.device.<class>.Detach` | vm | device | - | - | `device` is in form `<backend-name>+<device-ident>`
| `mgmt.vm.device.<class>.List` | vm | - | - | `<device> <options>\n` |
| `mgmt.vm.device.<class>.Available` | vm | device-ident | - | `<device-ident> <properties> description=<desc>\n` | optional service argument may be used to get info about a single device, <br/>optional (device class specific) properties are in `key=value` form, <br/>`description` must be the last one and is the only one allowed to contain spaces; <br/>options can include `persistent=yes` for "persistently" attached devices (default is temporary)
| `mgmt.vm.microphone.Attach` | vm | - | - | - |
| `mgmt.vm.microphone.Detach` | vm | - | - | - |
| `mgmt.pool.List` | `dom0` | - | - | `<pool>\n` |
| `mgmt.pool.ListDrivers` | `dom0` | - | - | `<pool-driver> <property> ...\n` | Properties allowed in `mgmt.pool.Add`
| `mgmt.pool.Info` | `dom0` | pool | - | `<property>=<value>\n` |
| `mgmt.pool.Add` | `dom0` | driver | `<property>=<value>\n` | - |
| `mgmt.pool.Remove` | `dom0` | pool | - | - |
| `mgmt.pool.volume.List` | `dom0` | pool | - | volume id |
| `mgmt.pool.volume.Info` | `dom0` | pool | vid | `<property>=<value>\n` |
| `mgmt.pool.volume.ListSnapshots` | `dom0` | pool | vid | `<snapshot>\n` |
| `mgmt.pool.volume.Snapshot` | `dom0` | pool | vid | snapshot |
| `mgmt.pool.volume.Revert` | `dom0` | pool | `<vid> <snapshot>` | - |
| `mgmt.pool.volume.Resize` | `dom0` | pool | `<vid> <size_in_bytes>` | - |
| `mgmt.pool.volume.Import` | `dom0` | pool | `<vid>\n<raw volume data>` | - |
| `mgmt.vm.volume.List` | vm | - | - | `<volume>\n` | `<volume>` is per-VM volume name, `<vid>` is pool-unique volume id
| `mgmt.vm.volume.Info` | vm | volume | - | `<property>=<value>\n` |
| `mgmt.vm.volume.ListSnapshots` | vm | volume | - | snapshot | duplicate of `mgmt.pool.volume.`, but with other call params |
| `mgmt.vm.volume.Snapshot` | vm | volume | - | snapshot | id. |
| `mgmt.vm.volume.Revert` | vm | volume | snapshot | - | id. |
| `mgmt.vm.volume.Resize` | vm | volume | size_in_bytes | - | id. |
| `mgmt.vm.volume.Import` | vm | volume | raw volume data | - | id. |
| `mgmt.vm.Start` | vm | - | - | - |
| `mgmt.vm.Shutdown` | vm | - | - | - |
| `mgmt.vm.Pause` | vm | - | - | - |
| `mgmt.vm.Unpause` | vm | - | - | - |
| `mgmt.vm.Kill` | vm | - | - | - |
| `mgmt.backup.Execute` | `dom0` | config i | - | - | config in `/etc/qubes/backup/<id>.conf` |
| `mgmt.backup.Info` | `dom0` | ? | content? | ? |
| `mgmt.backup.Restore` | `dom0` | ? | content | ? |
| `mgmt.Events` | `dom0|vm` | - | - | events |
Volume properties:
- `pool`
- `vid`
- `size`
- `usage`
- `rw`
- `internal`
- `source`
- `save_on_stop`
- `snap_on_start`
## Returned messages
First byte of a message is a message type. This is 8 bit non-zero integer.
Values start at 0x30 (48, `'0'`, zero digit in ASCII) for readability in hexdump.
Next byte must be 0x00 (a separator).
This alternatively can be thought of as zero-terminated string containing
single ASCII digit.
### OK (0)
```
30 00 <content>
```
Server will close the connection after delivering single message.
### EVENT (1)
```
31 00 <subject> 00 <event> 00 ( <key> 00 <value> 00 )* 00
```
Events are returned as stream of messages in selected API calls. Normally server
will not close the connection.
A method yielding events will not ever return a `OK` or `EXCEPTION` message.
When calling such method, it will produce an artificial event
`connection-established` just after connection, to help avoiding race
conditions during event handler registration.
### EXCEPTION (2)
```
32 00 <type> 00 ( <traceback> )? 00 <format string> 00 ( <field> 00 )*
```
Server will close the connection.
Traceback may be empty, can be enabled server-side as part of debug mode.
Delimiting zero-byte is always present.
Fields are should substituted into `%`-style format string, possibly after
client-side translation, to form final message to be displayed unto user. Server
does not by itself support translation.
## Tags
- `created-by-<vm>`
- `managed-by-<vm>`
- `backup-<id>`
## General notes
- there is no provision for `qvm-run`, but there already exists `qubes.VMShell` call
- generally actions `*.List` return a list of objects and have "object
identifier" as first word in a row. Such action can be also called with "object
identifier" in argument to get only a single entry (in the same format).
- closing qrexec connection normally does _not_ interrupt running operation; this is important to avoid leaving the system in inconsistent state
- actual operation starts only after caller send all the parameters (including a payload), signaled by sending EOF mark; there is no support for interactive protocols, to keep the protocol reasonable simple
## TODO
- something to configure/update policy
- notifications
- how to constrain the events?
- how to pass the parameters? maybe XML, since this is trusted anyway and
parser may be complicated
- how to constrain the possible values for `mgmt.vm.property.Set` etc, like
"you can change `netvm`, but you have to pick from this set"; this currently
can be done by writing an extension
- a call for executing `*.desktop` file from `/usr/share/applications`, for use
with appmenus without giving access to `qubes.VMShell`; currently this can be
done by writing custom qrexec calls
- maybe some generator for `.desktop` for appmenus, which would wrap calls in
`qrexec-client-vm`
<!-- vim: set ts=4 sts=4 sw=4 et : -->

9
services/qrexec3.md
View File

@ -192,6 +192,15 @@ second rule allowing calls to `$dispvm:anon-whonix-dvm`, or even if
there is a rule explicitly denying it. This is because the redirection happens
_after_ considering the action.
In Qubes 4.0 there are also additional methods to specify source/target VM:
* `$tag:some-tag` - meaning a VM with tag `some-tag`
* `$type:type` - meaning a VM of `type` (like `AppVM`, `TemplateVM` etc)
Target VM can be also specified as `$default`, which matches the case when
calling VM didn't specified any particular target (either by using `$default`
target, or empty target).
### Service argument in policy
Sometimes just service name isn't enough to make reasonable qrexec policy. One

49
troubleshooting/intel-igfx-troubleshooting.md Normal file
View File

@ -0,0 +1,49 @@
---
layout: doc
title: Intel Integrated Graphics Troubleshooting
permalink: /doc/intel-igfx-troubleshooting/
---
# Intel Integrated Graphics Troubleshooting #
Dom0 Kernels currently included in Qubes have issues related to VT-d (IOMMU) and some versions of the
integrated Intel Graphics Chip. Depending on the specific hardware / software combination the issues are quite wide ranging, from apparently harmless log errors, to VM window refresh issues,
to complete screen corruption and crashes rendering the machine unusable with Qubes.
Such issues have been reported on at least the following machines:
* HP Elitebook 2540p
* Lenovo x201
* Lenovo x220
* Thinkpad T410
* Thinkpad T450s
Log errors only on :
* Librem 13v1
* Librem 15v2
The installer for Qubes 4.0 final has been updated to disable IOMMU for the integrated intel graphics by default. However, users of 3.2 may experience
issues on install or on kernel upgrades to versions higher than 3.18.x
Disabling of IOMMU for the integrated graphics chip is not a security issue, as the
device currently lives in dom0 and is not passed to a VM. This behaviour is planned to be changed as of Qubes 4.1, when passthrough capabilities will be required for the GUI domain <sup id="a1-1">[1](#f1)</sup>
## Workaround for existing systems with VT-d enabled (grub / legacy mode) ##
Edit the startup parameters for Xen:
1. Open a terminal in dom0
2. Edit `/etc/default/grub` (e.g. `sudo nano /etc/default/grub`)
3. Add to the line `GRUB_CMDLINE_XEN_DEFAULT` the setting `iommu=no-igfx`, save and quit
4. Commit the change with`sudo grub2-mkconfig --output /boot/grub2/grub.cfg`
## Workaround for existing systems with VT-d enabled (UEFI) ##
Edit the startup parameters for Xen:
1. Open a terminal in dom0
2. Edit `/boot/efi/EFI/qubes/xen.cfg` (e.g. `sudo nano /boot/efi/EFI/qubes/xen.cfg`)
3. Add to the line `options` the setting `iommu=no-igfx`, save and quit
<b name="f1">1</b> <https://github.com/QubesOS/qubes-issues/issues/2841> [↩](#a1-1)

3
troubleshooting/macbook-troubleshooting.md
View File

@ -244,10 +244,12 @@ then press "e", edit grub cfg and boot pressing Fn+F10
* Fix grub2 configuration, which uses wrong command for EFI boot
* analyzing /mnt/sysimage/var/log/anaconda/program.log I found the faulty commands issues by Anaconda installer
~~~
chrooot /mnt/sysimage
~~~
* edit /boot/efi/EFI/qubes/xen.cfg file putting the following content
~~~
[global]
default=4.4.14-11.pvops.qubes.x868_64
@ -259,6 +261,7 @@ ramdisk=initramfs-4.4.14-11.pvops.qubes.x86_64.img
~~~
* The main mistake is the efibootmgr, that needs the right commands. Just in case, re-apply all the commands, adapting to your own disk layout (-d /dev/sdxxx -p partition_number)
~~~
grep Running /mnt/sysimage/var/log/anaconda/program.log | tail -n 20
efibootmgr -b 0000 -B