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

merged upstream/master

Browse Source
This commit is contained in:
GammaSQ 2019-03-04 19:40:20 +01:00
commit 9d01b070fc
No known key found for this signature in database
GPG Key ID: D552FD2F98647C64
48 changed files with 1232 additions and 482 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

17
about/faq.md
View File

@ -175,7 +175,6 @@ So, if feature X isn't enabled, it's most likely for one of three reasons:
3. Our platform supports it, but we're not aware that we can enable it or have forgotten to do so.
(If it seems like this is the case, let us know!)
----------
## Users
@ -263,7 +262,7 @@ Now, how does this apply to Qubes OS?
The above attack requires access to a PCI device, which means that it can be performed only from NetVM / UsbVM, so someone must first break into one of those VMs.
But this isn't that hard, because there is a lot of complex code handling network traffic.
Recent bugs include DHCP client, DNS client, etc.
Most attacks on NetVM / UsbVM (but not all!) require being somewhat close to the target system - for example connected to the same WiFi network, or in the case of a UsbVM, having physical acccess to a USB port.
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 access to a USB port.
### Can I use AMD-v instead of VT-x?
@ -513,8 +512,6 @@ Please don't ask for your favorite program to be installed by default or for som
This is an incredibly selfish attitude that demonstrates a complete lack of consideration for the thousands of other Qubes users who don't happen to share your preferences.
----------
## Developers
### Are there restrictions on the software that the Qubes developers are willing to use?
@ -582,3 +579,15 @@ Arguably secure boot reliance on UEFI integrity is not the best design.
The relevant binaries (shim.efi, xen.efi, kernel / initramfs) are not signed by the Qubes Team and secure boot has not been tested.
Intel TXT (used in [Anti Evil Maid](/doc/anti-evil-maid/)) at least tries to avoid or limit trust in BIOS.
See the Heads project [[1]](https://trmm.net/Heads) [[2]](http://osresearch.net/) for a better-designed non-UEFI-based secure boot scheme with very good support for Qubes.
### What is the canonical way to detect Qubes VM?
Check `/usr/share/qubes/marker-vm` file existence. Additionally, its last line contains Qubes release version (`3.2`, `4.0` etc).
The file was introduced after initial Qubes 3.2 and 4.0 release. If you need to support not-fully-updated systems, check `/usr/bin/qrexec-client-vm` existence.
### Is there a way to automate tasks for continuous integration or DevOps?
Yes, Qubes natively supports automation via [Salt (SaltStack)](/doc/salt/).
There is also the unofficial [ansible-qubes toolkit](https://github.com/Rudd-O/ansible-qubes).
(**Warning:** Since this is an external project that has not been reviewed or endorsed by the Qubes team, [allowing it to manage dom0 may be a security risk](/doc/security-guidelines/#dom0-precautions).)

7
about/support.md
View File

@ -243,10 +243,9 @@ 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 stable Qubes OS releases are
announced here.
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.
Only [Qubes Security Bulletins (QSBs)][qsb], new stable releases, and end-of-life notices are announced here.
To subscribe, send a blank email to `qubes-announce+subscribe@googlegroups.com`.
(Note: A Google account is *not* required. Any email address will work.)

12
about/video-tours.html
View File

@ -15,21 +15,21 @@ permalink: /video-tours/
<hr class="more-top more-bottom">
<div class="row">
<div class="col-lg-4 col-md-4 col-xs-12">
<h2>Introduction</h2>
<h3>Introduction</h3>
<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>
<h3>Screenshots</h3>
<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>
<h3>Getting Started</h3>
<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
@ -68,21 +68,21 @@ permalink: /video-tours/
<hr class="more-top more-bottom">
<div class="row">
<div class="col-lg-4 col-md-4 col-xs-12">
<h2>Docs</h2>
<h3>Docs</h3>
<p>Dive into the Qubes documentation with guides, tips, and troubleshooting help.</p>
<a href="/doc/" class="btn btn-primary">
<i class="fa fa-book"></i> Documentation
</a>
</div>
<div class="col-lg-4 col-md-4 col-xs-12">
<h2>Downloads</h2>
<h3>Downloads</h3>
<p>Download an ISO, verify your download, and install Qubes.</p>
<a href="/downloads/" class="btn btn-primary">
<i class="fa fa-download"></i> Downloads
</a>
</div>
<div class="col-lg-4 col-md-4 col-xs-12">
<h2>Security</h2>
<h3>Security</h3>
<p>Get PGP keys, security bulletins, and canaries. Learn more about our security practices.</p>
<a href="/security/" class="btn btn-primary">
<i class="fa fa-lock"></i> Security Center

203
basics_dev/gsoc.md
View File

@ -5,7 +5,7 @@ permalink: /gsoc/
redirect_from: /GSoC/
---
2018 Google Summer of Code
2019 Google Summer of Code
================
## Information for Students
@ -143,31 +143,72 @@ would override all the user changes there). More details:
**Mentor**: [Marek Marczykowski-Górecki](/team/)
### Easy inter-VM networking configuration
### USB passthrough to Windows qubes
**Project**: Easy inter-VM networking configuration
**Project**: USB passthrough to Windows qubes
**Brief explanation**: Utility to easily configure selected VMs to be reachable (by network) from other VMs or outside network. Currently such configuration require adding iptables rules in multiple VMs manually. For exposing VM to outside network, it may be good to adopt qrexec-based TCP forwarding ([#2148](https://github.com/QubesOS/qubes-issues/issues/2148)).
**Brief explanation**: Add ability to use individual USB devices in Windows qubes. Right now the only option to do that, is to assign the whole USB controller (PCI device), which applies to all the devices connected to it. USB passthrough on Qubes is based on USBIP project, with transport over qrexec instead of TCP/IP.
**Expected results**:
- support firewall rules for inter-VM traffic in qubes-firewall - both VM side (qubes-firewall service) and dom0 configuration side (relevant Admin API calls)
- mechanism for configuring firewall in target VM, especially INPUT iptables chain - currently it is hardcoded to drop new incoming connections
- convenient tool (or modification to existing tool) for controlling above mechanisms
- integration the above with existing GUI tools (especially VM settings)
Relevant links:
- [Qubes networking and firewall documentation](/doc/firewall/)
- [qubes-firewall service code](https://github.com/QubesOS/qubes-core-agent-linux/blob/master/qubesagent/firewall.py)
- Evaluate possible approaches (including flexibility, compatibility and performance), suggested ideas:
- use [USBIP for Windows](https://github.com/cezuni/usbip-win) and make it work with qrexec - similar as done for Linux
- use qrexec+USBIP in Linux-based stubdomain and plug it into USB emulation in qemu
- Choose one approach, write (very simple) design documentation
- Write relevant new code (applies mostly for usbip-win case)
- Plug the mechanism into Qubes core toolstack ([Devices API](https://dev.qubes-os.org/projects/core-admin/en/latest/qubes-devices.html))
**Knowledge prerequisite**:
- iptables
- basics of nft
- python3
- basic USB architecture knowledge (buses, devices, interfaces, functions)
- Python and Bash scripting
- C
- Windows USB stack and/or qemu USB stack
**Mentor**: [Marek Marczykowski-Górecki](/team/)
### Dedicated Audio qube
**Project**: Dedicated Audio qube
**Brief explanation**: Moving audio subsystem from dom0 to a dedicated AudioVM and/or a preexisting VM (e.g sys-usb with attached usb audio device). This would allow using USB audio devices system-wide, without leaving a USB controller in dom0. [Relevant github issue](https://github.com/QubesOS/qubes-issues/issues/1590).
**Expected results**:
- Make audio virtualization components work with non-dom0 backend (in short: add configuration option for the backend, instead of assuming "dom0")
- Possibly per-qube setting what should be used as an AudioVM
- Make other audio-related tools work with the new setup, especially enabling/disabling microphone (`qvm-device mic`) and volume control.
**Knowledge prerequisite**:
- Pulseaudio
- C
- Python
**Mentor**: [Marek Marczykowski-Górecki](/team/)
### Qubes as a Vagrant provider
**Project**: Qubes as a Vagrant provider
**Brief explanation**: Currently using Vagrant on Qubes requires finding an image that uses Docker as isolation provider and running Docker in a qube, or downloading the Vagrantfile and manually setting up a qube according to the Vagrantfile. This project aims at simplifying this workflow. Since introduction of Admin API, it's possible for a qube to provision another qube - which is exactly what is needed for Vagrant. [Related discussion](https://groups.google.com/d/msgid/qubes-devel/535299ca-d16a-4a70-8223-a4ac6be4be41%40googlegroups.com)
**Expected results**:
- Design how Vagrant Qubes provider should look like, including:
- [box format](https://www.vagrantup.com/docs/plugins/providers.html#box-format)
- method for running commands inside (ssh vs qvm-run)
- Write a Vagrant provider able to create/start/stop/etc a VM
- Document how to configure and use the provider, including required qrexec policy changes and possibly firewall rules
- Write integration tests
**Knowledge prerequisite**:
- Ruby
- Vagrant concepts
**Mentor**: [Wojtek Porczyk](/team/), [Marek Marczykowski-Górecki](/team/)
### Mechanism for maintaining in-VM configuration
**Project**: Mechanism for maintaining in-VM configuration
@ -186,7 +227,7 @@ Relevant links:
- shell and/or python scripting
- Qubes OS qrexec services
**Mentor**: [Marek Marczykowski-Górecki](/team/), [Wojtek Porczyk](/team/).
**Mentor**: [Frédéric Pierret](/team/)
### Wayland support in GUI agent and/or GUI daemon
@ -253,7 +294,7 @@ details: [#1552](https://github.com/QubesOS/qubes-issues/issues/1552),
- Python and Bash scripting
- Filesystems and block devices: loop devices, device-mapper, tmpfs, overlayfs, sparse files.
**Mentor**: [Marek Marczykowski-Górecki](/team/)
**Mentor**: [Frédéric Pierret](/team/)
### Unikernel-based firewallvm with Qubes firewall settings support
@ -271,32 +312,6 @@ details: [#1552](https://github.com/QubesOS/qubes-issues/issues/1552),
**Mentor**: [Thomas Leonard](mailto:talex5@gmail.com), [Marek Marczykowski-Górecki](/team/)
### Thunderbird, Firefox and Chrome extensions
**Project**: additional Thunderbird, Firefox and Chrome extensions
**Brief explanation**:
* browser/mail: open link in vm
* browser/mail: open link in dispvm
* browser: save destination to vm
* mail: add whitelisted senders option (address-based and signing key-based) [#845](https://github.com/QubesOS/qubes-issues/issues/845)
**Expected results**:
- Extend existing Thunderbird extension to decide on action (where to open/save attachments) based on message sender - recognized as email address, or signing key
- Add Firefox extension to open links in DisposableVM / selected VM (right-click option and a default action for not-whitelisted URLs/domains)
- The same for Chrome
- Add tests for above enhancements
- Update user documentation
**Knowledge prerequisite**:
- writing Thunderbird/Firefox extensions (XUL, javascript)
- writing Chrome extensions (javascript)
**Mentor**: Inquire on [qubes-devel][ml-devel].
### LogVM(s)
**Project**: LogVM(s)
@ -326,10 +341,10 @@ immune to altering past entries. See
- systemd
- Python/Bash scripting
**Mentor**: [Marek Marczykowski-Górecki](/team/)
**Mentor**: [Frédéric Pierret](/team/)
### Xen GPU pass-through for Intel integrated GPUs
**Project**: Xen GPU pass-through for Intel integrated GPUs (largely independent of Qubes)
### Xen GPU passthrough for Intel integrated GPUs
**Project**: Xen GPU passthrough 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
@ -415,6 +430,30 @@ details in [#2618](https://github.com/QubesOS/qubes-issues/issues/2618).
**Mentor**: [Rafał Wojdyła](/team/)
### Unattended Windows installation
**Project**: Unattended Windows installation
**Brief explanation**: Simplify Windows usage by providing a tool that perform unattended installation given required input data (installation image, license key, user name, etc). Similar feature is already supported in other virtualization solutions, including VMWare Workstation and VirtualBox. [Related github issue](https://github.com/QubesOS/qubes-issues/issues/4688).
**Expected results**:
- A template for `autounattended.xml` file for Windows installer - the template should have placeholders for settings that need to be provided by the user.
- A tool for generating actual `autounattended.xml` file based on the template and user settings.
- A tool for launching Windows installation, given installation image and `autounattended.xml` file (can be the same as in the above point).
- (Optional) Unattended installation should also include Qubes Windows Tools.
- (Optional) A tool should be able to use Windows license embedded in ACPI tables - [related discussion](https://groups.google.com/d/msgid/qubes-devel/0b7fabae-f843-e7ce-40cf-193326cecdb0%40zrubi.hu)
- User documentation
- Automated tests (unit tests, integration tests)
**Knowledge prerequisite**:
- Python scripting
- Linux administration, including handling loop devices, partition tables, filesystems etc
- For optional features, C language and x86 architecture (ACPI tables)
**Mentor**: [Rafał Wojdyła](/team/), [Marek Marczykowski-Górecki](/team/)
### GNOME support in dom0 / GUI VM
**Project**: GNOME support in dom0
@ -449,28 +488,28 @@ details in [#2618](https://github.com/QubesOS/qubes-issues/issues/2618).
- C language (patching metacity)
- Probably also javascript - for modifying GNOME shell extensions
**Mentor**: [Marek Marczykowski-Górecki](/team/)
**Mentor**: [Frédéric Pierret](/team/), [Marek Marczykowski-Górecki](/team/)
### Generalize the Qubes PDF Converter to other types of files
**Project**: Qubes Converters
**Brief explanation**: One of the pioneering ideas of Qubes is to use disposable virtual machines to convert untrustworthy files (such as documents given to journalists by unknown and potentially malicious whistleblowers) into trusthworhty files. See [Joanna's blog on the Qubes PDF Convert](http://theinvisiblethings.blogspot.co.uk/2013/02/converting-untrusted-pdfs-into-trusted.html) for details of the idea. Joanna has implemented a prototype for PDF documents. The goal of this project would be to generalize beyond the simple prototype to accommodate a wide variety of file formats, including Word documents, audio files, video files, spreadsheets, and so on. The converters should prioritise safety over faithful conversion. For example the Qubes PDF converter typically leads to lower quality PDFs (e.g. cut and paste is no longer possible), because this makes the conversion process safer.
**Brief explanation**: One of the pioneering ideas of Qubes is to use disposable virtual machines to convert untrustworthy files (such as documents given to journalists by unknown and potentially malicious whistleblowers) into trustworthy files. See [Joanna's blog on the Qubes PDF Convert](http://theinvisiblethings.blogspot.co.uk/2013/02/converting-untrusted-pdfs-into-trusted.html) for details of the idea. Joanna has implemented a prototype for PDF documents. The goal of this project would be to generalize beyond the simple prototype to accommodate a wide variety of file formats, including Word documents, audio files, video files, spreadsheets, and so on. The converters should prioritise safety over faithful conversion. For example the Qubes PDF converter typically leads to lower quality PDFs (e.g. cut and paste is no longer possible), because this makes the conversion process safer.
**Expected results**: We expect that in the timeframe, it will be possible to implement many converters for many file formats. However, if any unexpected difficulties arise, we would prioritise a small number of safe and high quality converters over a large number of unsafe or unuseful converters.
**Knowledge prerequisite**: Most of the coding will probably be implemented as shell scripts to interface with pre-existing converts (such as ImageMagick in the Qubes PDF converter). However, shell scripts are not safe for processing untrusted data, so any extra processing will need to be implemented in another language -- probably Python.
**Knowledge prerequisite**: Most of the coding will probably be implemented as shell scripts to interface with pre-existing converters (such as ImageMagick in the Qubes PDF converter). However, shell scripts are not safe for processing untrusted data, so any extra processing will need to be implemented in another language -- probably Python.
**Mentors**: Andrew Clausen and Jean-Philippe Ouellet
### Mitigate focus-stealing attacks
**Project**: Mitigate focus-stealing attacks
**Brief explanation**: [Focus stealing attacks](https://en.wikipedia.org/wiki/Focus_stealing) have long been an issue in Qubes OS. The Qubes community has long punted the issue due to having higher priority things to work on, and it being viewed as the responsability of the window manager, but nevertheless it remains a serious issue, and an *effective* mitigation would be most welcome. Any student wishing to work on this would need to engage the community in a discussion about the effectiveness of their proposed earlier rather than later. [#1166](https://github.com/QubesOS/qubes-issues/issues/1166)
**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 responsibility 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 solution 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.
**Knowledge prerequisite**: X APIs, Qubes GUI protocol, familiarity with the targeted window manager.
**Mentor**: Inquire on [qubes-devel][ml-devel].
@ -487,10 +526,70 @@ for more information and qubes-specific background.
**Expected results**: Significant progress towards making the Qubes build process deterministic. This would likely involve cooperation with and hacking on several upstream build tools to eliminate sources of variability.
**Knoledge prerequisite**: qubes-builder [[1]](/doc/qubes-builder/) [[2]](/doc/qubes-builder-details/) [[3]](https://github.com/QubesOS/qubes-builder/tree/master/doc), and efficient at introspecting complex systems: comfortable with tracing and debugging tools, ability to quickly identify and locate issues within a large codebase (upstream build tools), etc.
**Knowledge prerequisite**: qubes-builder [[1]](/doc/qubes-builder/) [[2]](/doc/qubes-builder-details/) [[3]](https://github.com/QubesOS/qubes-builder/tree/master/doc), and efficient at introspecting complex systems: comfortable with tracing and debugging tools, ability to quickly identify and locate issues within a large codebase (upstream build tools), etc.
**Mentor**: [Marek Marczykowski-Górecki](/team/)
### Porting Qubes to ARM/aarch64
**Project**: Porting Qubes to ARM/aarch64
**Brief explanation**:
Qubes currently only supports the x86_64 CPU architecture. Xen currently has additional support for ARM32/ARM64 processors, however work needs to be done to integrate this into the Qubes build process, as well as work in integrating this with the Qubes toolstack and security model. This may also be beneficial in simplifying the process of porting to other architectures.
Some related discussion:
- [#4318](https://github.com/QubesOS/qubes-issues/issues/4318) on porting to ppc64.
- [#3894](https://github.com/QubesOS/qubes-issues/issues/3894) on porting to L4 microkernel.
**Expected results**:
- Add cross-compilation support to qubes-builder and related components.
- Make aarch64 specific adjustments to Qubes toolstacks/manager (including passthrough of devices from device tree to guest domains).
- Aarch64 specific integration and unit tests.
- Production of generic u-boot or uefi capable image/iso for target hardware.
**Knowledge prerequisite**:
- Libvirt and Qubes toolstacks (C and python languages).
- Xen debugging.
- General ARM architecture knowledge.
**Mentor**: [Marek Marczykowski-Górecki](/team/)
### Porting Qubes to POWER9/PPC64
**Project**: Porting Qubes to POWER9/ppc64
**Brief explanation**:
Qubes currently supports the x86_64 CPU architecture. PowerPC is desirable for security purposes as it is the only architecture where one can get performant hardware with entirely open source firmware. Xen has **deprecated** support for Power9/PPC64 processors. Here are two directions to tackle this project from:
- Port Qubes to KVM then work on ppc64 specifics
- Implement some missing functionality in KVM then implement KVM support in the Qubes Hypervisor Abstraction Layer and build process. Improving the HAL will also be beneficial for simplifying the process of porting to further architectures and hypervisors.
- Port Xen to ppc64 then work on Qubes specifics
- For more information on porting Xen see [this thread](https://markmail.org/message/vuk7atnyqfq52epp).
More information and further links can be found in the related issue:
[#4318](https://github.com/QubesOS/qubes-issues/issues/4318).
**Expected results**:
- Add cross-compilation support to qubes-builder and related components.
- Make ppc64 specific adjustments to Qubes toolstacks/manager (including passthrough of devices from device tree to guest domains).
- ppc64 specific integration and unit tests.
- Production of generic u-boot or uefi capable image/iso for target hardware.
**Knowledge prerequisite**:
- Libvirt and Qubes toolstacks (C and python languages).
- KVM or XEN internals
- General ppc64 architecture knowledge.
**Mentor**: [Marek Marczykowski-Górecki](/team/)
### Android development in Qubes
**Project**: Research running Android in Qubes VM (probably HVM) and connecting it to Android Studio

97
basics_user/doc-guidelines.md
View File

@ -11,15 +11,11 @@ redirect_from:
Documentation Guidelines
========================
All Qubes OS documentation pages are stored as plain text files in the
dedicated [qubes-doc] repository. By cloning and regularly pulling from
this repo, users can maintain their own up-to-date offline copy of all Qubes
documentation rather than relying solely on the Web.
All Qubes OS documentation pages are stored as plain text files in the dedicated [qubes-doc] repository.
By cloning and regularly pulling from this repo, users can maintain their own up-to-date offline copy of all Qubes documentation rather than relying solely on the web.
The documentation is a community effort. Volunteers work hard trying to
keep everything accurate and comprehensive. If you notice a problem with the
documentation or some way it can be improved, please [report] it! Better
yet, you can [edit the documentation][contribute] yourself, both to add or improve existing content.
The documentation is a community effort. Volunteers work hard trying to keep everything accurate and comprehensive.
If you notice a problem or some way it can be improved, please [edit the documentation][contribute]!
Questions, problems, and improvements
@ -27,32 +23,35 @@ Questions, problems, and improvements
If you have a question about something you read in the documentation, please send it to the appropriate [mailing list][support].
If you see that something in the documentation should be fixed or improved, please [contribute] the change yourself.
To report an issue with the documentation, please follow our standard [issue reporting guidelines][report].
To report an issue with the documentation, please follow our standard [issue reporting guidelines][issue].
(If you report an issue with the documentation, you will likely be asked to address it, unless there is a clear indication in your report that you are not willing or able to do so.)
How to Contribute
-----------------
Editing the documentation is easy, so if you spot any errors, please help us
fix them! (As mentioned above, the documentation maintainers are just volunteers
who have day jobs of their own, so we rely heavily on the community to improve
the documentation.) Since Qubes is a security-oriented project, every
documentation change will be reviewed before it's published to the web. This
allows us to maintain quality control and protect our users.
Editing the documentation is easy, so if you see that a change should be made, please contribute it!
As mentioned above, we keep all the documentation in a dedicated [Git
repository][qubes-doc] hosted on [GitHub]. Thanks to the GitHub's interface, you can
edit the documentation even if you don't know Git at all! The only thing you
need is a GitHub account, which is free.
A few notes before we get started:
(Note: If you're already familiar with GitHub or wish to work from the command
line, you can skip the rest of this section. All you need to do to contribute is
to [fork and clone][gh-fork] the [qubes-doc] repo, make your changes, then
[submit a pull request][gh-pull].)
* Since Qubes is a security-oriented project, every documentation change will be reviewed before it's accepted.
This allows us to maintain quality control and protect our users.
* We don't want you to spend time and effort on a contribution that we can't accept.
If your contribution would take a lot of time, please [file an issue][issue] for it first so that we can make sure we're on the same page before significant works begins.
* Alternatively, you may already have written content that doesn't conform to these guidelines, but you'd be willing to modify it so that it does.
In this case, you can still submit it by following the instructions below.
Just make a note in your pull request that you're aware of the changes that need to be made and that you're just asking for the content to be reviewed before you spend time making those changes.
Ok, let's start. Every documentation page has an "Edit this page" button. It may
be on the right side (in the desktop layout):
As mentioned above, we keep all the documentation in a dedicated [Git repository][qubes-doc] hosted on [GitHub].
Thanks to GitHub's interface, you can edit the documentation even if you don't know Git at all!
The only thing you need is a GitHub account, which is free.
(**Note:** If you're already familiar with GitHub or wish to work from the command line, you can skip the rest of this section.
All you need to do to contribute is to [fork and clone][gh-fork] the [qubes-doc] repo, make your changes, then [submit a pull request][gh-pull].)
Ok, let's start.
Every documentation page has an "Edit this page" button.
It may be on the side (in the desktop layout):
![edit-button-desktop](/attachment/wiki/doc-edit/03-button2.png)
@ -60,48 +59,43 @@ Or at the bottom (in the mobile layout):
![edit-button-mobile](/attachment/wiki/doc-edit/02-button1.png)
When you click on it, you'll be prompted for your GitHub username and password
(if you aren't already logged in). You can also create an account from here.
When you click on it, you'll be prompted for your GitHub username and password (if you aren't already logged in).
You can also create an account from here.
![github-sign-in](/attachment/wiki/doc-edit/04-sign-in.png)
If this is your first contribution to the documentation, you need to "fork" the
repository (make your own copy). It's easy --- just click the big green button
on the next page. This step is only needed the first time you make a
contribution.
If this is your first contribution to the documentation, you need to "fork" the repository (make your own copy). It's easy --- just click the big green button on the next page.
This step is only needed the first time you make a contribution.
![fork](/attachment/wiki/doc-edit/05-fork.png)
Now you can make your modifications. You can also preview the changes to see how
they'll be formatted by clicking the "Preview changes" tab. **Important:** If
you're making any formatting changes, please [render the site locally] to verify
that everything looks correct before submitting any changes.
Now you can make your modifications.
You can also preview the changes to see how they'll be formatted by clicking the "Preview changes" tab.
If you're making formatting changes, please [render the site locally] to verify that everything looks correct before submitting any changes.
![edit](/attachment/wiki/doc-edit/06-edit.png)
Once you're finished, describe your changes at the bottom and click "Propose file
change".
Once you're finished, describe your changes at the bottom and click "Propose file change".
![commit](/attachment/wiki/doc-edit/07-commit-msg.png)
After that, you'll see exactly what modifications you've made. At this stage,
those changes are still in your own copy of the documentation ("fork"). If
everything looks good, send those changes to us by pressing the "Create pull
request" button.
After that, you'll see exactly what modifications you've made.
At this stage, those changes are still in your own copy of the documentation ("fork").
If everything looks good, send those changes to us by pressing the "Create pull request" button.
![pull-request](/attachment/wiki/doc-edit/08-review-changes.png)
You will be able to adjust the pull request message and title there. In most
cases, the defaults are ok, so you can just confirm by pressing the "Create pull
request" button again.
You will be able to adjust the pull request message and title there.
In most cases, the defaults are ok, so you can just confirm by pressing the "Create pull request" button again.
![pull-request-confirm](/attachment/wiki/doc-edit/09-create-pull-request.png)
That's all! We will review your changes. If everything looks good, we'll pull
them into the official documentation. Otherwise, we may have some questions for
you, which we'll post in a comment on your pull request. (GitHub will
automatically notify you if we do.) If, for some reason, we can't accept your
pull request, we'll post a comment explaining why we can't.
That's all!
We will review your changes.
If everything looks good, we'll pull them into the official documentation.
Otherwise, we may have some questions for you, which we'll post in a comment on your pull request.
(GitHub will automatically notify you if we do.)
If, for some reason, we can't accept your pull request, we'll post a comment explaining why we can't.
![done](/attachment/wiki/doc-edit/10-done.png)
@ -115,7 +109,7 @@ To add an image to a page, use the following syntax in the main document:
![Image Title](/attachment/wiki/page-title/image-filename.png)
```
Then, submit your image(s) in a separate pull request to the [qubes-attachment](https://github.com/QubesOS/qubes-attachment) repository using the same path and filename.
Then, submit your image(s) in a separate pull request to the [qubes-attachment] repository using the same path and filename.
Version-specific Documentation
@ -297,7 +291,7 @@ Please try to write good commit messages, according to the
[qubes-doc]: https://github.com/QubesOS/qubes-doc
[glossary]: /doc/glossary/
[report]: /doc/reporting-bugs/
[issue]: /doc/reporting-bugs/
[contribute]: #how-to-contribute
[qubes-issues]: https://github.com/QubesOS/qubes-issues/issues
[gh-fork]: https://guides.github.com/activities/forking/
@ -311,4 +305,5 @@ Please try to write good commit messages, according to the
[md]: https://daringfireball.net/projects/markdown/
[git-commit]: /doc/coding-style/#commit-message-guidelines
[render the site locally]: https://github.com/QubesOS/qubesos.github.io#instructions
[qubes-attachment]: https://github.com/QubesOS/qubes-attachment

9
basics_user/intro.md
View File

@ -175,30 +175,29 @@ pros and cons of this approach relative to Qubes:
[Software compartmentalization vs. physical separation][paper-compart].)
<hr class="add-top more-bottom">
<div class="row">
<div class="row more-bottom">
<div class="col-lg-4 col-md-4 col-xs-12">
<h2>Video Tours</h2>
<h3>Video Tours</h3>
<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>
<h3>Screenshots</h3>
<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>
<h3>Getting Started</h3>
<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
----------------

10
basics_user/reporting-bugs.md
View File

@ -65,6 +65,16 @@ If you're reporting a bug in a package that is in a [testing] repository, please
Project maintainers really appreciate thorough explanations.
It usually helps them address the problem more quickly, so everyone wins!
### Use the provided issue template ###
Please use the provided issue template.
Do not delete it or remove parts of it.
The issue template is carefully designed to elicit important information.
Without this information, the issue is likely to be incomplete.
It is also important to note the placement and content of the HTML comments in the issue template.
These help us to have issues with a consistent format.
### There are no guarantees that your issue will be addressed ###
Keep in mind that `qubes-issues` is an issue tracker, not a support system.

21
building/qubes-builder.md
View File

@ -135,6 +135,27 @@ If you want to somehow modify sources, you can also do it, here are some basic s
make iso
### Use pre-built Qubes packages
For building just few selected packages, it's very useful to download pre-built qubes-specific dependencies from `{yum,deb}.qubes-os.org`.
This is especially true for `gcc`, which takes several hours to build.
Before creating the `chroot`, add this to your `builder.conf`:
USE_QUBES_REPO_VERSION = $(RELEASE)
It will add the 'current' Qubes repository to your `chroot` environment.
This way, you can build only the packages you are interested in.
If you also want to use the 'current-testing' repository, add this to your configuration:
USE_QUBES_REPO_TESTING = 1
In the case of an existing `chroot`, for mock-enabled builds, it works immediately because `chroot` is constructed each time separately.
For legacy builds, it will not add the necessary configuration into the build environment unless a specific builder change or configuration would force rebuilding chroot.
Also, once enabled, disabling this setting will not disable repositories in relevant chroots.
And even if it did, there could be leftover packages installed from those repos (which may or may not be desirable).
Code verification keys management
---------------------------------

36
common-tasks/backup-emergency-restore-v4.md
View File

@ -39,11 +39,11 @@ uses an RPM-based system (Fedora), but the same general procedure should work on
any GNU/Linux system.
1. If you're not on Qubes 4.X, [get and verify the Release 4 Signing Key].
2. If you're not on Qubes 4.X, import the Release 4 Signing Key:
2. If you're not on Qubes 4.X, import the Release 4 Signing Key.
[user@restore ~]$ sudo rpm --import qubes-release-4-signing-key.asc
3. Download the `scrypt` RPM:
3. Download the `scrypt` RPM.
[user@restore ~]$ dnf download scrypt
@ -51,7 +51,7 @@ any GNU/Linux system.
[user@restore ~]$ curl -O https://yum.qubes-os.org/r4.0/current/vm/fc28/rpm/scrypt-1.2.1-1.fc28.x86_64.rpm
4. Verify the signature on the `scrypt` RPM:
4. Verify the signature on the `scrypt` RPM.
[user@restore ~]$ rpm -K scrypt-*.rpm
scrypt-*.rpm: digests signatures OK
@ -59,15 +59,15 @@ any GNU/Linux system.
The message `digests signatures OK` means that both the digest (i.e., the
output of a hash function) and PGP signature verification were successful.
5. Install `rpmdevtools`:
5. Install `rpmdevtools`.
[user@restore ~]$ sudo dnf install rpmdevtools
6. Extract the `scrypt` binary from the RPM:
6. Extract the `scrypt` binary from the RPM.
[user@restore ~]$ rpmdev-extract scrypt-*.rpm
7. (Optional) Create an alias for the new binary:
7. (Optional) Create an alias for the new binary.
[user@restore ~]$ alias scrypt="scrypt-*/usr/bin/scrypt"
@ -92,12 +92,24 @@ Emergency Recovery Instructions
vm1/whitelisted-appmenus.list.000.enc
dom0-home/dom0user.000.enc
**Note:** Each VM in the backup file has its path listed in
`qubes.xml.000.enc` (search for the `backup-path` property). You can
extract only the files necessary for your VM (`vmX`) with `tar -i -xvf
qubes-backup-2015-06-05T123456 backup-header backup-header.hmac vmX/`.
**To extract only specific VMs:** Each VM in the backup file has its path
listed in `qubes.xml.000.enc`. Decrypt it. (In this example, the password is
`password`.)
2. Set the backup passhprase environment variable. While this isn't strictly
[user@restore ~]$ cat backup-header | grep backup-id
backup-id=20190128T123456-1234
[user@restore ~]$ scrypt dec -P qubes.xml.000.enc qubes.xml.000
Please enter passphrase: 20190128T123456-1234!qubes.xml.000!password
[user@restore ~]$ tar -i -xvf qubes.xml.000
Now that you have the decrypted `qubes.xml.000` file, search for the
`backup-path` property inside of it. With the `backup-path`, extract only
the files necessary for your VM (`vmX`).
[user@restore ~]$ tar -i -xvf qubes-backup-2015-06-05T123456 \
backup-header backup-header.hmac vmX/
2. Set the backup passphrase environment variable. While this isn't strictly
required, it will be handy later and will avoid saving the passphrase in
the shell's history.
@ -176,7 +188,7 @@ Emergency Recovery Instructions
https://github.com/QubesOS/qubes-doc.git
[scrypt]: https://www.tarsnap.com/scrypt.html
[verify signatures]: https://www.qubes-os.org/security/verifying-signatures)
[verify signatures]: https://www.qubes-os.org/security/verifying-signatures
[get and verify the Release 4 Signing Key]: https://www.qubes-os.org/security/verifying-signatures/#2-get-the-release-signing-key
[Emergency Backup Recovery without Qubes (v2)]: https://www.qubes-os.org/doc/backup-emergency-restore-v2/
[Emergency Backup Recovery without Qubes (v3)]: https://www.qubes-os.org/doc/backup-emergency-restore-v3/

135
common-tasks/disposablevm.md
View File

@ -9,8 +9,7 @@ redirect_from:
- /wiki/DisposableVMs/
---
DisposableVMs
=============
# DisposableVMs #
A DisposableVM (previously known as a "DispVM") is a lightweight VM that can be created quickly and will disappear when closed.
DisposableVMs are usually created in order to host a single application, like a viewer, editor, or web browser.
@ -24,8 +23,7 @@ While running, DisposableVMs will appear in Qubes VM Manager with the name `disp
See [this article](https://blog.invisiblethings.org/2010/06/01/disposable-vms.html) for more on why one would want to use a DisposableVM.
Security
--------
## Security ##
If a [DVM Template] becomes compromised, then any DisposableVM based on that DVM Template could be compromised.
In particular, the *default* DVM Template is important because it is used by the "Open in DisposableVM" feature.
@ -40,8 +38,10 @@ For details, see [this thread](https://groups.google.com/d/topic/qubes-devel/QwL
When it is essential to avoid leaving any trace, consider using [Tails](https://tails.boum.org/).
DisposableVMs and Networking (R4.0 and later)
-----------------------------
## Qubes 4.0 ##
### DisposableVMs and Networking ###
Similarly to how AppVMs are based on their underlying [TemplateVM](https://www.qubes-os.org/doc/glossary/#templatevm), DisposableVMs are based on their underlying [DVM Template](https://www.qubes-os.org/doc/glossary/#dvm-template).
R4.0 introduces the concept of multiple DVM Templates, whereas R3.2 was limited to only one.
@ -85,11 +85,89 @@ Some DVM Templates will automatically create a menu item to launch a DVM, if you
To launch a DVM from the command line, in dom0 please type the following:
qvm-run --dispvm=NameOfDVM --service qubes.StartApp+NameOfApp
DisposableVMs and Networking (R3.2 and earlier)
-----------------------------
### Opening a file in a DisposableVM via GUI ###
In an AppVM's file manager, right click on the file you wish to open in a DisposableVM, then choose "Open in DisposableVM".
Wait a few seconds and the default application for this file type should appear displaying the file content.
This app is running in its own dedicated VM -- a DisposableVM created for the purpose of viewing or editing this very file.
Once you close the viewing application the whole DisposableVM will be destroyed.
If you have edited the file and saved the changes, the changed file will be saved back to the original AppVM, overwriting the original.
![r1-open-in-dispvm-1.png](/attachment/wiki/DisposableVms/r1-open-in-dispvm-1.png) ![r1-open-in-dispvm-2.png](/attachment/wiki/DisposableVms/r1-open-in-dispvm-2.png)
### Opening a fresh web browser instance in a new DisposableVM ###
Sometimes it is desirable to open an instance of Firefox within a new fresh DisposableVM.
This can be done easily using the Start Menu: just go to **Application Menu -\> DisposableVM -\> DisposableVM:Firefox web browser**.
Wait a few seconds until a web browser starts.
Once you close the viewing application the whole DisposableVM will be destroyed.
![r1-open-in-dispvm-3.png](/attachment/wiki/DisposableVms/r1-open-in-dispvm-3.png)
### Opening a file in a DisposableVM via command line (from AppVM) ###
Use the `qvm-open-in-dvm` command from a terminal in your AppVM:
~~~
[user@work-pub ~]$ qvm-open-in-dvm Downloads/apple-sandbox.pdf
~~~
Note that the `qvm-open-in-dvm` process will not exit until you close the application in the DisposableVM.
### Starting an arbitrary program in a DisposableVM from an AppVM ###
Sometimes it can be useful to start an arbitrary program in a DisposableVM. This can be done from an AppVM by running
~~~
[user@vault ~]$ qvm-run '$dispvm' xterm
~~~
The created DisposableVM can be accessed via other tools (such as `qvm-copy-to-vm`) using its `disp####` name as shown in the Qubes Manager or `qvm-ls`.
### Starting an arbitrary application in a DisposableVM via command line from dom0 ###
The Application Launcher has shortcuts for opening a terminal and a web browser in dedicated DisposableVMs, since these are very common tasks.
However, it is possible to start an arbitrary application in a DisposableVM directly from dom0 by running:
~~~
$ qvm-run --dispvm=dvm-template --service qubes.StartApp+xterm
~~~
The label color will be inherited from the `dvm-template`.
(The DisposableVM Application Launcher shortcut used for starting programs runs a very similar command to the one above.)
#### Opening a link in a DisposableVM based on a non-default DVM Template from a qube ####
Suppose that the default DVM Template for your `email` qube has no networking (e.g., so that untrusted attachments can't phone home).
However, sometimes you want to open email links in DisposableVMs.
Obviously, you can't use the default DVM Template, since it has no networking, so you need to be able to specify a different DVM Template.
You can do that with this command from the `email` qube (as long as your RPC policies allow it):
~~~
$ qvm-open-in-vm @dispvm:online-dvm-template https://www.qubes-os.org
~~~
This will create a new DisposableVM based on `online-dvm-template`, open the default web browser in that DisposableVM, and navigate to `https://www.qubes-os.org`.
### Customizing DisposableVMs ###
You can change the template used to generate the DisposableVMs, and change settings used in the DisposableVM savefile.
These changes will be reflected in every new DisposableVM based on that template.
Full instructions can be found [here](/doc/disposablevm-customization/).
## Qubes 3.2 ##
### DisposableVMs and Networking ###
NetVM and firewall rules for DisposableVMs can be set as they can for a normal VM.
By default a DisposableVM will inherit the NetVM and firewall settings of the VM from which it is launched.
@ -102,8 +180,8 @@ By default the DVM template is called `fedora-XX-dvm` (where `XX` is the Fedora
As an "internal" VM it is hidden in Qubes VM Manager, but can be shown by selecting "Show/Hide internal VMs".
Note that changing the "NetVM for DisposableVM" setting for the DVM Template does *not* affect the NetVM of DisposableVMs launched from the Start Menu; only changing the DVM Template's own NetVM does.
Opening a file in a DisposableVM via GUI
-----------------------------------------
### Opening a file in a DisposableVM via GUI ###
In an AppVM's file manager, right click on the file you wish to open in a DisposableVM, then choose "Open in DisposableVM".
Wait a few seconds and the default application for this file type should appear displaying the file content.
@ -113,8 +191,8 @@ If you have edited the file and saved the changes, the changed file will be save
![r1-open-in-dispvm-1.png](/attachment/wiki/DisposableVms/r1-open-in-dispvm-1.png) ![r1-open-in-dispvm-2.png](/attachment/wiki/DisposableVms/r1-open-in-dispvm-2.png)
Opening a fresh web browser instance in a new DisposableVM
-----------------------------------------------------------
### Opening a fresh web browser instance in a new DisposableVM ###
Sometimes it is desirable to open an instance of Firefox within a new fresh DisposableVM.
This can be done easily using the Start Menu: just go to **Application Menu -\> DisposableVM -\> DisposableVM:Firefox web browser**.
@ -123,8 +201,8 @@ Once you close the viewing application the whole DisposableVM will be destroyed.
![r1-open-in-dispvm-3.png](/attachment/wiki/DisposableVms/r1-open-in-dispvm-3.png)
Opening a file in a DisposableVM via command line (from AppVM)
---------------------------------------------------------------
### Opening a file in a DisposableVM via command line (from AppVM) ###
Use the `qvm-open-in-dvm` command from a terminal in your AppVM:
@ -134,8 +212,8 @@ Use the `qvm-open-in-dvm` command from a terminal in your AppVM:
Note that the `qvm-open-in-dvm` process will not exit until you close the application in the DisposableVM.
Starting an arbitrary program in a DisposableVM from an AppVM
--------------------------------------------------------------
### Starting an arbitrary program in a DisposableVM from an AppVM ###
Sometimes it can be useful to start an arbitrary program in a DisposableVM. This can be done from an AppVM by running
@ -145,26 +223,21 @@ Sometimes it can be useful to start an arbitrary program in a DisposableVM. This
The created DisposableVM can be accessed via other tools (such as `qvm-copy-to-vm`) using its `disp####` name as shown in the Qubes Manager or `qvm-ls`.
Starting an arbitrary application in a DisposableVM via command line (from Dom0)
---------------------------------------------------------------------------------
The Start Menu has shortcuts for opening a terminal and a web browser in dedicated DisposableVMs, since these are very common tasks.
However, it is possible to start an arbitrary application in a DisposableVM directly from Dom0 by running
### Starting an arbitrary application in a DisposableVM via command line (from Dom0) ###
The Application Launcher has shortcuts for opening a terminal and a web browser in dedicated DisposableVMs, since these are very common tasks.
However, it is possible to start an arbitrary application in a DisposableVM directly from dom0 by running:
R4.0 (border colour will be inherited from that set in the `dispvm-template`)
~~~
[joanna@dom0 ~]$ qvm-run --dispvm=dispvm-template --service qubes.StartApp+xterm
$ echo xterm | /usr/lib/qubes/qfile-daemon-dvm qubes.VMShell dom0 DEFAULT red
~~~
R3.2 (border colour can be specified in the command)
~~~
[joanna@dom0 ~]$ echo xterm | /usr/lib/qubes/qfile-daemon-dvm qubes.VMShell dom0 DEFAULT red
~~~
The label color will be inherited from the `dvm-template`.
(The DisposableVM Application Launcher shortcut used for starting programs runs a very similar command to the one above.)
(The DisposableVM appmenu used for starting Firefox runs a very similar command to the one above.)
Customizing DisposableVMs
--------------------------
### Customizing DisposableVMs ###
You can change the template used to generate the DisposableVMs, and change settings used in the DisposableVM savefile.
These changes will be reflected in every new DisposableVM based on that template.

20
common-tasks/optical-discs.md Normal file
View File

@ -0,0 +1,20 @@
---
layout: doc
title: Optical Discs
permalink: /doc/optical-discs/
redirect_from:
- /doc/recording-optical-discs/
- /en/doc/recording-optical-discs/
---
Optical Discs
=============
Passthrough reading and recording (a.k.a., "burning") are not supported by Xen.
Currently, the only options for reading and recording optical discs (e.g., CDs, DVDs, BRDs) in Qubes are:
1. Use a USB optical drive.
2. Attach a SATA optical drive to a secondary SATA controller, then assign this secondary SATA controller to a VM.
3. Use a SATA optical drive attached to dom0.
(**Caution:** This option is [potentially dangerous](/doc/security-guidelines/#dom0-precautions).)

22
common-tasks/recording-optical-discs.md
View File

@ -1,22 +0,0 @@
---
layout: doc
title: Recording Optical Discs
permalink: /doc/recording-optical-discs/
redirect_from: /en/doc/recording-optical-discs/
---
Recording Optical Discs
=======================
Passthrough recording (a.k.a., "burning") is not supported by Xen. Currently,
the only options for recording optical discs (e.g., CDs, DVDs, BRDs) in Qubes
are:
1. Use a USB optical drive.
2. Attach a SATA optical drive to a secondary SATA controller, then assign this
secondary SATA controller to a VM.
3. Use a SATA optical drive attached to dom0.
(**Caution:** This option may violate the Qubes security model if it entails
transferring untrusted data (e.g., an ISO) to dom0 in order to record it on
an optical disc.)

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

@ -46,7 +46,7 @@ Preventing data leaks
---------------------
First make sure to read [Understanding and Preventing Data Leaks](/doc/data-leaks/) section to understand the limits of this tip.
Suppose that you have within a not so trusted enviroment - for example, a Windows VM - an application that tracks and reports its usage, or you simply want to protect your data.
Suppose that you have within a not so trusted environment - for example, a Windows VM - an application that tracks and reports its usage, or you simply want to protect your data.
Start the Windows TemplateVM (which has no user data), install/upgrade apps; then start Windows AppVM (with data) in offline mode. So, if you worry (hypothetically) that your Windows or app updater might want to send your data away, this Qubes OS trick will prevent this.
This applies also to any TemplateBasedVM relative to its parent TemplateVM, but the privacy risk is especially high in the case of Windows.

2
configuration/assigning-devices.md
View File

@ -13,7 +13,7 @@ Assigning Devices to VMs in R3.2
(In case you were looking for the [R4.0 documentation](/doc/pci-devices/).)
Sometimes you may need to assign an entire PCI or PCI Express device directly to a qube.
This is also known as PCI pass-through.
This is also known as PCI passthrough.
The Qubes installer does this by default for `sys-net` (assigning all network class controllers), as well as `sys-usb` (assigning all USB controllers) if you chose to create the USB qube during install.
While this covers most use cases, there are some occasions when you may want to manually assign one NIC to `sys-net` and another to a custom NetVM, or have some other type of PCI controller you want to manually assign.

2
configuration/disk-trim.md
View File

@ -9,7 +9,7 @@ redirect_from:
---
Disk Trim
----------
=========
Disk trimming is the procedure by which the operating system informs the underlying storage device of which storage blocks are no longer in use.
It does this by issuing an `ATA_TRIM` command for the block. This is also known as a `discard`.

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

@ -11,8 +11,8 @@ VM kernel managed by dom0
By default, VMs kernels are provided by dom0. This means that:
1. You can select the kernel version in VM settings;
2. You can modify kernel options in VM settings;
1. You can select the kernel version (using GUI VM Settings tool or `qvm-prefs` commandline tool);
2. You can modify kernel options (using `qvm-prefs` commandline tool);
3. You can **not** modify any of the above from inside a VM;
4. Installing additional kernel modules is cumbersome.
@ -48,6 +48,14 @@ updatevm : sys-firewall
[user@dom0 ~]$ qubes-prefs -s default-kernel 3.19.fc20
~~~
To view kernel options, you can use the GUI VM Settings tool; to view and change them, use `qvm-prefs` commandline tool:
~~~
[user@dom0 ~]$ qvm-prefs -g work kernelopts
nopat
[user@dom0 ~]$ qvm-prefs -s work kernelopts "nopat apparmor=1 security=apparmor"
~~~
Installing different kernel using Qubes kernel package
----------------------------------
@ -207,6 +215,18 @@ mke2fs 1.42.12 (29-Aug-2014)
--> Done.
~~~
Kernel files structure
-----------------------
Kernel for a VM is stored in `/var/lib/qubes/vm-kernels/KERNEL_VERSION` directory (`KERNEL_VERSION` replaced with actual version). Qubes 4.x supports the following files there:
- `vmlinuz` - kernel binary (may not be a Linux kernel)
- `initramfs` - initramfs for the kernel to load
- `modules.img` - ext4 filesystem image containing Linux kernel modules (to be mounted at `/lib/modules`); additionally it should contain a copy of `vmlinuz` and `initramfs` in its root directory (for loading by qemu inside stubdomain)
- `default-kernelopts-common.txt` - default kernel options, in addition to those specified with `kernelopts` qube property (can be disabled with `no-default-kernelopts` feature)
All the files besides `vmlinuz` are optional.
Using kernel installed in the VM (R4.0)
--------------------------------

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

@ -47,7 +47,7 @@ An option is available in the AppVM Settings to enable setting the NetVM in brid
NetVM patch (Qubes R2B2)
------------------------
You need to modify manually the NetVM iptable script inside the NetVM. The reason is that by default the NetVM only accepts traffic coming from network interfaces called vif\* (in our case, we will use an additional interface called bridge0. The second reason is that all trafic is NATed by default. In our case, we want to forward traffic from the bridge interface without modifying it, while NATing traffic coming from vif\* interfaces.
You need to modify manually the NetVM iptable script inside the NetVM. The reason is that by default the NetVM only accepts traffic coming from network interfaces called vif\* (in our case, we will use an additional interface called bridge0. The second reason is that all traffic is NATed by default. In our case, we want to forward traffic from the bridge interface without modifying it, while NATing traffic coming from vif\* interfaces.
Modify manually the Template you use for your NetVM (not the NetVM itself). This is by default fedora-x86\_64. Edit the file /etc/sysconfig/iptables. You need to modify two parts of the file.

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

@ -15,40 +15,19 @@ Resize Disk Image
-----------------
There are several disk images which can be easily extended, but pay attention to the overall consumed space of your sparse/thin disk images.
In most cases, the GUI tool Qube Settings (available for every qube from the Start menu, and also in the Qube Manager) will allow you to easily increase maximum disk image size.
![vm-settings-disk-image.png](/attachment/wiki/DiskSize/vm-settings-disk-image.png)
In case of standalone qubes and templates, just change the Disk Storage settings above.
In case of template-based qubes, the private storage (the /home directory and user files) can be changed in the qube's own settings, but the system root image is [inherited from the template](/getting-started/#appvms-qubes-and-templatevms), and so it must be changed in the template settings.
If you are increasing the disk image size for Linux-based qubes installed from Qubes OS repositories in Qubes 4.0 or later, changing the settings above is all you need to do - in other cases, you may need to do more, according to instructions below.
See also [OS Specific Follow-up Instructions](/doc/resize-disk-image/#os-specific-follow-up-instructions) at the end of this page.
Since a TemplateBasedVM [inherits its system filesystem from the Template on which it is based](/getting-started/#appvms-qubes-and-templatevms), it is not possible to resize the system disk for a TemplateBasedVM.
### Resize disk image (R4.0)
### Template disk image (R4.0)
If you want install a lot of software in your TemplateVM, you may need to increase the amount of disk space your TemplateVM can use.
*Make sure changes in the TemplateVM between reboots don't exceed 10G.*
1. Resize the *root image* using Qubes version specific procedure below.
2. Start the template.
3. Resize the filesystem using OS appropriate tools (Qubes will handle this automatically under Linux).
4. Verify available space in the template using `df -h` or OS specific tools.
5. Shutdown the template.
### Template disk image (R3.2)
If you want install a lot of software in your TemplateVM, you may need to increase the amount of disk space your TemplateVM can use.
*Make sure changes in the TemplateVM between reboots don't exceed 10G.*
1. Make sure that all the VMs based on this template are shut down (including netvms etc).
2. Resize the *root image* using Qubes version specific procedure below.
3. If any netvm/proxyvm used by this template is based on it, set template's netvm to none.
4. Start the template.
5. Resize the filesystem using OS appropriate tools (Linux is `sudo resize2fs /dev/mapper/dmroot`).
6. Verify available space in the template using `df -h` or OS specific tools.
7. Shutdown the template.
8. Restore original netvm setting (if changed), and check firewall settings (setting netvm to none causes the firewall to reset to "block all")
### Expand disk image (R4.0)
1048576 MiB is the maximum size which can be assigned to storage through Qube Manager.
To grow the root or private disk image of an AppVM beyond this limit, `qvm-volume` can be used:
Use either GUI tool Qube Settings (`qubes-vm-settings`) or the CLI tool `qvm-volume`.
Maximum size which can be assigned through Qube Settings is 1048576 MiB - if you need more, use `qvm-volume`:
~~~
qvm-volume extend <vm_name>:root <size>
@ -60,6 +39,31 @@ qvm-volume extend <vm_name>:private <size>
Note: Size is the target size (i.e. 4096MB or 16GB, ...), not the size to add to the existing disk.
If you have run out of space for software in your Template, you need to increase *root image* of the Template (not private storage!).
**Make sure changes in the Template between reboots don't exceed 10G.**
It is recommended to restart (or start and then shutdown, if it is not running) the template after resizing the root image.
If you are **not** using Linux in the qube, you will also need to:
1. Start the template.
2. Resize the filesystem using OS appropriate tools.
3. Verify available space in the template using `df -h` or OS specific tools.
4. Shutdown the template.
### Template disk image (R3.2)
If you want install a lot of software in your TemplateVM, you may need to increase the amount of disk space your TemplateVM can use.
*Make sure changes in the TemplateVM between reboots don't exceed 10G.*
1. Make sure that all the VMs based on this template are shut down (including netvms etc).
2. Resize the *root image* using the procedure below.
3. If any netvm/proxyvm used by this template is based on it, set template's netvm to none.
4. Start the template.
5. Resize the filesystem using OS appropriate tools (Linux is `sudo resize2fs /dev/mapper/dmroot`).
6. Verify available space in the template using `df -h` or OS specific tools.
7. Shutdown the template.
8. Restore original netvm setting (if changed), and check firewall settings (setting netvm to none causes the firewall to reset to "block all")
### Expand disk image (R3.2)
1048576 MB is the maximum size which can be assigned to storage through Qubes Manager.
@ -78,8 +82,8 @@ Note: Size is the target size (i.e. 4096MB or 16GB, ...), not the size to add to
### Resize a StandaloneVM Root Image
For more flexibility, you may also turn your TemplateVM into a StandaloneVM.
Doing this means it will have its own root filesystem *(StandaloneVMs use a copy of the template, instead of smart sharing)*.
For more flexibility, you may also turn your Template into a Standalone qube.
Doing this means it will have its own root filesystem *(Standalone qubes use a copy of the template, instead of smart sharing)*.
To do this run `qvm-create --standalone` from `dom0` console, then perform the [OS Specific Follow-up Instructions](/doc/resize-disk-image/#os-specific-follow-up-instructions) below.
### Shrinking a disk image
@ -94,7 +98,8 @@ Note that we don't want to touch the VM filesystem directly in dom0 for security
OS Specific Follow-up Instructions
-----------------
After expanding volumes, the partition table and file-system may need to be adjusted.
In the case of Linux-based qubes installed from Qubes repositories, no further actions are required.
In some other cases, after expanding volumes, the partition table and file-system may need to be adjusted.
Use tools appropriate to the OS in your qube.
Brief instructions for Windows 7, FreeBSD, and Linux are provided below.
@ -118,6 +123,6 @@ zpool online -e poolname ada0
#### Linux
Qubes will automatically grow the filesystem for you on AppVMs but not HVMs (or Template root images on R3.2).
You will see that there is unallocated free space at the end of your primary disk.
Qubes will automatically grow the filesystem for you on all AppVMs with Qubes packages installed (which are all AppVMs installed from templates, cloned from templates etc. - if you have not created an empty HVM and installed a Linux distribution in it, without using Qubes repositories, you are almost certainly safe).
Otherwise, you will see that there is unallocated free space at the end of your primary disk.
You can use standard linux tools like `fdisk` and `resize2fs` to make this space available.

2
configuration/vpn.md
View File

@ -80,6 +80,8 @@ Set up a ProxyVM as a VPN gateway using NetworkManager
# (in case the vpn tunnel breaks)
iptables -I FORWARD -o eth0 -j DROP
iptables -I FORWARD -i eth0 -j DROP
ip6tables -I FORWARD -o eth0 -j DROP
ip6tables -I FORWARD -i eth0 -j DROP
```
6. Configure your AppVMs to use the new VM as a NetVM.

12
customization/bind-dirs.md
View File

@ -65,16 +65,22 @@ Creation of the file and folders in /rw/bind-dirs should be automatic the first
If you want to circumvent this process, you can create the relevant filestructure under /rw/bind-dirs and make any changes at the same time that you perform the configuration, before reboot.
## Limitations ##
* Files that exist in the TemplateVM root image cannot be deleted in the TemplateBasedVMs root image using bind-dirs.sh.
* Re-running `sudo /usr/lib/qubes/bind-dirs.sh` without a previous `sudo /usr/lib/qubes/bind-dirs.sh umount` does not work.
* Running `sudo /usr/lib/qubes/bind-dirs.sh umount` after boot (before shutdown) is probably not sane and nothing can be done about that.
* Many editors create a temporary file and copy it over the original file. If you have bind mounted an individual file this will break the mount.
Any changes you make will not survive a reboot. If you think it likely you will want to edit a file, then either include the parent directory in bind-dirs.rather than the file, or perform the file operation on the file in /rw/bind-dirs.
* Some files are altered when a qube boots - e.g. /etc/hosts. If you try to use bind-dirs on such files you may break your qube in unpredictable ways.
Any changes you make will not survive a reboot. If you think it likely you will want to edit a file, then either include the parent directory in bind-dirs rather than the file, or perform the file operation on the file in /rw/bind-dirs.
* Some files are altered when a qube boots - e.g. `/etc/hosts`. If you try to use bind-dirs on such files you may break your qube in unpredictable ways.
You can add persistent rules to `/etc/hosts` file using script `/rw/config/rc.local` that is designed to override configuration in /etc, starting services and etc. For example, to make software inside some TemplateBasedVM resolving the domain `example.com` as `127.0.0.1` open `/rw/config/rc.local` inside this TemplateBasedVM and add:
~~~
echo '127.0.0.1 example.com' >> /etc/hosts
~~~
After every boot of the TemplateBasedVM `rc.local` script will add line `127.0.0.1 example.com` to `/etc/hosts` file and the software inside the TemplateBasedVM will resolve domain `example.com` accordingly. You cam add several rules to `/etc/hosts` the same way.
## How to remove binds from bind-dirs.sh? ##

24
customization/disposablevm-customization.md
View File

@ -18,14 +18,16 @@ Security
If a DVM Template becomes compromised, then any DisposableVM based on that DVM Template could be compromised.
Therefore, you should not make any risky customizations (e.g., installing untrusted browser plugins) in important DVM Templates.
In particular, the *default* DVM Template is important becuase it is used by the "Open in DisposableVM" feature.
In particular, the *default* DVM Template is important because it is used by the "Open in DisposableVM" feature.
This means that it will have access to everything that you open with this feature.
For this reason, it is strongly recommended that you base the default DVM Template on a trusted TemplateVM and refrain from making any risky customizations to it.
Qubes 4.0
----------
A DisposableVM (previously known as a "DispVM") in Qubes 4.0 can be based on any TemplateBasedVM. You can also choose to use different AppVMs for different DisposableVMs. To prepare AppVM to be a base for DisposableVM, you need to set `template_for_dispvms` property, for example:
A DisposableVM (previously known as a "DispVM") in Qubes 4.0 can be based on any TemplateBasedVM.
You can also choose to use different DVM Templates for different DisposableVMs.
To prepare AppVM to be a DVM Template, you need to set `template_for_dispvms` property, for example:
[user@dom0 ~]$ qvm-prefs fedora-26-dvm template_for_dispvms True
@ -33,7 +35,7 @@ Additionally, if you want to have menu entries for starting applications in Disp
[user@dom0 ~]$ qvm-features fedora-26-dvm appmenus-dispvm 1
### Creating new DisposableVM base AppVM ###
### Creating a new DVM Template ###
In Qubes 4.0, you're no longer restricted to a single DVM Template. Instead, you can create as many as you want. Whenever you start a new DisposableVM, you can choose to base it on whichever DVM Template you like.
To create new DVM Template, lets say `custom-dvm`, based on `debian-9` template, use following commands:
@ -53,9 +55,10 @@ If you wish to use the `fedora-minimal` template as a DVM Template, see the "DVM
### Customization of DisposableVM ###
It is possible to change the settings for each new DisposableVM. This can be done by customizing the base AppVM:
It is possible to change the settings for each new DisposableVM.
This can be done by customizing the DVM Template on which it is based:
1. Start a terminal in the `fedora-26-dvm` qube (or another base for DisposableVM) by running the following command in a dom0 terminal. (If you enable `appmenus-dispvm` feature (as explained at the top), applications menu for this VM (`fedora-26-dvm`) will be "Disposable: fedora-26-dvm" (instead of "Domain: fedora-26-dvm") and entries there will start new DisposableVM based on that VM (`fedora-26-dvm`). Not in that VM (`fedora-26-dvm`) itself).
1. Start a terminal in the `fedora-26-dvm` qube (or another DVM Template) by running the following command in a dom0 terminal. (If you enable `appmenus-dispvm` feature (as explained at the top), applications menu for this VM (`fedora-26-dvm`) will be "Disposable: fedora-26-dvm" (instead of "Domain: fedora-26-dvm") and entries there will start new DisposableVM based on that VM (`fedora-26-dvm`). Not in that VM (`fedora-26-dvm`) itself).
[user@dom0 ~]$ qvm-run -a fedora-26-dvm gnome-terminal
@ -143,7 +146,7 @@ Using DisposableVMs in this manner is ideal for untrusted qubes which require pe
>_**Note:**_ Users who want customized VPN or firewall rule sets must create a separate dvm for use by each DisposableVM. If dvm customization is not needed, then a single dvm is used as a template for all DisposableVMs.
#### Create and configure the dvm from which the DisposableVM will be based on ####
#### Create and configure the DVM Template on which the DisposableVM will be based ####
1. Create the dvm
@ -247,6 +250,15 @@ Using DisposableVMs in this manner is ideal for untrusted qubes which require pe
7. Users should now follow instructions on [How to hide USB controllers from dom0](/doc/usb/#how-to-hide-all-usb-controllers-from-dom0)
8. At this point, your mouse may not work.
Edit the `qubes.InputMouse` policy file in dom0, which is located here:
/etc/qubes-rpc/policy/qubes.InputMouse
Add a line like this to the top of the file:
disp-sys-usb dom0 allow,user=root
#### Starting the DisposableVMs ####

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

@ -156,9 +156,9 @@ Choose theme packages for each framework. I recommend the following documentatio
> clearlooks-phenix-gtk2-theme clearlooks-phenix-gtk3-theme
You can search for other themes using dnf search theme gtk
You can search for other themes using `dnf search theme gtk`.
You can check your currently installed theme packages (to eventually remove them) using rpm -qa | grep theme
You can check your currently installed theme packages (to eventually remove them) using `rpm -qa | grep theme`.
### Tweaking theme and appearance

94
doc.md
View File

@ -14,11 +14,10 @@ redirect_from:
- /community/
---
User Documentation
==================
## User Documentation
### The Basics
The Basics
----------
* [What is Qubes OS?](/intro/)
* [Video Tours](/video-tours/)
* [Screenshots](/screenshots/)
@ -27,8 +26,8 @@ The Basics
* [Help, Support, and Mailing Lists](/support/)
* [How to Contribute](/doc/contributing/)
Security Information
--------------------
### Security Information
* [Security Center](/security/)
* [Security FAQ](/faq/#general--security)
* [Security Pack](/security/pack/)
@ -38,14 +37,14 @@ Security Information
* [Why and How to Verify Signatures](/security/verifying-signatures/)
* [Qubes PGP Keys](https://keys.qubes-os.org/keys/)
Choosing Your Hardware
----------------------
### Choosing Your Hardware
* [System Requirements](/doc/system-requirements/)
* [Certified Hardware](/doc/certified-hardware/)
* [Hardware Compatibility List (HCL)](/hcl/)
Installing & Upgrading Qubes
----------------------------
### Installing & Upgrading Qubes
* [Qubes Downloads](/downloads/)
* [Qubes Download Mirrors](/downloads/mirrors/)
* [Installation Guide](/doc/installation-guide/)
@ -58,29 +57,30 @@ Installing & Upgrading Qubes
* [Custom Installation](/doc/custom-install/)
* [Testing new releases and updates](/doc/testing/)
Common Tasks
------------
### Common Tasks
* [Copying and Pasting Text Between Domains](/doc/copy-paste/)
* [Copying and Moving Files Between Domains](/doc/copying-files/)
* [Copying from (and to) dom0](/doc/copy-from-dom0/)
* [Installing and Updating Software in dom0](/doc/software-update-dom0/)
* [Installing and Updating Software in VMs](/doc/software-update-vm/)
* [Backup, Restoration, and Migration](/doc/backup-restore/)
* [Using Disposable VMs](/doc/disposablevm/)
* [Using DisposableVMs](/doc/disposablevm/)
* [Using and Managing USB Devices in R3.2](/doc/usb/)
* [Using Block or Storage Devices in Qubes R4.0](/doc/block-devices/)
* [Using USB Devices in Qubes R4.0](/doc/usb-devices)
* [Recording Optical Discs](/doc/recording-optical-discs/)
* [Optical Discs](/doc/optical-discs/)
* [Managing Application Shortcuts](/doc/managing-appvm-shortcuts/)
* [Enabling Fullscreen Mode](/doc/full-screen-mode/)
* [Tips and Tricks](/doc/tips-and-tricks/)
Managing Operating Systems within Qubes
---------------------------------------
### Managing Operating Systems within Qubes
* [TemplateVMs](/doc/templates/)
* [Templates: Fedora](/doc/templates/fedora/)
* [Templates: Fedora Minimal](/doc/templates/fedora-minimal/)
* [Templates: Debian](/doc/templates/debian/)
* [Templates: Debian Minimal](/doc/templates/debian-minimal/)
* [Templates: Archlinux](/doc/templates/archlinux/)
* [Templates: Ubuntu](/doc/templates/ubuntu/)
* [Templates: Whonix](/doc/whonix/)
@ -95,8 +95,8 @@ Managing Operating Systems within Qubes
* [How to Reinstall a TemplateVM](/doc/reinstall-template/)
Security Guides
---------------
### Security Guides
* [Qubes OS Project Security Information](/security/)
* [Security Guidelines](/doc/security-guidelines/)
* [Understanding Qubes Firewall](/doc/firewall/)
@ -112,8 +112,8 @@ Security Guides
* [Note regarding password-less root access in VM](/doc/vm-sudo/)
Privacy Guides
--------------
### Privacy Guides
* [Whonix for Privacy & Anonymity](/doc/whonix/)
* [Running Tails in Qubes](/doc/tails/)
* [Anonymizing your MAC Address](/doc/anonymizing-your-mac-address/)
@ -122,8 +122,8 @@ Privacy Guides
* [Reducing the fingerprint of the text-based web browser w3m](/doc/w3m/)
Configuration Guides
--------------------
### Configuration Guides
* [Configuration Files](/doc/config-files/)
* [How to set up a ProxyVM as a VPN Gateway](/doc/vpn/)
* [Storing AppVMs on Secondary Drives](/doc/secondary-storage/)
@ -151,9 +151,9 @@ Configuration Guides
* [How to Make a Multimedia TemplateVM](/doc/multimedia/)
Customization Guides
--------------------
* [DispVM Customization](/doc/dispvm-customization/)
### Customization Guides
* [DisposableVM Customization](/doc/disposablevm-customization/)
* [Customizing Fedora minimal templates](/doc/fedora-minimal-template-customization/)
* [Customizing Windows 7 templates](/doc/windows-template-customization/)
* [Using KDE in dom0](/doc/kde/)
@ -166,8 +166,8 @@ Customization Guides
* [Safely Removing TemplateVM Packages (Example: Thunderbird)](/doc/removing-templatevm-packages/)
Troubleshooting
---------------
### Troubleshooting
* [Home directory is out of disk space error](/doc/out-of-memory/)
* [Newer hardware doesn't work](/doc/newer-hardware-troubleshooting/)
* [Installing on system with new AMD GPU (missing firmware problem)](https://groups.google.com/group/qubes-devel/browse_thread/thread/e27a57b0eda62f76)
@ -182,8 +182,8 @@ Troubleshooting
* [Intel Integrated Graphics Troubleshooting](/doc/intel-igfx-troubleshooting/)
Reference Pages
---------------
### Reference Pages
* [Command-Line Tools: Qubes 3.2, dom0](/doc/tools/3.2/dom0/)
* [Command-Line Tools: Qubes 3.2, domU](/doc/tools/3.2/domU/)
* [Command-Line Tools: Qubes 4.0, dom0](/doc/tools/4.0/dom0/)
@ -194,18 +194,17 @@ Reference Pages
* [Command Execution in VMs (and Qubes RPC)](/doc/qrexec/)
Presentation Slides
-------------------
### 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
=======================
## Developer Documentation
### The Basics
The Basics
----------
* [Developer FAQ](/faq/#developers)
* [Report a Security Issue](/security/)
* [Report a Bug](/doc/reporting-bugs/)
@ -218,12 +217,13 @@ The Basics
* [Documentation Guidelines](/doc/doc-guidelines/)
* [Code Signing](/doc/code-signing/)
* [Community-Developed Feature Tracker](/qubes-issues/)
* [Google Summer of Code](/gsoc/)
* [Books for Developers](/doc/devel-books/)
* [Style Guide](/doc/style-guide/)
* [Usability & UX](/doc/usability-ux/)
Security Information
--------------------
### Security Information
* [Security Center](/security/)
* [Security FAQ](/faq/#general--security)
* [Security Pack](/security/pack/)
@ -236,8 +236,8 @@ Security Information
* [Why and How to Verify Signatures](/security/verifying-signatures/)
* [Qubes PGP Keys](http://keys.qubes-os.org/keys/)
System
------
### System
* [Qubes OS Architecture Overview](/doc/architecture/)
* [Qubes OS Architecture Spec v0.3 [PDF]](/attachment/wiki/QubesArchitecture/arch-spec-0.3.pdf)
* [Security-critical Code in Qubes OS](/doc/security-critical-code/)
@ -251,16 +251,16 @@ System
* [Implementation of template sharing and updating](/doc/template-implementation/)
* [Storage Pools](/doc/storage-pools/)
Services
--------
### Services
* [Inter-domain file copying](/doc/qfilecopy/) (deprecates [`qfileexchgd`](/doc/qfileexchgd/))
* [Dynamic memory management in Qubes](/doc/qmemman/)
* [Implementation of DisposableVMs](/doc/dvm-impl/)
* [Article about DisposableVMs](http://theinvisiblethings.blogspot.com/2010/06/disposable-vms.html)
* [Dom0 secure update mechanism](/doc/dom0-secure-updates/)
Debugging
---------
### Debugging
* [Profiling python code](/doc/profiling/)
* [Test environment in separate machine for automatic tests](/doc/test-bench/)
* [Automated tests](/doc/automated-tests/)
@ -268,8 +268,8 @@ Debugging
* [Debugging Windows VMs](/doc/windows-debugging/)
* [Safe Remote Dom0 Terminals](/doc/safe-remote-ttys/)
Building
--------
### Building
* [Building Qubes](/doc/qubes-builder/) (["API" Details](/doc/qubes-builder-details/))
* [Development Workflow](/doc/development-workflow/)
* [Building Qubes OS ISO](/doc/qubes-r3-building/)
@ -279,8 +279,8 @@ Building
* [Building the Whonix Templates](/doc/building-whonix-template/)
* [How to compile kernels for dom0](https://groups.google.com/d/topic/qubes-users/yBeUJPwKwHM/discussion)
Releases
--------
### Releases
* [Release notes](/doc/releases/notes/)
* [Release schedules](/doc/releases/schedules/)
* [Release checklist](/doc/releases/todo/)

182
installing/custom-install.md
View File

@ -9,39 +9,179 @@ redirect_from:
Custom Installation
===================
In the present context, "custom installation" refers to things like manual
partitioning, setting up LVM and RAID, and manual LUKS encryption configuration.
In the present context, "custom installation" refers to things like manual partitioning, setting up LVM and RAID, and manual LUKS encryption configuration.
Installer Defaults (R3.2)
-------------------------
## Qubes 4.0
### Installer Defaults
For reference, these are the typical defaults for a single disk with legacy boot:
~~~
Mount Point: /boot
Desired Capacity: 1024 MiB
Device Type: Standard Partition
File System: ext4
Name: (none)
Mount Point: /
Desired Capacity: (your choice)
Device Type: LVM Thin Provisioning
Volume Group: qubes_dom0
File System: ext4
Name: root
Mount Point: (none)
Desired Capacity: 10 GiB
Device Type: LVM
Volume Group: qubes_dom0
File System: swap
Name: swap
~~~
~~~
SUMMARY OF CHANGES
Order Action Type Device Mount point
1 Destroy Format Unknown Disk (sda)
2 Create Format partition table (MSDOS) Disk (sda)
3 Create Device partition sda1 on Disk
4 Create Format ext4 sda1 on Disk /boot
5 Create Device partition sda2 on Disk
6 Create Format LUKS sda2 on Disk
7 Create Device luks/dm-crypt luks-sda2
8 Create Format physical volume (LVM) luks-sda2
9 Create Device lvmvg qubes_dom0
10 Create Device lvmthinpool qubes_dom0-pool00
11 Create Device lvmthinlv qubes_dom0-root
12 Create Device lvmlv qubes_dom0-swap
13 Create Format swap qubes_dom0-swap
14 Create Format ext4 qubes_dom0-root /
~~~
### Typical Partition Schemes
If you want your partition/LVM scheme to look like the Qubes default but with a few tweaks, follow this example.
With a single disk, the result should look something like this:
~~~
NAME SIZE TYPE MOUNTPOINT
sda disk
├──sda1 1G part /boot
└──sda2 part
└──luks-<UUID> crypt
├──qubes_dom0-pool00_tmeta lvm
├──qubes_dom0-pool00_tdata lvm
└──qubes_dom0-swap lvm [SWAP]
~~~
### Encryption Defaults
By default, `cryptsetup 1.7.5` will create a LUKS/dm-crypt volume as follows:
~~~
Version: 1
Cipher name: aes
Cipher mode: xts-plain64
Hash spec: sha256
~~~
~~~
$ cryptsetup --help
[...]
Default compiled-in device cipher parameters:
loop-AES: aes, Key 256 bits
plain: aes-cbc-essiv:sha256, Key: 256 bits, Password hashing: ripdemd160
LUKS1: aes-xts-plain64, Key: 256 bits, LUKS header hashing: sha256, RNG: /dev/urandom
~~~
This means that, by default, Qubes inherits these upstream defaults:
- AES-128 [[1]][cryptsetup-faq][[2]][dm-crypt][[3]][tomb-238]
- SHA-256
- `/dev/urandom`
- probably an `iter-time` of one second
If, instead, you'd like to use AES-256, SHA-512, `/dev/random`, and a longer `iter-time`, for example, you can configure encryption manually by following the instructions below.
### Example: Custom LUKS Configuration
Boot into the Qubes installer, then press `ctrl`+`alt`+`F2` to get a virtual console.
1. (Optional) Wipe the disk:
# dd if=/dev/zero of=/dev/sda bs=1M status=progress && sync
2. Create partitions:
# fdisk /dev/sda
Follow the steps to create two partitions:
- ~500MiB-1GiB for `/boot`
- The rest for `/` (might want to leave some for overprovisioning if it's an SSD)
4. Create LUKS encrypted volume:
# cryptsetup -v --hash sha512 --cipher aes-xts-plain64 --key-size 512 --use-random --iter-time 10000 --verify-passphrase luksFormat /dev/sda2
5. Open encrypted volume:
# cryptsetup open /dev/sda2 luks
6. Create LVM volumes:
# pvcreate /dev/mapper/luks
# vgcreate qubes_dom0 /dev/mapper/luks
# lvcreate -n swap -L 10G qubes_dom0
# lvcreate -T -l +100%FREE qubes_dom0/pool00
# lvcreate -V1G -T qubes_dom0/pool00 -n root
# lvextend -L <size_of_pool00> /dev/qubes_dom0/root
8. Proceed with the installer.
At the disk selection screen, select:
[x] I will configure partitioning.
[ ] Encrypt my data.
Decrypt your partition, then assign `/`, `/boot`, and `swap`.
Proceed normally from there.
## Qubes 3.2
### Installer Defaults
For reference, these are the defaults for a single disk:
~~~
Mount Point: `/`
Mount Point: /
Desired Capacity: (your choice)
Device Type: `LVM`
Volume Group: `qubes_dom0`
File System: `ext4`
Name: `root`
Device Type: LVM
Volume Group: qubes_dom0
File System: ext4
Name: root
Mount Point: `/boot`
Mount Point: /boot
Desired Capacity: 500 MiB (recommended)
Device Type: Standard Partition
File System: `ext4`
File System: ext4
Mount Point: (none)
Desired Capacity: 9.44 GiB (recommended)
Device Type: LVM
Volume Group: qubes_dom0
File System: `swap`
Name: `swap`
File System: swap
Name: swap
~~~
Typical Partition Schemes
-------------------------
### Typical Partition Schemes
If you want your partition/LVM scheme to look like the Qubes default but
with a few tweaks, follow these examples. With a single disk, the result
@ -80,8 +220,7 @@ If you're using `mdadm` software RAID, it should look something like this:
~~~
Example: LVM on LUKS on RAID (R3.2)
-----------------------------------
### Example: LVM on LUKS on RAID0
Boot into the Qubes installer, then press `ctrl`+`alt`+`F2` to get a virtual
console.
@ -128,8 +267,9 @@ console.
Continue normally from here.
Manual Encryption Configuration (R3.1)
--------------------------------------
## Qubes 3.1
### Manual Encryption Configuration
Qubes OS uses full disk encryption (FDE) by default. If you are an advanced
user who wishes to customize your encryption parameters during installation,
@ -191,3 +331,7 @@ configure the encryption options while installing Qubes as follows:
# cryptsetup luksDump /dev/sda2
[cryptsetup-faq]: https://gitlab.com/cryptsetup/cryptsetup/wikis/FrequentlyAskedQuestions
[dm-crypt]: https://wiki.archlinux.org/index.php/dm-crypt/Device_encryption
[tomb-238]: https://github.com/dyne/Tomb/issues/238

4
installing/install-security.md
View File

@ -75,6 +75,10 @@ Cons:
untrusted ISO to dom0 in order to burn it to disc, which leaves only the
other two options.)
Considering the pros and cons of each, perhaps a USB drive with non-rewritable
(or at least cryptographically-signed) firmware and a physical write-protect
switch might be the option.
[verify]: /security/verifying-signatures/
[classic problem]: https://www.ece.cmu.edu/~ganger/712.fall02/papers/p761-thompson.pdf

38
installing/installation-guide.md
View File

@ -28,37 +28,17 @@ Therefore, we *strongly* recommended that, prior to starting the Qubes installer
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.
Qubes 4.0 Warning
-----------------
Qubes 4.0.1 Warning
-------------------
In new installations of Qubes 4.0, the following steps may need to be applied in dom0 and Fedora 26 TemplateVMs in order to receive updates (see [#3737]).
Immediately after installing Qubes 4.0.1, please upgrade all of your Debian and Whonix TemplateVMs by executing the following commands in a dom0 terminal, as applicable for the templates you chose to install:
Steps for dom0 updates:
$ sudo qubes-dom0-update --action=upgrade qubes-template-debian-9
$ sudo qubes-dom0-update --enablerepo=qubes-templates-community --action=upgrade qubes-template-whonix-gw-14
$ sudo qubes-dom0-update --enablerepo=qubes-templates-community --action=upgrade qubes-template-whonix-ws-14
1. Open the Qubes Menu by clicking on the "Q" icon in the top-left corner of the screen.
2. Select `Terminal Emulator`.
3. In the window that opens, enter this command:
sudo nano /etc/yum.repos.d/qubes-dom0.repo
4. This opens the nano text editor. Change all four instances of `http` to `https`.
5. Press `CTRL+X`, then `Y`, then `ENTER` to save changes and exit.
6. Check for updates normally.
Steps for Fedora 26 TemplateVM updates:
1. Open the Qubes Menu by clicking on the "Q" icon in the top-left corner of the screen.
2. Select `Template: fedora-26`, then `fedora-26: Terminal`.
3. In the window that opens, enter the command for your version:
[Qubes 3.2] sudo gedit /etc/yum.repos.d/qubes-r3.repo
[Qubes 4.0] sudo gedit /etc/yum.repos.d/qubes-r4.repo
4. This opens the gedit text editor in a window. Change all four instances of `http` to `https`.
5. Click the "Save" button in the top-right corner of the window.
6. Close the window.
7. Check for updates normally.
8. Shut down the TemplateVM.
These upgrades are required in order to be protected from the APT update mechanism vulnerability that was announced and patched in [QSB #46], which was after the release of Qubes 4.0.1.
This method is simpler than the method recommended in [QSB #46], but it is just as safe and effective so long as it is performed immediately after installing Qubes OS.
Hardware Requirements
@ -168,7 +148,7 @@ Getting Help
[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
[#3737]: https://github.com/QubesOS/qubes-issues/issues/3737
[QSB #46]: /news/2019/01/23/qsb-46/
[system requirements]: /doc/system-requirements/
[Hardware Compatibility List]: /hcl/
[live USB]: /doc/live-usb/

17
installing/upgrade/upgrade-to-r4.0.md
View File

@ -90,6 +90,23 @@ Restore from your backup
For the TemplateVM OS versions supported in R4.0, see [Supported Versions](/doc/supported-versions/#templatevms).
If the restore tool complains about missing templates, you can select the option to restore the AppVMs anyway, then change them afterward to use one of the default R4.0 templates.
Note about additional disp-* qubes created during restore
---------------------------------------------------------
One of differences between R3.2 and R4.0 is the handling of DisposableVMs.
In R3.2, a DisposableVM inherited its network settings (NetVM and firewall rules) from the calling qube.
In R4.0, this is no longer the case.
Instead, in R4.0 it's possible to create multiple DVM Templates and choose which one should be used by each qube.
It's even possible to use different DVM Templates for different operations from the same qube.
This allows much more flexibility, since it allows you to differentiate not only network settings, but all of a qube's properties (including its template, memory settings, etc.).
Restoring a backup from R3.2 preserves the old behavior by creating separate DVM Template for each network-providing qube (and also `disp-no-netvm` for network-isolated qubes).
Then, each restored qube is configured to use the appropriate DVM Template according to its `netvm` or `dispvm_netvm` property from R3.2.
This way, DisposableVMs started on R4.0 by qubes restored from a R3.2 backup have the same NetVM settings as they had on R3.2.
If you find this behavior undesirable and want to configure it differently, you can remove those `disp-*` DVM Templates.
But, to do so, you must first make sure they are not set as the value for the `default_dispvm` property on any other qube.
Both Qubes Manager and the `qvm-remove` tool will show you where a DVM Template is being used, so you can go there and change the setting.
Upgrade all Template and Standalone VM(s)
-----------------------------------------

2
installing/version-scheme.md
View File

@ -67,7 +67,7 @@ The next RC is released five weeks after the former. All packets are published
in `current` repository and the cycle starts over. There should be no less than
1 and no more than 3 release candidates before final release.
<table border>
<table>
<thead>
<tr><th>stage</th><th>time</th></tr>
</thead>

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

@ -29,7 +29,7 @@ Kali Linux is the most widely used penetration testing Linux distribution.
There are multiple ways to create a Kali Linux VM:
1. Create a HVM and use the offical ISO to install the system or convert a [Virtual Image][kali-vbox]. Explained [here](#hvm3_2).
1. Create a HVM and use the official ISO to install the system or convert a [Virtual Image][kali-vbox]. Explained [here](#hvm3_2).
2. Clone the Qubes OS latest Debian template image and turn it into a Kali Linux distribution:
- using [katoolin]. Explained [here](#katoolin3_2).
- manually. Explained [here](#templatevm-from-debian3_2).
@ -321,7 +321,7 @@ Kali Linux is the most widely used penetration testing Linux distribution.
There are multiple ways to create a Kali Linux VM:
1. Create a HVM and use the offical ISO to install the system or convert a [Virtual Image][kali-vbox]. Explained [here](#hvm4_0).
1. Create a HVM and use the official ISO to install the system or convert a [Virtual Image][kali-vbox]. Explained [here](#hvm4_0).
2. Clone the Qubes OS latest Debian template image and turn it into a Kali Linux distribution:
- using [katoolin]. Explained [here](#katoolin4_0).
- manually. Explained [here](#templatevm-from-debian4_0).

7
managing-os/templates.md
View File

@ -81,9 +81,8 @@ When you install a new template or upgrade a clone of a template, it is recommen
Applications Menu --> System Tools --> Qubes Global Settings --> Default template
2. Base AppVMs on the new template.
In Qubes Manager, for each VM that is currently based on `old-template` that you would like to base on `new-template`, enter its VM settings and change the Template selection:
Applications Menu --> (select a VM) --> VM settings --> Template
Applications Menu --> System Tools --> Qubes Template Manager
3. Base the [DVM Template](/doc/glossary/#dvm-template) on the new template.
@ -99,7 +98,7 @@ Invisible Things Lab (ITL) Supported templates
These are the templates ITL builds and releases updates for.
ITL guarantees that the binary updates are compiled from exactly the same source code as we publish.
* Fedora (default base template)
* [Fedora](/doc/templates/fedora/) (default base template)
* [Fedora - Minimal](/doc/templates/fedora-minimal)
* [Debian](/doc/templates/debian/)
@ -137,7 +136,7 @@ Important Notes (R4.0)
(1) Upon creation
(2) Following shutdown
(3) Including [DVM Templates](/doc/disposablevm/#disposablevms-and-networking-r40-and-later)
(3) Including [DVM Templates](/doc/glossary/#dvm-template)
Important Notes (R3.2 and earlier)
---------------

115
managing-os/templates/debian-minimal.md Normal file
View File

@ -0,0 +1,115 @@
---
layout: doc
title: Debian Minimal Template
permalink: /doc/templates/debian-minimal/
---
Debian - minimal
================
The template weighs about 200 MB compressed (0.75 GB on disk) and has only the most vital packages installed, including a minimal X and xterm installation.
The minimal template, however, can be easily extended to fit your requirements.
The sections below contain instructions on cloning the template and provide some examples for commonly desired use cases.
Note that use of the minimal template requires some familiarity with the command line and basics of Qubes.
Installation
------------
The Debian minimal template can be installed with the following command:
~~~
[user@dom0 ~]$ sudo qubes-dom0-update --enable-repo qubes-templates-itl-testing qubes-template-debian-9-minimal
~~~
The download may take a while depending on your connection speed.
Duplication and first steps
---------------------------
It is highly recommended that you 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 debian-9-minimal your-new-clone
~~~
You must start the template in order to customize it.
Customization
-------------
Customizing the template for specific use cases normally only requires installing additional packages.
The following table provides an overview of which packages are needed for which purpose.
As you would expect, the required packages can be installed in the running template with any apt-based command.
For example : (Replace "packages` with a space-delimited list of packages to be installed.)
~~~
[user@your-new-clone ~]$ sudo apt install packages
~~~
Qubes 4.0
---------
In Qubes R4.0 the minimal template is not configured for passwordless root.
To update or install packages to it, from a dom0 terminal window run:
~~~
[user@dom0 ~]$ qvm-run -u root debian-9-minimal xterm
~~~
to open a root terminal in the template, from which you can use apt tools without sudo.
You will have to do this every time you want root access if you choose not to enable passwordless root.
If you want the usual qubes `sudo ...` commands, open the root terminal using the above command, and in the root xterm window enter
~~~
bash-4.4# apt install qubes-core-agent-passwordless-root polkit
~~~
Optionally check this worked: from the gui open the minimal template's xterm and give the command:
~~~
[user@debian-9-minimal ~]$ sudo -l
~~~
which should give you output that includes the NOPASSWD keyword.
### Package table for Qubes 4.0
Use case | Description | Required steps
--- | --- | ---
**Standard utilities** | If you need the commonly used utilities | Install the following packages: `pciutils` `vim-minimal` `less` `psmisc` `gnome-keyring`
**Networking** | If you want networking | Install qubes-core-agent-networking
**Audio** | If you want sound from your VM... | Install `pulseaudio-qubes`
**FirewallVM** | You can use the minimal template as a template for a [FirewallVM](/doc/firewall/), like `sys-firewall` | Install `qubes-core-agent-networking`, and `nftables`. Also install `qubes-core-agent-dom0-updates` if you want to use a qube based on the template as an updateVM (normally sys-firewall).
**NetVM** | You can use this template as the basis for a NetVM such as `sys-net` | Install the following packages: `qubes-core-agent-networking`, `qubes-core-agent-network-manager`, and `nftables`.
**NetVM (extra firmware)** | If your network devices need extra packages for a network VM | Use the `lspci` command to identify the devices, then find the package that provides necessary firnware and install it.
**Network utilities** | If you need utilities for debugging and analyzing network connections | Install the following packages: `tcpdump` `telnet` `nmap` `nmap-ncat`
**USB** | If you want to use this template as the basis for a [USB](/doc/usb/) qube such as `sys-usb` | Install `qubes-usb-proxy`. To use USB mouse or keyboard install `qubes-input-proxy-sender`.
**VPN** | You can use this template as basis for a [VPN](/doc/vpn/) qube | You may need to install network-manager VPN packages, depending on the VPN technology you'll be using. After creating a machine based on this template, follow the [VPN howto](/doc/vpn/#set-up-a-proxyvm-as-a-vpn-gateway-using-networkmanager) to configure it.
In Qubes 4.0, additional packages from the `qubes-core-agent` suite may be needed to make the customized minimal template work properly.
These packages are:
- `qubes-core-agent-nautilus`: This package provides integration with the Nautilus file manager (without it, items like "copy to VM/open in disposable VM" will not be shown in Nautilus).
- `qubes-core-agent-thunar`: This package provides integration with the thunar file manager (without it, items like "copy to VM/open in disposable VM" will not be shown in thunar).
- `qubes-core-agent-dom0-updates`: Script required to handle `dom0` updates. Any template on which the qube responsible for 'dom0' updates (e.g. `sys-firewall`) is based must contain this package.
- `qubes-menus`: Defines menu layout.
- `qubes-desktop-linux-common`: Contains icons and scripts to improve desktop experience.
Also, there are packages to provide additional services:
- `qubes-gpg-split`: For implementing split GPG.
- `qubes-u2f`: For implementing secure forwarding of U2F messages.
- `qubes-pdf-converter`: For implementing safe conversion of PDFs.
- `qubes-image-converter`: For implementing safe conversion of images.
- `qubes-snapd-helper`: If you want to use snaps in qubes.
- `qubes-thunderbird`: Additional tools for use in thunderbird.
- `qubes-app-shutdown-idle`: If you want qubes to automatically shutdown when idle.
- `qubes-mgmt-\*`: If you want to use salt management on the template and qubes.
Documentation on all of these can be found in the [docs](/doc)
You could, of course, use qubes-vm-recommended to automatically install many of these, but in that case you are well on the way to a standard Debian template.

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

@ -96,11 +96,11 @@ The lesson is that you should carefully look at what is being installed to your
By default, templates in 4.0 only have a loopback interface.
Some packages will thow an error on installation in this situation. For example, Samba expects to be configured using a network interface post installation.
Some packages will throw an error on installation in this situation. For example, Samba expects to be configured using a network interface post installation.
One solution is to add a dummy interface to allow the package to install correctly:
ip link add d0 type dummy
ip link add d0 type dummy
ip addr add 192.168.0.1/24 dev d0
ip link set d0 up

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

@ -12,8 +12,21 @@ redirect_from:
Fedora - minimal
================
The template only weighs about 600 MB compressed (2 GB on disk) and has only the most vital packages installed, including a minimal X and xterm installation.
The minimal template, however, can be easily extended to fit your requirements. The sections below contain the instructions on duplicating the template and provide some examples for commonly desired use cases.
The template only weighs about 600 MB compressed (1.6 GB on disk) and has only the most vital packages installed, including a minimal X and xterm installation.
The minimal template, however, can be easily extended to fit your requirements.
The sections below contain the instructions on duplicating the template and provide some examples for commonly desired use cases.
Important
---------
1. The Fedora minimal template is intended only for advanced users.
If you encounter problems with the Fedora minimal template, we recommend that you use the [default Fedora template] instead.
2. If something works with the default Fedora template but not the minimal template, this is most likely due to user error (e.g., a missing package or misconfiguration) rather than a bug.
In such cases, you should write to [qubes-users] to ask for help rather than filing a bug report, then [contribute what you learn to the documentation][doc-guidelines].
3. The Fedora minimal template is intentionally *minimal*.
[Do not ask for your favorite package to be added to the minimal template by default.][pref-default]
Installation
------------
@ -21,7 +34,7 @@ Installation
The Fedora minimal template can be installed with the following command:
~~~
[user@dom0 ~]$ sudo qubes-dom0-update qubes-template-fedora-27-minimal
[user@dom0 ~]$ sudo qubes-dom0-update qubes-template-fedora-29-minimal
~~~
The download may take a while depending on your connection speed.
@ -32,7 +45,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-27-minimal your-new-clone
[user@dom0 ~]$ qvm-clone fedora-29-minimal your-new-clone
~~~
You must start the template in order to customize it.
@ -67,8 +80,8 @@ Use case | Description | Required steps
Use case | Description | Required steps
--- | --- | ---
**Standard utilities** | If you need the commonly used utilities | Install the following packages: `pciutils` `vim-minimal` `less` `psmisc` `gnome-keyring`
**Audio** | If you want sound from your VM... | Install `pulseaudio-qubes`
**FirewallVM** | You can use the minimal template as a [FirewallVM](/doc/firewall/), such as the basis template for `sys-firewall` | Install at least `qubes-core-agent-networking`, and also `qubes-core-agent-dom0-updates` if you want to use it as the updatevm (which is normally sys-firewall).
**Audio** | If you want sound from your VM | Install `pulseaudio-qubes`
**FirewallVM** | You can use the minimal template as a [FirewallVM](/doc/firewall/), such as the basis template for `sys-firewall` | Install at least `qubes-core-agent-networking` and `iproute`, and also `qubes-core-agent-dom0-updates` if you want to use it as the updatevm (which is normally sys-firewall).
**NetVM** | You can use this template as the basis for a NetVM such as `sys-net` | Install the following packages: `qubes-core-agent-networking` `qubes-core-agent-network-manager` `NetworkManager-wifi` `network-manager-applet` `wireless-tools` `dejavu-sans-fonts` `notification-daemon` `gnome-keyring` `polkit` `@hardware-support`.
**NetVM (extra firmware)** | If your network devices need extra packages for the template to work as a network VM | Use the `lspci` command to identify the devices, then run `dnf search firmware` (replace `firmware` with the appropriate device identifier) to find the needed packages and then install them.
**Network utilities** | If you need utilities for debugging and analyzing network connections | Install the following packages: `tcpdump` `telnet` `nmap` `nmap-ncat`
@ -84,7 +97,7 @@ Qubes 4.0
In Qubes R4.0 the minimal template is not configured for passwordless root. To update or install packages to it, from a dom0 terminal window:
~~~
[user@dom0 ~]$ qvm-run -u root fedora-27-minimal xterm
[user@dom0 ~]$ qvm-run -u root fedora-29-minimal xterm
~~~
to open a root terminal in the template, from which you can use dnf without sudo. You will have to do this every time if you choose not to enable passwordless root.
@ -107,7 +120,7 @@ In Qubes 4.0, additional packages from the `qubes-core-agent` suite may be neede
- `qubes-core-agent-qrexec`: Qubes qrexec agent. Installed by default.
- `qubes-core-agent-systemd`: Qubes unit files for SystemD init style. Installed by default.
- `qubes-core-agent-passwordless-root`, `polkit`: By default the 'fedora-27-minimal' template doesn't have passwordless root. These two packages enable this feature. (Note from R4.0 a design choice was made that passwordless should be optional, so is left out of the minimal templates)
- `qubes-core-agent-passwordless-root`, `polkit`: By default the 'fedora-29-minimal' template doesn't have passwordless root. These two packages enable this feature. (Note from R4.0 a design choice was made that passwordless should be optional, so is left out of the minimal templates)
- `qubes-core-agent-nautilus`: This package provides integration with the Nautilus file manager (without it things like "copy to VM/open in disposable VM" will not be shown in Nautilus).
- `qubes-core-agent-sysvinit`: Qubes unit files for SysV init style or upstart.
- `qubes-core-agent-networking`: Networking support. Required for general network access and particularly if the template is to be used for a `sys-net` or `sys-firewall` VM.
@ -126,4 +139,10 @@ Users requiring the `rsyslog` service should install it manually.
To access the `journald` log, use the `journalctl` command.
[default Fedora template]: /doc/templates/fedora/
[qubes-users]: /support/#qubes-users
[doc-guidelines]: /doc/doc-guidelines/
[pref-default]: /faq/#could-you-please-make-my-preference-the-default
[GUIDE]: /doc/fedora-minimal-template-customization/

1
managing-os/templates/fedora.md
View File

@ -55,6 +55,7 @@ Upgrading
To upgrade your Fedora TemplateVM, please consult the guide that corresponds to your situation:
* [Upgrading the Fedora 28 Template to Fedora 29](/doc/template/fedora/upgrade-28-to-29/)
* [Upgrading the Fedora 27 Template to Fedora 28](/doc/template/fedora/upgrade-27-to-28/)
* [Upgrading the Fedora 26 Template to Fedora 27](/doc/template/fedora/upgrade-26-to-27/)
* [Upgrading the Fedora 25 Template to Fedora 26](/doc/template/fedora/upgrade-25-to-26/)

218
managing-os/templates/fedora/upgrade-28-to-29.md Normal file
View File

@ -0,0 +1,218 @@
---
layout: doc
title: Upgrading the Fedora 28 Template to Fedora 29
permalink: /doc/template/fedora/upgrade-28-to-29/
redirect_from:
- /doc/fedora-template-upgrade-28/
- /en/doc/fedora-template-upgrade-28/
- /doc/FedoraTemplateUpgrade28/
- /wiki/FedoraTemplateUpgrade28/
---
Upgrading the Fedora 28 Template to Fedora 29
=============================================
This page provides instructions for performing an in-place upgrade of an
installed Fedora 28 [TemplateVM] to Fedora 29. If you wish to install a new,
unmodified Fedora 29 template instead of upgrading a template that is already
installed in your system, please see the [Fedora TemplateVM] page instead.
These instructions can also be used to upgrade a Fedora 26 TemplateVM to
Fedora 29. Simply start by cloning `fedora-26` instead of `fedora-28` in the
instructions below.
Important information regarding RPM Fusion repos
------------------------------------------------
If your RPM Fusion repositories are **disabled** when you upgrade a TemplateVM from Fedora 28 to 29, all RPM Fusion packages and RPM Fusion repo definitions will be removed from that TemplateVM.
If your RPM Fusion repositories are **enabled** when upgrading, all RPM Fusion packages and repo definitions will be retained and updated as expected.
For most users, this behavior should not cause a problem, since a TemplateVM in which the RPM Fusion repos are disabled is probably a TemplateVM in which you never wish to use them.
However, if you wish to have the RPM Fusion repo definitions after upgrading in a TemplateVM in which they are currently disabled, you may wish to temporarily enable them prior to upgrading or manually create, copy, or download them after upgrading.
Qubes 4.0 Instructions
----------------------
### Summary: Upgrading the Standard Fedora 28 Template to Fedora 29 ###
**Note:** The prompt on each line indicates where each command should be entered
(`@dom0` or `@fedora-29`).
[user@dom0 ~]$ qvm-clone fedora-28 fedora-29
[user@dom0 ~]$ truncate -s 5GB /var/tmp/template-upgrade-cache.img
[user@dom0 ~]$ qvm-run -a fedora-29 gnome-terminal
[user@dom0 ~]$ dev=$(sudo losetup -f --show /var/tmp/template-upgrade-cache.img)
[user@dom0 ~]$ qvm-block attach fedora-29 dom0:${dev##*/}
[user@fedora-29 ~]$ sudo mkfs.ext4 /dev/xvdi
[user@fedora-29 ~]$ sudo mount /dev/xvdi /mnt/removable
[user@fedora-29 ~]$ sudo dnf clean all
[user@fedora-29 ~]$ sudo dnf --releasever=29 --setopt=cachedir=/mnt/removable --best --allowerasing distro-sync
[user@fedora-29 ~]$ sudo fstrim -v /
(Shut down TemplateVM by any normal means.)
[user@dom0 ~]$ sudo losetup -d $dev
[user@dom0 ~]$ rm /var/tmp/template-upgrade-cache.img
(Optional cleanup: Switch everything over to the new template and delete the old
one. See instructions below for details.)
### Detailed: Upgrading the Standard Fedora 28 Template to Fedora 29 ###
These instructions will show you how to upgrade the standard Fedora 28
TemplateVM to Fedora 29. The same general procedure may be used to upgrade any
template based on the standard Fedora 28 template.
**Note:** The command-line prompt on each line indicates where each command
should be entered (`@dom0` or `@fedora-29`).
1. Ensure the existing template is not running.
[user@dom0 ~]$ qvm-shutdown fedora-28
2. Clone the existing template and start a terminal in the new template.
[user@dom0 ~]$ qvm-clone fedora-28 fedora-29
[user@dom0 ~]$ qvm-run -a fedora-29 gnome-terminal
3. Attempt the upgrade process in the new template.
[user@fedora-29 ~]$ sudo dnf clean all
[user@fedora-29 ~]$ sudo dnf --releasever=29 distro-sync --best --allowerasing
**Note:** `dnf` might ask you to approve importing a new package signing
key. For example, you might see a prompt like this one:
warning: /mnt/removable/updates-0b4cc238d1aa4ffe/packages/kernel-4.18.17-300.fc29.x86_64.rpm: Header V3 RSA/SHA256 Signature, key ID 429476b4: NOKEY
Importing GPG key 0x429476B4:
Userid : "Fedora 29 (29) <fedora-29@fedoraproject.org>"
Fingerprint: 5A03 B4DD 8254 ECA0 2FDA 1637 A20A A56B 4294 76B4
From : /etc/pki/rpm-gpg/RPM-GPG-KEY-fedora-29-x86_64
Is this ok [y/N]: y
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 ~]$ dev=$(sudo losetup -f --show /var/tmp/template-upgrade-cache.img)
[user@dom0 ~]$ qvm-block attach fedora-29 dom0:${dev##*/}
Then reattempt the upgrade process, but this time use the virtual disk
as a cache.
[user@fedora-29 ~]$ sudo mkfs.ext4 /dev/xvdi
[user@fedora-29 ~]$ sudo mount /dev/xvdi /mnt/removable
[user@fedora-29 ~]$ sudo dnf clean all
[user@fedora-29 ~]$ sudo dnf --releasever=29 --setopt=cachedir=/mnt/removable --best --allowerasing 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. Check that you are on the correct (new) fedora release.
[user@fedora-29 ~]$ cat /etc/fedora-release
5. Trim the new template.
[user@fedora-29 ~]$ sudo fstrim -v /
6. Shut down the new TemplateVM (from the command-line or Qubes VM Manager).
[user@dom0 ~]$ qvm-shutdown fedora-29
7. Remove the cache file, if you created one.
[user@dom0 ~]$ sudo losetup -d $dev
[user@dom0 ~]$ rm /var/tmp/template-upgrade-cache.img
8. (Recommended) [Switch everything that was set to the old template to the new
template.][switching-4.0]
9. (Optional) Remove the old template. (Make sure to type `fedora-28`, not
`fedora-29`.)
[user@dom0 ~]$ sudo dnf remove qubes-template-fedora-28
### Upgrading StandaloneVMs ###
The procedure for upgrading a StandaloneVM from Fedora 28 to Fedora 29 is the
same as for a TemplateVM.
### Summary: Upgrading the Minimal Fedora 28 Template to Fedora 29 ###
**Note:** The prompt on each line indicates where each command should be entered
(`@dom0` or `@fedora-29`).
[user@dom0 ~]$ qvm-clone fedora-28-minimal fedora-29-minimal
[user@dom0 ~]$ qvm-run -u root -a fedora-29-minimal xterm
[root@fedora-29-minimal ~]# dnf clean all
[user@fedora-29-minimal ~]# dnf --releasever=29 --best --allowerasing distro-sync
[user@fedora-29-minimal ~]# fstrim -v /
(Shut down TemplateVM by any normal means.)
(If you encounter insufficient space issues, you may need to use the methods
described for the standard template above.)
Qubes 3.2
---------
Fedora 29 is currently not supported on Qubes 3.2. Since official support for Qubes 3.2 ends (2019-03-28) before end of support for Fedora 28 (not earlier than 2019-05-30), Qubes team does not plan to add support for Fedora 29 to Qubes 3.2.
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. Do the upgrade in parts, e.g., by using package groups. (First upgrade
`@core` packages, then the rest.)
4. 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)
[TemplateVM]: /doc/templates/
[Fedora TemplateVM]: /doc/templates/fedora/
[resize-disk-image]: /doc/resize-disk-image/
[Additional Information]: #additional-information
[Compacting the Upgraded Template]: #compacting-the-upgraded-template
[switching-3.2]: /doc/templates/#how-to-switch-templates-32
[switching-4.0]: /doc/templates/#how-to-switch-templates-40
[DispVM]: /doc/dispvm/

4
managing-os/windows/windows-tools.md
View File

@ -24,9 +24,9 @@ Qubes Windows Tools are open source and are distributed under a GPL license.
NOTES:
- Qubes Windows Tools are currently unmaintained
- Currently only 64-bit versions of Windows 7 are supported by Qubes Windows Tools. Only emulated SVGA GPU is supported (although [there has been reports](https://groups.google.com/forum/#!topic/qubes-users/cmPRMOkxkdA) on working GPU pass-through).
- Currently only 64-bit versions of Windows 7 are supported by Qubes Windows Tools. Only emulated SVGA GPU is supported (although [there has been reports](https://groups.google.com/forum/#!topic/qubes-users/cmPRMOkxkdA) on working GPU passthrough).
- There is currently no audio support for Windows HVMs.
- There is currently no USB passsthrough support for Windows HVMs.
- There is currently no USB pass-through support for Windows HVMs.
- __This page documents the process of installing Qubes Windows Tools on versions up to R3.2.__. Installation on Qubes R4.0 is possible but is a work in progress and there are limitations/bugs (see [issue #3585](https://github.com/QubesOS/qubes-issues/issues/3585)).

46
security-info/canaries.md
View File

@ -10,36 +10,18 @@ Qubes Canaries
Qubes Canaries are published through the [Qubes Security Pack](/security/pack/).
2015
----
- [Qubes Canary \#1](https://github.com/QubesOS/qubes-secpack/blob/master/canaries/canary-001-2015.txt)
- [Qubes Canary \#2](https://github.com/QubesOS/qubes-secpack/blob/master/canaries/canary-002-2015.txt)
- [Qubes Canary \#3](https://github.com/QubesOS/qubes-secpack/blob/master/canaries/canary-003-2015.txt)
- [Qubes Canary \#4](https://github.com/QubesOS/qubes-secpack/blob/master/canaries/canary-004-2015.txt)
- [Qubes Canary \#5](https://github.com/QubesOS/qubes-secpack/blob/master/canaries/canary-005-2015.txt)
2016
----
- [Qubes Canary \#6](https://github.com/QubesOS/qubes-secpack/blob/master/canaries/canary-006-2016.txt)
- [Qubes Canary \#7](https://github.com/QubesOS/qubes-secpack/blob/master/canaries/canary-007-2016.txt)
- [Qubes Canary \#8](https://github.com/QubesOS/qubes-secpack/blob/master/canaries/canary-008-2016.txt)
- [Qubes Canary \#9](https://github.com/QubesOS/qubes-secpack/blob/master/canaries/canary-009-2016.txt)
- [Qubes Canary \#10](https://github.com/QubesOS/qubes-secpack/blob/master/canaries/canary-010-2016.txt)
2017
----
- [Qubes Canary \#11](https://github.com/QubesOS/qubes-secpack/blob/master/canaries/canary-011-2017.txt)
- [Qubes Canary \#12](https://github.com/QubesOS/qubes-secpack/blob/master/canaries/canary-012-2017.txt)
- [Qubes Canary \#13](https://github.com/QubesOS/qubes-secpack/blob/master/canaries/canary-013-2017.txt)
- [Qubes Canary \#14](https://github.com/QubesOS/qubes-secpack/blob/master/canaries/canary-014-2017.txt)
2018
----
- [Qubes Canary \#15](https://github.com/QubesOS/qubes-secpack/blob/master/canaries/canary-015-2018.txt)
- [Qubes Canary \#16](https://github.com/QubesOS/qubes-secpack/blob/master/canaries/canary-016-2018.txt)
- [Qubes Canary \#17](https://github.com/QubesOS/qubes-secpack/blob/master/canaries/canary-017-2018.txt)
<table>
<tr>
<th title="Anchor Link"><span class="fa fa-link"></span></th>
<th>Date</th>
<th>Qubes Canary</th>
</tr>
{% for canary in site.data.canary reversed %}
<tr id="{{ canary.canary }}">
<td><a href="#{{ canary.canary }}" class="fa fa-link black-icon" title="Anchor link to Qubes Canary row: Qubes Canary #{{ canary.canary }}"></a></td>
<td>{{ canary.date }}</td>
<td><a href="https://github.com/QubesOS/qubes-secpack/blob/master/canaries/canary-{{ canary.canary }}-{{ canary.date | date: '%Y' }}.txt">Qubes Canary #{{ canary.canary }}</a></td>
</tr>
{% endfor %}
</table>

24
security-info/canary-checklist.md Normal file
View File

@ -0,0 +1,24 @@
---
layout: security
title: Canary Checklist
permalink: /security/canaries/checklist/
---
Canary Checklist
================
Preparation
-----------
* Draft canary and push to private repository
* Finalize canary, sign, and add signed tags
Announcement
------------
* Push canary to public repository
* Publish a [news post](/news/) using the [Canary Template](/security/canaries/template/)
* Send the content of the news post to the appropriate [mailing lists](/support/)
* Share link to news post on social media
* Set a reminder for the next canary

6
security-info/security-bulletins-checklist.md
View File

@ -20,5 +20,7 @@ Announcement
* Upload packages to `security-testing` and `current-testing` repositories
* Push QSB to public repository
* Announce on the [mailing lists](/support/) using the [QSB Template](/security/bulletins/template/)
* Announce on social media
* Publish a [news post](/news/) using the [QSB Template](/security/bulletins/template/)
* Send the content of the news post to the appropriate [mailing lists](/support/)
* Share link to news post on social media

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

@ -1,6 +1,6 @@
---
layout: security
title: Security Bulletins
title: Qubes Security Bulletins
permalink: /security/bulletins/
redirect_from:
- /doc/security-bulletins/
@ -10,90 +10,23 @@ redirect_from:
- /trac/wiki/SecurityBulletins/
---
Qubes Security Bulletins
========================
Qubes Security Bulletins (QSBs)
===============================
Qubes Security Bulletins are published through the [Qubes Security Pack](/security/pack/).
Qubes Security Bulletins (QSBs) are published through the [Qubes Security Pack](/security/pack/).
2010
----
- None
2011
----
- [Qubes Security Bulletin \#01](https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-001-2011.txt) (Gui daemon bug, Intel VT-d escape on non-IR hardware)
2012
----
- [Qubes Security Bulletin \#02](https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-002-2012.txt) (Intel SYSRET bug)
- [Qubes Security Bulletin \#03](https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-003-2012.txt) (Xen hypervisor bugs: XSA 13, others with DoS potential)
- [Qubes Security Bulletin \#04](https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-004-2012.txt) (Qubes firewall misconfiguration: ipv6 allowed)
- [Qubes Security Bulletin \#05](https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-005-2012.txt) (Xen hypervisor bugs: XSA 29, others with DoS potential)
2013
----
- [Qubes Security Bulletin \#06](https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-006-2013.txt) (Xen hypervisor bugs: XSA 50, others with DoS potential)
- [Qubes Security Bulletin \#07](https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-007-2013.txt) (Xen hypervisor bugs: XSA 57 potential escalation, also XSA 52-54 with potential leaks)
- [Qubes Security Bulletin \#08](https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-008-2013.txt) (Xen hypervisor bugs: XSA 45,58 potential DoS)
2014
----
- [Qubes Security Bulletin \#09](https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-009-2014.txt) (Qubes qvm-open-in-[d]vm environment inter-VM leak)
- [Qubes Security Bulletin \#10](https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-010-2014.txt) (Qubes pulseaudio & vchan bugs, Xen XSA 87)
- [Qubes Security Bulletin \#11](https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-011-2014.txt) (Qubes clipboard inter-VM leak)
- [Qubes Security Bulletin \#12](https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-012-2014.txt) (Memory leak in Xen hypervisor via RDMSR emulation bug (XSA 108))
2015
----
- [Qubes Security Bulletin \#13](https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-013-2015.txt) (Qubes Clipboard Timing Attacks and Qubes Core Python API Inconsistency)
- [Qubes Security Bulletin \#14](https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-014-2015.txt) (Race condition in Qubes Inter-VM File-Copy Mechanism)
- [Qubes Security Bulletin \#15](https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-015-2015.txt) (Critical Xen Hypervisor Vulnerability (XSA 109))
- [Qubes Security Bulletin \#16](https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-016-2015.txt) (Xen Hypervisor Information Leaks Vulnerabilities (XSA 121 & 122))
- [Qubes Security Bulletin \#17](https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-017-2015.txt) (Xen DoS from malicious driver domains or devices (XSA 120 & 124))
- [Qubes Security Bulletin \#18](https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-018-2015.txt) (Xen Hypervisor Instruction Emulation Bug (XSA 123))
- [Qubes Security Bulletin \#19](https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-019-2015.txt) (Anti Evil Maid bypass through unusual LUKS header)
- [Qubes Security Bulletin \#20](https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-020-2015.txt) (Fedora os-prober considered harmful)
- [Qubes Security Bulletin \#21](https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-021-2015.txt) (Anti Evil Maid bypass through filesystem ID collision)
- [Qubes Security Bulletin \#22](https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-022-2015.txt) (Critical Xen bug in PV memory virtualization code (XSA 148))
- [Qubes Security Bulletin \#23](https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-023-2015.txt) (Race condition bugs in Xen code (XSA-155 and XSA-166), other Xen bugs)
2016
----
- [Qubes Security Bulletin \#24](https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-024-2016.txt) (Critical Xen bug in PV memory virtualization code (XSA 182))
- [Qubes Security Bulletin \#25](https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-025-2016.txt) (Xen bug in event channel handling code (XSA 188))
- [Qubes Security Bulletin \#26](https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-026-2016.txt) (Colored window border handling bug in Qubes GUI daemon)
- [Qubes Security Bulletin \#27](https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-027-2016.txt) (Xen 64-bit bit test instruction emulation broken (XSA 195))
- [Qubes Security Bulletin \#28](https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-028-2016.txt) (Debian update mechanism vulnerability)
2017
----
- [Qubes Security Bulletin \#29](https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-029-2017.txt) (Critical Xen bug in PV memory virtualization code (XSA-212))
- [Qubes Security Bulletin \#30](https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-030-2017.txt) (Critical Xen bugs related to PV memory virtualization (XSA-213, XSA-214))
- [Qubes Security Bulletin \#31](https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-031-2017.txt) (Xen hypervisor vulnerabilities with unresearched impact (XSA 216-224))
- [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 \#35](https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-035-2017.txt) (Xen hypervisor issue related to grant tables (XSA-236))
- [Qubes Security Bulletin \#36](https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-036-2017.txt) (Xen hypervisor issue in populate-on-demand code (XSA-247))
2018
----
- [Qubes Security Bulletin \#37](https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-037-2018.txt) (Information leaks due to processor speculative execution bugs)
- [Qubes Security Bulletin \#38](https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-038-2018.txt) (Qrexec policy bypass and possible information leak)
- [Qubes Security Bulletin \#39](https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-039-2018.txt) (Xen vulnerability (XSA-260) and GUI daemon issue)
- [Qubes Security Bulletin \#40](https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-040-2018.txt) (Information leaks due to processor speculative store bypass (XSA-263))
- [Qubes Security Bulletin \#41](https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-041-2018.txt) (Speculative register leakage from lazy FPU context switching (XSA-267))
- [Qubes Security Bulletin \#42](https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-042-2018.txt) (Linux netback driver OOB access in hash handling (XSA-270))
- [Qubes Security Bulletin \#43](https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-043-2018.txt) (L1 Terminal Fault speculative side channel (XSA-273))
- [Qubes Security Bulletin \#44](https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-044-2018.txt) (Multiple Xen vulnerabilities (XSA-275, XSA-280))
- [Qubes Security Bulletin \#45](https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-045-2018.txt) (Insecure default Salt configuration)
<table>
<tr>
<th title="Anchor Link"><span class="fa fa-link"></span></th>
<th>Date</th>
<th>Qubes Security Bulletin</th>
</tr>
{% for qsb in site.data.qsb reversed %}
<tr id="{{ qsb.qsb }}">
<td><a href="#{{ qsb.qsb }}" class="fa fa-link black-icon" title="Anchor link to QSB row: QSB #{{ qsb.qsb }}"></a></td>
<td>{{ qsb.date }}</td>
<td><a href="https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-{{ qsb.qsb }}-{{ qsb.date | date: '%Y' }}.txt">QSB #{{ qsb.qsb }}: {{ qsb.title | truncate: 68 }}</a></td>
</tr>
{% endfor %}
</table>

10
security/anti-evil-maid.md
View File

@ -16,6 +16,16 @@ Background
Please read [this blog article](https://blog.invisiblethings.org/2011/09/07/anti-evil-maid.html).
Requirements
----------
The current package requires a TPM 1.2 interface and a working Intel TXT engine.
If you cleaned your Intel Management Engine with e.g. [me_cleaner](https://github.com/corna/me_cleaner)
while installing [CoreBoot](https://www.coreboot.org/) then you are out of luck.
For now you have to choose between cleaning your BIOS and deploying Anti Evil Maid.
[Discussion](https://groups.google.com/d/msg/qubes-users/sEmZfOZqYXM/j5rHeex1BAAJ)
Installing
----------

2
security/split-gpg.md
View File

@ -256,7 +256,7 @@ unparalleled security for one's master secret key.
### Setup Description ###
In this example, the following keys are stored in the following locations
(see below for defintions of these terms):
(see below for definitions of these terms):
| PGP Key(s) | VM Name |
| ---------- | ------------ |

2
security/vm-sudo.md
View File

@ -142,7 +142,7 @@ this for extra security.**
[root@debian-8]# rm /etc/polkit-1/rules.d/00-qubes-allow-all.rules
[root@debian-8]# rm /etc/polkit-1/localauthority/50-local.d/qubes-allow-all.pkla
- In /etc/pam.d/su, comment out this line near the bottom of the file:
- In /etc/pam.d/su.qubes, comment out this line near the bottom of the file:
auth sufficient pam_permit.so

29
services/qrexec3.md
View File

@ -167,6 +167,35 @@ be fatal to Qubes security. On the other hand, this mechanism allows to
delegate processing of untrusted input to less privileged (or disposable)
AppVMs, thus wise usage of it increases security.
For example, this command will run the `firefox` command in a DisposableVM based
on `work`:
```
$ qvm-run --dispvm=work firefox
```
By contrast, consider this command:
```
$ qvm-run --dispvm=work --service qubes.StartApp+firefox
```
This will look for a `firefox.desktop` file in a standard location in a
DisposableVM based on `work`, then launch the application described by that
file. The practical difference is that the bare `qvm-run` command uses the
`qubes.VMShell` service, which allows you to run an arbitrary command with
arbitrary arguments, essentially providing full control over the target VM. By
contrast, the `qubes.StartApp` service allows you to run only applications that
are advertised in `/usr/share/applications` (or other standard locations)
*without* control over the arguments, so giving a VM access to `qubes.StartApp`
is much safer. While there isn't much practical difference between the two
commands above when starting an application from dom0 in Qubes 4.0, there is a
significant security risk when launching applications from a domU (e.g., from
a separate GUI domain). This is why `qubes.StartApp` uses our standard `qrexec`
argument grammar to strictly filter the permissible grammar of the `Exec=` lines
in `.desktop` files that are passed from untrusted domUs to dom0, thereby
protecting dom0 from command injection by maliciously-crafted `.desktop` files.
### Extra keywords available in Qubes 4.0 and later
**This section is about a not-yet-released version, some details may change**

3
system/storage-pools.md
View File

@ -9,6 +9,9 @@ Storage Pools in Qubes
Qubes OS R3.2 introduced the concept of storage drivers and pools. This feature
was a first step towards a saner storage API, which is heavily rewritten in R4.
See [here](https://dev.qubes-os.org/projects/core-admin/en/latest/qubes-storage.html)
for documentation on storage pools in R4.
A storage driver provides a way to store VM images in a Qubes OS system.
Currently, the default driver is `xen` which is the default way of storing
volume images as files in a directory tree like `/var/lib/qubes/`.

12
troubleshooting/macbook-troubleshooting.md
View File

@ -180,7 +180,7 @@ For security reasons, you should install Qubes using the whole disk. I preferred
Download and prepare a USB with Qubes 3.2
You can install Qubes using BIOS or UEFI:
* BIOS/CSM/Legacy: I have not been able to install using legagy, but I did not spend a lot of time on it.
* BIOS/CSM/Legacy: I have not been able to install using legacy, but I did not spend a lot of time on it.
* UEFI plain: grub menu appears, but any gave me a quick flash and returned the main menu. I can boot it manually fixing the grub.cfg file, adding commands linuexefi and initrdefi, pointing proper files in /efi/boot. After boot, I end up with no root file system.
* UEFI, using rEFInd: I have been successful, despite some issues to be fixed manually, after installation completion
* download [rEFInd] refind-bin-0.10.4.zip: this file is not signed, so decide if you trust it or not. SHA1 sum is 3d69c23b7d338419e5559a93cd6ae3ec66323b1e
@ -197,12 +197,12 @@ You can install Qubes using BIOS or UEFI:
* As a general rule, keep the default values proposed during installation: you can change them later on
* Keep English, as language, locale
* My macbook has a US keyboard, so I cannot say what happens if you change keyboard layout
* My Macbook has a US keyboard, so I cannot say what happens if you change keyboard layout
* DO NOT CHANGE the timezone, because it will trigger the wifi card, leading to a system freeze
* Choose the "installation destination": do not change anything and press DONE button
* Insert your password for Full Disk Encryption
* If you do not already have free space on internal SSD disk, you will be prompted to reclaim some space:
* If you shrunk OSX partition, disk utility left an empy partition: delete useless partition (eg: if you shrunk OSX parition, diskutil created an empty partition)
* If you shrunk OSX partition, disk utility left an empty partition: delete useless partition (e.g.: if you shrunk OSX partition, diskutil created an empty partition)
* Press on "reclaim space"
* Press on "begin installation"
* create your user and password
@ -279,7 +279,7 @@ Everything should now be ok, Qubes OS boots using EFI and you will get the last
### 6. Fix pulseaudio, which locks CPU freezing the system often for 20 seconds
My macbook has frequent freezes. Looking at journalctl output I saw that pulseaudio locks CPU for 20 seconds, very often.
My Macbook has frequent freezes. Looking at journalctl output I saw that pulseaudio locks CPU for 20 seconds, very often.
You can fix this issue, killing audio support with this quick workaround:
* open a dom0 terminal, as root and edit /etc/pulse/client.conf
@ -303,7 +303,7 @@ You can fix this issue, killing audio support with this quick workaround:
Press Fn+F2 and complete setup
* reboot and you finally have your Qubes OS
* DO NOT launch sys-net machine
* Open its setting and remove wifi adapter from the Selected devices, using Qubes Manager or use the following command line. Get the BFD of the adapter and remove it. On my macbook BFD is 04:00.0 and you will use it later on, also
* Open its setting and remove wifi adapter from the Selected devices, using Qubes Manager or use the following command line. Get the BFD of the adapter and remove it. On my Macbook BFD is 04:00.0 and you will use it later on, also
~~~
qvm-pci -l sys-net
qvm-pci -d sys-net 04:00.0
@ -319,7 +319,7 @@ qvm-start sys-net
xl pci-attach sys-net 04:00.0
~~~
These latest steps are required to launch sys-net with wifi access. They can be automated in a custom systemd service
These latest steps are required to launch sys-net with wifi access. They can be automated in a custom systemd service.

2
troubleshooting/sony-vaio-tinkering.md
View File

@ -24,7 +24,7 @@ If you think you are ready to reflash you BIOS, here are the instructions that w
[http://forum.notebookreview.com/sony/473226-insyde-hacking-new-vaio-z-advanced-menu-bios.html](http://forum.notebookreview.com/sony/473226-insyde-hacking-new-vaio-z-advanced-menu-bios.html)
**WARNING**: We take absolutely no responsibility that the BIOS relflashing instructions given at the referenced forum are 1) valid, 2) non-malicious, and 3) work at all. Do this step at your own risk. Keep in mind that reflashing your BIOS might yield your system unusable. If you don't feel like taking this risk (which is a reasonable state of mind), look for a different notebook, or ask Sony Support to enable this option for you.
**WARNING**: We take absolutely no responsibility that the BIOS reflashing instructions given at the referenced forum are 1) valid, 2) non-malicious, and 3) work at all. Do this step at your own risk. Keep in mind that reflashing your BIOS might yield your system unusable. If you don't feel like taking this risk (which is a reasonable state of mind), look for a different notebook, or ask Sony Support to enable this option for you.
In practice I have downloaded the BIOS-patching tools, run them in a VM on a BIOS image I extracted from my laptop, diffed the two versions, and concluded that it doesn't *seem* malicious, and then bravely applied tha patched image. If you don't know what are you doing, just get a different laptop, really!

10
troubleshooting/uefi-troubleshooting.md
View File

@ -225,3 +225,13 @@ If that's not an option there, or legacy mode does not work either, you can try
7. Continue with setting up default templates and logging in to Qubes.
Whenever there is a kernel or Xen update for Qubes, you will need to follow these [other steps above](/doc/uefi-troubleshooting/#boot-device-not-recognized-after-installing) because your system is using the fallback UEFI bootloader in `[...]/EFI/BOOT` instead of directly booting to the Qubes entry under `[...]/EFI/qubes`.
Accessing installer Rescue mode on UEFI
---------------------------------------
In UEFI mode installer do not have boot menu, but starts directly the installation wizard. To get into Rescue mode, you need to switch to tty2 (Ctrl+Alt+F2) and then execute:
~~~
pkill -9 anaconda
anaconda --rescue
~~~