From d4ab4aa524c0e9edce68efe7f0ab01b21fed9e51 Mon Sep 17 00:00:00 2001 From: Yassine Ilmi Date: Sat, 13 Jan 2018 11:00:04 +0000 Subject: [PATCH 01/67] Custom "kernel" key in xen.cfg on USB install media Reviewing the HCL a lot of reporters had to install in legacy mode because UEFI mode would fail. For various reports, they used custom kernel parameters by changing the grub entry. This is frequent for recent hardware or some configurations (dual gpu,...). With this procedure a user can perform UEFI install with custom kernel parameters --- troubleshooting/uefi-troubleshooting.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/troubleshooting/uefi-troubleshooting.md b/troubleshooting/uefi-troubleshooting.md index 46b19886..a5f74ca1 100644 --- a/troubleshooting/uefi-troubleshooting.md +++ b/troubleshooting/uefi-troubleshooting.md @@ -7,6 +7,19 @@ permalink: /doc/uefi-troubleshooting/ Troubleshooting UEFI related problems ======================================== +Change installer kernel parameters in UEFI +--------------------- + +If you've installed successfully in legacy mode but had to change some kernel parameters for it to work, you should try installing in UEFI with the same kernel parameters. + +Change the `xen.cfg` on a USB media + +01. Attach the usb disk, find the EFI partition and mount it +02. Edit your xen.cfg changing the `kernel` key to add your kernel parameters on the boot entry of your choice +03. Install using your modified boot entry + +You can also update an iso image, use `losetup` to isolate the EFI partition and mount it. + Cannot start installation, installation completes successfully but then BIOS loops at boot device selection, hangs at four penguins after choosing "Test media and install Qubes OS" in GRUB menu --------------------- From 2d84312ac5108cd5ff6d190322f696ea1b25c082 Mon Sep 17 00:00:00 2001 From: Peter Gerber Date: Mon, 22 Jan 2018 01:29:01 +0100 Subject: [PATCH 02/67] Improve instructions for randomizing MAC addresses NetworkManager, by default, uses a connection ID and a per-host random and secret key to generate `stable` MAC addresses. The intention is to keep a connection's MAC address stable indefinitely but for it to be different on every host. The current instruction mention that "`stable` generates a random address that persists for each boot session". This is indeed true for AppVMs using stock TemplateVMs. The reason is that the secret key doesn't exist in the template and thus is only created when the AppVM starts. This, however, may not be true for other VMs. In order to ensure that MACs are always only `stable` during one boot session, `stable-id`, which is used to generate MACs, can be adjusted. NetworkManager's documentation suggests to use `${CONNECTION}/${BOOT}` to ensure generated MACs are unique to a boot session and connection [1]. [1]: https://developer.gnome.org/NetworkManager/stable/nm-settings.html --- privacy/anonymizing-your-mac-address.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/privacy/anonymizing-your-mac-address.md b/privacy/anonymizing-your-mac-address.md index 1ae437bb..7a92429e 100644 --- a/privacy/anonymizing-your-mac-address.md +++ b/privacy/anonymizing-your-mac-address.md @@ -34,10 +34,11 @@ wifi.scan-rand-mac-address=yes [connection] wifi.cloned-mac-address=stable ethernet.cloned-mac-address=stable +connection.stable-id=${CONNECTION}/${BOOT} ~~~ -`stable` generates a random address that persists for each boot session. -`random` generates a random address each time a link goes up. +* `stable` in combination with `${CONNECTION}/${BOOT}` generates a random address that persists for each boot session. +* `random` generates a random address each time a link goes up. To see all the available configuration options, refer to the man page: `man nm-settings` From 13d7375ff204ca5d05ee7b86f87bba458434b6b3 Mon Sep 17 00:00:00 2001 From: Patrick Schleizer Date: Thu, 25 Jan 2018 21:11:34 +0000 Subject: [PATCH 03/67] formatting and rewording enhancements --- configuration/vpn.md | 402 ++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 381 insertions(+), 21 deletions(-) diff --git a/configuration/vpn.md b/configuration/vpn.md index 41bd81d9..acff4421 100644 --- a/configuration/vpn.md +++ b/configuration/vpn.md @@ -68,29 +68,168 @@ This method is more involved than the one above, but has anti-leak features that Note: Do not enable NetworkManager in the ProxyVM, as it can interfere with the scripts' DNS features. If you enabled NetworkManager or used other methods in a previous attempt, do not re-use the old ProxyVM... Create a new one according to this step. - If your choice of template VM doesn't already have the VPN client software, you'll need to install the software in the template before proceeding. Disable any auto-starting service that comes with the software package: for example `sudo systemctl disable openvpn.service`. + If your choice of TemplateVM doesn't already have the VPN client software, you'll need to install the software in the template before proceeding. Disable any auto-starting service that comes with the software package. For example for OpenVPN. - You may also wish to install `nano` or another simple text editor for entering the scripts below. + sudo systemctl disable openvpn.service + +You may also wish to install `nano` or another simple text editor for entering the scripts below. 2. Set up and test the VPN client. Make sure the VPN VM and its template VM are not running. - Run a terminal (CLI) in the VPN VM -- this will start the VM. Then make a new 'vpn' folder with `sudo mkdir /rw/config/vpn` and copy your VPN config files here (the example config filename used here is `openvpn-client.ovpn`). Files accompanying the main config such as *.crt and *.pem should also go here, and should not be referenced in the main config by absolute paths such as '/etc/...'. + Run a terminal (CLI) in the VPN VM -- this will start the VM. Then make a new 'vpn' folder with. + + sudo mkdir /rw/config/vpn + +Copy your VPN config files to `/rw/config/vpn`. Your VPN config file should be named `openvpn-client.ovpn` so you can use the instructions and scripts below as is without modification. Otherwise you would have to replace the file name. - Notes about VPN config options: The VPN scripts here are intended to work with commonly used `tun` interfaces, whereas `tap` mode is untested. Also, the config should route all traffic through your VPN's interface after a connection is created; For openvpn the directive for this is `redirect-gateway def1`. Lastly, the VPN client may not be able to prompt you for credentials when connecting to the server: Creating a file in the 'vpn' folder with your credentials and using a directive such as openvpn's `auth-user-pass ` is recommended. +Files accompanying the main config such as `*.crt` and `*.pem` should also go to `/rw/config/vpn`. + +Files referenced in `openvpn-client.ovpn` should not be referenced by absolute paths such as `/etc/...`. + +--- +layout: doc +title: VPN +permalink: /doc/vpn/ +redirect_from: +- /doc/privacy/vpn/ +- /en/doc/vpn/ +- /doc/VPN/ +- /wiki/VPN/ +--- + +How To make a VPN Gateway in Qubes +================================== + +Although setting up a VPN connection is not by itself Qubes specific, Qubes includes a number of tools that can make the client-side setup of your VPN more versatile and secure. This document is a Qubes-specific outline for choosing the type of VM to use, and shows how to prepare a ProxyVM for either NetworkManager or a set of fail-safe VPN scripts. + +Please refer to your guest OS and VPN service documentation when considering the specific steps and parameters for your connection(s); The relevant documentation for the Qubes default guest OS (Fedora) is [Establishing a VPN Connection.](https://docs.fedoraproject.org/en-US/Fedora/23/html/Networking_Guide/sec-Establishing_a_VPN_Connection.html) + +### NetVM + +The simplest case is to set up a VPN connection using the NetworkManager service inside your NetVM. Because the NetworkManager service is already started, you are ready to set up your VPN connection. However this has some disadvantages: + +- You have to place (and probably save) your VPN credentials inside the NetVM, which is directly connected to the outside world +- All your AppVMs which are connected to the NetVM will be connected to the VPN (by default) + +### AppVM + +While the NetworkManager service is not started here (for a good reason), you can configure any kind of VPN client in your AppVM as well. However this is only suggested if your VPN client has special requirements. + +### ProxyVM + +One of the best unique features of Qubes OS is its special type of VM called a ProxyVM. The special thing is that your AppVMs see this as a NetVM (or uplink), and your NetVMs see it as a downstream AppVM. Because of this, you can place a ProxyVM between your AppVMs and your NetVM. This is how the default sys-firewall VM functions. + +Using a ProxyVM to set up a VPN client gives you the ability to: + +- Separate your VPN credentials from your NetVM. +- Separate your VPN credentials from your AppVM data. +- Easily control which of your AppVMs are connected to your VPN by simply setting it as a NetVM of the desired AppVM. + +Set up a ProxyVM as a VPN gateway using NetworkManager +------------------------------------------------------ + +1. Create a new VM, name it, click the ProxyVM radio button, and choose a color and template. + + ![Create\_New\_VM.png](/attachment/wiki/VPN/Create_New_VM.png) + +2. Add the `network-manager` service to this new VM. + + ![Settings-services.png](/attachment/wiki/VPN/Settings-services.png) + +3. Set up your VPN as described in the NetworkManager documentation linked above. + +4. Configure your AppVMs to use the new VM as a NetVM. + + ![Settings-NetVM.png](/attachment/wiki/VPN/Settings-NetVM.png) + +5. Optionally, you can install some [custom icons](https://github.com/Zrubi/qubes-artwork-proxy-vpn) for your VPN + + +Set up a ProxyVM as a VPN gateway using iptables and CLI scripts +---------------------------------------------------------------- + +This method is more involved than the one above, but has anti-leak features that also make the connection _fail closed_ should it be interrupted. It has been tested with Fedora 23 and Debian 8 templates. + +1. Create a new VM, name it, click the ProxyVM radio button, and choose a color and template. + + ![Create\_New\_VM.png](/attachment/wiki/VPN/Create_New_VM.png) - __Test your client configuration:__ Run the client from a CLI prompt in the 'vpn' folder, preferably as root. For example: - ``` - sudo openvpn --cd /rw/config/vpn --config openvpn-client.ovpn - ``` + Note: Do not enable NetworkManager in the ProxyVM, as it can interfere with the scripts' DNS features. If you enabled NetworkManager or used other methods in a previous attempt, do not re-use the old ProxyVM... Create a new one according to this step. - Watch for status messages that indicate whether the connection is successful and test from another VPN VM terminal window with `ping` and `traceroute`. DNS may be tested at this point by replacing addresses in `/etc/resolv.conf` with ones appropriate for your VPN (although this file will not be used when setup is complete). Diagnose any connection problems using resources such as client documentation and help from your VPN service provider. +If your choice of TemplateVM doesn't already have the VPN client software, you'll need to install the software in the template before proceeding. For example in any Debian based VM to install OpenVPN. + + sudo apt-get install openvpn + +Disable any auto-starting service that comes with the software package. For example for OpenVPN. - Proceed to the next step when you're sure the basic VPN connection is working. + sudo systemctl disable openvpn.service + +You may also wish to install `nano` or another simple text editor for entering the scripts below. + +2. Set up and test the VPN client. + +Make sure the VPN VM and its TemplateVM is not running. + +Run a terminal (CLI) in the VPN VM -- this will start the VM. Then create a new `/rw/config/vpn` folder with. + + sudo mkdir /rw/config/vpn + +Copy your VPN config files to `/rw/config/vpn`. Your VPN config file should be named `openvpn-client.ovpn`) so you can use the scripts below as is without modification. Otherwise you would have to replace the file name. + +Files accompanying the main config such as `*.crt` and `*.pem` should also go to `/rw/config/vpn`. + +Files reference in `openvpn-client.ovpn` should not be referenced in the main config by absolute paths such as `/etc/...`. + +`openvpn-client.ovpn` contents: The VPN scripts here are intended to work with commonly used `tun` interfaces, whereas `tap` mode is untested. + +Also, the config should route all traffic through your VPN's interface after a connection is created; For openvpn the directive for this is `redirect-gateway def1`. For OpenVPN. + + sudo nano /rw/config/vpn/openvpn-client.ovpn + + Make sure it already includes or add. + + redirect-gateway def1 + +The VPN client may not be able to prompt you for credentials when connecting to the server. Create a file in the `/rw/config/vpn` folder with your credentials and using a directive. For example for OpenVPN, add. + + auth-user-pass pass.txt + + Save file `/rw/config/vpn/openvpn-client.ovpn`. + + Make sure a `/rw/config/vpn/pass.txt` file actually exists. + + sudo nano /rw/config/vpn/pass.txt + + Add. + + ``` + username + password + ``` + + Replace `username` and `password` with your actual username and password. + + __Test your client configuration:__ Run the client from a CLI prompt in the 'vpn' folder, preferably as root. For example: + + sudo openvpn --cd /rw/config/vpn --config openvpn-client.ovpn + +Watch for status messages that indicate whether the connection is successful and test from another VPN VM terminal window with `ping`. + + ping 8.8.8.8 + +`ping` can be aborted by pressing the two keys `ctrl` + `c` at the same time. + +DNS may be tested at this point by replacing addresses in `/etc/resolv.conf` with ones appropriate for your VPN (although this file will not be used when setup is complete). Diagnose any connection problems using resources such as client documentation and help from your VPN service provider. + +Proceed to the next step when you're sure the basic VPN connection is working. 3. Create the DNS-handling script. - Use `sudo nano /rw/config/vpn/qubes-vpn-handler.sh` to edit and add: + + sudo nano /rw/config/vpn/qubes-vpn-handler.sh + + Edit and add: ~~~ #!/bin/bash @@ -130,22 +269,37 @@ This method is more involved than the one above, but has anti-leak features that esac ~~~ - Now save the script and make it executable: - `sudo chmod +x /rw/config/vpn/qubes-vpn-handler.sh` +Save the script. + +Make it executable. + + sudo chmod +x /rw/config/vpn/qubes-vpn-handler.sh -4. Configure client to use the DNS handling script. Using openvpn as an example, edit the config with `sudo nano /rw/config/vpn/openvpn-client.ovpn` and add these lines: +4. Configure client to use the DNS handling script. Using openvpn as an example, edit the config. + + sudo nano /rw/config/vpn/openvpn-client.ovpn + + Add the following. ~~~ script-security 2 up 'qubes-vpn-handler.sh up' down 'qubes-vpn-handler.sh down' ~~~ + +Remove other instances of lines starting with `script-security`, `up` or `down` should there be any others. - **Restart the client and test the connection again** ...this time from an AppVM! +Save the script. + +**Restart the client and test the connection again** ...this time from an AppVM! 5. Set up iptables anti-leak rules. - Edit the firewall script with `sudo nano /rw/config/qubes-firewall-user-script` then clear out the existing lines and add: + Edit the firewall script. + + sudo nano /rw/config/qubes-firewall-user-script + +Clear out the existing lines and add. ~~~ #!/bin/bash @@ -171,12 +325,17 @@ This method is more involved than the one above, but has anti-leak features that iptables -I OUTPUT -p all -o eth0 -m owner --gid-owner qvpn -j ACCEPT ~~~ - Now save the script and make it executable: - `sudo chmod +x /rw/config/qubes-firewall-user-script` +Save the script. + +Make it executable. + + sudo chmod +x /rw/config/qubes-firewall-user-script 5. Set up the VPN's autostart. - Use `sudo nano /rw/config/rc.local` to clear out the existing lines and add: + sudo nano /rw/config/rc.local + +Clear out the existing lines and add. ~~~ #!/bin/bash @@ -188,9 +347,11 @@ This method is more involved than the one above, but has anti-leak features that sg qvpn -c "$VPN_CLIENT $VPN_OPTIONS" ~~~ - Change the `VPN_CLIENT` and `VPN_OPTIONS` variables to match your VPN software. +If you are using anything other than OpenVPN, change the `VPN_CLIENT` and `VPN_OPTIONS` variables to match your VPN software. - Now save the script and make it executable: +Save the script. + +Make it executable: `sudo chmod +x /rw/config/rc.local` 6. Restart the new VM! The link should then be established automatically with a popup notification to that effect. @@ -214,6 +375,205 @@ You can do this in the Services tab in Qubes VM Manager or on the command-line: Then, configure your templates to use your new FirewallVM as their NetVM. +Troubleshooting +--------------- + +* Always test your basic VPN connection before adding scripts. +* Test DNS: Ping a familiar domain name from an appVM. It should print the IP address for the domain. +* For scripting: Ping external IP addresses from inside the VPN VM using `sudo sg qvpn -c 'ping ...'`, then from an appVM using just `ping ...`. Once the firewall rules are in place, you will have to use `sudo sg` to run any IP network commands in the VPN VM. +* Use `iptables -L -v` and `iptables -L -v -t nat` to check firewall rules. The latter shows the critical PR-QBS chain that enables DNS forwarding. + The VPN scripts here are intended to work with commonly used `tun` interfaces, whereas `tap` mode is untested. + +Also, the config should route all traffic through your VPN's interface after a connection is created; For openvpn the directive for this is `redirect-gateway def1`. For OpenVPN. + + sudo nano /rw/config/vpn/openvpn-client.ovpn + + Make sure it already includes or add. + + redirect-gateway def1 + +The VPN client may not be able to prompt you for credentials when connecting to the server: Creating a file in the `/rw/config/vpn` folder with your credentials and using a directive. For example for OpenVPN, add + + auth-user-pass pass.txt + + Make sure a `/rw/config/vpn/pass.txt` file actually exists. + + sudo nano /rw/config/vpn/pass.txt + + Add. + + ``` + username + password + ``` + + Replace the username and password with your actual username and password. + + __Test your client configuration:__ Run the client from a CLI prompt in the 'vpn' folder, preferably as root. For example: + + sudo openvpn --cd /rw/config/vpn --config openvpn-client.ovpn + +Watch for status messages that indicate whether the connection is successful and test from another VPN VM terminal window with `ping`. + + ping 8.8.8.8 + +ping can be aborted by pressing the two keys `ctrl` + `c` at the same time. + +DNS may be tested at this point by replacing addresses in `/etc/resolv.conf` with ones appropriate for your VPN (although this file will not be used when setup is complete). Diagnose any connection problems using resources such as client documentation and help from your VPN service provider. + +Proceed to the next step when you're sure the basic VPN connection is working. + +3. Create the DNS-handling script. + + sudo nano /rw/config/vpn/qubes-vpn-handler.sh + + Edit and add: + + ~~~ + #!/bin/bash + set -e + export PATH="$PATH:/usr/sbin:/sbin" + + case "$1" in + + up) + # To override DHCP DNS, assign DNS addresses to 'vpn_dns' env variable before calling this script; + # Format is 'X.X.X.X Y.Y.Y.Y [...]' + if [[ -z "$vpn_dns" ]] ; then + # Parses DHCP foreign_option_* vars to automatically set DNS address translation: + for optionname in ${!foreign_option_*} ; do + option="${!optionname}" + unset fops; fops=($option) + if [ ${fops[1]} == "DNS" ] ; then vpn_dns="$vpn_dns ${fops[2]}" ; fi + done + fi + + iptables -t nat -F PR-QBS + if [[ -n "$vpn_dns" ]] ; then + # Set DNS address translation in firewall: + for addr in $vpn_dns; do + iptables -t nat -A PR-QBS -i vif+ -p udp --dport 53 -j DNAT --to $addr + iptables -t nat -A PR-QBS -i vif+ -p tcp --dport 53 -j DNAT --to $addr + done + su - -c 'notify-send "$(hostname): LINK IS UP." --icon=network-idle' user + else + su - -c 'notify-send "$(hostname): LINK UP, NO DNS!" --icon=dialog-error' user + fi + + ;; + down) + su - -c 'notify-send "$(hostname): LINK IS DOWN !" --icon=dialog-error' user + ;; + esac + ~~~ + +Save the script. + +Make it executable. + + sudo chmod +x /rw/config/vpn/qubes-vpn-handler.sh + +4. Configure client to use the DNS handling script. Using openvpn as an example, edit the config. + + sudo nano /rw/config/vpn/openvpn-client.ovpn + + Add the following. + + ~~~ + script-security 2 + up 'qubes-vpn-handler.sh up' + down 'qubes-vpn-handler.sh down' + ~~~ + +Remove other instances of lines starting with `script-security`, `up` or `down` should there be any others. + +Save the script. + +**Restart the client and test the connection again** ...this time from an AppVM! + +5. Set up iptables anti-leak rules. + +Open Qubes firewall script. + + sudo nano /rw/config/qubes-firewall-user-script + +Clear out the existing lines and add. + + ~~~ + #!/bin/bash + # Block forwarding of connections through upstream network device + # (in case the vpn tunnel breaks): + iptables -I FORWARD -o eth0 -j DROP + iptables -I FORWARD -i eth0 -j DROP + + # Block all outgoing traffic + iptables -P OUTPUT DROP + iptables -F OUTPUT + iptables -I OUTPUT -o lo -j ACCEPT + + # Add the `qvpn` group to system, if it doesn't already exist + if ! grep -q "^qvpn:" /etc/group ; then + groupadd -rf qvpn + sync + fi + sleep 2s + + # Allow traffic from the `qvpn` group to the uplink interface (eth0); + # Our VPN client will run with group `qvpn`. + iptables -I OUTPUT -p all -o eth0 -m owner --gid-owner qvpn -j ACCEPT + ~~~ + +Save the script. + +Make it executable. + + sudo chmod +x /rw/config/qubes-firewall-user-script + +5. Set up the VPN's autostart. + + sudo nano /rw/config/rc.local + +Clear out the existing lines and add. + + ~~~ + #!/bin/bash + VPN_CLIENT='openvpn' + VPN_OPTIONS='--cd /rw/config/vpn/ --config openvpn-client.ovpn --daemon' + + su - -c 'notify-send "$(hostname): Starting $VPN_CLIENT..." --icon=network-idle' user + groupadd -rf qvpn ; sleep 2s + sg qvpn -c "$VPN_CLIENT $VPN_OPTIONS" + ~~~ + +If you are using anything other than OpenVPN, change the `VPN_CLIENT` and `VPN_OPTIONS` variables to match your VPN software. + +Save the script. + +Make it executable. + + sudo chmod +x /rw/config/rc.local + +6. Restart the new VM! The link should then be established automatically with a popup notification to that effect. + +Usage +----- + +Configure your AppVMs to use the VPN VM as a NetVM... + +![Settings-NetVM.png](/attachment/wiki/VPN/Settings-NetVM.png) + + +If you want to be able to use the [Qubes firewall](/doc/firewall), create a new FirewallVM (as a ProxyVM) and set it to use the VPN VM as its NetVM. +Then, configure AppVMs to use your new FirewallVM as their NetVM. + +If you want to update your TemplateVMs through the VPN, enable the `qubes-updates-proxy` service in your new FirewallVM. +You can do this in the Services tab in Qubes VM Manager or on the command-line: + + $ qvm-service -e qubes-updates-proxy + +Then, configure your templates to use your new FirewallVM as their NetVM. + + Troubleshooting --------------- From 8e9982cf0828e9db01fac55a531da9ad5992d01f Mon Sep 17 00:00:00 2001 From: Patrick Schleizer Date: Thu, 25 Jan 2018 22:46:24 +0000 Subject: [PATCH 04/67] fix --- configuration/vpn.md | 299 +------------------------------------------ 1 file changed, 3 insertions(+), 296 deletions(-) diff --git a/configuration/vpn.md b/configuration/vpn.md index acff4421..3a1a4574 100644 --- a/configuration/vpn.md +++ b/configuration/vpn.md @@ -74,100 +74,6 @@ This method is more involved than the one above, but has anti-leak features that You may also wish to install `nano` or another simple text editor for entering the scripts below. -2. Set up and test the VPN client. - - Make sure the VPN VM and its template VM are not running. - - Run a terminal (CLI) in the VPN VM -- this will start the VM. Then make a new 'vpn' folder with. - - sudo mkdir /rw/config/vpn - -Copy your VPN config files to `/rw/config/vpn`. Your VPN config file should be named `openvpn-client.ovpn` so you can use the instructions and scripts below as is without modification. Otherwise you would have to replace the file name. - -Files accompanying the main config such as `*.crt` and `*.pem` should also go to `/rw/config/vpn`. - -Files referenced in `openvpn-client.ovpn` should not be referenced by absolute paths such as `/etc/...`. - ---- -layout: doc -title: VPN -permalink: /doc/vpn/ -redirect_from: -- /doc/privacy/vpn/ -- /en/doc/vpn/ -- /doc/VPN/ -- /wiki/VPN/ ---- - -How To make a VPN Gateway in Qubes -================================== - -Although setting up a VPN connection is not by itself Qubes specific, Qubes includes a number of tools that can make the client-side setup of your VPN more versatile and secure. This document is a Qubes-specific outline for choosing the type of VM to use, and shows how to prepare a ProxyVM for either NetworkManager or a set of fail-safe VPN scripts. - -Please refer to your guest OS and VPN service documentation when considering the specific steps and parameters for your connection(s); The relevant documentation for the Qubes default guest OS (Fedora) is [Establishing a VPN Connection.](https://docs.fedoraproject.org/en-US/Fedora/23/html/Networking_Guide/sec-Establishing_a_VPN_Connection.html) - -### NetVM - -The simplest case is to set up a VPN connection using the NetworkManager service inside your NetVM. Because the NetworkManager service is already started, you are ready to set up your VPN connection. However this has some disadvantages: - -- You have to place (and probably save) your VPN credentials inside the NetVM, which is directly connected to the outside world -- All your AppVMs which are connected to the NetVM will be connected to the VPN (by default) - -### AppVM - -While the NetworkManager service is not started here (for a good reason), you can configure any kind of VPN client in your AppVM as well. However this is only suggested if your VPN client has special requirements. - -### ProxyVM - -One of the best unique features of Qubes OS is its special type of VM called a ProxyVM. The special thing is that your AppVMs see this as a NetVM (or uplink), and your NetVMs see it as a downstream AppVM. Because of this, you can place a ProxyVM between your AppVMs and your NetVM. This is how the default sys-firewall VM functions. - -Using a ProxyVM to set up a VPN client gives you the ability to: - -- Separate your VPN credentials from your NetVM. -- Separate your VPN credentials from your AppVM data. -- Easily control which of your AppVMs are connected to your VPN by simply setting it as a NetVM of the desired AppVM. - -Set up a ProxyVM as a VPN gateway using NetworkManager ------------------------------------------------------- - -1. Create a new VM, name it, click the ProxyVM radio button, and choose a color and template. - - ![Create\_New\_VM.png](/attachment/wiki/VPN/Create_New_VM.png) - -2. Add the `network-manager` service to this new VM. - - ![Settings-services.png](/attachment/wiki/VPN/Settings-services.png) - -3. Set up your VPN as described in the NetworkManager documentation linked above. - -4. Configure your AppVMs to use the new VM as a NetVM. - - ![Settings-NetVM.png](/attachment/wiki/VPN/Settings-NetVM.png) - -5. Optionally, you can install some [custom icons](https://github.com/Zrubi/qubes-artwork-proxy-vpn) for your VPN - - -Set up a ProxyVM as a VPN gateway using iptables and CLI scripts ----------------------------------------------------------------- - -This method is more involved than the one above, but has anti-leak features that also make the connection _fail closed_ should it be interrupted. It has been tested with Fedora 23 and Debian 8 templates. - -1. Create a new VM, name it, click the ProxyVM radio button, and choose a color and template. - - ![Create\_New\_VM.png](/attachment/wiki/VPN/Create_New_VM.png) - - Note: Do not enable NetworkManager in the ProxyVM, as it can interfere with the scripts' DNS features. If you enabled NetworkManager or used other methods in a previous attempt, do not re-use the old ProxyVM... Create a new one according to this step. - -If your choice of TemplateVM doesn't already have the VPN client software, you'll need to install the software in the template before proceeding. For example in any Debian based VM to install OpenVPN. - - sudo apt-get install openvpn - -Disable any auto-starting service that comes with the software package. For example for OpenVPN. - - sudo systemctl disable openvpn.service - -You may also wish to install `nano` or another simple text editor for entering the scripts below. - 2. Set up and test the VPN client. Make sure the VPN VM and its TemplateVM is not running. @@ -178,9 +84,9 @@ Run a terminal (CLI) in the VPN VM -- this will start the VM. Then create a new Copy your VPN config files to `/rw/config/vpn`. Your VPN config file should be named `openvpn-client.ovpn`) so you can use the scripts below as is without modification. Otherwise you would have to replace the file name. -Files accompanying the main config such as `*.crt` and `*.pem` should also go to `/rw/config/vpn`. +Files accompanying the main config such as `*.crt` and `*.pem` should also go to `/rw/config/vpn` folder. -Files reference in `openvpn-client.ovpn` should not be referenced in the main config by absolute paths such as `/etc/...`. +Files reference in `openvpn-client.ovpn` should not be referenced by absolute paths such as `/etc/...`. `openvpn-client.ovpn` contents: The VPN scripts here are intended to work with commonly used `tun` interfaces, whereas `tap` mode is untested. @@ -188,7 +94,7 @@ Also, the config should route all traffic through your VPN's interface after a c sudo nano /rw/config/vpn/openvpn-client.ovpn - Make sure it already includes or add. +Make sure it already includes or add. redirect-gateway def1 @@ -375,205 +281,6 @@ You can do this in the Services tab in Qubes VM Manager or on the command-line: Then, configure your templates to use your new FirewallVM as their NetVM. -Troubleshooting ---------------- - -* Always test your basic VPN connection before adding scripts. -* Test DNS: Ping a familiar domain name from an appVM. It should print the IP address for the domain. -* For scripting: Ping external IP addresses from inside the VPN VM using `sudo sg qvpn -c 'ping ...'`, then from an appVM using just `ping ...`. Once the firewall rules are in place, you will have to use `sudo sg` to run any IP network commands in the VPN VM. -* Use `iptables -L -v` and `iptables -L -v -t nat` to check firewall rules. The latter shows the critical PR-QBS chain that enables DNS forwarding. - The VPN scripts here are intended to work with commonly used `tun` interfaces, whereas `tap` mode is untested. - -Also, the config should route all traffic through your VPN's interface after a connection is created; For openvpn the directive for this is `redirect-gateway def1`. For OpenVPN. - - sudo nano /rw/config/vpn/openvpn-client.ovpn - - Make sure it already includes or add. - - redirect-gateway def1 - -The VPN client may not be able to prompt you for credentials when connecting to the server: Creating a file in the `/rw/config/vpn` folder with your credentials and using a directive. For example for OpenVPN, add - - auth-user-pass pass.txt - - Make sure a `/rw/config/vpn/pass.txt` file actually exists. - - sudo nano /rw/config/vpn/pass.txt - - Add. - - ``` - username - password - ``` - - Replace the username and password with your actual username and password. - - __Test your client configuration:__ Run the client from a CLI prompt in the 'vpn' folder, preferably as root. For example: - - sudo openvpn --cd /rw/config/vpn --config openvpn-client.ovpn - -Watch for status messages that indicate whether the connection is successful and test from another VPN VM terminal window with `ping`. - - ping 8.8.8.8 - -ping can be aborted by pressing the two keys `ctrl` + `c` at the same time. - -DNS may be tested at this point by replacing addresses in `/etc/resolv.conf` with ones appropriate for your VPN (although this file will not be used when setup is complete). Diagnose any connection problems using resources such as client documentation and help from your VPN service provider. - -Proceed to the next step when you're sure the basic VPN connection is working. - -3. Create the DNS-handling script. - - sudo nano /rw/config/vpn/qubes-vpn-handler.sh - - Edit and add: - - ~~~ - #!/bin/bash - set -e - export PATH="$PATH:/usr/sbin:/sbin" - - case "$1" in - - up) - # To override DHCP DNS, assign DNS addresses to 'vpn_dns' env variable before calling this script; - # Format is 'X.X.X.X Y.Y.Y.Y [...]' - if [[ -z "$vpn_dns" ]] ; then - # Parses DHCP foreign_option_* vars to automatically set DNS address translation: - for optionname in ${!foreign_option_*} ; do - option="${!optionname}" - unset fops; fops=($option) - if [ ${fops[1]} == "DNS" ] ; then vpn_dns="$vpn_dns ${fops[2]}" ; fi - done - fi - - iptables -t nat -F PR-QBS - if [[ -n "$vpn_dns" ]] ; then - # Set DNS address translation in firewall: - for addr in $vpn_dns; do - iptables -t nat -A PR-QBS -i vif+ -p udp --dport 53 -j DNAT --to $addr - iptables -t nat -A PR-QBS -i vif+ -p tcp --dport 53 -j DNAT --to $addr - done - su - -c 'notify-send "$(hostname): LINK IS UP." --icon=network-idle' user - else - su - -c 'notify-send "$(hostname): LINK UP, NO DNS!" --icon=dialog-error' user - fi - - ;; - down) - su - -c 'notify-send "$(hostname): LINK IS DOWN !" --icon=dialog-error' user - ;; - esac - ~~~ - -Save the script. - -Make it executable. - - sudo chmod +x /rw/config/vpn/qubes-vpn-handler.sh - -4. Configure client to use the DNS handling script. Using openvpn as an example, edit the config. - - sudo nano /rw/config/vpn/openvpn-client.ovpn - - Add the following. - - ~~~ - script-security 2 - up 'qubes-vpn-handler.sh up' - down 'qubes-vpn-handler.sh down' - ~~~ - -Remove other instances of lines starting with `script-security`, `up` or `down` should there be any others. - -Save the script. - -**Restart the client and test the connection again** ...this time from an AppVM! - -5. Set up iptables anti-leak rules. - -Open Qubes firewall script. - - sudo nano /rw/config/qubes-firewall-user-script - -Clear out the existing lines and add. - - ~~~ - #!/bin/bash - # Block forwarding of connections through upstream network device - # (in case the vpn tunnel breaks): - iptables -I FORWARD -o eth0 -j DROP - iptables -I FORWARD -i eth0 -j DROP - - # Block all outgoing traffic - iptables -P OUTPUT DROP - iptables -F OUTPUT - iptables -I OUTPUT -o lo -j ACCEPT - - # Add the `qvpn` group to system, if it doesn't already exist - if ! grep -q "^qvpn:" /etc/group ; then - groupadd -rf qvpn - sync - fi - sleep 2s - - # Allow traffic from the `qvpn` group to the uplink interface (eth0); - # Our VPN client will run with group `qvpn`. - iptables -I OUTPUT -p all -o eth0 -m owner --gid-owner qvpn -j ACCEPT - ~~~ - -Save the script. - -Make it executable. - - sudo chmod +x /rw/config/qubes-firewall-user-script - -5. Set up the VPN's autostart. - - sudo nano /rw/config/rc.local - -Clear out the existing lines and add. - - ~~~ - #!/bin/bash - VPN_CLIENT='openvpn' - VPN_OPTIONS='--cd /rw/config/vpn/ --config openvpn-client.ovpn --daemon' - - su - -c 'notify-send "$(hostname): Starting $VPN_CLIENT..." --icon=network-idle' user - groupadd -rf qvpn ; sleep 2s - sg qvpn -c "$VPN_CLIENT $VPN_OPTIONS" - ~~~ - -If you are using anything other than OpenVPN, change the `VPN_CLIENT` and `VPN_OPTIONS` variables to match your VPN software. - -Save the script. - -Make it executable. - - sudo chmod +x /rw/config/rc.local - -6. Restart the new VM! The link should then be established automatically with a popup notification to that effect. - -Usage ------ - -Configure your AppVMs to use the VPN VM as a NetVM... - -![Settings-NetVM.png](/attachment/wiki/VPN/Settings-NetVM.png) - - -If you want to be able to use the [Qubes firewall](/doc/firewall), create a new FirewallVM (as a ProxyVM) and set it to use the VPN VM as its NetVM. -Then, configure AppVMs to use your new FirewallVM as their NetVM. - -If you want to update your TemplateVMs through the VPN, enable the `qubes-updates-proxy` service in your new FirewallVM. -You can do this in the Services tab in Qubes VM Manager or on the command-line: - - $ qvm-service -e qubes-updates-proxy - -Then, configure your templates to use your new FirewallVM as their NetVM. - - Troubleshooting --------------- From 56774d73eb8634d29b6d5f112ba2aeb20769bf5f Mon Sep 17 00:00:00 2001 From: Patrick Schleizer Date: Thu, 25 Jan 2018 22:50:43 +0000 Subject: [PATCH 05/67] fix --- configuration/vpn.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/configuration/vpn.md b/configuration/vpn.md index 3a1a4574..ccb12c91 100644 --- a/configuration/vpn.md +++ b/configuration/vpn.md @@ -257,8 +257,9 @@ If you are using anything other than OpenVPN, change the `VPN_CLIENT` and `VPN_O Save the script. -Make it executable: - `sudo chmod +x /rw/config/rc.local` +Make it executable. + + sudo chmod +x /rw/config/rc.local` 6. Restart the new VM! The link should then be established automatically with a popup notification to that effect. From 5fd8389c7399e21a09e17bfe0bf2c8a64688fcc1 Mon Sep 17 00:00:00 2001 From: Patrick Schleizer Date: Thu, 25 Jan 2018 22:52:47 +0000 Subject: [PATCH 06/67] fix --- configuration/vpn.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/configuration/vpn.md b/configuration/vpn.md index ccb12c91..2d326aa0 100644 --- a/configuration/vpn.md +++ b/configuration/vpn.md @@ -82,13 +82,13 @@ Run a terminal (CLI) in the VPN VM -- this will start the VM. Then create a new sudo mkdir /rw/config/vpn -Copy your VPN config files to `/rw/config/vpn`. Your VPN config file should be named `openvpn-client.ovpn`) so you can use the scripts below as is without modification. Otherwise you would have to replace the file name. +Copy your VPN config files to `/rw/config/vpn`. Your VPN config file should be named `openvpn-client.ovpn`) so you can use the scripts below as is without modification. Otherwise you would have to replace the file name. `openvpn-client.ovpn` contents: Files accompanying the main config such as `*.crt` and `*.pem` should also go to `/rw/config/vpn` folder. -Files reference in `openvpn-client.ovpn` should not be referenced by absolute paths such as `/etc/...`. +Files referenced in `openvpn-client.ovpn` should not use absolute paths such as `/etc/...`. -`openvpn-client.ovpn` contents: The VPN scripts here are intended to work with commonly used `tun` interfaces, whereas `tap` mode is untested. +The VPN scripts here are intended to work with commonly used `tun` interfaces, whereas `tap` mode is untested. Also, the config should route all traffic through your VPN's interface after a connection is created; For openvpn the directive for this is `redirect-gateway def1`. For OpenVPN. From 35c721095c7c1f91927e98c6016195ab3b021032 Mon Sep 17 00:00:00 2001 From: awokd <34515595+awokd@users.noreply.github.com> Date: Fri, 26 Jan 2018 11:55:26 +0000 Subject: [PATCH 07/67] Update software-update-dom0.md Dnf vs. Yum, add EFI update --- common-tasks/software-update-dom0.md | 32 ++++++++++++++++++++++------ 1 file changed, 25 insertions(+), 7 deletions(-) diff --git a/common-tasks/software-update-dom0.md b/common-tasks/software-update-dom0.md index 1c59390f..50365969 100644 --- a/common-tasks/software-update-dom0.md +++ b/common-tasks/software-update-dom0.md @@ -58,10 +58,14 @@ Of course, command line tools are still available for accomplishing various upda sudo qubes-dom0-update package-version ~~~ - Yum will say that there is no update, but the package will nonetheless be downloaded to dom0. + Dnf/Yum will say that there is no update, but the package will nonetheless be downloaded to dom0. -2. Downgrade the package: +2. Downgrade the package (R4.0+): + ~~~ + sudo dnf downgrade package-version + ~~~ + R3.2 and earlier ~~~ sudo yum downgrade package-version ~~~ @@ -76,20 +80,26 @@ You can re-install in a similar fashion to downgrading. sudo qubes-dom0-update package ~~~ - Yum will say that there is no update, but the package will nonetheless be downloaded to dom0. + Dnf/Yum will say that there is no update, but the package will nonetheless be downloaded to dom0. -2. Re-install the package: +2. Re-install the package (R4.0+): + ~~~ + sudo dnf reinstall package + ~~~ + R3.2 and earlier ~~~ sudo yum reinstall package ~~~ - Note that yum will only re-install if the installed and downloaded versions match. You can ensure they match by either updating the package to the latest version, or specifying the package version in the first step using the form `package-version`. + Note that Dnf/Yum will only re-install if the installed and downloaded versions match. You can ensure they match by either updating the package to the latest version, or specifying the package version in the first step using the form `package-version`. ### How to uninstall a package -If you've installed a package such as anti-evil-maid, you can remove it with the following command: +If you've installed a package such as anti-evil-maid, you can remove it with the following command (R4.0+): + sudo dnf remove anti-evil-maid +R3.2 and earlier sudo yum remove anti-evil-maid ### Testing repositories @@ -124,8 +134,16 @@ is needed for the VMs. (Note that the following example enables the unstable rep sudo qubes-dom0-update --enablerepo=qubes-dom0-unstable kernel kernel-qubes-vm ~~~ -Rebuild grub config. +If the update process does not automatically do it (you should see it mentioned in the CLI output +from the update command), you may need to manually rebuild the EFI or grub config depending on which +your system uses. +EFI (Replace the file names with the correct versions for your updated kernel) +~~~ +sudo /usr/bin/dracut -f /boot/efi/EFI/qubes/initramfs-4.4.31-11.pvops.qubes.x86_64.img 4.4.31-11.pvops.qubes.x86_64 +~~~ + +Grub2 ~~~ sudo grub2-mkconfig -o /boot/grub2/grub.cfg ~~~ From ad0d428cbcccd2392dc1c77bd487afcca59111c2 Mon Sep 17 00:00:00 2001 From: awokd <34515595+awokd@users.noreply.github.com> Date: Sat, 27 Jan 2018 10:20:53 +0000 Subject: [PATCH 08/67] Remove Yum --- common-tasks/software-update-dom0.md | 24 +++++++----------------- 1 file changed, 7 insertions(+), 17 deletions(-) diff --git a/common-tasks/software-update-dom0.md b/common-tasks/software-update-dom0.md index 50365969..e39a1f2c 100644 --- a/common-tasks/software-update-dom0.md +++ b/common-tasks/software-update-dom0.md @@ -14,7 +14,7 @@ Updating software in dom0 Why would one want to update software in dom0? ---------------------------------------------- -Normally, there should be few reasons for updating software in dom0. This is because there is no networking in dom0, which means that even if some bugs are discovered e.g. in the dom0 Desktop Manager, this really is not a problem for Qubes, because none of the third-party software running in dom0 is accessible from VMs or the network in any way. Some exceptions to this include: Qubes GUI daemon, Xen store daemon, and disk back-ends. (We plan move the disk backends to an untrusted domain in Qubes 2.0.) Of course, we believe this software is reasonably secure, and we hope it will not need patching. +Normally, there should be few reasons for updating software in dom0. This is because there is no networking in dom0, which means that even if some bugs are discovered e.g. in the dom0 Desktop Manager, this really is not a problem for Qubes, because none of the third-party software running in dom0 is accessible from VMs or the network in any way. Some exceptions to this include: Qubes GUI daemon, Xen store daemon, and disk back-ends. (We plan move the disk backends to an untrusted domain.) Of course, we believe this software is reasonably secure, and we hope it will not need patching. However, we anticipate some other situations in which updating dom0 software might be necessary or desirable: @@ -58,17 +58,13 @@ Of course, command line tools are still available for accomplishing various upda sudo qubes-dom0-update package-version ~~~ - Dnf/Yum will say that there is no update, but the package will nonetheless be downloaded to dom0. + Dnf will say that there is no update, but the package will nonetheless be downloaded to dom0. -2. Downgrade the package (R4.0+): +2. Downgrade the package: ~~~ sudo dnf downgrade package-version ~~~ - R3.2 and earlier - ~~~ - sudo yum downgrade package-version - ~~~ ### How to re-install a package @@ -80,27 +76,21 @@ You can re-install in a similar fashion to downgrading. sudo qubes-dom0-update package ~~~ - Dnf/Yum will say that there is no update, but the package will nonetheless be downloaded to dom0. + Dnf will say that there is no update, but the package will nonetheless be downloaded to dom0. -2. Re-install the package (R4.0+): +2. Re-install the package: ~~~ sudo dnf reinstall package ~~~ - R3.2 and earlier - ~~~ - sudo yum reinstall package - ~~~ - Note that Dnf/Yum will only re-install if the installed and downloaded versions match. You can ensure they match by either updating the package to the latest version, or specifying the package version in the first step using the form `package-version`. + Note that Dnf will only re-install if the installed and downloaded versions match. You can ensure they match by either updating the package to the latest version, or specifying the package version in the first step using the form `package-version`. ### How to uninstall a package -If you've installed a package such as anti-evil-maid, you can remove it with the following command (R4.0+): +If you've installed a package such as anti-evil-maid, you can remove it with the following command: sudo dnf remove anti-evil-maid -R3.2 and earlier - sudo yum remove anti-evil-maid ### Testing repositories From 2d5fbd15fe4f7fbadf6dc681a34caf61e7574135 Mon Sep 17 00:00:00 2001 From: awokd <34515595+awokd@users.noreply.github.com> Date: Sat, 27 Jan 2018 13:31:36 +0000 Subject: [PATCH 09/67] Update for 4.0 Split out 4.0 and 3.2 into multiple sections due to multiple minor differences between procedures. Emergency 4.0 Recovery procedure needs to be developed. --- common-tasks/backup-restore.md | 68 ++++++++++++++++++++++++++++++---- 1 file changed, 61 insertions(+), 7 deletions(-) diff --git a/common-tasks/backup-restore.md b/common-tasks/backup-restore.md index 0b2ecaa7..14f02a2f 100644 --- a/common-tasks/backup-restore.md +++ b/common-tasks/backup-restore.md @@ -11,7 +11,7 @@ redirect_from: Qubes Backup, Restoration, and Migration ======================================== -**Caution:** The Qubes backup system currently relies on a [weak key derivation scheme](https://github.com/QubesOS/qubes-issues/issues/971). It is *strongly recommended* that users select a *high-entropy* passphrase for use with Qubes backups. +**Caution:** The Qubes R3.2 backup system currently relies on a [weak key derivation scheme](https://github.com/QubesOS/qubes-issues/issues/971). Although resolved in R4.0 and higher with the switch to scrypt, it is *strongly recommended* that users select a *high-entropy* passphrase for use with Qubes backups. With Qubes, it's easy to back up and restore your whole system, as well as to migrate between two physical machines. @@ -19,7 +19,36 @@ With Qubes, it's easy to back up and restore your whole system, as well as to mi As of Qubes R2B3, these functions are integrated into the Qubes VM Manager GUI. There are also two command-line tools available which perform the same functions: [qvm-backup](/doc/dom0-tools/qvm-backup/) and [qvm-backup-restore](/doc/dom0-tools/qvm-backup-restore/). -Creating a Backup +Creating a Backup (R4.0 and later) +----------------- + +1. In **Qubes VM Manager**, click **System** on the menu bar, then click **Backup Qubes** in the drop-down list. This brings up the **Qubes Backup VMs** window. + +2. Move the VMs that you want to back up to the right-hand **Selected** column. VMs in the left-hand **Available** column will not be backed up. + + **Note:** A VM must be shut down in order to be backed up. Currently running VMs appear in red. + + You may choose whether to compress backups by checking or unchecking the **Compress the backup** box. Normally this should be left on unless you have a specific reason otherwise. + + Once you have selected all desired VMs, click **Next**. + +3. Select the destination for the backup: + + If you wish to send your backup to a (currently running) VM, select the VM in the drop-down box next to **Target AppVM**. + If you wish to send your backup to a [USB mass storage device](/doc/stick-mounting/), first mount the device in a VM, then select the mount point inside that VM as the backup destination. + + You must also specify a directory on the device or in the VM, or a command to be executed in the VM as a destination for your backup. For example, if you wish to send your backup to the `~/backups` folder in the target VM, you would simply type or browse to `backups` in this field. This destination directory must already exist. If it does not exist, you must create it manually prior to backing up. + + By specifying the appropriate directory as the destination in a VM, it is possible to send the backup directly to, e.g., a USB mass storage device attached to the VM. Likewise, it is possible to enter any command as a backup target by specifying the command as the destination in the VM. This can be used to send your backup directly to, e.g., a remote server using SSH. + + **Note:** The supplied passphrase is used for **both** encryption/decryption and integrity verification. + + At this point, you may also choose whether to save your settings by checking or unchecking the **Save settings as default backup profile** box. + **Warning: Saving the settings will result in your backup passphrase being saved in plaintext in dom0, so consider your threat model before checking this box.** + +4. When you are ready, click **Next**. Qubes will proceed to create your backup. Once the progress bar has completed, you may click **Finish**. + +Creating a Backup (R3.2 and earlier) ----------------- 1. In **Qubes VM Manager**, click **System** on the menu bar, then click **Backup VMs** in the drop-down list. This brings up the **Qubes Backup VMs** window. @@ -35,7 +64,7 @@ Creating a Backup If you wish to send your backup to a (currently running) VM, select the VM in the drop-down box next to **Target AppVM**. If you wish to send your backup to a [USB mass storage device](/doc/stick-mounting/), first mount the device in a VM, then select the mount point inside that VM as the backup destination. - You must also specify a directory on the device or in the VM, or a command to be executed in the VM as a destination for your backup. For example, if you wish to send your backup to the `~/backups` folder in the target VM, you would simply type `backups` in this field. This destination directory must already exist. If it does not exist, you must create it manually prior to backing up. + You must also specify a directory on the device or in the VM, or a command to be executed in the VM as a destination for your backup. For example, if you wish to send your backup to the `~/backups` folder in the target VM, you would simply type or browse to `backups` in this field. This destination directory must already exist. If it does not exist, you must create it manually prior to backing up. By specifying the appropriate directory as the destination in a VM, it is possible to send the backup directly to, e.g., a USB mass storage device attached to the VM. Likewise, it is possible to enter any command as a backup target by specifying the command as the destination in the VM. This can be used to send your backup directly to, e.g., a remote server using SSH. @@ -48,7 +77,32 @@ Creating a Backup 4. When you are ready, click **Next**. Qubes will proceed to create your backup. Once the progress bar has completed, you may click **Finish**. -Restoring from a Backup +Restoring from a Backup (R4.0 and later) +----------------------- + +1. In **Qubes VM Manager**, click **System** on the menu bar, then click **Restore Qubes from backup** in the drop-down list. This brings up the **Qubes Restore VMs** window. + +2. Select the source location of the backup to be restored: + + - If your backup is located on a [USB mass storage device](/doc/stick-mounting/), select the device in the drop-down box next to **Device**. + - If your backup is located in a (currently running) VM, select the VM in the drop-down box next to **AppVM**. + + You must also specify the directory in which the backup resides (or a command to be executed in a VM). If you followed the instructions in the previous section, "Creating a Backup," then your backup is most likely in the location you chose as the destination in step 3. For example, if you had chosen the `~/backups` directory of a VM as your destination in step 3, you would now select the same VM and again type `backups` into the **Backup directory** field. + + **Note:** After you have typed the directory location of the backup in the **Backup directory** field, click the ellipsis button `...` to the right of the field. + +3. There are three options you may select when restoring from a backup: + 1. **ignore missing templates and net VMs**: If any of the VMs in your backup depended upon a NetVM or TemplateVM that is not present in (i.e., "missing from") the current system, checking this box will ignore the fact that they are missing and restore the VMs anyway. + 2. **ignore username mismatch**: This option applies only to the restoration of dom0's home directory. If your backup was created on a Qubes system which had a different dom0 username than the dom0 username of the current system, then checking this box will ignore the mismatch between the two usernames and proceed to restore the home directory anyway. + 3. **Verify backup integrity, do not restore the data**: Like it says- check this if you only want to verify. + +4. If your backup is encrypted, you must check the **Encrypted backup** box. If a passphrase was supplied during the creation of your backup (regardless of whether it is encrypted), then you must supply it here. + + **Note:** The passphrase which was supplied when the backup was created was used for **both** encryption/decryption and integrity verification. If the backup was not encrypted, the supplied passphrase is used only for integrity verification. + +5. When you are ready, click **Next**. Qubes will proceed to restore from your backup. Once the progress bar has completed, you may click **Finish**. + +Restoring from a Backup (R3.2 and earlier) ----------------------- 1. In **Qubes VM Manager**, click **System** on the menu bar, then click **Restore VMs from backup** in the drop-down list. This brings up the **Qubes Restore VMs** window. @@ -65,7 +119,7 @@ Restoring from a Backup 3. There are three options you may select when restoring from a backup: 1. **ignore missing**: If any of the VMs in your backup depended upon a NetVM, ProxyVM, or TemplateVM that is not present in (i.e., "missing from") the current system, checking this box will ignore the fact that they are missing and restore the VMs anyway. 2. **ignore username mismatch**: This option applies only to the restoration of dom0's home directory. If your backup was created on a Qubes system which had a different dom0 username than the dom0 username of the current system, then checking this box will ignore the mismatch between the two usernames and proceed to restore the home directory anyway. - 3. **skip dom0**: If this box is checked, dom0's home directory will not be restored from your backup. + 3. **Verify backup integrity, do not restore the data**: Like it says- check this if you only want to verify. 4. If your backup is encrypted, you must check the **Encrypted backup** box. If a passphrase was supplied during the creation of your backup (regardless of whether it is encrypted), then you must supply it here. @@ -81,7 +135,7 @@ Emergency Backup Recovery without Qubes The Qubes backup system has been designed with emergency disaster recovery in mind. No special Qubes-specific tools are required to access data backed up by Qubes. In the event a Qubes system is unavailable, you can access your data on any GNU/Linux system with the following procedure. -For emergency restore of backup created on Qubes R2 or newer take a look [here](/doc/backup-emergency-restore-v3/). For backups created on earlier Qubes version, take a look [here](/doc/backup-emergency-restore-v2/). +For emergency restore of a backup created on Qubes R4 or newer, take a look here (TBD). For R3 take a look [here](/doc/backup-emergency-restore-v3/). For backups created on even earlier Qubes versions, take a look [here](/doc/backup-emergency-restore-v2/). Migrating Between Two Physical Machines @@ -101,6 +155,6 @@ Here are some things to consider when selecting a passphrase for your backups: Notes ----- - * The Qubes backup system relies on `openssl enc`, which is known to use a very weak key derivation scheme. The Qubes backup system also uses the same passphrase for authentication and for encryption, which is problematic from a security perspective. Users are advised to use a very high entropy passphrase for Qubes backups. For a full discussion, see [this ticket](https://github.com/QubesOS/qubes-issues/issues/971) and [this thread](https://groups.google.com/d/msg/qubes-devel/CZ7WRwLXcnk/u_rZPoVxL5IJ). + * The Qubes R3.2 and earlier backup system relies on `openssl enc`, which is known to use a very weak key derivation scheme. The Qubes backup system also uses the same passphrase for authentication and for encryption, which is problematic from a security perspective. Users are advised to use a very high entropy passphrase for Qubes backups. For a full discussion, see [this ticket](https://github.com/QubesOS/qubes-issues/issues/971) and [this thread](https://groups.google.com/d/msg/qubes-devel/CZ7WRwLXcnk/u_rZPoVxL5IJ). * For the technical details of the backup system, please refer to [this thread](https://groups.google.com/d/topic/qubes-devel/TQr_QcXIVww/discussion). * If working with symlinks, note the issues described in [this thread](https://groups.google.com/d/topic/qubes-users/EITd1kBHD30/discussion). From 1d9c917d7988a58b8b0237b636e6caef22a1249b Mon Sep 17 00:00:00 2001 From: awokd <34515595+awokd@users.noreply.github.com> Date: Sat, 27 Jan 2018 17:29:16 +0000 Subject: [PATCH 10/67] Add link to v4 emergency restore Didn't need to develop, just had to have it pointed out to me --- common-tasks/backup-restore.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/common-tasks/backup-restore.md b/common-tasks/backup-restore.md index 14f02a2f..dfaaa433 100644 --- a/common-tasks/backup-restore.md +++ b/common-tasks/backup-restore.md @@ -135,7 +135,11 @@ Emergency Backup Recovery without Qubes The Qubes backup system has been designed with emergency disaster recovery in mind. No special Qubes-specific tools are required to access data backed up by Qubes. In the event a Qubes system is unavailable, you can access your data on any GNU/Linux system with the following procedure. -For emergency restore of a backup created on Qubes R4 or newer, take a look here (TBD). For R3 take a look [here](/doc/backup-emergency-restore-v3/). For backups created on even earlier Qubes versions, take a look [here](/doc/backup-emergency-restore-v2/). +Refer to the follow for emergency restore of a backup created on: + + * [Qubes R4 or newer](/doc/backup-emergency-restore-v4/) + * [Qubes R3](/doc/backup-emergency-restore-v3/) + * [Earlier Qubes versions](/doc/backup-emergency-restore-v2/) Migrating Between Two Physical Machines From b975d77280dd87a5f48c219e55c5b255a1f8bca8 Mon Sep 17 00:00:00 2001 From: awokd <34515595+awokd@users.noreply.github.com> Date: Sat, 27 Jan 2018 17:34:30 +0000 Subject: [PATCH 11/67] Grammar and word choice --- common-tasks/backup-restore.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/common-tasks/backup-restore.md b/common-tasks/backup-restore.md index dfaaa433..c7de18b4 100644 --- a/common-tasks/backup-restore.md +++ b/common-tasks/backup-restore.md @@ -135,11 +135,11 @@ Emergency Backup Recovery without Qubes The Qubes backup system has been designed with emergency disaster recovery in mind. No special Qubes-specific tools are required to access data backed up by Qubes. In the event a Qubes system is unavailable, you can access your data on any GNU/Linux system with the following procedure. -Refer to the follow for emergency restore of a backup created on: +Refer to the following for emergency restore of a backup created on: * [Qubes R4 or newer](/doc/backup-emergency-restore-v4/) * [Qubes R3](/doc/backup-emergency-restore-v3/) - * [Earlier Qubes versions](/doc/backup-emergency-restore-v2/) + * [Qubes R2 or older](/doc/backup-emergency-restore-v2/) Migrating Between Two Physical Machines From 80c0a3c47004e6b5067bd09a5f6214a3f2ae842b Mon Sep 17 00:00:00 2001 From: awokd <34515595+awokd@users.noreply.github.com> Date: Sat, 27 Jan 2018 17:57:08 +0000 Subject: [PATCH 12/67] Better description of Verify only restore option --- common-tasks/backup-restore.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/common-tasks/backup-restore.md b/common-tasks/backup-restore.md index c7de18b4..42e7c6fd 100644 --- a/common-tasks/backup-restore.md +++ b/common-tasks/backup-restore.md @@ -94,7 +94,7 @@ Restoring from a Backup (R4.0 and later) 3. There are three options you may select when restoring from a backup: 1. **ignore missing templates and net VMs**: If any of the VMs in your backup depended upon a NetVM or TemplateVM that is not present in (i.e., "missing from") the current system, checking this box will ignore the fact that they are missing and restore the VMs anyway. 2. **ignore username mismatch**: This option applies only to the restoration of dom0's home directory. If your backup was created on a Qubes system which had a different dom0 username than the dom0 username of the current system, then checking this box will ignore the mismatch between the two usernames and proceed to restore the home directory anyway. - 3. **Verify backup integrity, do not restore the data**: Like it says- check this if you only want to verify. + 3. **Verify backup integrity, do not restore the data**: This will scan the backup file for corrupted data. However, it does not currently detect if it is missing data as long as it is a correctly structured, non-corrupted backup file. See [issue #3498](https://github.com/QubesOS/qubes-issues/issues/3498) for more details. 4. If your backup is encrypted, you must check the **Encrypted backup** box. If a passphrase was supplied during the creation of your backup (regardless of whether it is encrypted), then you must supply it here. @@ -119,7 +119,7 @@ Restoring from a Backup (R3.2 and earlier) 3. There are three options you may select when restoring from a backup: 1. **ignore missing**: If any of the VMs in your backup depended upon a NetVM, ProxyVM, or TemplateVM that is not present in (i.e., "missing from") the current system, checking this box will ignore the fact that they are missing and restore the VMs anyway. 2. **ignore username mismatch**: This option applies only to the restoration of dom0's home directory. If your backup was created on a Qubes system which had a different dom0 username than the dom0 username of the current system, then checking this box will ignore the mismatch between the two usernames and proceed to restore the home directory anyway. - 3. **Verify backup integrity, do not restore the data**: Like it says- check this if you only want to verify. + 3. **Verify backup integrity, do not restore the data**: This will scan the backup file for corrupted data. However, it does not currently detect if it is missing data as long as it is a correctly structured, non-corrupted backup file. See [issue #3498](https://github.com/QubesOS/qubes-issues/issues/3498) for more details.. 4. If your backup is encrypted, you must check the **Encrypted backup** box. If a passphrase was supplied during the creation of your backup (regardless of whether it is encrypted), then you must supply it here. From 2c02e7a13a36be1d2e1963c5ecceac1427f01b22 Mon Sep 17 00:00:00 2001 From: awokd <34515595+awokd@users.noreply.github.com> Date: Sat, 27 Jan 2018 18:12:29 +0000 Subject: [PATCH 13/67] Added whitespace, removed superfluous "." --- common-tasks/backup-restore.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/common-tasks/backup-restore.md b/common-tasks/backup-restore.md index 42e7c6fd..9940f6ca 100644 --- a/common-tasks/backup-restore.md +++ b/common-tasks/backup-restore.md @@ -44,6 +44,7 @@ Creating a Backup (R4.0 and later) **Note:** The supplied passphrase is used for **both** encryption/decryption and integrity verification. At this point, you may also choose whether to save your settings by checking or unchecking the **Save settings as default backup profile** box. + **Warning: Saving the settings will result in your backup passphrase being saved in plaintext in dom0, so consider your threat model before checking this box.** 4. When you are ready, click **Next**. Qubes will proceed to create your backup. Once the progress bar has completed, you may click **Finish**. @@ -119,7 +120,7 @@ Restoring from a Backup (R3.2 and earlier) 3. There are three options you may select when restoring from a backup: 1. **ignore missing**: If any of the VMs in your backup depended upon a NetVM, ProxyVM, or TemplateVM that is not present in (i.e., "missing from") the current system, checking this box will ignore the fact that they are missing and restore the VMs anyway. 2. **ignore username mismatch**: This option applies only to the restoration of dom0's home directory. If your backup was created on a Qubes system which had a different dom0 username than the dom0 username of the current system, then checking this box will ignore the mismatch between the two usernames and proceed to restore the home directory anyway. - 3. **Verify backup integrity, do not restore the data**: This will scan the backup file for corrupted data. However, it does not currently detect if it is missing data as long as it is a correctly structured, non-corrupted backup file. See [issue #3498](https://github.com/QubesOS/qubes-issues/issues/3498) for more details.. + 3. **Verify backup integrity, do not restore the data**: This will scan the backup file for corrupted data. However, it does not currently detect if it is missing data as long as it is a correctly structured, non-corrupted backup file. See [issue #3498](https://github.com/QubesOS/qubes-issues/issues/3498) for more details. 4. If your backup is encrypted, you must check the **Encrypted backup** box. If a passphrase was supplied during the creation of your backup (regardless of whether it is encrypted), then you must supply it here. From 047353056aa1e2fc33f4ce7eb2dedc06d030f4f0 Mon Sep 17 00:00:00 2001 From: awokd <34515595+awokd@users.noreply.github.com> Date: Sun, 28 Jan 2018 17:50:45 +0000 Subject: [PATCH 14/67] Update backup-restore.md --- common-tasks/backup-restore.md | 48 ++++++++++++++++++---------------- 1 file changed, 25 insertions(+), 23 deletions(-) diff --git a/common-tasks/backup-restore.md b/common-tasks/backup-restore.md index 9940f6ca..9593fa4d 100644 --- a/common-tasks/backup-restore.md +++ b/common-tasks/backup-restore.md @@ -22,12 +22,10 @@ As of Qubes R2B3, these functions are integrated into the Qubes VM Manager GUI. Creating a Backup (R4.0 and later) ----------------- -1. In **Qubes VM Manager**, click **System** on the menu bar, then click **Backup Qubes** in the drop-down list. This brings up the **Qubes Backup VMs** window. +1. Go to **Applications menu -> System Tools -> Backup Qubes**. This brings up the **Qubes Backup VMs** window. 2. Move the VMs that you want to back up to the right-hand **Selected** column. VMs in the left-hand **Available** column will not be backed up. - **Note:** A VM must be shut down in order to be backed up. Currently running VMs appear in red. - You may choose whether to compress backups by checking or unchecking the **Compress the backup** box. Normally this should be left on unless you have a specific reason otherwise. Once you have selected all desired VMs, click **Next**. @@ -35,9 +33,9 @@ Creating a Backup (R4.0 and later) 3. Select the destination for the backup: If you wish to send your backup to a (currently running) VM, select the VM in the drop-down box next to **Target AppVM**. - If you wish to send your backup to a [USB mass storage device](/doc/stick-mounting/), first mount the device in a VM, then select the mount point inside that VM as the backup destination. + If you wish to send your backup to a [USB mass storage device](/doc/stick-mounting/), you can use the directory selection widget to mount a connected device (under "Other locations" item on the left); or first mount the device in a VM, then select the mount point inside that VM as the backup destination. - You must also specify a directory on the device or in the VM, or a command to be executed in the VM as a destination for your backup. For example, if you wish to send your backup to the `~/backups` folder in the target VM, you would simply type or browse to `backups` in this field. This destination directory must already exist. If it does not exist, you must create it manually prior to backing up. + You must also specify a directory on the device or in the VM, or a command to be executed in the VM as a destination for your backup. For example, if you wish to send your backup to the `~/backups` folder in the target VM, you would simply browse to it using the convenient directory selection dialog (`...`) at the right. This destination directory must already exist. If it does not exist, you must create it manually prior to backing up. By specifying the appropriate directory as the destination in a VM, it is possible to send the backup directly to, e.g., a USB mass storage device attached to the VM. Likewise, it is possible to enter any command as a backup target by specifying the command as the destination in the VM. This can be used to send your backup directly to, e.g., a remote server using SSH. @@ -47,7 +45,9 @@ Creating a Backup (R4.0 and later) **Warning: Saving the settings will result in your backup passphrase being saved in plaintext in dom0, so consider your threat model before checking this box.** -4. When you are ready, click **Next**. Qubes will proceed to create your backup. Once the progress bar has completed, you may click **Finish**. +4. You will now the the summary of VMs to be backed up. If there are any issues preventing the backup, they will be listed here and the **Next** button greyed out. + +5. When you are ready, click **Next**. Qubes will proceed to create your backup. Once the progress bar has completed, you may click **Finish**. Creating a Backup (R3.2 and earlier) ----------------- @@ -63,9 +63,9 @@ Creating a Backup (R3.2 and earlier) 3. Select the destination for the backup: If you wish to send your backup to a (currently running) VM, select the VM in the drop-down box next to **Target AppVM**. - If you wish to send your backup to a [USB mass storage device](/doc/stick-mounting/), first mount the device in a VM, then select the mount point inside that VM as the backup destination. + If you wish to send your backup to a [USB mass storage device](/doc/stick-mounting/), you can use the directory selection widget to mount a connected device (under "Other locations" item on the left); or first mount the device in a VM, then select the mount point inside that VM as the backup destination. - You must also specify a directory on the device or in the VM, or a command to be executed in the VM as a destination for your backup. For example, if you wish to send your backup to the `~/backups` folder in the target VM, you would simply type or browse to `backups` in this field. This destination directory must already exist. If it does not exist, you must create it manually prior to backing up. + You must also specify a directory on the device or in the VM, or a command to be executed in the VM as a destination for your backup. For example, if you wish to send your backup to the `~/backups` folder in the target VM, you would simply browse to it using the convenient directory selection dialog (`...`) at the right. If it does not exist, you must create it manually prior to backing up. By specifying the appropriate directory as the destination in a VM, it is possible to send the backup directly to, e.g., a USB mass storage device attached to the VM. Likewise, it is possible to enter any command as a backup target by specifying the command as the destination in the VM. This can be used to send your backup directly to, e.g., a remote server using SSH. @@ -75,33 +75,35 @@ Creating a Backup (R3.2 and earlier) **Note:** The supplied passphrase is used for **both** encryption/decryption and integrity verification. If you decide not to encrypt your backup (by unchecking the **Encrypt backup** box), the passphrase you supply will be used **only** for integrity verification. If you supply a passphrase but do not check the **Encrypt backup** box, your backup will **not** be encrypted! -4. When you are ready, click **Next**. Qubes will proceed to create your backup. Once the progress bar has completed, you may click **Finish**. +4. You will now the the summary of VMs to be backed up. If there are any issues preventing the backup, they will be listed here and the **Next** button greyed out. + +5. When you are ready, click **Next**. Qubes will proceed to create your backup. Once the progress bar has completed, you may click **Finish**. Restoring from a Backup (R4.0 and later) ----------------------- -1. In **Qubes VM Manager**, click **System** on the menu bar, then click **Restore Qubes from backup** in the drop-down list. This brings up the **Qubes Restore VMs** window. +1. Go to **Applications menu -> System Tools -> Restore Backup**. This brings up the **Qubes Restore VMs** window. 2. Select the source location of the backup to be restored: - - If your backup is located on a [USB mass storage device](/doc/stick-mounting/), select the device in the drop-down box next to **Device**. + - If your backup is located on a [USB mass storage device](/doc/stick-mounting/), attach it first to another VM or select `sys-usb` in the next item. - If your backup is located in a (currently running) VM, select the VM in the drop-down box next to **AppVM**. - You must also specify the directory in which the backup resides (or a command to be executed in a VM). If you followed the instructions in the previous section, "Creating a Backup," then your backup is most likely in the location you chose as the destination in step 3. For example, if you had chosen the `~/backups` directory of a VM as your destination in step 3, you would now select the same VM and again type `backups` into the **Backup directory** field. - - **Note:** After you have typed the directory location of the backup in the **Backup directory** field, click the ellipsis button `...` to the right of the field. + You must also specify the directory and filename of the backup (or a command to be executed in a VM) in the **Backup file** field. If you followed the instructions in the previous section, "Creating a Backup," then your backup is most likely in the location you chose as the destination in step 3. For example, if you had chosen the `~/backups` directory of a VM as your destination in step 3, you would now select the same VM and again browse to (using `...`) the `backups` folder. Once you've located the backup file, double-click it or select it and hit **OK**. 3. There are three options you may select when restoring from a backup: - 1. **ignore missing templates and net VMs**: If any of the VMs in your backup depended upon a NetVM or TemplateVM that is not present in (i.e., "missing from") the current system, checking this box will ignore the fact that they are missing and restore the VMs anyway. + 1. **ignore missing templates and net VMs**: If any of the VMs in your backup depended upon a NetVM or TemplateVM that is not present in (i.e., "missing from") the current system, checking this box will ignore the fact that they are missing and restore the VMs anyway and set them to use the default NetVM and system default template. 2. **ignore username mismatch**: This option applies only to the restoration of dom0's home directory. If your backup was created on a Qubes system which had a different dom0 username than the dom0 username of the current system, then checking this box will ignore the mismatch between the two usernames and proceed to restore the home directory anyway. 3. **Verify backup integrity, do not restore the data**: This will scan the backup file for corrupted data. However, it does not currently detect if it is missing data as long as it is a correctly structured, non-corrupted backup file. See [issue #3498](https://github.com/QubesOS/qubes-issues/issues/3498) for more details. 4. If your backup is encrypted, you must check the **Encrypted backup** box. If a passphrase was supplied during the creation of your backup (regardless of whether it is encrypted), then you must supply it here. - **Note:** The passphrase which was supplied when the backup was created was used for **both** encryption/decryption and integrity verification. If the backup was not encrypted, the supplied passphrase is used only for integrity verification. + **Note:** The passphrase which was supplied when the backup was created was used for **both** encryption/decryption and integrity verification. If the backup was not encrypted, the supplied passphrase is used only for integrity verification. All backups made from a Qubes R4.0 system will be encrypted. -5. When you are ready, click **Next**. Qubes will proceed to restore from your backup. Once the progress bar has completed, you may click **Finish**. +5. You will now the the summary of VMs to be restored. If there are any issues preventing the restore, they will be listed here and the **Next** button greyed out. + +6. When you are ready, click **Next**. Qubes will proceed to restore from your backup. Once the progress bar has completed, you may click **Finish**. Restoring from a Backup (R3.2 and earlier) ----------------------- @@ -110,15 +112,13 @@ Restoring from a Backup (R3.2 and earlier) 2. Select the source location of the backup to be restored: - - If your backup is located on a [USB mass storage device](/doc/stick-mounting/), select the device in the drop-down box next to **Device**. + - If your backup is located on a [USB mass storage device](/doc/stick-mounting/), attach it first to another VM or select `sys-usb` in the next item. - If your backup is located in a (currently running) VM, select the VM in the drop-down box next to **AppVM**. - You must also specify the directory in which the backup resides (or a command to be executed in a VM). If you followed the instructions in the previous section, "Creating a Backup," then your backup is most likely in the location you chose as the destination in step 3. For example, if you had chosen the `~/backups` directory of a VM as your destination in step 3, you would now select the same VM and again type `backups` into the **Backup directory** field. - - **Note:** After you have typed the directory location of the backup in the **Backup directory** field, click the ellipsis button `...` to the right of the field. + You must also specify the directory and filename of the backup (or a command to be executed in a VM) in the **Backup file** field. If you followed the instructions in the previous section, "Creating a Backup," then your backup is most likely in the location you chose as the destination in step 3. For example, if you had chosen the `~/backups` directory of a VM as your destination in step 3, you would now select the same VM and again browse to (using `...`) the `backups` folder. Once you've located the backup file, double-click or select it and hit **OK**. 3. There are three options you may select when restoring from a backup: - 1. **ignore missing**: If any of the VMs in your backup depended upon a NetVM, ProxyVM, or TemplateVM that is not present in (i.e., "missing from") the current system, checking this box will ignore the fact that they are missing and restore the VMs anyway. + 1. **ignore missing**: If any of the VMs in your backup depended upon a NetVM, ProxyVM, or TemplateVM that is not present in (i.e., "missing from") the current system, checking this box will ignore the fact that they are missing and restore the VMs anyway and set them to use the default NetVM and system default template. 2. **ignore username mismatch**: This option applies only to the restoration of dom0's home directory. If your backup was created on a Qubes system which had a different dom0 username than the dom0 username of the current system, then checking this box will ignore the mismatch between the two usernames and proceed to restore the home directory anyway. 3. **Verify backup integrity, do not restore the data**: This will scan the backup file for corrupted data. However, it does not currently detect if it is missing data as long as it is a correctly structured, non-corrupted backup file. See [issue #3498](https://github.com/QubesOS/qubes-issues/issues/3498) for more details. @@ -128,7 +128,9 @@ Restoring from a Backup (R3.2 and earlier) **Note:** A VM cannot be restored from a backup if a VM with the same name already exists on the current system. You must first remove or change the name of any VM with the same name in order to restore such a VM. -5. When you are ready, click **Next**. Qubes will proceed to restore from your backup. Once the progress bar has completed, you may click **Finish**. +5. You will now the the summary of VMs to be restored. If there are any issues preventing the restore, they will be listed here and the **Next** button greyed out. + +6. When you are ready, click **Next**. Qubes will proceed to restore from your backup. Once the progress bar has completed, you may click **Finish**. Emergency Backup Recovery without Qubes From 75a7a003c596ac07aa710c2b75c1bf48f5d3855e Mon Sep 17 00:00:00 2001 From: Patrick Schleizer Date: Sun, 28 Jan 2018 19:23:24 +0100 Subject: [PATCH 15/67] fix duplicate "For OpenVPN." --- configuration/vpn.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/configuration/vpn.md b/configuration/vpn.md index 2d326aa0..f0029828 100644 --- a/configuration/vpn.md +++ b/configuration/vpn.md @@ -90,7 +90,7 @@ Files referenced in `openvpn-client.ovpn` should not use absolute paths such as The VPN scripts here are intended to work with commonly used `tun` interfaces, whereas `tap` mode is untested. -Also, the config should route all traffic through your VPN's interface after a connection is created; For openvpn the directive for this is `redirect-gateway def1`. For OpenVPN. +Also, the config should route all traffic through your VPN's interface after a connection is created; For OpenVPN the directive for this is `redirect-gateway def1`. sudo nano /rw/config/vpn/openvpn-client.ovpn From 15bf72edad40c7de87113c1f404ccde6f86e821c Mon Sep 17 00:00:00 2001 From: Patrick Schleizer Date: Sun, 28 Jan 2018 19:26:35 +0100 Subject: [PATCH 16/67] fixes --- configuration/vpn.md | 16 +++++++--------- 1 file changed, 7 insertions(+), 9 deletions(-) diff --git a/configuration/vpn.md b/configuration/vpn.md index f0029828..3518b9ef 100644 --- a/configuration/vpn.md +++ b/configuration/vpn.md @@ -94,11 +94,11 @@ Also, the config should route all traffic through your VPN's interface after a c sudo nano /rw/config/vpn/openvpn-client.ovpn -Make sure it already includes or add. +Make sure it already includes or add: redirect-gateway def1 -The VPN client may not be able to prompt you for credentials when connecting to the server. Create a file in the `/rw/config/vpn` folder with your credentials and using a directive. For example for OpenVPN, add. +The VPN client may not be able to prompt you for credentials when connecting to the server. Create a file in the `/rw/config/vpn` folder with your credentials and using a directive. For example for OpenVPN, add: auth-user-pass pass.txt @@ -108,12 +108,10 @@ The VPN client may not be able to prompt you for credentials when connecting to sudo nano /rw/config/vpn/pass.txt - Add. + Add: - ``` - username - password - ``` + username + password Replace `username` and `password` with your actual username and password. @@ -205,7 +203,7 @@ Save the script. sudo nano /rw/config/qubes-firewall-user-script -Clear out the existing lines and add. +Clear out the existing lines and add: ~~~ #!/bin/bash @@ -241,7 +239,7 @@ Make it executable. sudo nano /rw/config/rc.local -Clear out the existing lines and add. +Clear out the existing lines and add: ~~~ #!/bin/bash From ee5361c3e3602fcc6fe5293e5a7e79d5150fd01d Mon Sep 17 00:00:00 2001 From: awokd <34515595+awokd@users.noreply.github.com> Date: Sun, 28 Jan 2018 19:31:21 +0000 Subject: [PATCH 17/67] Update backup-restore.md --- common-tasks/backup-restore.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/common-tasks/backup-restore.md b/common-tasks/backup-restore.md index 9593fa4d..d07e1e1a 100644 --- a/common-tasks/backup-restore.md +++ b/common-tasks/backup-restore.md @@ -33,7 +33,7 @@ Creating a Backup (R4.0 and later) 3. Select the destination for the backup: If you wish to send your backup to a (currently running) VM, select the VM in the drop-down box next to **Target AppVM**. - If you wish to send your backup to a [USB mass storage device](/doc/stick-mounting/), you can use the directory selection widget to mount a connected device (under "Other locations" item on the left); or first mount the device in a VM, then select the mount point inside that VM as the backup destination. + If you wish to send your backup to a [USB mass storage device](/doc/usb/), you can use the directory selection widget to mount a connected device (under "Other locations" item on the left); or first mount the device in a VM, then select the mount point inside that VM as the backup destination. You must also specify a directory on the device or in the VM, or a command to be executed in the VM as a destination for your backup. For example, if you wish to send your backup to the `~/backups` folder in the target VM, you would simply browse to it using the convenient directory selection dialog (`...`) at the right. This destination directory must already exist. If it does not exist, you must create it manually prior to backing up. @@ -45,7 +45,7 @@ Creating a Backup (R4.0 and later) **Warning: Saving the settings will result in your backup passphrase being saved in plaintext in dom0, so consider your threat model before checking this box.** -4. You will now the the summary of VMs to be backed up. If there are any issues preventing the backup, they will be listed here and the **Next** button greyed out. +4. You will now see the summary of VMs to be backed up. If there are any issues preventing the backup, they will be listed here and the **Next** button greyed out. 5. When you are ready, click **Next**. Qubes will proceed to create your backup. Once the progress bar has completed, you may click **Finish**. @@ -63,7 +63,7 @@ Creating a Backup (R3.2 and earlier) 3. Select the destination for the backup: If you wish to send your backup to a (currently running) VM, select the VM in the drop-down box next to **Target AppVM**. - If you wish to send your backup to a [USB mass storage device](/doc/stick-mounting/), you can use the directory selection widget to mount a connected device (under "Other locations" item on the left); or first mount the device in a VM, then select the mount point inside that VM as the backup destination. + If you wish to send your backup to a [USB mass storage device](/doc/usb/), you can use the directory selection widget to mount a connected device (under "Other locations" item on the left); or first mount the device in a VM, then select the mount point inside that VM as the backup destination. You must also specify a directory on the device or in the VM, or a command to be executed in the VM as a destination for your backup. For example, if you wish to send your backup to the `~/backups` folder in the target VM, you would simply browse to it using the convenient directory selection dialog (`...`) at the right. If it does not exist, you must create it manually prior to backing up. @@ -75,7 +75,7 @@ Creating a Backup (R3.2 and earlier) **Note:** The supplied passphrase is used for **both** encryption/decryption and integrity verification. If you decide not to encrypt your backup (by unchecking the **Encrypt backup** box), the passphrase you supply will be used **only** for integrity verification. If you supply a passphrase but do not check the **Encrypt backup** box, your backup will **not** be encrypted! -4. You will now the the summary of VMs to be backed up. If there are any issues preventing the backup, they will be listed here and the **Next** button greyed out. +4. You will now see the summary of VMs to be backed up. If there are any issues preventing the backup, they will be listed here and the **Next** button greyed out. 5. When you are ready, click **Next**. Qubes will proceed to create your backup. Once the progress bar has completed, you may click **Finish**. @@ -87,7 +87,7 @@ Restoring from a Backup (R4.0 and later) 2. Select the source location of the backup to be restored: - - If your backup is located on a [USB mass storage device](/doc/stick-mounting/), attach it first to another VM or select `sys-usb` in the next item. + - If your backup is located on a [USB mass storage device](/doc/usb/), attach it first to another VM or select `sys-usb` in the next item. - If your backup is located in a (currently running) VM, select the VM in the drop-down box next to **AppVM**. You must also specify the directory and filename of the backup (or a command to be executed in a VM) in the **Backup file** field. If you followed the instructions in the previous section, "Creating a Backup," then your backup is most likely in the location you chose as the destination in step 3. For example, if you had chosen the `~/backups` directory of a VM as your destination in step 3, you would now select the same VM and again browse to (using `...`) the `backups` folder. Once you've located the backup file, double-click it or select it and hit **OK**. @@ -101,7 +101,7 @@ Restoring from a Backup (R4.0 and later) **Note:** The passphrase which was supplied when the backup was created was used for **both** encryption/decryption and integrity verification. If the backup was not encrypted, the supplied passphrase is used only for integrity verification. All backups made from a Qubes R4.0 system will be encrypted. -5. You will now the the summary of VMs to be restored. If there are any issues preventing the restore, they will be listed here and the **Next** button greyed out. +5. You will now see the summary of VMs to be restored. If there are any issues preventing the restore, they will be listed here and the **Next** button greyed out. 6. When you are ready, click **Next**. Qubes will proceed to restore from your backup. Once the progress bar has completed, you may click **Finish**. @@ -112,7 +112,7 @@ Restoring from a Backup (R3.2 and earlier) 2. Select the source location of the backup to be restored: - - If your backup is located on a [USB mass storage device](/doc/stick-mounting/), attach it first to another VM or select `sys-usb` in the next item. + - If your backup is located on a [USB mass storage device](/doc/usb/), attach it first to another VM or select `sys-usb` in the next item. - If your backup is located in a (currently running) VM, select the VM in the drop-down box next to **AppVM**. You must also specify the directory and filename of the backup (or a command to be executed in a VM) in the **Backup file** field. If you followed the instructions in the previous section, "Creating a Backup," then your backup is most likely in the location you chose as the destination in step 3. For example, if you had chosen the `~/backups` directory of a VM as your destination in step 3, you would now select the same VM and again browse to (using `...`) the `backups` folder. Once you've located the backup file, double-click or select it and hit **OK**. @@ -128,7 +128,7 @@ Restoring from a Backup (R3.2 and earlier) **Note:** A VM cannot be restored from a backup if a VM with the same name already exists on the current system. You must first remove or change the name of any VM with the same name in order to restore such a VM. -5. You will now the the summary of VMs to be restored. If there are any issues preventing the restore, they will be listed here and the **Next** button greyed out. +5. You will now see the summary of VMs to be restored. If there are any issues preventing the restore, they will be listed here and the **Next** button greyed out. 6. When you are ready, click **Next**. Qubes will proceed to restore from your backup. Once the progress bar has completed, you may click **Finish**. From 6b3eb8fd71bf7ef4f65c52a1584f10d2b4b0f52d Mon Sep 17 00:00:00 2001 From: Peter Gerber Date: Sun, 28 Jan 2018 23:14:56 +0100 Subject: [PATCH 18/67] clarify description for randomizing MAC addresses --- privacy/anonymizing-your-mac-address.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/privacy/anonymizing-your-mac-address.md b/privacy/anonymizing-your-mac-address.md index 7a92429e..3e7f0921 100644 --- a/privacy/anonymizing-your-mac-address.md +++ b/privacy/anonymizing-your-mac-address.md @@ -37,7 +37,7 @@ ethernet.cloned-mac-address=stable connection.stable-id=${CONNECTION}/${BOOT} ~~~ -* `stable` in combination with `${CONNECTION}/${BOOT}` generates a random address that persists for each boot session. +* `stable` in combination with `${CONNECTION}/${BOOT}` generates a random address that persists until reboot. * `random` generates a random address each time a link goes up. To see all the available configuration options, refer to the man page: `man nm-settings` From 9db21775d3c64ea54aa9f3061e5b8716670740b1 Mon Sep 17 00:00:00 2001 From: Patrick Schleizer Date: Mon, 29 Jan 2018 14:10:53 +0100 Subject: [PATCH 19/67] remove trailing spaces --- configuration/vpn.md | 58 ++++++++++++++++++++++---------------------- 1 file changed, 29 insertions(+), 29 deletions(-) diff --git a/configuration/vpn.md b/configuration/vpn.md index 3518b9ef..475446d3 100644 --- a/configuration/vpn.md +++ b/configuration/vpn.md @@ -65,23 +65,23 @@ This method is more involved than the one above, but has anti-leak features that 1. Create a new VM, name it, click the ProxyVM radio button, and choose a color and template. ![Create\_New\_VM.png](/attachment/wiki/VPN/Create_New_VM.png) - + Note: Do not enable NetworkManager in the ProxyVM, as it can interfere with the scripts' DNS features. If you enabled NetworkManager or used other methods in a previous attempt, do not re-use the old ProxyVM... Create a new one according to this step. - + If your choice of TemplateVM doesn't already have the VPN client software, you'll need to install the software in the template before proceeding. Disable any auto-starting service that comes with the software package. For example for OpenVPN. - + sudo systemctl disable openvpn.service - + You may also wish to install `nano` or another simple text editor for entering the scripts below. 2. Set up and test the VPN client. Make sure the VPN VM and its TemplateVM is not running. - + Run a terminal (CLI) in the VPN VM -- this will start the VM. Then create a new `/rw/config/vpn` folder with. - + sudo mkdir /rw/config/vpn - + Copy your VPN config files to `/rw/config/vpn`. Your VPN config file should be named `openvpn-client.ovpn`) so you can use the scripts below as is without modification. Otherwise you would have to replace the file name. `openvpn-client.ovpn` contents: Files accompanying the main config such as `*.crt` and `*.pem` should also go to `/rw/config/vpn` folder. @@ -93,7 +93,7 @@ The VPN scripts here are intended to work with commonly used `tun` interfaces, w Also, the config should route all traffic through your VPN's interface after a connection is created; For OpenVPN the directive for this is `redirect-gateway def1`. sudo nano /rw/config/vpn/openvpn-client.ovpn - + Make sure it already includes or add: redirect-gateway def1 @@ -101,38 +101,38 @@ Make sure it already includes or add: The VPN client may not be able to prompt you for credentials when connecting to the server. Create a file in the `/rw/config/vpn` folder with your credentials and using a directive. For example for OpenVPN, add: auth-user-pass pass.txt - + Save file `/rw/config/vpn/openvpn-client.ovpn`. - + Make sure a `/rw/config/vpn/pass.txt` file actually exists. - + sudo nano /rw/config/vpn/pass.txt - + Add: - + username password - + Replace `username` and `password` with your actual username and password. - + __Test your client configuration:__ Run the client from a CLI prompt in the 'vpn' folder, preferably as root. For example: - + sudo openvpn --cd /rw/config/vpn --config openvpn-client.ovpn - + Watch for status messages that indicate whether the connection is successful and test from another VPN VM terminal window with `ping`. ping 8.8.8.8 - + `ping` can be aborted by pressing the two keys `ctrl` + `c` at the same time. DNS may be tested at this point by replacing addresses in `/etc/resolv.conf` with ones appropriate for your VPN (although this file will not be used when setup is complete). Diagnose any connection problems using resources such as client documentation and help from your VPN service provider. - + Proceed to the next step when you're sure the basic VPN connection is working. 3. Create the DNS-handling script. sudo nano /rw/config/vpn/qubes-vpn-handler.sh - + Edit and add: ~~~ @@ -178,11 +178,11 @@ Save the script. Make it executable. sudo chmod +x /rw/config/vpn/qubes-vpn-handler.sh - + 4. Configure client to use the DNS handling script. Using openvpn as an example, edit the config. sudo nano /rw/config/vpn/openvpn-client.ovpn - + Add the following. ~~~ @@ -190,7 +190,7 @@ Make it executable. up 'qubes-vpn-handler.sh up' down 'qubes-vpn-handler.sh down' ~~~ - + Remove other instances of lines starting with `script-security`, `up` or `down` should there be any others. Save the script. @@ -200,9 +200,9 @@ Save the script. 5. Set up iptables anti-leak rules. Edit the firewall script. - + sudo nano /rw/config/qubes-firewall-user-script - + Clear out the existing lines and add: ~~~ @@ -211,7 +211,7 @@ Clear out the existing lines and add: # (in case the vpn tunnel breaks): iptables -I FORWARD -o eth0 -j DROP iptables -I FORWARD -i eth0 -j DROP - + # Block all outgoing traffic iptables -P OUTPUT DROP iptables -F OUTPUT @@ -245,12 +245,12 @@ Clear out the existing lines and add: #!/bin/bash VPN_CLIENT='openvpn' VPN_OPTIONS='--cd /rw/config/vpn/ --config openvpn-client.ovpn --daemon' - + su - -c 'notify-send "$(hostname): Starting $VPN_CLIENT..." --icon=network-idle' user groupadd -rf qvpn ; sleep 2s sg qvpn -c "$VPN_CLIENT $VPN_OPTIONS" ~~~ - + If you are using anything other than OpenVPN, change the `VPN_CLIENT` and `VPN_OPTIONS` variables to match your VPN software. Save the script. @@ -258,7 +258,7 @@ Save the script. Make it executable. sudo chmod +x /rw/config/rc.local` - + 6. Restart the new VM! The link should then be established automatically with a popup notification to that effect. Usage From 13f66bce387c850b0aedc8c5f9d87abce5775299 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Marczykowski-G=C3=B3recki?= Date: Mon, 29 Jan 2018 15:47:47 +0100 Subject: [PATCH 20/67] Remove completed projects --- basics_dev/gsoc.md | 119 ++------------------------------------------- 1 file changed, 4 insertions(+), 115 deletions(-) diff --git a/basics_dev/gsoc.md b/basics_dev/gsoc.md index 126cb941..544798fa 100644 --- a/basics_dev/gsoc.md +++ b/basics_dev/gsoc.md @@ -92,44 +92,6 @@ If applicable, links to more information or discussions **Mentor**: Name and email address. ``` -### Qubes MIME handlers - -**Project**: Qubes MIME handlers - -**Brief explanation**: [#441](https://github.com/QubesOS/qubes-issues/issues/441) (including remembering decision whether some file -should be opened in DispVM or locally) - -**Expected results**: - - - Design mechanism for recognising which files should be opened locally and which in Disposable VM. This mechanism should: - - Respect default action like "by default open files in Disposable VM" (this - may be about files downloaded from the internet, transferred from - other VM etc). - - Allow setting persistent flag for a file that should be opened in specific - way ("locally"); this flag should local to the VM - it shouldn't be possible - to preserve (or even fabricate) the flag while transferring the file from/to - VM. - - See linked ticket for simple ideas. - - Implement generic file handler to apply this mechanism; it should work - regardless of file type, and if file is chosen to be opened locally, normal - (XDG) rules of choosing application should apply. - - Setting/unsetting the flag should be easy - like if once file is chosen to - be opened locally, it should remember that decision. - - Preferably use generic mechanism to integrate it into file managers (XDG - standards). If not possible - integrate with Nautilus and Dolphin. - - Optionally implement the same for Windows. - - Document the mechanism (how the flag is stored, how mechanism is plugged - into file managers etc). - - Write unit tests and integration tests. - -**Knowledge prerequisite**: - - - XDG standards - - Bash or Python scripting - - Basic knowledge of configuration/extension for file managers - -**Mentor**: [Marek Marczykowski-Górecki](/team/) - ### Template manager, new template distribution mechanism **Project**: Template manager, new template distribution mechanism @@ -231,37 +193,8 @@ details: [#1552](https://github.com/QubesOS/qubes-issues/issues/1552), **Mentor**: [Thomas Leonard](mailto:talex5@gmail.com), [Marek Marczykowski-Górecki](/team/) -### IPv6 support -**Project**: IPv6 support - -**Brief explanation**: Add support for native IPv6 in Qubes VMs. This should -include IPv6 routing (+NAT...), IPv6-aware firewall, DNS configuration, dealing -with IPv6 being available or not in directly connected network. See -[#718](https://github.com/QubesOS/qubes-issues/issues/718) for more details. - -**Expected results**: - - - Add IPv6 handling to network configuration scripts in VMs - - Add support for IPv6 in Qubes firewall (including CLI/GUI tools to configure it) - - Design and implement simple mechanism to propagate information about IPv6 - being available at all (if necessary). This should be aware of ProxyVMs - potentially adding/removing IPv6 support - like VPN, Tor etc. - - Add unit tests and integration tests for both configuration scripts and UI - enhancements. - - Update documentation. - -**Knowledge prerequisite**: - - - network protocols, especially IPv6, TCP, DNS, DHCPv6, ICMPv6 (including - autoconfiguration) - - ip(6)tables, nftables, NAT - - Python and Bash scripting - - network configuration on Linux: ip tool, configuration files on Debian and - Fedora, NetworkManager - -**Mentor**: [Marek Marczykowski-Górecki](/team/) - ### Thunderbird, Firefox and Chrome extensions + **Project**: additional Thunderbird, Firefox and Chrome extensions **Brief explanation**: @@ -315,31 +248,7 @@ immune to altering past entries. See - systemd - Python/Bash scripting -**Mentor**: Inquire on [qubes-devel][ml-devel]. - -### GUI improvements - -**Project**: GUI improvements - -**Brief explanation**: - -* GUI for enabling USB keyboard: [#2329](https://github.com/QubesOS/qubes-issues/issues/2329) -* GUI for enabling USB passthrough: [#2328](https://github.com/QubesOS/qubes-issues/issues/2328) -* GUI interface for /etc/qubes/guid.conf: [#2304](https://github.com/QubesOS/qubes-issues/issues/2304) -* Improving inter-VM file copy / move UX master ticket: [#1839](https://github.com/QubesOS/qubes-issues/issues/1839) -* and comprehensive list of GUI issues: [#1117](https://github.com/QubesOS/qubes-issues/issues/1117) - -**Expected results**: - - - Add/enhance GUI tools to configure/do things mentioned in description above. - Reasonable subset of those things is acceptable. - - Write tests for added elements. - -**Knowledge prerequisite**: - - - Python, PyGTK - -**Mentor**: Inquire on [qubes-devel][ml-devel]. +**Mentor**: [Marek Marczykowski-Górecki](/team/) ### Xen GPU pass-through for Intel integrated GPUs **Project**: Xen GPU pass-through for Intel integrated GPUs (largely independent of Qubes) @@ -424,27 +333,7 @@ details in [#2618](https://github.com/QubesOS/qubes-issues/issues/2618). **Mentor**: [Rafał Wojdyła](/team/) -### Make Anti Evil Maid resistant against shoulder surfing and video surveillance - -**Project**: Observing the user during early boot should not be sufficient to defeat the protection offered by Anti Evil Maid. - -**Brief explanation**: - -1. Implement optional support for time-based one-time-password seed secrets. Instead of verifying a static text or picture (which the attacker can record and replay later on a compromised system), the user would verify an ephemeral six-digit code displayed on another device, e.g. a smartphone running any Google Authenticator compatible code generator app. - -2. Implement optional support for storing a passphrase-encrypted LUKS disk decryption key on a secondary AEM device. The attacker would then have to seize this device in order to decrypt the user's data; just recording the passphrase as it is entered would no longer be enough. - -**Expected results**: AEM package updates implementing both features, with fallback support in case the user does not have their smartphone or secondary AEM device at hand. Good UX and documentation for enrolling or upgrading users. - -**Knowledge prerequisite**: - -- Bash scripting -- The AEM threat model -- GRUB2, dracut, systemd, LUKS - -**Mentor**: [Rusty Bird](mailto:rustybird@openmailbox.org) - -### GNOME support in dom0 +### GNOME support in dom0 / GUI VM **Project**: GNOME support in dom0 @@ -518,7 +407,7 @@ for more information and qubes-specific background. **Knoledge prerequisite**: qubes-builder [[1]](https://www.qubes-os.org/doc/qubes-builder/) [[2]](https://www.qubes-os.org/doc/qubes-builder-details/) [[3]](https://github.com/QubesOS/qubes-builder/tree/master/doc), and efficient at introspecting complex systems: comfortable with tracing and debugging tools, ability to quickly identify and locate issues within a large codebase (upstream build tools), etc. -**Mentor**: Inquire on [qubes-devel][ml-devel]. +**Mentor**: [Marek Marczykowski-Górecki](/team/) ### Android development in Qubes From 5427e4c4b2da0da8961cb66b9ea091749874fad5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Marczykowski-G=C3=B3recki?= Date: Mon, 29 Jan 2018 16:39:07 +0100 Subject: [PATCH 21/67] gsoc: add new ideas collected from qubes-devel ML --- basics_dev/gsoc.md | 94 +++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 88 insertions(+), 6 deletions(-) diff --git a/basics_dev/gsoc.md b/basics_dev/gsoc.md index 544798fa..d73b0203 100644 --- a/basics_dev/gsoc.md +++ b/basics_dev/gsoc.md @@ -36,7 +36,7 @@ Before the summer starts, there are some preparatory tasks which are highly enco ### Student proposal guidelines -A project proposal is what you will be judged upon. Write a clear proposal on what you plan to do, the scope of your project, and why we should choose you to do it. Proposals are the basis of the GSoC projects and therefore one of the most important things to do well. The proposal is not only the basis of our decision of which student to choose, it has also an effect on Google's decision as to how many student slots are assigned to Qubes. +A project proposal is what you will be judged upon. Write a clear proposal on what you plan to do, the scope of your project, and why we should choose you to do it. Proposals are the basis of the GSoC projects and therefore one of the most important things to do well. The proposal is not only the basis of our decision of which student to choose, it has also an effect on Google's decision as to how many student slots are assigned to Qubes. Below is the application template: @@ -86,7 +86,7 @@ These project ideas were contributed by our developers and may be incomplete. If **Expected results**: What is the expected result in the timeframe given -**Knowledge prerequisite**: Pre-requisites for working on the project. What coding language and knowledge is needed? +**Knowledge prerequisite**: Pre-requisites for working on the project. What coding language and knowledge is needed? If applicable, links to more information or discussions **Mentor**: Name and email address. @@ -128,7 +128,7 @@ would override all the user changes there). More details: [#1705](https://github.com/QubesOS/qubes-issues/issues/1705) for some idea (this one lack integrity verification, but similar service could be developed with that added) - - If new "package" format is developed, add support for it into + - If new "package" format is developed, add support for it into [linux-template-builder](https://github.com/QubesOS/qubes-linux-template-builder). - Document the mechanism. - Write unit tests and integration tests. @@ -143,6 +143,84 @@ would override all the user changes there). More details: **Mentor**: [Marek Marczykowski-Górecki](/team/) +### Easy inter-VM networking configuration + +**Project**: Easy inter-VM networking configuration + +**Brief explanation**: Utility to easily configure selected VMs to be reachable (by network) from other VMs or outside network. Currently such configuration require adding iptables rules in multiple VMs manually. For exposing VM to outside network, it may be good to adopt qrexec-based TCP forwarding ([#2148](https://github.com/QubesOS/qubes-issues/issues/2148)). + +**Expected results**: + +- support firewall rules for inter-VM traffic in qubes-firewall - both VM side (qubes-firewall service) and dom0 configuration side (relevant Admin API calls) +- mechanism for configuring firewall in target VM, especially INPUT iptables chain - currently it is hardcoded to drop new incoming connections +- convenient tool (or modification to existing tool) for controlling above mechanisms +- integration the above with existing GUI tools (especially VM settings) + +Relevant links: + - [Qubes networking and firewall documentation](/doc/firewall/) + - [qubes-firewall service code](https://github.com/QubesOS/qubes-core-agent-linux/blob/master/qubesagent/firewall.py) + +**Knowledge prerequisite**: + +- iptables +- basics of nft +- python3 + +**Mentor**: [Marek Marczykowski-Górecki](/team/) + +### Mechanism for maintaining in-VM configuration + +**Project**: Mechanism for maintaining in-VM configuration + +**Brief explanation**: Large number of VMs is hard to maintain. Templates helps with keeping them updated, but many applications have configuration in user home directory, which is not synchronized. + +**Expected results**: + +- Design a mechanism how to _safely_ synchronize application configuration living in user home directory (`~/.config`, some other "dotfiles"). Mechanism should be resistant against malicious VM forcing its configuration on other VMs. Some approach could be a strict control which VM can send what changes (whitelist approach, not blacklist). +- Implementation of the above mechanism. +- Documentation how to configure it securely. + + +**Knowledge prerequisite**: + +- shell and/or python scripting +- Qubes OS qrexec services + +**Mentor**: [Marek Marczykowski-Górecki](/team/), [Wojtek Porczyk](/team/). + +### Wayland support in GUI agent and/or GUI daemon + +**Project**: Wayland support in GUI agent and/or GUI daemon + +**Brief explanation**: Currently both GUI agent (VM side of the GUI virtualization) and GUI daemon (dom0 side of GUI virtualization) support X11 protocol only. It may be useful to add support for Wayland there. Note that those are in fact two independent projects: + +1. GUI agent - make it work as Wayland compositor, instead of extracting window's composition buffers using custom X11 driver +2. GUI daemon - act as Wayland application, showing windows retrieved from VMs, keeping zero-copy display path (window content is directly mapped from application running in VM, not copied) + +**Expected results**: + +Choose either of GUI agent, GUI daemon. Both are of similar complexity and each separately looks like a good task for GSoC time period. + +- design relevant GUI agent/daemon changes, the GUI protocol should not be affected +- consider window decoration handling - VM should have no way of spoofing those, so it must be enforced by GUI daemon (either client-side - by GUI daemon itself, or server-side, based on hints given by GUI daemon) +- implement relevant GUI agent/daemon changes +- implement tests for new GUI handling, similar to existing tests for X11 based GUI + +Relevant links: + - [Low level GUI documentation](/doc/gui/) + - [qubes-gui-agent-linux](https://github.com/qubesos/qubes-gui-agent-linux) + - [qubes-gui-daemon](https://github.com/qubesos/qubes-gui-daemon) + - [Use Wayland instead of X11 to increase performance](https://github.com/qubesos/qubes-issues/issues/3366) + +**Knowledge prerequisite**: + +- Wayland architecture +- basics of X11 (for understanding existing code) +- C language +- using shared memory (synchronization methods etc) + +**Mentor**: [Marek Marczykowski-Górecki](/team/). + ### Qubes Live USB **Project**: Revive Qubes Live USB, integrate it with installer @@ -197,7 +275,7 @@ details: [#1552](https://github.com/QubesOS/qubes-issues/issues/1552), **Project**: additional Thunderbird, Firefox and Chrome extensions -**Brief explanation**: +**Brief explanation**: * browser/mail: open link in vm * browser/mail: open link in dispvm @@ -288,7 +366,7 @@ details in [#2618](https://github.com/QubesOS/qubes-issues/issues/2618). **Brief explanation**: [T509](https://phabricator.whonix.org/T509) -**Expected results**: +**Expected results**: - Work at upstream Tor: An older version of https://trac.torproject.org/projects/tor/wiki/doc/TransparentProxy page was the origin of Whonix. Update that page for nftables / IPv6 support without mentioning Whonix. Then discuss that on the tor-talk mailing list for wider input. - https://trac.torproject.org/projects/tor/ticket/21397 - implement corridor feature request add IPv6 support / port to nftables - https://github.com/rustybird/corridor/issues/39 @@ -296,7 +374,11 @@ details in [#2618](https://github.com/QubesOS/qubes-issues/issues/2618). - make connections to IPv6 Tor relays work - make connections to IPv6 destinations work -**Knowledge prerequisite**: +**Knowledge prerequisite**: + +- nftables +- iptables +- IPv6 **Mentor**: [Patrick Schleizer](/team/) From 3fc8bf94d94382f4ae57ccaef4ecd50ea1bd1e7e Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Mon, 29 Jan 2018 20:40:00 -0600 Subject: [PATCH 22/67] Introduce restrictive clauses with "that" instead of "which" --- reference/glossary.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/reference/glossary.md b/reference/glossary.md index 817c7190..3cc17a13 100644 --- a/reference/glossary.md +++ b/reference/glossary.md @@ -22,7 +22,7 @@ The main principle of Qubes OS is security by compartmentalization (or isolation VM -- An abbreviation for "virtual machine." -A software implementation of a machine (for example, a computer) which executes programs like a physical machine. +A software implementation of a machine (for example, a computer) that executes programs like a physical machine. Qube ---- @@ -62,34 +62,34 @@ By default, most domUs lack direct hardware access. TemplateVM ---------- Template Virtual Machine. -Any [VM](#vm) which supplies its root filesystem to another VM. +Any [VM](#vm) that supplies its root filesystem to another VM. TemplateVMs are intended for installing and updating software applications, but not for running them. * Colloquially, TemplateVMs are often referred to as "templates." TemplateBasedVM --------------- -Any [VM](#vm) which depends on a [TemplateVM](#templatevm) for its root filesystem. +Any [VM](#vm) that depends on a [TemplateVM](#templatevm) for its root filesystem. Standalone(VM) -------------- Standalone (Virtual Machine). In general terms, a [VM](#vm) is described as **standalone** if and only if it does not depend on any other VM for its root filesystem. (In other words, a VM is standalone if and only if it is not a TemplateBasedVM.) -More specifically, a **StandaloneVM** is a type of VM in Qubes which is created by cloning a TemplateVM. +More specifically, a **StandaloneVM** is a type of VM in Qubes that is created by cloning a TemplateVM. Unlike TemplateVMs, however, StandaloneVMs do not supply their root filesystems to other VMs. (Therefore, while a TemplateVM is a type of standalone VM, it is not a StandaloneVM.) AppVM ----- Application Virtual Machine. -A [VM](#vm) which is intended for running software applications. +A [VM](#vm) that is intended for running software applications. Typically a TemplateBasedVM, but may be a StandaloneVM. Never a TemplateVM. NetVM ----- Network Virtual Machine. -A type of [VM](#vm) which connects directly to a network and provides access to that network to other VMs which connect to the NetVM. +A type of [VM](#vm) that connects directly to a network and provides network access any VMs connected to the NetVM. A NetVM called `sys-net` is created by default in most Qubes installations. Alternatively, "NetVM" may refer to whichever VM is directly connected to a VM for networking purposes. @@ -98,18 +98,18 @@ For example, if `untrusted` is directly connected to `sys-firewall` for network ProxyVM ------- Proxy Virtual Machine. -A type of [VM](#vm) which proxies network access for other VMs. -Typically, a ProxyVM sits between a NetVM and another VM (such as an AppVM or a TemplateVM) which requires network access. +A type of [VM](#vm) that proxies network access for other VMs. +Typically, a ProxyVM sits between a NetVM and another VM (such as an AppVM or a TemplateVM) that requires network access. FirewallVM ---------- Firewall Virtual Machine. -A type of [ProxyVM](#proxyvm) which is used to enforce network-level policies (a.k.a. "firewall rules"). +A type of [ProxyVM](#proxyvm) that is used to enforce network-level policies (a.k.a. "firewall rules"). A FirewallVM called `sys-firewall` is created by default in most Qubes installations. DispVM ------ -[Disposable Virtual Machine]. A temporary [AppVM](#appvm) based on a [DVM Template](#dvm-template) which can quickly be created, used, and destroyed. +[Disposable Virtual Machine]. A temporary [AppVM](#appvm) based on a [DVM Template](#dvm-template) that can quickly be created, used, and destroyed. DVM --- @@ -139,12 +139,12 @@ Although HVMs are typically slower than paravirtualized VMs due to the required StandaloneHVM ------------- -Any [HVM](#hvm) which is standalone (i.e., does not depend on any other VM for its root filesystem). +Any [HVM](#hvm) that is standalone (i.e., does not depend on any other VM for its root filesystem). In Qubes, StandaloneHVMs are referred to simply as **HVMs**. TemplateHVM ----------- -Any [HVM](#hvm) which functions as a [TemplateVM](#templatevm) by supplying its root filesystem to other VMs. +Any [HVM](#hvm) that functions as a [TemplateVM](#templatevm) by supplying its root filesystem to other VMs. In Qubes, TemplateHVMs are referred to as **HVM templates**. TemplateBasedHVM From f4454dd2dd265d5eae52edf76ffefa2d86c2845c Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Mon, 29 Jan 2018 20:45:11 -0600 Subject: [PATCH 23/67] Clarify the definition of "NetVM" --- reference/glossary.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/reference/glossary.md b/reference/glossary.md index 3cc17a13..bd1af6ce 100644 --- a/reference/glossary.md +++ b/reference/glossary.md @@ -89,7 +89,8 @@ Typically a TemplateBasedVM, but may be a StandaloneVM. Never a TemplateVM. NetVM ----- Network Virtual Machine. -A type of [VM](#vm) that connects directly to a network and provides network access any VMs connected to the NetVM. +A type of [VM](#vm) that connects directly to a network. +Other VMs gain access to a network by connecting to a NetVM (usually indirectly, via a [FirewallVM](#firewallvm)). A NetVM called `sys-net` is created by default in most Qubes installations. Alternatively, "NetVM" may refer to whichever VM is directly connected to a VM for networking purposes. From 82f50fe2e0dab972d7e028ee5232ecdf2cf3680d Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Mon, 29 Jan 2018 21:09:08 -0600 Subject: [PATCH 24/67] Add "TemplateVM" notes; update "DVM Template" for 4.0 https://github.com/QubesOS/qubes-issues/issues/2486 https://github.com/QubesOS/qubes-doc/pull/543 --- reference/glossary.md | 19 ++++++++++++++----- 1 file changed, 14 insertions(+), 5 deletions(-) diff --git a/reference/glossary.md b/reference/glossary.md index bd1af6ce..3e6d0d3f 100644 --- a/reference/glossary.md +++ b/reference/glossary.md @@ -66,6 +66,9 @@ Any [VM](#vm) that supplies its root filesystem to another VM. TemplateVMs are intended for installing and updating software applications, but not for running them. * Colloquially, TemplateVMs are often referred to as "templates." + * Since every TemplateVM supplies its *own* root filesystem to at least one other VM, no TemplateVM can be based on another TemplateVM. + In other words, no TemplateVM is a [TemplateBasedVM](#templatebasedvm). + * Since every TemplateVM supplies its *root* filesystem to at least one other VM, no [DVM Template](#dvm-template) is a TemplateVM. TemplateBasedVM --------------- @@ -118,12 +121,18 @@ An abbreviation of [DispVM](#dispvm), typically used to refer to [DVM Templates] DVM Template ------------ -TemplateBasedVMs on which [DispVMs](#dispvm) are based. +A type of [TemplateBasedVM](#templatebasedvm) on which [DispVMs](#dispvm) are based. By default, a DVM Template named `fedora-XX-dvm` is created on most Qubes installations (where `XX` is the Fedora version of the default TemplateVM). -DVM Templates are neither [TemplateVMs](#templatevm) nor [AppVMs](#appvm). -They are intended neither for installing nor running software. -Rather, they are intended for *customizing* or *configuring* software that has already been installed on the TemplateVM on which the DVM Template is based (see [DispVM Customization]). -This software is then intended to be run (in its customized state) in DispVMs that are based on the DVM Template. +DVM Templates are not [TemplateVMs](#templatevm), since (being TemplateBasedVMs) they do not have root filesystems of their own to provide to other VMs. +Rather, DVM Templates are complementary to TemplateVMs insofar as DVM Templates provide their own user filesystems to the DispVMs based on them. +There are two main kinds of DVM Templates: + + * **Dedicated** DVM Templates are intended neither for installing nor running software. + Rather, they are intended for *customizing* or *configuring* software that has already been installed on the TemplateVM on which the DVM Template is based (see [DispVM Customization]). + This software is then intended to be run (in its customized state) in DispVMs that are based on the DVM Template. + * **Non-dedicated** DVM Templates are typically [AppVMs](#appvm) on which DispVMs are based. + For example, an AppVM could be used to generate and store trusted data. + Then, a DispVM could be created based on the AppVM (thereby making the AppVM a DVM Template) so that the data can be analyzed by an untrusted program without jeopardizing the integrity of the original data. PV -- From a61d08fed4f1e34410ca5c95de0cd9b02e5ba990 Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Mon, 29 Jan 2018 21:19:19 -0600 Subject: [PATCH 25/67] Add "SystemVM" to the glossary --- reference/glossary.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/reference/glossary.md b/reference/glossary.md index 3e6d0d3f..f2ceb492 100644 --- a/reference/glossary.md +++ b/reference/glossary.md @@ -167,6 +167,12 @@ Service Virtual Machine. A [VM](#vm) the primary purpose of which is to provide a service or services to other VMs. NetVMs and ProxyVMs are examples of ServiceVMs. +SystemVM +-------- +System Virtual Machine. +A synonym for [ServiceVM](#servicevm). +SystemVMs usually have the prefix `sys-`. + PVHVM ----- [PV](#pv) on [HVM](#hvm). From e59b6c29b1c74918b8744c3c34690a2d97856d39 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Marczykowski-G=C3=B3recki?= Date: Tue, 30 Jan 2018 06:14:09 +0100 Subject: [PATCH 26/67] networking: update for 3.2+, add IPv6 (4.0+) --- system/networking.md | 42 +++++++++++++++++++++++++++++++++++------- 1 file changed, 35 insertions(+), 7 deletions(-) diff --git a/system/networking.md b/system/networking.md index 9fce8984..cde78ade 100644 --- a/system/networking.md +++ b/system/networking.md @@ -15,9 +15,9 @@ VM network in Qubes Overall description ------------------- -In Qubes, the standard Xen networking is used, based on backend driver in the driver domain and frontend drivers in VMs. In order to eliminate layer 2 attacks originating from a compromised VM, routed networking is used instead of the default bridging of `vif` devices. The default *vif-route* script had some deficiencies (requires `eth0` device to be up, and sets some redundant iptables rules), therefore the custom *vif-route-qubes* script is used. +In Qubes, the standard Xen networking is used, based on backend driver in the driver domain and frontend drivers in VMs. In order to eliminate layer 2 attacks originating from a compromised VM, routed networking is used instead of the default bridging of `vif` devices and NAT is applied at each network hop. The default *vif-route* script had some deficiencies (requires `eth0` device to be up, and sets some redundant iptables rules), therefore the custom *vif-route-qubes* script is used. -The IP address of `eth0` interface in AppVM, as well as two IP addresses to be used as nameservers (`DNS1` and `DNS2`), are passed via xenstore to AppVM during its boot (thus, there is no need for DHCP daemon in the network driver domain). `DNS1` and `DNS2` are private addresses; whenever an interface is brought up in the network driver domain, the */usr/lib/qubes/qubes\_setup\_dnat\_to\_ns* script sets up the DNAT iptables rules translating `DNS1` and `DNS2` to the newly learned real dns servers. This way AppVM networking configuration does not need to be changed when configuration in the network driver domain changes (e.g. user switches to a different WLAN). Moreover, in the network driver domain, there is no DNS server either, and consequently there are no ports open to the VMs. +The IP address of `eth0` interface in AppVM, as well as two IP addresses to be used as nameservers (`DNS1` and `DNS2`), are passed via QubesDB to AppVM during its boot (thus, there is no need for DHCP daemon in the network driver domain). `DNS1` and `DNS2` are private addresses; whenever an interface is brought up in the network driver domain, the */usr/lib/qubes/qubes\_setup\_dnat\_to\_ns* script sets up the DNAT iptables rules translating `DNS1` and `DNS2` to the newly learned real dns servers. This way AppVM networking configuration does not need to be changed when configuration in the network driver domain changes (e.g. user switches to a different WLAN). Moreover, in the network driver domain, there is no DNS server either, and consequently there are no ports open to the VMs. Routing tables examples ----------------------- @@ -32,12 +32,40 @@ Network driver domain routing table is a bit longer: || |Destination|Gateway|Genmask|Flags|Metric|Ref|Use|Iface| -|10.2.0.16|0.0.0.0|255.255.255.255|UH|0|0|0|vif4.0| -|10.2.0.7|0.0.0.0|255.255.255.255|UH|0|0|0|vif10.0| -|10.2.0.9|0.0.0.0|255.255.255.255|UH|0|0|0|vif9.0| -|10.2.0.8|0.0.0.0|255.255.255.255|UH|0|0|0|vif8.0| -|10.2.0.12|0.0.0.0|255.255.255.255|UH|0|0|0|vif3.0| +|10.137.0.16|0.0.0.0|255.255.255.255|UH|0|0|0|vif4.0| +|10.137.0.7|0.0.0.0|255.255.255.255|UH|0|0|0|vif10.0| +|10.137.0.9|0.0.0.0|255.255.255.255|UH|0|0|0|vif9.0| +|10.137.0.8|0.0.0.0|255.255.255.255|UH|0|0|0|vif8.0| +|10.137.0.12|0.0.0.0|255.255.255.255|UH|0|0|0|vif3.0| |192.168.0.0|0.0.0.0|255.255.255.0|U|1|0|0|eth0| |0.0.0.0|192.168.0.1|0.0.0.0|UG|0|0|0|eth0| +IPv6 +---- + +Starting with Qubes 4.0, there is opt-in support for IPv6 forwarding. Similar to the IPv4, traffic is routed and NAT is applied at each network gateway. This way we avoid reconfiguring every connected qube whenever uplink connection is changed, and even telling the qube what that uplink is - which may be complex when VPN or other tunneling services are employed. +The feature can be enabled on any network-providing qube, and will be propagated down the network tree, so every qube connected to it will also have IPv6 enabled. +To enable the `ipv6` feature use `qvm-features` tool and set the value to `1`. For example to enable it on `sys-net`, execute in dom0: + + qvm-features sys-net ipv6 1 + +It is also possible to explicitly disable IPv6 support for some qubes, even if it is connected to IPv6-providing one. This can be done by setting `ipv6` feature to empty value: + + qvm-features ipv4-only-qube ipv6 '' + +This configuration is presented below - green qubes have IPv6 access, red one does not. + +![ipv6-1](/attachment/wiki/IPv6/ipv6-1.png) + +In that case, system uplink connection have native IPv6. But in some cases it may not be true. Then some tunneling solution can be used (for example teredo). The same will apply when the user is connected to VPN service providing IPv6 support, regardless of user's internet connection. +Such configuration can be expressed by enabling `ipv6` feature only on some subset of Qubes networking, for example by creating separate qube to encapsulate IPv6 traffic and setting `ipv6` to `1` only there. See diagram below + +![ipv6-2](/attachment/wiki/IPv6/ipv6-2.png) + +Besides enabling IPv6 forwarding, standard Qubes firewall can be used to limit what network resources are available to each qube. Currently only `qvm-firewall` command support adding IPv6 rules, GUI firewall editor will have this ability later. + +### Limitations ### + +Currently only IPv4 DNS servers are configured, regardless of `ipv6` feature state. It is done this way to avoid reconfiguring all connected qubes whenever IPv6 DNS becomes available or not. Configuring qubes to always use IPv6 DNS and only fallback to IPv4 may result in relatively long timeouts and poor usability. +But note that DNS using IPv4 does not prevent to return IPv6 addresses. In practice this is only a problem for IPv6-only networks. From ce4e5f8cd967b79edd16ec06f1507d2578449af9 Mon Sep 17 00:00:00 2001 From: awokd <34515595+awokd@users.noreply.github.com> Date: Tue, 30 Jan 2018 12:40:50 +0000 Subject: [PATCH 27/67] mention discard mount option nothing 4.0 specific --- common-tasks/tips-and-tricks.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/common-tasks/tips-and-tricks.md b/common-tasks/tips-and-tricks.md index 668d38fb..0ecc6486 100644 --- a/common-tasks/tips-and-tricks.md +++ b/common-tasks/tips-and-tricks.md @@ -58,4 +58,5 @@ Trim for standalone AppVMs --------------------- The `qvm-trim-template` command is not available for a standalone AppVM. -It is still possible to trim the AppVM disks by using the `fstrim --all` command from the appvm +It is still possible to trim the AppVM disks by using the `fstrim --all` command from the appvm. +Note you may need to add the `discard` option to the mount line in `/etc/fstab` inside the standalone AppVM before this will work as expected. From eeef6a0c0572ba2dab7c4e85b10cf5d7bcbadd93 Mon Sep 17 00:00:00 2001 From: awokd <34515595+awokd@users.noreply.github.com> Date: Tue, 30 Jan 2018 12:49:04 +0000 Subject: [PATCH 28/67] move rarely used content down --- common-tasks/usb.md | 359 ++++++++++++++++++++++---------------------- 1 file changed, 179 insertions(+), 180 deletions(-) diff --git a/common-tasks/usb.md b/common-tasks/usb.md index 655048de..ad3e0fab 100644 --- a/common-tasks/usb.md +++ b/common-tasks/usb.md @@ -21,186 +21,6 @@ redirect_from: Using and Managing USB Devices ============================== -Creating and Using a USB qube ------------------------------ - -**Warning:** This has the potential to prevent you from connecting a keyboard to Qubes via USB. There are problems with doing this in an encrypted install (LUKS). If you find yourself in this situation, see this [issue][2270-comm23]. - -Connecting an untrusted USB device to dom0 is a security risk since dom0, -like almost every OS, reads partition tables automatically. The whole -USB stack is put to work to parse the data presented by the USB device in order -to determine if it is a USB mass storage device, to read its configuration, etc. -This happens even if the drive is then assigned and mounted in another qube. - -To avoid this risk, it is possible to prepare and utilize a USB qube. - -A USB qube acts as a secure handler for potentially malicious USB devices, -preventing them from coming into contact with dom0 (which could otherwise be -fatal to the security of the whole system). With a USB qube, every time you -connect an untrusted USB drive to a USB port managed by that USB controller, you -will have to attach it to the qube in which you wish to use it (if different -from the USB qube itself), either by using Qubes VM Manager or the command line -(see instructions above). -You can create a USB qube using the management stack by performing the following -steps as root in dom0: - - 1. Enable `sys-usb`: - - sudo qubesctl top.enable qvm.sys-usb - - 2. Apply the configuration: - - sudo qubesctl state.highstate - -Alternatively, you can create a USB qube manually as follows: - - 1. Read the [Assigning Devices] page to learn how to list and identify your - USB controllers. Carefully check whether you have a USB controller that - would be appropriate to assign to a USB qube. Note that it should have no - input devices, programmable devices, and any other devices that must be - directly available to dom0. If you find a free controller, note its name - and proceed to step 2. - 2. Create a new qube. Give it an appropriate name and color label - (recommended: `sys-usb`, red). If you need to attach a networking device, - it might make sense to create a NetVM. If not, an AppVM might make more - sense. (The default `sys-usb` is a NetVM.) - 3. In the qube's settings, go to the "Devices" tab. Find the USB controller - that you identified in step 1 in the "Available" list. Move it to the - "Selected" list. - - **Caution:** By assigning a USB controller to a USB qube, it will no longer - be available to dom0. This can make your system unusable if, for example, - you have only one USB controller, and you are running Qubes off of a USB - drive. - - 4. Click "OK." Restart the qube. - 5. Recommended: Check the box on the "Basic" tab which says "Start VM - automatically on boot." (This will help to mitigate attacks in which - someone forces your system to reboot, then plugs in a malicious USB - device.) - -If the USB qube will not start, see [here][faq-usbvm]. - -How to hide all USB controllers from dom0 ------------------------------------------ - -If you create a USB qube manually, there will be a brief period of time during the -boot process during which dom0 will be exposed to your USB controllers (and any -attached devices). This is a potential security risk, since even brief exposure -to a malicious USB device could result in dom0 being compromised. There are two -approaches to this problem: - -1. Physically disconnect all USB devices whenever you reboot the host. -2. Hide (i.e., blacklist) all USB controllers from dom0. - -**Warning:** If you use a USB [AEM] device, do not use the second option. Using -a USB AEM device requires dom0 to have access to the USB controller to which -your USB AEM device is attached. If dom0 cannot read your USB AEM device, AEM -will hang. - -The procedure to hide all USB controllers from dom0 is as follows: - -1. Open the file `/etc/default/grub` in dom0. -2. Find the line that begins with `GRUB_CMDLINE_LINUX`. -3. Add `rd.qubes.hide_all_usb` to that line. -4. Save and close the file. -5. Run the command `grub2-mkconfig -o /boot/grub2/grub.cfg` in dom0. -6. Reboot. - -(Note: Beginning with R3.2, `rd.qubes.hide_all_usb` is set automatically if you -opt to create a USB qube during installation. This also occurs automatically if -you choose to [create a USB qube] using the `qubesctl` method, which is the -first pair of steps in the linked section.) - -**Warning:** USB keyboard cannot be used to type the disk passphrase -if USB controllers were hidden from dom0. Before hiding USB controllers -make sure your laptop keyboard is not internally connected via USB -(by checking output of `lsusb` command) or that you have a PS/2 keyboard at hand -(if using a desktop PC). Failure to do so will render your system unusable. - - -Removing a USB qube -------------------- - -**Warning:** This procedure will result in your USB controller(s) being attached -directly to dom0. - -1. Shut down the USB qube. -2. In Qubes Manager, right-click on the USB qube and select "Remove VM." -3. Open the file `/etc/default/grub` in dom0. -4. Find the line(s) that begins with `GRUB_CMDLINE_LINUX`. -5. If `rd.qubes.hide_all_usb` appears anywhere in those lines, remove it. -6. Save and close the file. -7. Run the command `grub2-mkconfig -o /boot/grub2/grub.cfg` in dom0. -8. Reboot. - - -Security Warning about USB Input Devices ----------------------------------------- - -**Important security warning. Please read this section carefully!** - -If you connect USB input devices (keyboard and mouse) to a VM, that VM will effectively have control over your system. -Because of this, the benefits of using a USB qube are much smaller than using a fully untrusted USB qube. -In addition to having control over your system, such VM can also sniff all the input you enter there (for example, passwords in the case of a USB keyboard). - -There is no simple way to protect against sniffing, but you can make it harder to exploit control over input devices. - -If you have only a USB mouse connected to a USB qube, but the keyboard is connected directly to dom0 (using a PS/2 connector, for example), you simply need to lock the screen when you are away from your computer. -You must do this every time you leave your computer unattended, even if there no risk of anyone else having direct physical access to your computer. -This is because you are guarding the system not only against anyone with local access, but also against possible actions from a potentially compromised USB qube. - -If your keyboard is also connected to a USB qube, things are much harder. -Locking the screen (with a traditional password) does not solve the problem, because the USB qube can simply sniff this password and later easily unlock the screen. -One possibility is to set up the screen locker to require an additional step to unlock (i.e., two-factor authentication). -One way to achieve this is to use a [YubiKey], or some other hardware token, or even to manually enter a one-time password. - -How to use a USB keyboard -------------------------- - -**Caution:** Please carefully read the [Security Warning about USB Input Devices] before proceeding. - -In order to use a USB keyboard, you must first attach it to a USB qube, then give that qube permission to pass keyboard input to dom0. -Edit the `qubes.InputKeyboard` policy file in dom0, which is located here: - - /etc/qubes-rpc/policy/qubes.InputKeyboard - -Add a line like this one to the top of the file: - - sys-usb dom0 allow,user=root - -(Change `sys-usb` to your desired USB qube.) - -You can now use your USB keyboard. - -For a confirmation dialog each time the USB keyboard is connected, change this line to: -``` -sys-usb dom0 ask,default_target=dom0 -``` - -How to use a USB mouse ----------------------- - -**Caution:** Please carefully read the [Security Warning about USB Input Devices] before proceeding. - -In order to use a USB mouse, you must first attach it to a USB qube, then give that qube permission to pass mouse input to dom0. -Edit the `qubes.InputMouse` policy file in dom0, which is located here: - - /etc/qubes-rpc/policy/qubes.InputMouse - -Add a line like this to the top of the file: - - sys-usb dom0 allow,user=root - -(Change `sys-usb` to your desired USB qube.) - -You can now use your USB mouse. - -For a confirmation dialog each time the USB mouse is connected, change this line to: -``` -sys-usb dom0 ask,default_target=dom0 -``` - How to attach USB drives ------------------------ @@ -383,6 +203,185 @@ When you finish, detach the device: This feature is not yet available in Qubes Manager however, if you would like to contribute to Qubes OS project by implementing it and are a student please consider applying for the [Google Summer of Code][gsoc-page] scholarship and choosing QubesOS Project as a mentor organization. You can find list of our our Project Ideas [here][project-page]. +Creating and Using a USB qube +----------------------------- + +**Warning:** This has the potential to prevent you from connecting a keyboard to Qubes via USB. There are problems with doing this in an encrypted install (LUKS). If you find yourself in this situation, see this [issue][2270-comm23]. + +Connecting an untrusted USB device to dom0 is a security risk since dom0, +like almost every OS, reads partition tables automatically. The whole +USB stack is put to work to parse the data presented by the USB device in order +to determine if it is a USB mass storage device, to read its configuration, etc. +This happens even if the drive is then assigned and mounted in another qube. + +To avoid this risk, it is possible to prepare and utilize a USB qube. + +A USB qube acts as a secure handler for potentially malicious USB devices, +preventing them from coming into contact with dom0 (which could otherwise be +fatal to the security of the whole system). With a USB qube, every time you +connect an untrusted USB drive to a USB port managed by that USB controller, you +will have to attach it to the qube in which you wish to use it (if different +from the USB qube itself), either by using Qubes VM Manager or the command line +(see instructions above). +You can create a USB qube using the management stack by performing the following +steps as root in dom0: + + 1. Enable `sys-usb`: + + sudo qubesctl top.enable qvm.sys-usb + + 2. Apply the configuration: + + sudo qubesctl state.highstate + +Alternatively, you can create a USB qube manually as follows: + + 1. Read the [Assigning Devices] page to learn how to list and identify your + USB controllers. Carefully check whether you have a USB controller that + would be appropriate to assign to a USB qube. Note that it should have no + input devices, programmable devices, and any other devices that must be + directly available to dom0. If you find a free controller, note its name + and proceed to step 2. + 2. Create a new qube. Give it an appropriate name and color label + (recommended: `sys-usb`, red). If you need to attach a networking device, + it might make sense to create a NetVM. If not, an AppVM might make more + sense. (The default `sys-usb` is a NetVM.) + 3. In the qube's settings, go to the "Devices" tab. Find the USB controller + that you identified in step 1 in the "Available" list. Move it to the + "Selected" list. + + **Caution:** By assigning a USB controller to a USB qube, it will no longer + be available to dom0. This can make your system unusable if, for example, + you have only one USB controller, and you are running Qubes off of a USB + drive. + + 4. Click "OK." Restart the qube. + 5. Recommended: Check the box on the "Basic" tab which says "Start VM + automatically on boot." (This will help to mitigate attacks in which + someone forces your system to reboot, then plugs in a malicious USB + device.) + +If the USB qube will not start, see [here][faq-usbvm]. + +How to hide all USB controllers from dom0 +----------------------------------------- + +If you create a USB qube manually, there will be a brief period of time during the +boot process during which dom0 will be exposed to your USB controllers (and any +attached devices). This is a potential security risk, since even brief exposure +to a malicious USB device could result in dom0 being compromised. There are two +approaches to this problem: + +1. Physically disconnect all USB devices whenever you reboot the host. +2. Hide (i.e., blacklist) all USB controllers from dom0. + +**Warning:** If you use a USB [AEM] device, do not use the second option. Using +a USB AEM device requires dom0 to have access to the USB controller to which +your USB AEM device is attached. If dom0 cannot read your USB AEM device, AEM +will hang. + +The procedure to hide all USB controllers from dom0 is as follows: + +1. Open the file `/etc/default/grub` in dom0. +2. Find the line that begins with `GRUB_CMDLINE_LINUX`. +3. Add `rd.qubes.hide_all_usb` to that line. +4. Save and close the file. +5. Run the command `grub2-mkconfig -o /boot/grub2/grub.cfg` in dom0. +6. Reboot. + +(Note: Beginning with R3.2, `rd.qubes.hide_all_usb` is set automatically if you +opt to create a USB qube during installation. This also occurs automatically if +you choose to [create a USB qube] using the `qubesctl` method, which is the +first pair of steps in the linked section.) + +**Warning:** USB keyboard cannot be used to type the disk passphrase +if USB controllers were hidden from dom0. Before hiding USB controllers +make sure your laptop keyboard is not internally connected via USB +(by checking output of `lsusb` command) or that you have a PS/2 keyboard at hand +(if using a desktop PC). Failure to do so will render your system unusable. + + +Removing a USB qube +------------------- + +**Warning:** This procedure will result in your USB controller(s) being attached +directly to dom0. + +1. Shut down the USB qube. +2. In Qubes Manager, right-click on the USB qube and select "Remove VM." +3. Open the file `/etc/default/grub` in dom0. +4. Find the line(s) that begins with `GRUB_CMDLINE_LINUX`. +5. If `rd.qubes.hide_all_usb` appears anywhere in those lines, remove it. +6. Save and close the file. +7. Run the command `grub2-mkconfig -o /boot/grub2/grub.cfg` in dom0. +8. Reboot. + + +Security Warning about USB Input Devices +---------------------------------------- + +**Important security warning. Please read this section carefully!** + +If you connect USB input devices (keyboard and mouse) to a VM, that VM will effectively have control over your system. +Because of this, the benefits of using a USB qube are much smaller than using a fully untrusted USB qube. +In addition to having control over your system, such VM can also sniff all the input you enter there (for example, passwords in the case of a USB keyboard). + +There is no simple way to protect against sniffing, but you can make it harder to exploit control over input devices. + +If you have only a USB mouse connected to a USB qube, but the keyboard is connected directly to dom0 (using a PS/2 connector, for example), you simply need to lock the screen when you are away from your computer. +You must do this every time you leave your computer unattended, even if there no risk of anyone else having direct physical access to your computer. +This is because you are guarding the system not only against anyone with local access, but also against possible actions from a potentially compromised USB qube. + +If your keyboard is also connected to a USB qube, things are much harder. +Locking the screen (with a traditional password) does not solve the problem, because the USB qube can simply sniff this password and later easily unlock the screen. +One possibility is to set up the screen locker to require an additional step to unlock (i.e., two-factor authentication). +One way to achieve this is to use a [YubiKey], or some other hardware token, or even to manually enter a one-time password. + +How to use a USB keyboard +------------------------- + +**Caution:** Please carefully read the [Security Warning about USB Input Devices] before proceeding. + +In order to use a USB keyboard, you must first attach it to a USB qube, then give that qube permission to pass keyboard input to dom0. +Edit the `qubes.InputKeyboard` policy file in dom0, which is located here: + + /etc/qubes-rpc/policy/qubes.InputKeyboard + +Add a line like this one to the top of the file: + + sys-usb dom0 allow,user=root + +(Change `sys-usb` to your desired USB qube.) + +You can now use your USB keyboard. + +For a confirmation dialog each time the USB keyboard is connected, change this line to: +``` +sys-usb dom0 ask,default_target=dom0 +``` + +How to use a USB mouse +---------------------- + +**Caution:** Please carefully read the [Security Warning about USB Input Devices] before proceeding. + +In order to use a USB mouse, you must first attach it to a USB qube, then give that qube permission to pass mouse input to dom0. +Edit the `qubes.InputMouse` policy file in dom0, which is located here: + + /etc/qubes-rpc/policy/qubes.InputMouse + +Add a line like this to the top of the file: + + sys-usb dom0 allow,user=root + +(Change `sys-usb` to your desired USB qube.) + +You can now use your USB mouse. + +For a confirmation dialog each time the USB mouse is connected, change this line to: +``` +sys-usb dom0 ask,default_target=dom0 +``` [mass-storage]: https://en.wikipedia.org/wiki/USB_mass_storage_device_class [Assigning Devices]: /doc/assigning-devices/ From 216d339201b0f8c1d79fb63a9dbdc84142d3c2d3 Mon Sep 17 00:00:00 2001 From: awokd <34515595+awokd@users.noreply.github.com> Date: Tue, 30 Jan 2018 13:50:46 +0000 Subject: [PATCH 29/67] update usb:How to attach USB drives with 4.0 --- common-tasks/usb.md | 94 ++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 92 insertions(+), 2 deletions(-) diff --git a/common-tasks/usb.md b/common-tasks/usb.md index ad3e0fab..e1bfea27 100644 --- a/common-tasks/usb.md +++ b/common-tasks/usb.md @@ -35,6 +35,95 @@ qube's settings page in Qubes VM Manager or by using the [qvm-pci][Assigning Devices] command. For guidance on finding the correct USB controller, see [here][usb-controller].) + * R4.0 + +USB drive mounting is integrated into the Connection Widget. This is the tooltray +icon with a yellow square located in the top right of your screen by default. +Simply insert +your USB drive and click on the widget. You will see multiple entries for your +USB drive; typically, `sys-usb:sda`, `sys-usb:sda1`, and `sys-usb:2-1` for example. +The simplest (but slightly less secure, see note below about attaching individual +partitions) option is to attach the entire block drive. In our example, this is `sda`, +so hover over it. +This will pop up a submenu showing running VMs to which the USB drive can be connected. +Click on one and your USB drive will be attached! + +Note that attaching individual partitions can be slightly more secure because it doesn't +force the target AppVM to parse the partition table. However, it often means the +AppVM won't detect the new partition and you will need to manually mount it inside +the AppVM. To do this with the GUI, +you'd select the `sda1` entry in our example and proceed to connect to an AppVM. +Once the USB drive has been attached to the AppVM, it will +appear as `/dev/xvd*` (usually `xvdi` but sometimes with higher letters if you +have multiple devices attached.) Follow the below steps if you need to manually mount +the partition: + ``` + cd ~ + mkdir mnt + sudo mount /dev/xvdi mnt + ``` + And when done: + `sudo umount mnt` + +The command-line tool you may use to mount whole USB drives or their partitions +is `qvm-block`. This tool can be used to assign a USB drive to a qube as +follows: + + 1. Insert your USB drive. + + 2. In a dom0 console (running as a normal user), list all available block + devices: + + qvm-block + + This will list all available block devices connected to any USB controller + in your system, no matter which qube hosts the controller. The name of the + qube hosting the USB controller is displayed before the colon in the device + name. The string after the colon is the name of the device used within the + qube, like so: + + dom0:sdb1 Cruzer () 4GiB + + usbVM:sdb1 Disk () 2GiB + + **Note:** If your device is not listed here, you may refresh the list by + calling (from the qube to which the device is connected): + + sudo udevadm trigger --action=change + + 3. Assuming your USB drive is attached to dom0 and is `sdb`, we attach the + device to a qube with the name `personal` like so: + + qvm-block a personal dom0:sdb + + This will attach the device to the qube as `/dev/xvdi` if that name is not + already taken by another attached device, or `/dev/xvdj`, etc. + + You may also mount one partition at a time by using the same command with + the partition number after `sdb`. + + **Warning:** when working with single partitions, it is possible to assign + the same partition to multiple qubes. For example, you could attach `sdb1` + to qube1 and then `sdb` to qube2. It is up to the user not to make this + mistake. The Xen block device framework currently does not provide an easy + way around this. Point 2 of [this comment on issue 1072][1072-comm2] gives + details about this. + + 4. The USB drive is now attached to the qube. If using a default qube, you may + open the Nautilus file manager in the qube, and your drive should be + visible in the **Devices** panel on the left. + + 5. When you finish using your USB drive, click the eject button or right-click + and select **Unmount**. + + 6. In a dom0 console, detach the stick + + qvm-block d + + 7. You may now remove the device. + + * R3.2 + USB drive mounting is integrated into the Qubes VM Manager GUI. Simply insert your USB drive, right-click on the desired qube in the Qubes VM Manager list, click **Attach/detach block devices**, and select your desired action and @@ -50,7 +139,7 @@ follows: 2. In a dom0 console (running as a normal user), list all available block devices: - qvm-block -l + qvm-block This will list all available block devices connected to any USB controller in your system, no matter which qube hosts the controller. The name of the @@ -76,7 +165,8 @@ follows: already taken by another attached device, or `/dev/xvdj`, etc. You may also mount one partition at a time by using the same command with - the partition number after `sdb`. + the partition number after `sdb`. This is slightly more secure because it + does not force the target AppVM to parse the partition table. **Warning:** when working with single partitions, it is possible to assign the same partition to multiple qubes. For example, you could attach `sdb1` From d85351b4721f3535d4b78a3a8f18dc9cf82605a6 Mon Sep 17 00:00:00 2001 From: awokd <34515595+awokd@users.noreply.github.com> Date: Tue, 30 Jan 2018 14:58:43 +0000 Subject: [PATCH 30/67] Update tips-and-tricks.md --- common-tasks/tips-and-tricks.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/common-tasks/tips-and-tricks.md b/common-tasks/tips-and-tricks.md index 0ecc6486..39be0303 100644 --- a/common-tasks/tips-and-tricks.md +++ b/common-tasks/tips-and-tricks.md @@ -59,4 +59,4 @@ Trim for standalone AppVMs The `qvm-trim-template` command is not available for a standalone AppVM. It is still possible to trim the AppVM disks by using the `fstrim --all` command from the appvm. -Note you may need to add the `discard` option to the mount line in `/etc/fstab` inside the standalone AppVM before this will work as expected. +You can also add the `discard` option to the mount line in `/etc/fstab` inside the standalone AppVM if you want trimming to be performed automatically, but there may be a performance impact on writes and deletes. From 866d25120f1b562bf11f316a9d4e0a9d9387784c Mon Sep 17 00:00:00 2001 From: awokd <34515595+awokd@users.noreply.github.com> Date: Tue, 30 Jan 2018 16:05:24 +0000 Subject: [PATCH 31/67] Cleanup How to attach USB drives section --- common-tasks/usb.md | 61 ++++++++++++++++++++++++++------------------- 1 file changed, 35 insertions(+), 26 deletions(-) diff --git a/common-tasks/usb.md b/common-tasks/usb.md index e1bfea27..91f81710 100644 --- a/common-tasks/usb.md +++ b/common-tasks/usb.md @@ -35,9 +35,9 @@ qube's settings page in Qubes VM Manager or by using the [qvm-pci][Assigning Devices] command. For guidance on finding the correct USB controller, see [here][usb-controller].) - * R4.0 +**R4.0** -USB drive mounting is integrated into the Connection Widget. This is the tooltray +USB drive mounting is integrated into the Connection Widget. This is the tool tray icon with a yellow square located in the top right of your screen by default. Simply insert your USB drive and click on the widget. You will see multiple entries for your @@ -51,19 +51,7 @@ Click on one and your USB drive will be attached! Note that attaching individual partitions can be slightly more secure because it doesn't force the target AppVM to parse the partition table. However, it often means the AppVM won't detect the new partition and you will need to manually mount it inside -the AppVM. To do this with the GUI, -you'd select the `sda1` entry in our example and proceed to connect to an AppVM. -Once the USB drive has been attached to the AppVM, it will -appear as `/dev/xvd*` (usually `xvdi` but sometimes with higher letters if you -have multiple devices attached.) Follow the below steps if you need to manually mount -the partition: - ``` - cd ~ - mkdir mnt - sudo mount /dev/xvdi mnt - ``` - And when done: - `sudo umount mnt` +the AppVM. See below for more detailed steps. The command-line tool you may use to mount whole USB drives or their partitions is `qvm-block`. This tool can be used to assign a USB drive to a qube as @@ -91,10 +79,10 @@ follows: sudo udevadm trigger --action=change - 3. Assuming your USB drive is attached to dom0 and is `sdb`, we attach the + 3. Assuming your USB drive is attached to `sys-usb` and is `sdb`, we attach the device to a qube with the name `personal` like so: - qvm-block a personal dom0:sdb + qvm-block a personal sys-usb:sdb This will attach the device to the qube as `/dev/xvdi` if that name is not already taken by another attached device, or `/dev/xvdj`, etc. @@ -108,13 +96,21 @@ follows: mistake. The Xen block device framework currently does not provide an easy way around this. Point 2 of [this comment on issue 1072][1072-comm2] gives details about this. - + 4. The USB drive is now attached to the qube. If using a default qube, you may open the Nautilus file manager in the qube, and your drive should be - visible in the **Devices** panel on the left. + visible in the **Devices** panel on the left. If you've attached a single + partition, you may need to manually mount before it becomes visible: + ``` + cd ~ + mkdir mnt + sudo mount /dev/xvdi mnt + ``` 5. When you finish using your USB drive, click the eject button or right-click - and select **Unmount**. + and select **Unmount**. If you've manually mounted a single partition + in the above step, use: + `sudo umount mnt` 6. In a dom0 console, detach the stick @@ -122,7 +118,7 @@ follows: 7. You may now remove the device. - * R3.2 +**R3.2** USB drive mounting is integrated into the Qubes VM Manager GUI. Simply insert your USB drive, right-click on the desired qube in the Qubes VM Manager list, @@ -130,6 +126,11 @@ click **Attach/detach block devices**, and select your desired action and device. This, however, only works for the whole device. If you would like to attach individual partitions, you must use the command-line tool. +Note that attaching individual partitions can be slightly more secure because it doesn't +force the target AppVM to parse the partition table. However, it often means the +AppVM won't detect the new partition and you will need to manually mount it inside +the AppVM. See below for more detailed steps. + The command-line tool you may use to mount whole USB drives or their partitions is `qvm-block`. This tool can be used to assign a USB drive to a qube as follows: @@ -156,10 +157,10 @@ follows: sudo udevadm trigger --action=change - 3. Assuming your USB drive is attached to dom0 and is `sdb`, we attach the + 3. Assuming your USB drive is attached to `sys-usb` and is `sdb`, we attach the device to a qube with the name `personal` like so: - qvm-block -a personal dom0:sdb + qvm-block -a personal sys-usb:sdb This will attach the device to the qube as `/dev/xvdi` if that name is not already taken by another attached device, or `/dev/xvdj`, etc. @@ -177,10 +178,18 @@ follows: 4. The USB drive is now attached to the qube. If using a default qube, you may open the Nautilus file manager in the qube, and your drive should be - visible in the **Devices** panel on the left. - + visible in the **Devices** panel on the left. If you've attached a single + partition, you may need to manually mount before it becomes visible: + ``` + cd ~ + mkdir mnt + sudo mount /dev/xvdi mnt + ``` + 5. When you finish using your USB drive, click the eject button or right-click - and select **Unmount**. + and select **Unmount**. If you've manually mounted a single partition + in the above step, use: + `sudo umount mnt` 6. In a dom0 console, detach the stick From bf6c66e95a083efc836edaf0e6ea5bb3fc30af20 Mon Sep 17 00:00:00 2001 From: awokd <34515595+awokd@users.noreply.github.com> Date: Tue, 30 Jan 2018 16:35:27 +0000 Subject: [PATCH 32/67] Incorporate Marmarek's comments --- common-tasks/usb.md | 36 +++++++++++++++++------------------- 1 file changed, 17 insertions(+), 19 deletions(-) diff --git a/common-tasks/usb.md b/common-tasks/usb.md index 91f81710..e4322ff8 100644 --- a/common-tasks/usb.md +++ b/common-tasks/usb.md @@ -30,14 +30,11 @@ sticks, this includes things like USB external hard drives.) Qubes OS supports the ability to attach a USB drive (or just one or more of its partitions) to any qube easily, no matter which qube actually handles the USB -controller. (The USB controller may be assigned on the **Devices** tab of a -qube's settings page in Qubes VM Manager or by using the -[qvm-pci][Assigning Devices] command. For guidance on finding the correct USB -controller, see [here][usb-controller].) +controller. **R4.0** -USB drive mounting is integrated into the Connection Widget. This is the tool tray +USB drive mounting is integrated into the Devices Widget. This is the tool tray icon with a yellow square located in the top right of your screen by default. Simply insert your USB drive and click on the widget. You will see multiple entries for your @@ -75,14 +72,14 @@ follows: usbVM:sdb1 Disk () 2GiB **Note:** If your device is not listed here, you may refresh the list by - calling (from the qube to which the device is connected): + calling from the qube to which the device is connected (typically `sys-usb`): sudo udevadm trigger --action=change 3. Assuming your USB drive is attached to `sys-usb` and is `sdb`, we attach the device to a qube with the name `personal` like so: - qvm-block a personal sys-usb:sdb + qvm-block attach personal sys-usb:sdb This will attach the device to the qube as `/dev/xvdi` if that name is not already taken by another attached device, or `/dev/xvdj`, etc. @@ -90,13 +87,6 @@ follows: You may also mount one partition at a time by using the same command with the partition number after `sdb`. - **Warning:** when working with single partitions, it is possible to assign - the same partition to multiple qubes. For example, you could attach `sdb1` - to qube1 and then `sdb` to qube2. It is up to the user not to make this - mistake. The Xen block device framework currently does not provide an easy - way around this. Point 2 of [this comment on issue 1072][1072-comm2] gives - details about this. - 4. The USB drive is now attached to the qube. If using a default qube, you may open the Nautilus file manager in the qube, and your drive should be visible in the **Devices** panel on the left. If you've attached a single @@ -114,7 +104,7 @@ follows: 6. In a dom0 console, detach the stick - qvm-block d + qvm-block detach 7. You may now remove the device. @@ -153,7 +143,7 @@ follows: usbVM:sdb1 Disk () 2GiB **Note:** If your device is not listed here, you may refresh the list by - calling (from the qube to which the device is connected): + calling from the qube to which the device is connected (typically `sys-usb`): sudo udevadm trigger --action=change @@ -321,7 +311,10 @@ fatal to the security of the whole system). With a USB qube, every time you connect an untrusted USB drive to a USB port managed by that USB controller, you will have to attach it to the qube in which you wish to use it (if different from the USB qube itself), either by using Qubes VM Manager or the command line -(see instructions above). +(see instructions above). The USB controller may be assigned on the **Devices** tab of a +qube's settings page in Qubes VM Manager or by using the +[qvm-pci][Assigning Devices] command. For guidance on finding the correct USB +controller, see [here][usb-controller].) You can create a USB qube using the management stack by performing the following steps as root in dom0: @@ -331,7 +324,7 @@ steps as root in dom0: 2. Apply the configuration: - sudo qubesctl state.highstate + sudo qubesctl state.sls qvm.sys-usb Alternatively, you can create a USB qube manually as follows: @@ -464,7 +457,12 @@ How to use a USB mouse **Caution:** Please carefully read the [Security Warning about USB Input Devices] before proceeding. -In order to use a USB mouse, you must first attach it to a USB qube, then give that qube permission to pass mouse input to dom0. +In order to use a USB mouse, you must first attach it to a USB qube, then give that +qube permission to pass mouse input to dom0. +The following steps are already done by default if you created the sys-usb qube with +`qubesctl state.sls qvm.sys-usb` above, or let Qubes create it for you on first boot. However, +if you've created the USB qube manually: + Edit the `qubes.InputMouse` policy file in dom0, which is located here: /etc/qubes-rpc/policy/qubes.InputMouse From acdc936726ca9f7a1541c394020a3eb23700ce5e Mon Sep 17 00:00:00 2001 From: awokd <34515595+awokd@users.noreply.github.com> Date: Tue, 30 Jan 2018 17:15:08 +0000 Subject: [PATCH 33/67] Add 4.0 content to usage of qubes-usb-proxy Also set "What if I removed the device before detaching it from the VM?" to R3.2 because procedure should be unnecessary under 4.0 and attempting it on 4.0 results in "libxl: error: libxl.c:2233:device_disk_add: device already exists in xenstore". --- common-tasks/usb.md | 55 ++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 49 insertions(+), 6 deletions(-) diff --git a/common-tasks/usb.md b/common-tasks/usb.md index e4322ff8..6206e327 100644 --- a/common-tasks/usb.md +++ b/common-tasks/usb.md @@ -200,7 +200,7 @@ manually. The device will show up as `/dev/xvdi` (or `/dev/xvdj` if there is already one device attached -- if two, `/dev/xvdk`, and so on). -### What if I removed the device before detaching it from the VM? ### +### What if I removed the device before detaching it from the VM? (R3.2) ### Currently (until issue [1082] gets implemented), if you remove the device before detaching it from the qube, Qubes OS (more precisely, `libvirtd`) will @@ -219,7 +219,7 @@ steps: [user@dom0 ~]$ qvm-block sys-usb:sda DataTraveler_2.0 () 246 MiB (attached to 'testvm' as 'xvdi') - [user@dom0 ~]$ xl block-attach testvm phy:/dev/sda backend=sys-usb xvdi + [user@dom0 ~]$ sudo xl block-attach testvm phy:/dev/sda backend=sys-usb xvdi In above example, all `xl block-attach` parameters can be deduced from the output of `qvm-block`. In order: @@ -260,7 +260,52 @@ you want to attach the USB device to. - Fedora: `sudo dnf install qubes-usb-proxy` - Debian/Ubuntu: `sudo apt-get install qubes-usb-proxy` -### Usage of qubes-usb-proxy ### +### Usage of qubes-usb-proxy (R4.0) ### + +This feature is also available from the Devices Widget. This is the tool tray +icon with a yellow square located in the top right of your screen by default. +Simply insert +your USB device and click on the widget. You will see an entry for your device +such as `sys-usb:2-5 - 058f_USB_2.0_Camera` for example. +Hover over it. +This will pop up a submenu showing running VMs to which the USB device can be connected. +Click on one and your device will be attached! You may also use the command line: + +Listing available USB devices: + + [user@dom0 ~]$ qvm-usb + sys-usb:2-4 04ca:300d 04ca_300d + sys-usb:2-5 058f:3822 058f_USB_2.0_Camera + sys-usb:2-1 03f0:0641 PixArt_HP_X1200_USB_Optical_Mouse + +Attaching selected USB device: + + [user@dom0 ~]$ qvm-usb attach conferences sys-usb:2-5 + [user@dom0 ~]$ qvm-usb + conferences:2-1 058f:3822 058f_USB_2.0_Camera + sys-usb:2-4 04ca:300d 04ca_300d + sys-usb:2-5 058f:3822 058f_USB_2.0_Camera (attached to conferences) + sys-usb:2-1 03f0:0641 PixArt_HP_X1200_USB_Optical_Mouse + +Now, you can use your USB device (camera in this case) in the `conferences` qube. +If you see the error `ERROR: qubes-usb-proxy not installed in the VM` instead, +please refer to the [Installation Section][installation]. + +When you finish, detach the device. This can be done in the GUI by +clicking on the Devices Widget. You will see a bolded entry for your device +such as `sys-usb:2-5 - 058f_USB_2.0_Camera` for example. +Hover over it. +This will pop up a submenu showing running VMs. The one which your device is +connected to will have an Eject button next to it. Click that and your device +will be detached. You may also use the command line: + + [user@dom0 ~]$ qvm-usb detach sys-usb:2-5 + [user@dom0 ~]$ qvm-usb + sys-usb:2-4 04ca:300d 04ca_300d + sys-usb:2-5 058f:3822 058f_USB_2.0_Camera + sys-usb:2-1 03f0:0641 PixArt_HP_X1200_USB_Optical_Mouse + +### Usage of qubes-usb-proxy (R3.2) ### Listing available USB devices: @@ -290,7 +335,7 @@ When you finish, detach the device: sys-usb:2-5 058f:3822 058f_USB_2.0_Camera sys-usb:2-1 03f0:0641 PixArt_HP_X1200_USB_Optical_Mouse -This feature is not yet available in Qubes Manager however, if you would like to contribute to Qubes OS project by implementing it and are a student please consider applying for the [Google Summer of Code][gsoc-page] scholarship and choosing QubesOS Project as a mentor organization. You can find list of our our Project Ideas [here][project-page]. +This feature is not available in Qubes Manager. Creating and Using a USB qube ----------------------------- @@ -494,8 +539,6 @@ sys-usb dom0 ask,default_target=dom0 [1618]: https://github.com/QubesOS/qubes-issues/issues/1618 [create a USB qube]: #creating-and-using-a-usb-qube [usb-challenges]: https://blog.invisiblethings.org/2011/05/31/usb-security-challenges.html -[project-page]: /gsoc/ -[gsoc-page]: https://summerofcode.withgoogle.com/organizations/6239659689508864/ [YubiKey]: /doc/YubiKey/ [Security Warning about USB Input Devices]: #security-warning-about-usb-input-devices [qubes-usb-proxy]: https://github.com/QubesOS/qubes-app-linux-usb-proxy From eb61ae021255129b61ed3313eb2516032840196a Mon Sep 17 00:00:00 2001 From: awokd <34515595+awokd@users.noreply.github.com> Date: Tue, 30 Jan 2018 17:42:41 +0000 Subject: [PATCH 34/67] Add EFI, misc cleanup --- common-tasks/usb.md | 57 +++++++++++++++++++++++++++++++-------------- 1 file changed, 39 insertions(+), 18 deletions(-) diff --git a/common-tasks/usb.md b/common-tasks/usb.md index 6206e327..96d1cdb3 100644 --- a/common-tasks/usb.md +++ b/common-tasks/usb.md @@ -292,14 +292,14 @@ If you see the error `ERROR: qubes-usb-proxy not installed in the VM` instead, please refer to the [Installation Section][installation]. When you finish, detach the device. This can be done in the GUI by -clicking on the Devices Widget. You will see a bolded entry for your device -such as `sys-usb:2-5 - 058f_USB_2.0_Camera` for example. +clicking on the Devices Widget. You will see an entry in bold for your device +such as **`sys-usb:2-5 - 058f_USB_2.0_Camera`**. Hover over it. This will pop up a submenu showing running VMs. The one which your device is connected to will have an Eject button next to it. Click that and your device will be detached. You may also use the command line: - [user@dom0 ~]$ qvm-usb detach sys-usb:2-5 + [user@dom0 ~]$ qvm-usb detach conferences sys-usb:2-5 [user@dom0 ~]$ qvm-usb sys-usb:2-4 04ca:300d 04ca_300d sys-usb:2-5 058f:3822 058f_USB_2.0_Camera @@ -359,7 +359,7 @@ from the USB qube itself), either by using Qubes VM Manager or the command line (see instructions above). The USB controller may be assigned on the **Devices** tab of a qube's settings page in Qubes VM Manager or by using the [qvm-pci][Assigning Devices] command. For guidance on finding the correct USB -controller, see [here][usb-controller].) +controller, see [here][usb-controller]. You can create a USB qube using the management stack by performing the following steps as root in dom0: @@ -419,12 +419,22 @@ will hang. The procedure to hide all USB controllers from dom0 is as follows: -1. Open the file `/etc/default/grub` in dom0. -2. Find the line that begins with `GRUB_CMDLINE_LINUX`. -3. Add `rd.qubes.hide_all_usb` to that line. -4. Save and close the file. -5. Run the command `grub2-mkconfig -o /boot/grub2/grub.cfg` in dom0. -6. Reboot. + * GRUB2 + + 1. Open the file `/etc/default/grub` in dom0. + 2. Find the line that begins with `GRUB_CMDLINE_LINUX`. + 3. Add `rd.qubes.hide_all_usb` to that line. + 4. Save and close the file. + 5. Run the command `grub2-mkconfig -o /boot/grub2/grub.cfg` in dom0. + 6. Reboot. + + * EFI + + 1. Open the file `/boot/efi/EFI/qubes/xen.cfg` in dom0. + 2. Find the lines that begin with `kernel=`. There may be more than one. + 3. Add `rd.qubes.hide_all_usb` to those lines. + 4. Save and close the file. + 5. Reboot. (Note: Beginning with R3.2, `rd.qubes.hide_all_usb` is set automatically if you opt to create a USB qube during installation. This also occurs automatically if @@ -444,15 +454,26 @@ Removing a USB qube **Warning:** This procedure will result in your USB controller(s) being attached directly to dom0. -1. Shut down the USB qube. -2. In Qubes Manager, right-click on the USB qube and select "Remove VM." -3. Open the file `/etc/default/grub` in dom0. -4. Find the line(s) that begins with `GRUB_CMDLINE_LINUX`. -5. If `rd.qubes.hide_all_usb` appears anywhere in those lines, remove it. -6. Save and close the file. -7. Run the command `grub2-mkconfig -o /boot/grub2/grub.cfg` in dom0. -8. Reboot. + * GRUB2 + + 1. Shut down the USB qube. + 2. In Qubes Manager, right-click on the USB qube and select "Remove VM." + 3. Open the file `/etc/default/grub` in dom0. + 4. Find the line(s) that begins with `GRUB_CMDLINE_LINUX`. + 5. If `rd.qubes.hide_all_usb` appears anywhere in those lines, remove it. + 6. Save and close the file. + 7. Run the command `grub2-mkconfig -o /boot/grub2/grub.cfg` in dom0. + 8. Reboot. + * EFI + + 1. Shut down the USB qube. + 2. In Qubes Manager, right-click on the USB qube and select "Remove VM." + 3. Open the file `/boot/efi/EFI/qubes/xen.cfg` in dom0. + 4. Find the line(s) that begins with `kernel=`. + 5. If `rd.qubes.hide_all_usb` appears anywhere in those lines, remove it. + 6. Save and close the file. + 7. Reboot. Security Warning about USB Input Devices ---------------------------------------- From b41c8bf4acef3c49461a7edbcc817789ae92c896 Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Tue, 30 Jan 2018 20:41:56 -0600 Subject: [PATCH 35/67] Fix formatting https://github.com/QubesOS/qubes-doc/pull/544 --- configuration/vpn.md | 299 +++++++++++++++++++++---------------------- 1 file changed, 149 insertions(+), 150 deletions(-) diff --git a/configuration/vpn.md b/configuration/vpn.md index 475446d3..ff4b41c6 100644 --- a/configuration/vpn.md +++ b/configuration/vpn.md @@ -20,8 +20,8 @@ Please refer to your guest OS and VPN service documentation when considering the The simplest case is to set up a VPN connection using the NetworkManager service inside your NetVM. Because the NetworkManager service is already started, you are ready to set up your VPN connection. However this has some disadvantages: -- You have to place (and probably save) your VPN credentials inside the NetVM, which is directly connected to the outside world -- All your AppVMs which are connected to the NetVM will be connected to the VPN (by default) +- You have to place (and probably save) your VPN credentials inside the NetVM, which is directly connected to the outside world +- All your AppVMs which are connected to the NetVM will be connected to the VPN (by default) ### AppVM @@ -33,26 +33,26 @@ One of the best unique features of Qubes OS is its special type of VM called a P Using a ProxyVM to set up a VPN client gives you the ability to: -- Separate your VPN credentials from your NetVM. -- Separate your VPN credentials from your AppVM data. -- Easily control which of your AppVMs are connected to your VPN by simply setting it as a NetVM of the desired AppVM. +- Separate your VPN credentials from your NetVM. +- Separate your VPN credentials from your AppVM data. +- Easily control which of your AppVMs are connected to your VPN by simply setting it as a NetVM of the desired AppVM. Set up a ProxyVM as a VPN gateway using NetworkManager ------------------------------------------------------ -1. Create a new VM, name it, click the ProxyVM radio button, and choose a color and template. +1. Create a new VM, name it, click the ProxyVM radio button, and choose a color and template. - ![Create\_New\_VM.png](/attachment/wiki/VPN/Create_New_VM.png) + ![Create\_New\_VM.png](/attachment/wiki/VPN/Create_New_VM.png) -2. Add the `network-manager` service to this new VM. +2. Add the `network-manager` service to this new VM. - ![Settings-services.png](/attachment/wiki/VPN/Settings-services.png) + ![Settings-services.png](/attachment/wiki/VPN/Settings-services.png) -3. Set up your VPN as described in the NetworkManager documentation linked above. +3. Set up your VPN as described in the NetworkManager documentation linked above. -4. Configure your AppVMs to use the new VM as a NetVM. +4. Configure your AppVMs to use the new VM as a NetVM. - ![Settings-NetVM.png](/attachment/wiki/VPN/Settings-NetVM.png) + ![Settings-NetVM.png](/attachment/wiki/VPN/Settings-NetVM.png) 5. Optionally, you can install some [custom icons](https://github.com/Zrubi/qubes-artwork-proxy-vpn) for your VPN @@ -60,206 +60,206 @@ Set up a ProxyVM as a VPN gateway using NetworkManager Set up a ProxyVM as a VPN gateway using iptables and CLI scripts ---------------------------------------------------------------- -This method is more involved than the one above, but has anti-leak features that also make the connection _fail closed_ should it be interrupted. It has been tested with Fedora 23 and Debian 8 templates. +This method is more involved than the one above, but has anti-leak features that also make the connection _fail closed_ should it be interrupted. +It has been tested with Fedora 23 and Debian 8 templates. 1. Create a new VM, name it, click the ProxyVM radio button, and choose a color and template. - ![Create\_New\_VM.png](/attachment/wiki/VPN/Create_New_VM.png) + ![Create\_New\_VM.png](/attachment/wiki/VPN/Create_New_VM.png) - Note: Do not enable NetworkManager in the ProxyVM, as it can interfere with the scripts' DNS features. If you enabled NetworkManager or used other methods in a previous attempt, do not re-use the old ProxyVM... Create a new one according to this step. + Note: Do not enable NetworkManager in the ProxyVM, as it can interfere with the scripts' DNS features. + If you enabled NetworkManager or used other methods in a previous attempt, do not re-use the old ProxyVM... + Create a new one according to this step. - If your choice of TemplateVM doesn't already have the VPN client software, you'll need to install the software in the template before proceeding. Disable any auto-starting service that comes with the software package. For example for OpenVPN. + If your choice of TemplateVM doesn't already have the VPN client software, you'll need to install the software in the template before proceeding. + Disable any auto-starting service that comes with the software package. + For example for OpenVPN. sudo systemctl disable openvpn.service -You may also wish to install `nano` or another simple text editor for entering the scripts below. + You may also wish to install `nano` or another simple text editor for entering the scripts below. -2. Set up and test the VPN client. +2. Set up and test the VPN client. + Make sure the VPN VM and its TemplateVM is not running. + Run a terminal (CLI) in the VPN VM -- this will start the VM. + Then create a new `/rw/config/vpn` folder with. -Make sure the VPN VM and its TemplateVM is not running. + sudo mkdir /rw/config/vpn -Run a terminal (CLI) in the VPN VM -- this will start the VM. Then create a new `/rw/config/vpn` folder with. + Copy your VPN config files to `/rw/config/vpn`. + Your VPN config file should be named `openvpn-client.ovpn`) so you can use the scripts below as is without modification. + Otherwise you would have to replace the file name. + `openvpn-client.ovpn` contents: - sudo mkdir /rw/config/vpn + * Files accompanying the main config such as `*.crt` and `*.pem` should also go to `/rw/config/vpn` folder. + * Files referenced in `openvpn-client.ovpn` should not use absolute paths such as `/etc/...`. -Copy your VPN config files to `/rw/config/vpn`. Your VPN config file should be named `openvpn-client.ovpn`) so you can use the scripts below as is without modification. Otherwise you would have to replace the file name. `openvpn-client.ovpn` contents: - -Files accompanying the main config such as `*.crt` and `*.pem` should also go to `/rw/config/vpn` folder. - -Files referenced in `openvpn-client.ovpn` should not use absolute paths such as `/etc/...`. - -The VPN scripts here are intended to work with commonly used `tun` interfaces, whereas `tap` mode is untested. - -Also, the config should route all traffic through your VPN's interface after a connection is created; For OpenVPN the directive for this is `redirect-gateway def1`. + The VPN scripts here are intended to work with commonly used `tun` interfaces, whereas `tap` mode is untested. + Also, the config should route all traffic through your VPN's interface after a connection is created; For OpenVPN the directive for this is `redirect-gateway def1`. sudo nano /rw/config/vpn/openvpn-client.ovpn -Make sure it already includes or add: + Make sure it already includes or add: redirect-gateway def1 -The VPN client may not be able to prompt you for credentials when connecting to the server. Create a file in the `/rw/config/vpn` folder with your credentials and using a directive. For example for OpenVPN, add: + The VPN client may not be able to prompt you for credentials when connecting to the server. + Create a file in the `/rw/config/vpn` folder with your credentials and using a directive. + For example for OpenVPN, add: - auth-user-pass pass.txt + auth-user-pass pass.txt - Save file `/rw/config/vpn/openvpn-client.ovpn`. + Save file `/rw/config/vpn/openvpn-client.ovpn`. + Make sure a `/rw/config/vpn/pass.txt` file actually exists. - Make sure a `/rw/config/vpn/pass.txt` file actually exists. + sudo nano /rw/config/vpn/pass.txt - sudo nano /rw/config/vpn/pass.txt + Add: - Add: + username + password - username - password + Replace `username` and `password` with your actual username and password. - Replace `username` and `password` with your actual username and password. - - __Test your client configuration:__ Run the client from a CLI prompt in the 'vpn' folder, preferably as root. For example: + **Test your client configuration:** + Run the client from a CLI prompt in the 'vpn' folder, preferably as root. + For example: sudo openvpn --cd /rw/config/vpn --config openvpn-client.ovpn -Watch for status messages that indicate whether the connection is successful and test from another VPN VM terminal window with `ping`. + Watch for status messages that indicate whether the connection is successful and test from another VPN VM terminal window with `ping`. ping 8.8.8.8 -`ping` can be aborted by pressing the two keys `ctrl` + `c` at the same time. + `ping` can be aborted by pressing the two keys `ctrl` + `c` at the same time. + DNS may be tested at this point by replacing addresses in `/etc/resolv.conf` with ones appropriate for your VPN (although this file will not be used when setup is complete). + Diagnose any connection problems using resources such as client documentation and help from your VPN service provider. + Proceed to the next step when you're sure the basic VPN connection is working. -DNS may be tested at this point by replacing addresses in `/etc/resolv.conf` with ones appropriate for your VPN (although this file will not be used when setup is complete). Diagnose any connection problems using resources such as client documentation and help from your VPN service provider. +3. Create the DNS-handling script. -Proceed to the next step when you're sure the basic VPN connection is working. + sudo nano /rw/config/vpn/qubes-vpn-handler.sh -3. Create the DNS-handling script. + Edit and add: - sudo nano /rw/config/vpn/qubes-vpn-handler.sh + ~~~ + #!/bin/bash + set -e + export PATH="$PATH:/usr/sbin:/sbin" + + case "$1" in + + up) + # To override DHCP DNS, assign DNS addresses to 'vpn_dns' env variable before calling this script; + # Format is 'X.X.X.X Y.Y.Y.Y [...]' + if [[ -z "$vpn_dns" ]] ; then + # Parses DHCP foreign_option_* vars to automatically set DNS address translation: + for optionname in ${!foreign_option_*} ; do + option="${!optionname}" + unset fops; fops=($option) + if [ ${fops[1]} == "DNS" ] ; then vpn_dns="$vpn_dns ${fops[2]}" ; fi + done + fi + + iptables -t nat -F PR-QBS + if [[ -n "$vpn_dns" ]] ; then + # Set DNS address translation in firewall: + for addr in $vpn_dns; do + iptables -t nat -A PR-QBS -i vif+ -p udp --dport 53 -j DNAT --to $addr + iptables -t nat -A PR-QBS -i vif+ -p tcp --dport 53 -j DNAT --to $addr + done + su - -c 'notify-send "$(hostname): LINK IS UP." --icon=network-idle' user + else + su - -c 'notify-send "$(hostname): LINK UP, NO DNS!" --icon=dialog-error' user + fi + + ;; + down) + su - -c 'notify-send "$(hostname): LINK IS DOWN !" --icon=dialog-error' user + ;; + esac + ~~~ - Edit and add: - - ~~~ - #!/bin/bash - set -e - export PATH="$PATH:/usr/sbin:/sbin" - - case "$1" in - - up) - # To override DHCP DNS, assign DNS addresses to 'vpn_dns' env variable before calling this script; - # Format is 'X.X.X.X Y.Y.Y.Y [...]' - if [[ -z "$vpn_dns" ]] ; then - # Parses DHCP foreign_option_* vars to automatically set DNS address translation: - for optionname in ${!foreign_option_*} ; do - option="${!optionname}" - unset fops; fops=($option) - if [ ${fops[1]} == "DNS" ] ; then vpn_dns="$vpn_dns ${fops[2]}" ; fi - done - fi - - iptables -t nat -F PR-QBS - if [[ -n "$vpn_dns" ]] ; then - # Set DNS address translation in firewall: - for addr in $vpn_dns; do - iptables -t nat -A PR-QBS -i vif+ -p udp --dport 53 -j DNAT --to $addr - iptables -t nat -A PR-QBS -i vif+ -p tcp --dport 53 -j DNAT --to $addr - done - su - -c 'notify-send "$(hostname): LINK IS UP." --icon=network-idle' user - else - su - -c 'notify-send "$(hostname): LINK UP, NO DNS!" --icon=dialog-error' user - fi - - ;; - down) - su - -c 'notify-send "$(hostname): LINK IS DOWN !" --icon=dialog-error' user - ;; - esac - ~~~ - -Save the script. - -Make it executable. + Save the script. + Make it executable. sudo chmod +x /rw/config/vpn/qubes-vpn-handler.sh -4. Configure client to use the DNS handling script. Using openvpn as an example, edit the config. +4. Configure client to use the DNS handling script. Using openvpn as an example, edit the config. sudo nano /rw/config/vpn/openvpn-client.ovpn - Add the following. + Add the following. - ~~~ - script-security 2 - up 'qubes-vpn-handler.sh up' - down 'qubes-vpn-handler.sh down' - ~~~ + script-security 2 + up 'qubes-vpn-handler.sh up' + down 'qubes-vpn-handler.sh down' -Remove other instances of lines starting with `script-security`, `up` or `down` should there be any others. + Remove other instances of lines starting with `script-security`, `up` or `down` should there be any others. + Save the script. + **Restart the client and test the connection again** ...this time from an AppVM! -Save the script. - -**Restart the client and test the connection again** ...this time from an AppVM! - -5. Set up iptables anti-leak rules. - - Edit the firewall script. +5. Set up iptables anti-leak rules. + Edit the firewall script. sudo nano /rw/config/qubes-firewall-user-script -Clear out the existing lines and add: + Clear out the existing lines and add: - ~~~ - #!/bin/bash - # Block forwarding of connections through upstream network device - # (in case the vpn tunnel breaks): - iptables -I FORWARD -o eth0 -j DROP - iptables -I FORWARD -i eth0 -j DROP - - # Block all outgoing traffic - iptables -P OUTPUT DROP - iptables -F OUTPUT - iptables -I OUTPUT -o lo -j ACCEPT - - # Add the `qvpn` group to system, if it doesn't already exist - if ! grep -q "^qvpn:" /etc/group ; then + ~~~ + #!/bin/bash + # Block forwarding of connections through upstream network device + # (in case the vpn tunnel breaks): + iptables -I FORWARD -o eth0 -j DROP + iptables -I FORWARD -i eth0 -j DROP + + # Block all outgoing traffic + iptables -P OUTPUT DROP + iptables -F OUTPUT + iptables -I OUTPUT -o lo -j ACCEPT + + # Add the `qvpn` group to system, if it doesn't already exist + if ! grep -q "^qvpn:" /etc/group ; then groupadd -rf qvpn sync - fi - sleep 2s + fi + sleep 2s + + # Allow traffic from the `qvpn` group to the uplink interface (eth0); + # Our VPN client will run with group `qvpn`. + iptables -I OUTPUT -p all -o eth0 -m owner --gid-owner qvpn -j ACCEPT + ~~~ - # Allow traffic from the `qvpn` group to the uplink interface (eth0); - # Our VPN client will run with group `qvpn`. - iptables -I OUTPUT -p all -o eth0 -m owner --gid-owner qvpn -j ACCEPT - ~~~ - -Save the script. - -Make it executable. + Save the script. + Make it executable. sudo chmod +x /rw/config/qubes-firewall-user-script -5. Set up the VPN's autostart. +5. Set up the VPN's autostart. sudo nano /rw/config/rc.local -Clear out the existing lines and add: + Clear out the existing lines and add: - ~~~ - #!/bin/bash - VPN_CLIENT='openvpn' - VPN_OPTIONS='--cd /rw/config/vpn/ --config openvpn-client.ovpn --daemon' + ~~~ + #!/bin/bash + VPN_CLIENT='openvpn' + VPN_OPTIONS='--cd /rw/config/vpn/ --config openvpn-client.ovpn --daemon' + + su - -c 'notify-send "$(hostname): Starting $VPN_CLIENT..." --icon=network-idle' user + groupadd -rf qvpn ; sleep 2s + sg qvpn -c "$VPN_CLIENT $VPN_OPTIONS" + ~~~ - su - -c 'notify-send "$(hostname): Starting $VPN_CLIENT..." --icon=network-idle' user - groupadd -rf qvpn ; sleep 2s - sg qvpn -c "$VPN_CLIENT $VPN_OPTIONS" - ~~~ - -If you are using anything other than OpenVPN, change the `VPN_CLIENT` and `VPN_OPTIONS` variables to match your VPN software. - -Save the script. - -Make it executable. + If you are using anything other than OpenVPN, change the `VPN_CLIENT` and `VPN_OPTIONS` variables to match your VPN software. + Save the script. + Make it executable. sudo chmod +x /rw/config/rc.local` -6. Restart the new VM! The link should then be established automatically with a popup notification to that effect. +6. Restart the new VM! + The link should then be established automatically with a popup notification to that effect. + Usage ----- @@ -268,14 +268,13 @@ Configure your AppVMs to use the VPN VM as a NetVM... ![Settings-NetVM.png](/attachment/wiki/VPN/Settings-NetVM.png) - If you want to be able to use the [Qubes firewall](/doc/firewall), create a new FirewallVM (as a ProxyVM) and set it to use the VPN VM as its NetVM. Then, configure AppVMs to use your new FirewallVM as their NetVM. If you want to update your TemplateVMs through the VPN, enable the `qubes-updates-proxy` service in your new FirewallVM. You can do this in the Services tab in Qubes VM Manager or on the command-line: - $ qvm-service -e qubes-updates-proxy + qvm-service -e qubes-updates-proxy Then, configure your templates to use your new FirewallVM as their NetVM. From e5e2aa78098155f1c088c0fbe0bd09057c682491 Mon Sep 17 00:00:00 2001 From: awokd <34515595+awokd@users.noreply.github.com> Date: Wed, 31 Jan 2018 12:36:25 +0000 Subject: [PATCH 36/67] Update usb.md --- common-tasks/usb.md | 10 ++-------- 1 file changed, 2 insertions(+), 8 deletions(-) diff --git a/common-tasks/usb.md b/common-tasks/usb.md index 96d1cdb3..4c2d7e18 100644 --- a/common-tasks/usb.md +++ b/common-tasks/usb.md @@ -361,15 +361,9 @@ qube's settings page in Qubes VM Manager or by using the [qvm-pci][Assigning Devices] command. For guidance on finding the correct USB controller, see [here][usb-controller]. You can create a USB qube using the management stack by performing the following -steps as root in dom0: +as root in dom0: - 1. Enable `sys-usb`: - - sudo qubesctl top.enable qvm.sys-usb - - 2. Apply the configuration: - - sudo qubesctl state.sls qvm.sys-usb + sudo qubesctl state.sls qvm.sys-usb Alternatively, you can create a USB qube manually as follows: From cd5acfea81f5e921f77c28fd1c68ffe979471cdd Mon Sep 17 00:00:00 2001 From: awokd <34515595+awokd@users.noreply.github.com> Date: Wed, 31 Jan 2018 13:35:12 +0000 Subject: [PATCH 37/67] templates 4.0 updates Add 4.0 and split out version specific content --- managing-os/templates.md | 37 ++++++++++++++++++++++++++++--------- 1 file changed, 28 insertions(+), 9 deletions(-) diff --git a/managing-os/templates.md b/managing-os/templates.md index 3189aa57..b936c7e3 100644 --- a/managing-os/templates.md +++ b/managing-os/templates.md @@ -45,7 +45,23 @@ By installing these templates, you are trusting not only ITL and the distributio * [Archlinux](/doc/templates/archlinux/) -Important Notes +Important Notes (R4.0) +--------------- + + * Whenever a TemplateBasedVM is created, the contents of the `/home` + directory of its parent TemplateVM are *not* copied to the child TemplateBasedVM's + `/home`. The child TemplateBasedVM's `/home` + is always independent from its parent TemplateVM's `/home`, which means that any + subsequent changes to the parent TemplateVM's `/home` will not affect + the child TemplateBasedVM's `/home`. + + * Template VMs are created in a thin pool, making `qvm-trim-template` + no longer necessary. + + The root filesystems in Standalone VMs can employ + TRIM/discard on the root fs using normal tools and configuration options. + +Important Notes (R3.2 and earlier) --------------- * Whenever a TemplateBasedVM is created, the contents of the `/home` @@ -54,6 +70,16 @@ Important Notes is independent from its parent TemplateVM's `/home`, which means that any subsequent changes to the parent TemplateVM's `/home` will no longer affect the child TemplateBasedVM's `/home`. + + * Template VMs can occupy more space on the dom0 filesystem than necessary + because they cannot employ automatic TRIM/discard on the root fs. The + `qvm-trim-template` command in dom0 is used to recover this unused space. + + Conversely, the root filesystems in Standalone VMs *can* employ + TRIM/discard on the root fs using normal tools and configuration options. + +Important Notes (all versions) +--------------- * Once a TemplateBasedVM has been created, any changes in its `/home`, `/usr/local`, or `/rw/config` directories will be persistent across reboots, @@ -71,18 +97,11 @@ Important Notes update a template from dom0 (and thereby lose any user modifications in the existing template), you must first uninstall the existing template from dom0: - $ sudo yum remove qubes-template-fedora-25 + $ sudo dnf remove qubes-template-fedora-25 * Standalone VMs using Template VMs as a basis can be created easily. These VMs receive a *copy* of the operating system and do not get automatically updated when Template VMs are updated--they must be updated individually. - - * Template VMs can occupy more space on the dom0 filesystem than necessary - because they cannot employ automatic TRIM/discard on the root fs. The - `qvm-trim-template` command in dom0 is used to recover this unused space. - - Conversely, the root filesystems in Standalone VMs *can* employ - TRIM/discard on the root fs using normal tools and configuration options. * On XFCE based Dom0, a manual action may be required to remove the "Start Menu" sub-menu of the removed TemplateVM. For example, to remove a dangling sub-menu From 80149fc0b9fdc0dd74ecf833a4c34b0a8ac32d70 Mon Sep 17 00:00:00 2001 From: awokd <34515595+awokd@users.noreply.github.com> Date: Wed, 31 Jan 2018 14:20:24 +0000 Subject: [PATCH 38/67] hvm 4.0rc4 updates --- managing-os/hvm.md | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/managing-os/hvm.md b/managing-os/hvm.md index 8d27c51b..fc095ce2 100644 --- a/managing-os/hvm.md +++ b/managing-os/hvm.md @@ -17,8 +17,14 @@ What are HVM domains? HVM domains (Hardware VM), in contrast to PV domains (Paravirtualized domains), allow one to create domains based on any OS for which one has an installation ISO. For example, this allows one to have Windows-based VMs in Qubes. -Interested readers might want to check [this article](https://blog.invisiblethings.org/2012/03/03/windows-support-coming-to-qubes.html) to learn why it took so long for Qubes OS to support HVM domains (Qubes 1 only supported Linux based PV domains). As of -Qubes 4, every VM is HVM by default ([see here](https://blog.invisiblethings.org/2017/07/31/qubes-40-rc1.html)). +Interested readers might want to check +[this article](https://blog.invisiblethings.org/2012/03/03/windows-support-coming-to-qubes.html) +to learn why it took so long for Qubes OS to support HVM domains +(Qubes 1 only supported Linux based PV domains). As of +Qubes 4, every VM is PVH by default, except those with attached PCI devices which are HVM. +[See here](https://blog.invisiblethings.org/2017/07/31/qubes-40-rc1.html) for a discussion +of the switch to HVM from R3.2's PV, and [here](https://www.qubes-os.org/news/2018/01/11/qsb-37/) +for changing the default to PVH. Creating an HVM domain ---------------------- From 199359538fc13e6107aa3d367e9c69b73dbadaa3 Mon Sep 17 00:00:00 2001 From: Yassine Ilmi Date: Wed, 31 Jan 2018 22:44:03 +0000 Subject: [PATCH 39/67] Precised part number and iso update procedure As per @marmarek comments specify that EFI part is #2 and added procedure to edit iso using losetup --- troubleshooting/uefi-troubleshooting.md | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/troubleshooting/uefi-troubleshooting.md b/troubleshooting/uefi-troubleshooting.md index a5f74ca1..e36e28ad 100644 --- a/troubleshooting/uefi-troubleshooting.md +++ b/troubleshooting/uefi-troubleshooting.md @@ -10,15 +10,19 @@ Troubleshooting UEFI related problems Change installer kernel parameters in UEFI --------------------- -If you've installed successfully in legacy mode but had to change some kernel parameters for it to work, you should try installing in UEFI with the same kernel parameters. +If you've installed successfully in legacy mode but had to change some kernel parameters for it to work, you should try installing in UEFI mode with the same parameters. -Change the `xen.cfg` on a USB media - -01. Attach the usb disk, find the EFI partition and mount it -02. Edit your xen.cfg changing the `kernel` key to add your kernel parameters on the boot entry of your choice +**Change the xen configuration on a USB media** +01. Attach the usb disk, mount the EFI partition (second partition available on the disk) +02. Edit your xen config (`xen.cfg/BOOTX64.cfg`) changing the `kernel` key to add your kernel parameters on the boot entry of your choice 03. Install using your modified boot entry -You can also update an iso image, use `losetup` to isolate the EFI partition and mount it. +**Change xen configuration directly in an iso image** +01. Get EFI partition boundaries `parted Qubes-R4.0-rc4-x86_64.iso unit B print` +02. Using the start address and the size of the EFI partition, setup a loop device for it `sudo losetup -o 524288 --sizelimit 30562304 /dev/loop0 Qubes-R4.0-rc4-x86_64.iso` +03. Mount the loop device `sudo mount /dev/loop0 /mnt` +04. Edit `EFI/BOOT/BOOTX64.cfg` to add your params to the `kernel` configuration key +05. Save your changes, unmount and dd to usb device Cannot start installation, installation completes successfully but then BIOS loops at boot device selection, hangs at four penguins after choosing "Test media and install Qubes OS" in GRUB menu From 27052b83a67428eae37f9e719df824344c06e662 Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Wed, 31 Jan 2018 22:31:03 -0600 Subject: [PATCH 40/67] Improve organization, clarify procedure, and clean up source --- basics_user/reporting-bugs.md | 103 +++++++++++++++++----------------- 1 file changed, 51 insertions(+), 52 deletions(-) diff --git a/basics_user/reporting-bugs.md b/basics_user/reporting-bugs.md index 7cd31084..8fb9ca63 100644 --- a/basics_user/reporting-bugs.md +++ b/basics_user/reporting-bugs.md @@ -16,71 +16,65 @@ redirect_from: Reporting Bugs ============== -One of the most important ways in which you can [contribute to the Qubes OS Project] is by reporting any bugs you have found. -Please note that there is a separate process for [reporting security issues](/security/). +One of the most important ways in which you can [contribute to the Qubes OS Project] is by reporting any bugs you have found. -Before you submit a report --------------------------- +Important +--------- -Before you submit a bug report, please take a moment to: - - * Check whether your issue has already been reported. - - * Determine which venue is most appropriate for it. - - * Read the [documentation] to see whether what you've found is really a bug. - - * Search through the existing [Qubes issues][qubes-issues] by typing your key - words in the **Filters** box. Make sure to check both currently open issues, - as well as issues that are already closed. If you find an issue that seems to - be similar to yours, read through it. If this issue is the same as yours, you - can comment with additional information to help the maintainer debug it. - Adding a comment will subscribe you to email notifications, which can be - helpful in getting important updates regarding the issue. If you don't have - anything to add but still want to receive email updates, you can click the - "watch" button at the bottom of the comments. - - * Search through our [mailing list] archives by visiting the Google Groups web - interfaces for both [qubes-users] and [qubes-devel]. +- **To disclose a security issue confidentially, please see the [Security] page.** +- **In all other cases, please do not email individual developers about bugs.** +- **Please note that many issues can be resolved by reading the [documentation].** Where to submit your report --------------------------- -Our [GitHub issues][qubes-issues] tracker is not intended for personal, -localized troubleshooting questions, such as problems that affect only a -specific laptop model. Those questions are more likely to be answered in -[qubes-users], which receives much more traffic. Instead, GitHub issues are -meant to track more general bugs and enhancements that affect a broad range of -Qubes users. - - -How to copy information out of Dom0 ------------------------------------ - -See [Copying from (and to) dom0](/doc/copy-from-dom0/). - - -How to submit a report on the mailing lists -------------------------------------------- - -Please see the [mailing list guidelines][mailing list]. +All issues pertaining to the Qubes OS Project (including auxiliary infrastructure such as the [website]) are tracked in [qubes-issues], our GitHub issues tracker. +However, [qubes-issues] is not intended for personal, localized troubleshooting questions, such as problems that affect only a specific laptop model. +Those questions should instead be asked in [qubes-users], where they are more likely to be answered. +Instead, [qubes-issues] is meant for tracking more general bugs and enhancements that affect a broad range of Qubes users. +Please see the sections [How to submit a report on GitHub] and [How to submit a report on the mailing lists] below for more information. How to submit a report on GitHub -------------------------------- -We track all bugs in the [qubes-issues] tracker on GitHub. +**Before you submit an issue in [qubes-issues], please check to see whether it has already been reported.** +Search through the existing issues by typing your key words in the **Filters** box. +Make sure to check both currently open issues, as well as issues that are already closed. +If you find an issue that seems to be similar to yours, read through it. +If this issue is the same as yours, you can comment with additional information to help the maintainer debug it. +Adding a comment will subscribe you to email notifications, which can be helpful in getting important updates regarding the issue. +If you don't have anything to add but still want to receive email updates, you can click the "watch" button at the bottom of the comments. -When you file a new issue, you should be sure to include the version of Qubes -your'e using, as well as versions of related software packages. If your issue is -related to hardware, provide as many details as possible about the hardware, -which could include using command-line tools such as `lspci`. +When you file a new issue, you should be sure to include the version of Qubes you're using, as well as versions of related software packages. +If your issue is related to hardware, provide as many details as possible about the hardware, which could include using command-line tools such as `lspci`. If you're reporting a bug in a package that is in a [testing] repository, please reference the appropriate issue in the [updates-status] repository. +Project maintainers really appreciate thorough explanations. +It usually helps them address the problem more quickly, so everyone wins! -Project maintainers really appreciate thorough explanations. It usually -helps them address the problem more quickly, so everyone wins! +Once your issue is addressed, your GitHub issue may be closed. +After that, the package containing the fix will move to the appropriate [testing] repository, then to the appropriate stable repository. +If you so choose, you can test the fix while it's in the [testing] repository, or you can wait for it to land in the stable repository. +If, after testing the fix, you find that it does not really fix your bug, please leave a comment on your issue explaining the situation. +When you do, we will receive a notification and respond on your issue or reopen it (or both). +Please **do not** create a duplicate issue or attempt to contact the developers individually about your problem. + + +How to submit a report on the mailing lists +------------------------------------------- + +Before submitting a report on the mailing lists, please check to see whether your issue has already been reported by searching through the archives. +You can do this by visiting the Google Groups web interfaces for both [qubes-users] and [qubes-devel]. +Please see the [Mailing Lists] page for further information. + + +How to copy information out of dom0 +----------------------------------- + +Copying information out of dom0 can be useful when reporting bugs. +See [Copying from (and to) dom0] for more information. Testing new releases and updates @@ -96,12 +90,17 @@ Please see our guidelines on [how to contribute code]. [contribute to the Qubes OS Project]: /doc/contributing/ +[Security]: /security/ [documentation]: /doc/ +[website]: / [qubes-issues]: https://github.com/QubesOS/qubes-issues/issues -[mailing list]: https://www.qubes-os.org/mailing-lists/ -[qubes-users]: https://groups.google.com/group/qubes-users -[qubes-devel]: https://groups.google.com/group/qubes-devel +[Mailing List]: /mailing-lists/ +[qubes-users]: /mailing-lists/#qubes-users +[qubes-devel]: /mailing-lists/#qubes-devel +[How to submit a report on GitHub]: #how-to-submit-a-report-on-github +[How to submit a report on the mailing lists]: #how-to-submit-a-report-on-the-mailing-lists [testing]: /doc/testing/ [updates-status]: https://github.com/QubesOS/updates-status/issues +[Copying from (and to) dom0]: /doc/copy-from-dom0/ [how to contribute code]: /doc/contributing/#contributing-code From fb7952840e001711554a58da107abb06e3b3c9cb Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Wed, 31 Jan 2018 22:40:01 -0600 Subject: [PATCH 41/67] Clarify language, improve links, and clean up source --- security-info/security.md | 53 +++++++++++++++++++++++++-------------- 1 file changed, 34 insertions(+), 19 deletions(-) diff --git a/security-info/security.md b/security-info/security.md index b44c2136..323774c0 100644 --- a/security-info/security.md +++ b/security-info/security.md @@ -17,38 +17,53 @@ redirect_from: Qubes OS Project Security Center ================================ -- [Security FAQ](/faq/#general--security) -- [Security Goals](/security/goals/) -- [Security Pack](/security/pack/) -- [Security Bulletins](/security/bulletins/) -- [Canaries](/security/canaries/) -- [Xen Security Advisory (XSA) Tracker](/security/xsa/) -- [Why and How to Verify Signatures](/security/verifying-signatures/) -- [PGP Keys](https://keys.qubes-os.org/keys/) +- [Security FAQ] +- [Security Goals] +- [Security Pack] +- [Security Bulletins] +- [Canaries] +- [Xen Security Advisory (XSA) Tracker] +- [Why and How to Verify Signatures] +- [PGP Keys] + Reporting Security Issues in Qubes OS ------------------------------------- If you believe you have found a security issue affecting Qubes OS, either directly or indirectly (e.g. the issue affects Xen in a configuration that is used in Qubes OS), then we would be more than happy to hear from you! +We promise to treat any reported issue seriously and, if the investigation confirms that it affects Qubes, to patch it within a reasonable time and release a public [Qubes Security Bulletin][Security Bulletins] that describes the issue, discusses the potential impact of the vulnerability, references applicable patches or workarounds, and credits the discoverer. -We promise to treat any reported issue seriously and, if the investigation confirms it affects Qubes, to patch it within a reasonable time, release a public Security Bulletin that describes the issue, discuss potential impact of the vulnerability, reference applicable patches or workarounds, and credit the discoverer. - -The list of all Qubes Security Advisories published so far can be found [here](/security/bulletins/). The Qubes Security Team ----------------------- -The Qubes Security Team can be contacted via email using the following address: +The Qubes Security Team can be contacted via email at the following address: -~~~ -security at qubes-os dot org -~~~ + security at qubes-os dot org -### Qubes Security Team GPG Key ### -Please use [this GPG key](https://keys.qubes-os.org/keys/qubes-os-security-team-key.asc) to encrypt any emails sent to this address. Like all GPG keys used by the Qubes project, this key is signed by the Qubes Master key. Please see [this page](/security/verifying-signatures/) for more information on how to verify the keys. +### Security Team PGP Key ### + +Please use the [Security Team PGP Key] to encrypt all emails sent to this address. +This key is signed by the [Qubes Master Signing Key]. +Please see [Why and How to Verify Signatures] for information about how to verify these keys. ### Members of the Security Team ### -- Joanna Rutkowska \ -- Marek Marczykowski \ +- [Joanna Rutkowska] +- [Marek Marczykowski-Górecki] + + +[Security FAQ]: /faq/#general--security +[Security Goals]: /security/goals/ +[Security Pack]: /security/pack/ +[Security Bulletins]: /security/bulletins/ +[Canaries]: /security/canaries/ +[Xen Security Advisory (XSA) Tracker]: /security/xsa/ +[Why and How to Verify Signatures]: /security/verifying-signatures/ +[PGP Keys]: https://keys.qubes-os.org/keys/ +[Security Team PGP Key]: https://keys.qubes-os.org/keys/qubes-os-security-team-key.asc +[Qubes Master Signing Key]: https://keys.qubes-os.org/keys/qubes-master-signing-key.asc +[Joanna Rutkowska]: /team/#joanna-rutkowska +[Marek Marczykowski-Górecki]: /team/#marek-marczykowski-górecki + From 922340303e71cbddebfcee31ae4846374d360300 Mon Sep 17 00:00:00 2001 From: awokd <34515595+awokd@users.noreply.github.com> Date: Thu, 1 Feb 2018 14:59:45 +0000 Subject: [PATCH 42/67] security-guidelines 4.0 update yum -> dnf Replace R3.x specific description of treatment of template's home directory with link to /doc/template --- security/security-guidelines.md | 13 +++++-------- 1 file changed, 5 insertions(+), 8 deletions(-) diff --git a/security/security-guidelines.md b/security/security-guidelines.md index cf712f13..1d143600 100644 --- a/security/security-guidelines.md +++ b/security/security-guidelines.md @@ -32,7 +32,7 @@ See the page on [Verifying Signatures](https://www.qubes-os.org/security/verifyi Once you have Qubes installed, the standard program installation command for Fedora and Qubes repositories ~~~ -sudo yum install +sudo dnf install ~~~ automatically accomplishes this verification. @@ -93,7 +93,7 @@ sudo qubes-dom0-update and run in templates and standalone VM ~~~ -sudo yum update +sudo dnf update ~~~ or use the equivalent items in Qubes Manager, which displays an icon when an update is available. @@ -154,12 +154,6 @@ As explained [here](/getting-started/#appvms-qubes-and-templatevms), dom0 should TemplateBasedVM Directories --------------------------- - * Whenever a TemplateBasedVM is created, the contents of its `/home` - directory is copied from its parent TemplateVM. From that point onward, the child TemplateBasedVM's `/home` - is independent from its parent TemplateVM's `/home`, which means that any - subsequent changes to the parent TemplateVM's `/home` will no longer affect - the child TemplateBasedVM's `/home`. - * Once a TemplateBasedVM has been created, any changes in its `/home`, `/usr/local`, or `/rw/config` directories will be persistent across reboots, which means that any files stored there will still be available after @@ -167,3 +161,6 @@ TemplateBasedVM Directories TemplateBasedVMs persist in this manner. If you would like to make changes in other directories which *do* persist in this manner, you must make those changes in the parent TemplateVM. + + * See [here](/doc/templates) for more detail and version specific information. + From 2f523a8d8343d131b921a87e46b57a17d84c8271 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Marczykowski-G=C3=B3recki?= Date: Fri, 2 Feb 2018 00:32:22 +0100 Subject: [PATCH 43/67] 4.0 release notes: add link to upgrade instruction --- releases/4.0/release-notes.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/releases/4.0/release-notes.md b/releases/4.0/release-notes.md index aed5bc95..8119b4b7 100644 --- a/releases/4.0/release-notes.md +++ b/releases/4.0/release-notes.md @@ -58,6 +58,7 @@ Upgrading There is no in-place upgrade path from earlier Qubes versions. The only supported option to upgrade to Qubes R4.0 is to install it from scratch and use [qubes backup and restore tools][backup] for migrating of all of the user VMs. +We also provide [detailed instruction][upgrade-to-r4.0] for this procedure. [backup]: /doc/backup-restore/ @@ -77,3 +78,4 @@ supported option to upgrade to Qubes R4.0 is to install it from scratch and use [qsb-24]: https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-024-2016.txt [backup-format]: /doc/backup-emergency-restore-v4/ [api-doc]: https://dev.qubes-os.org/projects/qubes-core-admin/en/latest/ +[upgrade-to-r4.0]: https://www.qubes-os.org/doc/upgrade-to-r4.0/ From 9801e192db18702585ae7332693b90c1bb139fd4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Marczykowski-G=C3=B3recki?= Date: Fri, 2 Feb 2018 01:03:44 +0100 Subject: [PATCH 44/67] USB: USB keyboard usage, including LUKS passphrase --- common-tasks/usb.md | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/common-tasks/usb.md b/common-tasks/usb.md index 4c2d7e18..18f82500 100644 --- a/common-tasks/usb.md +++ b/common-tasks/usb.md @@ -494,6 +494,24 @@ How to use a USB keyboard **Caution:** Please carefully read the [Security Warning about USB Input Devices] before proceeding. +If you use USB keyboard, automatic USB qube creation during installation is disabled. +Additional steps are required to avoid locking you out from the system. +Those steps are not performed by default, because of risk explained in [Security Warning about USB Input Devices]. + +### R4.0, using salt ### + +To allow USB keyboard usage (including early boot for LUKS passphrase), execute in dom0: + + sudo qubesctl state.sls qvm.usb-keyboard + +The above command will take care of all required configuration, including creating USB qube if not present. +Note that it will expose dom0 to USB devices while entering LUKS passphrase. +Users are advised to physically disconnect other devices from the system for that time, to minimize the risk. + +If you wish to perform only subset of this configuration (for example do not enable USB keyboard during boot), see manual instructions below. + +### R3.2, manual ### + In order to use a USB keyboard, you must first attach it to a USB qube, then give that qube permission to pass keyboard input to dom0. Edit the `qubes.InputKeyboard` policy file in dom0, which is located here: @@ -512,6 +530,9 @@ For a confirmation dialog each time the USB keyboard is connected, change this l sys-usb dom0 ask,default_target=dom0 ``` +Additionally, if you want to use USB keyboard to enter LUKS passphrase, it is incompatible with [hiding USB controllers from dom0][How to hide all USB controllers from dom0]. +You need to revert that procedure (remove `rd.qubes.hide_all_usb` option from files mentioned there) and employ alternative protection during system boot - disconnect other devices during startup. + How to use a USB mouse ---------------------- @@ -556,4 +577,5 @@ sys-usb dom0 ask,default_target=dom0 [usb-challenges]: https://blog.invisiblethings.org/2011/05/31/usb-security-challenges.html [YubiKey]: /doc/YubiKey/ [Security Warning about USB Input Devices]: #security-warning-about-usb-input-devices +[How to hide all USB controllers from dom0]: #how-to-hide-all-usb-controllers-from-dom0 [qubes-usb-proxy]: https://github.com/QubesOS/qubes-app-linux-usb-proxy From 9e144a3154cc1a6a23eafcd9c0277dae65d830b5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Marczykowski-G=C3=B3recki?= Date: Fri, 2 Feb 2018 01:27:11 +0100 Subject: [PATCH 45/67] usb keyboard: add note about updating dom0 first --- common-tasks/usb.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/common-tasks/usb.md b/common-tasks/usb.md index 18f82500..c3ef3d60 100644 --- a/common-tasks/usb.md +++ b/common-tasks/usb.md @@ -500,7 +500,7 @@ Those steps are not performed by default, because of risk explained in [Security ### R4.0, using salt ### -To allow USB keyboard usage (including early boot for LUKS passphrase), execute in dom0: +To allow USB keyboard usage (including early boot for LUKS passphrase), make sure you have the latest `qubes-mgmt-salt-dom0-virtual-machines` package (simply [install dom0 updates][dom0-updates]) and execute in dom0: sudo qubesctl state.sls qvm.usb-keyboard @@ -579,3 +579,4 @@ sys-usb dom0 ask,default_target=dom0 [Security Warning about USB Input Devices]: #security-warning-about-usb-input-devices [How to hide all USB controllers from dom0]: #how-to-hide-all-usb-controllers-from-dom0 [qubes-usb-proxy]: https://github.com/QubesOS/qubes-app-linux-usb-proxy +[dom0-updates]: /doc/software-update-dom0/#how-to-update-software-in-dom0 From 80179d4481f5552a01b449f0a6138141dcef6272 Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Thu, 1 Feb 2018 23:35:35 -0600 Subject: [PATCH 46/67] Improve 4.0 upgrade instructions regarding TemplateVMs Fixes QubesOS/qubes-issues#3514 --- installing/upgrade/upgrade-to-r4.0.md | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/installing/upgrade/upgrade-to-r4.0.md b/installing/upgrade/upgrade-to-r4.0.md index 650965f6..b3771760 100644 --- a/installing/upgrade/upgrade-to-r4.0.md +++ b/installing/upgrade/upgrade-to-r4.0.md @@ -84,18 +84,19 @@ Restore from your backup 4. Go to **Qubes menu -> System Tools -> Qubes Manager** to start it. 5. Follow the **Restoring from a Backup** section in the [Backup, Restoration, and Migration](/doc/backup-restore/) guide. - It is cleanest to restore only the [AppVMs](/doc/glossary/#appvm) and [StandaloneVMs](/doc/glossary/#standalonevm) from R3.2, so it is recommended not to select any **sys-** or templates to restore unless you've heavily customized them. - If the restore tool complains about missing templates, you can select the option to restore the AppVMs anyways, then change them after restore to use one of the default R4.0 templates. + We recommend that you restore only your [TemplateBasedVMs](/doc/glossary/#templatebasedvm) and [StandaloneVMs](/doc/glossary/#standalonevm) from R3.2. + Using [TemplateVMs](/doc/templates/) and [SystemVMs](/doc/glossary/#systemvm) from R3.2 is not fully supported (see [#3514](https://github.com/QubesOS/qubes-issues/issues/3514)). + Instead, we recommend using the TemplateVMs that were created specifically for R4.0, which you can [customize](/doc/software-update-vm/) according to your needs. + 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. Upgrade all Template and Standalone VM(s) ----------------------------------------- -By default, in Qubes R4.0, there are few [TemplateVMs](/doc/templates/) and no [StandaloneVMs](/doc/glossary/#standalonevm). -However, users are free to create StandaloneVMs. -More information on using multiple TemplateVMs, as well as StandaloneVMs, can be found [here](/doc/software-update-vm/). -We strongly recommend that you upgrade **all** TemplateVMs and StandaloneVMs. -Please consult the guides below for specific instructions: +We strongly recommend that you update **all** TemplateVMs and StandaloneVMs before use so that you have the latest security patches from upstream distributions. +In addition, if the default templates have reached EOL (end-of-life) by the time you install R4.0, we strongly recommend that you upgrade them before use. +Please see [Supported Versions](/doc/supported-versions/) for information on supported OS versions and consult the guides below for specific upgrade instructions: * [Upgrading Fedora TemplateVMs](/doc/templates/fedora/#upgrading) * [Upgrading Debian TemplateVMs](/doc/templates/debian/#upgrading) From 6a631651d6403938cb16dc7d7388a56f8891036e Mon Sep 17 00:00:00 2001 From: awokd <34515595+awokd@users.noreply.github.com> Date: Fri, 2 Feb 2018 13:06:10 +0000 Subject: [PATCH 47/67] firewall 4.0 updates --- security/firewall.md | 43 ++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 40 insertions(+), 3 deletions(-) diff --git a/security/firewall.md b/security/firewall.md index fa908a33..8285278b 100644 --- a/security/firewall.md +++ b/security/firewall.md @@ -32,6 +32,11 @@ Manager and press the "firewall" button: ![r2b1-manager-firewall.png](/attachment/wiki/QubesFirewall/r2b1-manager-firewall.png) +*R4.0 note:* ICMP and DNS are no longer accessible in the GUI, but can be changed +via `qvm-firewall` described below. Connections to Updates Proxy are no longer made +over network so can not be allowed or blocked with firewall rules +(see [R4.0 Updates proxy](https://www.qubes-os.org/doc/software-update-vm/) for more detail. + Note that if you specify a rule by DNS name it will be resolved to IP(s) *at the moment of applying the rules*, and not on the fly for each new connection. This means it will not work for servers using load balancing. More @@ -52,7 +57,28 @@ by putting appropriate rules in `/rw/config`. See [below](#where-to-put-firewall In complex cases, it might be appropriate to load a ruleset using `iptables-restore` called from `/rw/config/rc.local`. -Reconnecting VMs after a NetVM reboot +Reconnecting VMs after a NetVM reboot (R4.0) +---------------------------------------- + +Normally Qubes doesn't let the user stop a NetVM if there are other qubes +running which use it as their own NetVM. But in case the NetVM stops for +whatever reason (e.g. it crashes, or the user forces its shutdown via qvm-kill +via terminal in Dom0), Qubes R4.0 will often automatically repair the +connection. If it does not, then there is an easy way to restore the connection to +the NetVM by issuing: + +` qvm-prefs netvm ` + +Normally qubes do not connect directly to the actual NetVM which has networking +devices, but rather to the default sys-firewall first, and in most cases it would +be the NetVM that will crash, e.g. in response to S3 sleep/restore or other +issues with WiFi drivers. In that case it is only necessary to issue the above +command once, for the sys-firewall (this assumes default VM-naming used by the +default Qubes installation): + +` qvm-prefs sys-firewall netvm sys-net ` + +Reconnecting VMs after a NetVM reboot (R3.2) ---------------------------------------- Normally Qubes doesn't let the user stop a NetVM if there are other qubes @@ -70,7 +96,7 @@ issues with WiFi drivers. In that case it is only necessary to issue the above command once, for the sys-firewall (this assumes default VM-naming used by the default Qubes installation): -` qvm-prefs sys-firewall -s netvm netvm ` +` qvm-prefs sys-firewall -s netvm sys-net ` Enabling networking between two qubes -------------------------------------- @@ -344,7 +370,18 @@ fi This time testing should allow connectivity to the service as long as the service is up :-) -Where to put firewall rules +Where to put firewall rules (R4.0) +--------------------------- + +Implicit in the above example [scripts](/doc/config-files/), but worth +calling attention to: for all qubes *except* NetVMs, iptables commands +should be added to the `/rw/config/rc.local` script. For NetVMs +(`sys-firewall` inclusive), iptables commands should be added to +`/rw/config/qubes-firewall-user-script`. This is because a NetVM is +constantly adjusting its firewall, and therefore initial settings from +`rc.local` do not persist. + +Where to put firewall rules (R3.2) --------------------------- Implicit in the above example [scripts](/doc/config-files/), but worth From 019b577b4595b27a66000f8eb34aac01dbaf0a0a Mon Sep 17 00:00:00 2001 From: awokd <34515595+awokd@users.noreply.github.com> Date: Fri, 2 Feb 2018 13:28:58 +0000 Subject: [PATCH 48/67] multifactor-authentication update fedora version and yum -> dnf --- security/multifactor-authentication.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/security/multifactor-authentication.md b/security/multifactor-authentication.md index a60b3104..20b2ce82 100644 --- a/security/multifactor-authentication.md +++ b/security/multifactor-authentication.md @@ -67,24 +67,24 @@ Optional Preparation Steps [minimal Fedora template][FedoraMinimal]. Get it if you haven't already done so: - [user@dom0 ~]$ sudo qubes-dom0-update qubes-template-fedora-25-minimal + [user@dom0 ~]$ sudo qubes-dom0-update qubes-template-fedora-26-minimal 2. Since we'll be making some modifications, you may want to clone the minimal template: - [user@dom0 ~]$ qvm-clone fedora-25-minimal fedora-25-min-mfa + [user@dom0 ~]$ qvm-clone fedora-26-minimal fedora-26-min-mfa 3. Since this is going to be a minimal environment in which we run `oathtool` from the command line, we'll install only a couple of packages: - [user@fedora-25-min-mfa ~]$ su - - [user@fedora-25-min-mfa ~]# yum install oathtool vim-minimal - [user@fedora-25-min-mfa ~]$ poweroff + [user@fedora-26-min-mfa ~]$ su - + [user@fedora-26-min-mfa ~]# dnf install oathtool vim-minimal + [user@fedora-26-min-mfa ~]$ poweroff 4. Create an AppVM and set it to use the TemplateVM we just created: [user@dom0 ~]$ qvm-create -l black mfa - [user@dom0 ~]$ qvm-prefs -s mfa template fedora-25-min-mfa + [user@dom0 ~]$ qvm-prefs -s mfa template fedora-26-min-mfa 5. Isolate the new AppVM from the network: From 1a6c777d8b2ae598484521ee34253ddd92786c4a Mon Sep 17 00:00:00 2001 From: awokd <34515595+awokd@users.noreply.github.com> Date: Fri, 2 Feb 2018 13:40:40 +0000 Subject: [PATCH 49/67] split-gpg update package utilities yum -> dnf apt-get -> apt --- security/split-gpg.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/security/split-gpg.md b/security/split-gpg.md index f519ec27..64d0b759 100644 --- a/security/split-gpg.md +++ b/security/split-gpg.md @@ -86,11 +86,11 @@ In dom0, make sure the `qubes-gpg-split-dom0` package is installed. If using templates based on Debian or Whonix, make sure you have the `qubes-gpg-split` package installed. - [user@debian-8 ~]$ sudo apt-get install qubes-gpg-split + [user@debian-8 ~]$ sudo apt install qubes-gpg-split For Fedora. - [user@fedora-25 ~]$ sudo yum install qubes-gpg-split + [user@fedora-25 ~]$ sudo dnf install qubes-gpg-split Start with creating a dedicated AppVM for storing your keys (the GPG backend domain). It is recommended that this domain be network disconnected (set its From 471696d97903ba1dadf0055b06df2299ddb2c6d1 Mon Sep 17 00:00:00 2001 From: awokd <34515595+awokd@users.noreply.github.com> Date: Fri, 2 Feb 2018 13:44:51 +0000 Subject: [PATCH 50/67] usb make headings consistent --- common-tasks/usb.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/common-tasks/usb.md b/common-tasks/usb.md index c3ef3d60..7eaef543 100644 --- a/common-tasks/usb.md +++ b/common-tasks/usb.md @@ -32,7 +32,7 @@ Qubes OS supports the ability to attach a USB drive (or just one or more of its partitions) to any qube easily, no matter which qube actually handles the USB controller. -**R4.0** +### R4.0 ### USB drive mounting is integrated into the Devices Widget. This is the tool tray icon with a yellow square located in the top right of your screen by default. @@ -108,7 +108,7 @@ follows: 7. You may now remove the device. -**R3.2** +### R3.2 ### USB drive mounting is integrated into the Qubes VM Manager GUI. Simply insert your USB drive, right-click on the desired qube in the Qubes VM Manager list, From 646aa7d5f5cf13d69ab43ee17173c3da1ba07b5f Mon Sep 17 00:00:00 2001 From: awokd <34515595+awokd@users.noreply.github.com> Date: Fri, 2 Feb 2018 15:15:06 +0000 Subject: [PATCH 51/67] Update firewall.md --- security/firewall.md | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/security/firewall.md b/security/firewall.md index 8285278b..6b9898b8 100644 --- a/security/firewall.md +++ b/security/firewall.md @@ -374,12 +374,11 @@ Where to put firewall rules (R4.0) --------------------------- Implicit in the above example [scripts](/doc/config-files/), but worth -calling attention to: for all qubes *except* NetVMs, iptables commands -should be added to the `/rw/config/rc.local` script. For NetVMs -(`sys-firewall` inclusive), iptables commands should be added to -`/rw/config/qubes-firewall-user-script`. This is because a NetVM is -constantly adjusting its firewall, and therefore initial settings from -`rc.local` do not persist. +calling attention to: for all qubes *except* AppVMs supplying networking, +iptables commands should be added to the `/rw/config/rc.local` script. For +AppVMs supplying networking (`sys-firewall` inclusive), +iptables commands should be added to +`/rw/config/qubes-firewall-user-script`. Where to put firewall rules (R3.2) --------------------------- From 2a48a90f4262a8bd453e59abe17150eb464cc2ac Mon Sep 17 00:00:00 2001 From: awokd <34515595+awokd@users.noreply.github.com> Date: Sat, 3 Feb 2018 13:23:34 +0000 Subject: [PATCH 52/67] link to deprecated /doc/torvm --- privacy/whonix.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/privacy/whonix.md b/privacy/whonix.md index d2dc9ce5..3b55bef8 100644 --- a/privacy/whonix.md +++ b/privacy/whonix.md @@ -22,6 +22,9 @@ a **"workstation"**. Qubes security architecture makes use of Whonix's isolation by using the gateway as a ProxyVM to route all network traffic through Tor, while the workstation is used for making AppVMs. +Whonix in Qubes replaces the deprecated [TorVM](/doc/torvm) service used in earlier +versions of Qubes. + ## Getting Started with Whonix * Note: To install Whonix in Qubes, you must already have a working Qubes machine. * [Installing Whonix in Qubes](/doc/whonix/install/) From 39bd80291b7b79fb52b5e9238e6c907a13a8b2a9 Mon Sep 17 00:00:00 2001 From: awokd <34515595+awokd@users.noreply.github.com> Date: Sat, 3 Feb 2018 13:25:49 +0000 Subject: [PATCH 53/67] remove deprecated TorVM from doc list --- doc.md | 1 - 1 file changed, 1 deletion(-) diff --git a/doc.md b/doc.md index 48b85b3f..154fc482 100644 --- a/doc.md +++ b/doc.md @@ -113,7 +113,6 @@ Privacy Guides * [Whonix for Privacy & Anonymity](/doc/whonix/) * [Running Tails in Qubes](/doc/tails/) * [Anonymizing your MAC Address](/doc/anonymizing-your-mac-address/) - * [TorVM](/doc/torvm/) * [Martus](/doc/martus/) * [Signal](/doc/signal/) * [Reducing the fingerprint of the text-based web browser w3m](/doc/w3m/) From 6d2f80b5003531bae8d639234301682cf88cc007 Mon Sep 17 00:00:00 2001 From: awokd <34515595+awokd@users.noreply.github.com> Date: Sat, 3 Feb 2018 13:36:52 +0000 Subject: [PATCH 54/67] add VM Settings -> Applications path --- privacy/signal.md | 1 + 1 file changed, 1 insertion(+) diff --git a/privacy/signal.md b/privacy/signal.md index 73bf1cd8..69b7fed7 100644 --- a/privacy/signal.md +++ b/privacy/signal.md @@ -51,6 +51,7 @@ Always obtain a trusted key fingerprint via other channels, and always check any 6. Create an AppVM based on this TemplateVM 7. With your mouse select the `Q` menu -> `Domain: "AppVM Name"` -> `"AppVM Name": Add more shortcuts` +(or `"AppVM Name": VM Settings` -> `Applications`). Select `Signal` from the left `Available` column, move it to the right `Selected` column by clicking the `>` button and then `OK` to apply the changes and close the window. ----- From 3d6379b968aa89bbbdaa54b8103cd6e59bbf7b8d Mon Sep 17 00:00:00 2001 From: awokd <34515595+awokd@users.noreply.github.com> Date: Sat, 3 Feb 2018 13:48:00 +0000 Subject: [PATCH 55/67] fix spelling --- configuration/w3m.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/configuration/w3m.md b/configuration/w3m.md index 9586ef40..5511adb3 100644 --- a/configuration/w3m.md +++ b/configuration/w3m.md @@ -19,7 +19,7 @@ You can reduce the [browser fingerprint](https://panopticlick.eff.org/about#brow * Set `user_agent` to `user_agent Mozilla/5.0 (Windows NT 6.1; rv:45.0) Gecko/20100101 Firefox/45.0`. - By default w3m identifies itself as `w3m/` + version number. The user agent `Mozilla/5.0 (Windows NT 6.1; rv:45.0) Gecko/20100101 Firefox/45.0` is the most common and the one used by the Tor Browser Bundle (TBB). One in fourteen browsers finderprinted by Panopticlick has this value. + By default w3m identifies itself as `w3m/` + version number. The user agent `Mozilla/5.0 (Windows NT 6.1; rv:45.0) Gecko/20100101 Firefox/45.0` is the most common and the one used by the Tor Browser Bundle (TBB). One in fourteen browsers fingerprinted by Panopticlick has this value. * Make w3m use the same HTTP_ACCEPT headers the TBB by adding the following lines at the end of the file: @@ -29,7 +29,7 @@ You can reduce the [browser fingerprint](https://panopticlick.eff.org/about#brow These changes will hide your computer's locale and some other information that may or may not be unique to the VM in which it is running. With the modifications above w3m will have the same headers as about one in fifteen browsers fingerprinted by Panopticlick. -Testing these settings on returns a fingerprint that is destinguishable from that of the TBB (with JavaScript disabled) only by 'Screen Size (CSS)' and 'Browser supports HSTS?'.\* ( does not work with w3m.) Due to the low number of w3m users it is highly likely that you will have an unique browser fingerprint among the visitors of a website using somewhat sofisticated browser fingerprinting technology. But at least your browser fingerprint will not reveal your computer's locale settings or other specifics about it in the HTTP_ACCEPT headers. And while it may be inferred from your fingerprint that you use w3m, it is not be explicitly stated in the User-Agent header. +Testing these settings on returns a fingerprint that is distinguishable from that of the TBB (with JavaScript disabled) only by 'Screen Size (CSS)' and 'Browser supports HSTS?'.\* ( does not work with w3m.) Due to the low number of w3m users it is highly likely that you will have an unique browser fingerprint among the visitors of a website using somewhat sophisticated browser fingerprinting technology. But at least your browser fingerprint will not reveal your computer's locale settings or other specifics about it in the HTTP_ACCEPT headers. And while it may be inferred from your fingerprint that you use w3m, it is not be explicitly stated in the User-Agent header. **Reminder: Do not rely on these settings for anonymity. Using w3m is all but guaranteed to make you stand out in the crowd.** From bddcd0cad29e7aa864664149eaa2c860c33ee8be Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Sat, 3 Feb 2018 14:51:06 -0600 Subject: [PATCH 56/67] Replace absolute with relative paths for Qubes URLs --- about/code-of-conduct.md | 2 +- about/faq.md | 6 +++--- basics_dev/gsoc.md | 18 +++++++++--------- basics_user/contributing.md | 2 +- building/building-archlinux-template.md | 2 +- building/qubes-builder.md | 2 +- common-tasks/dispvm.md | 2 +- configuration/resize-disk-image.md | 2 +- configuration/secondary-storage.md | 4 ++-- customization/kde.md | 2 +- customization/xfce.md | 2 +- installing/live-usb.md | 2 +- managing-os/hvm.md | 2 +- managing-os/templates/debian.md | 2 +- privacy/anonymizing-your-mac-address.md | 2 +- privacy/tails.md | 4 ++-- privacy/torvm.md | 8 ++++---- releases/3.2/release-notes.md | 4 ++-- releases/4.0/release-notes.md | 2 +- security/security-guidelines.md | 4 ++-- security/yubi-key.md | 2 +- troubleshooting/install-nvidia-driver.md | 2 +- troubleshooting/macbook-troubleshooting.md | 2 +- 23 files changed, 40 insertions(+), 40 deletions(-) diff --git a/about/code-of-conduct.md b/about/code-of-conduct.md index af4ae3fa..3925c62d 100644 --- a/about/code-of-conduct.md +++ b/about/code-of-conduct.md @@ -27,7 +27,7 @@ Examples of unacceptable behavior by participants include: - Publishing others' private information, such as a physical or electronic address, without explicit permission - Other conduct which could reasonably be considered inappropriate in a professional setting -(Please also see our [mailing list discussion guidelines](https://www.qubes-os.org/mailing-lists/#discussion-list-guidelines).) +(Please also see our [mailing list discussion guidelines](/mailing-lists/#discussion-list-guidelines).) ## Our Responsibilities diff --git a/about/faq.md b/about/faq.md index b21f41c2..e3a02b59 100644 --- a/about/faq.md +++ b/about/faq.md @@ -113,7 +113,7 @@ At the same time, due to the smart use of Xen shared memory, our GUI implementat ### Why passwordless sudo? -Please refer to [this page](https://www.qubes-os.org/doc/vm-sudo/). +Please refer to [this page](/doc/vm-sudo/). ### How should I report documentation issues? @@ -193,7 +193,7 @@ Qubes assumes that the user who controls Dom0 controls the whole system. It is very difficult to **securely** implement multi-user support. See [here](https://groups.google.com/group/qubes-devel/msg/899f6f3efc4d9a06) for details. -However, in Qubes 4.x we will be implementing management functionality. See [Admin API](https://www.qubes-os.org/news/2017/06/27/qubes-admin-api/) and [Core Stack](https://www.qubes-os.org/news/2017/10/03/core3/) for more details. +However, in Qubes 4.x we will be implementing management functionality. See [Admin API](/news/2017/06/27/qubes-admin-api/) and [Core Stack](/news/2017/10/03/core3/) for more details. ### What are the system requirements for Qubes OS? @@ -352,7 +352,7 @@ Another solution would be to set the pci_strictreset option in dom0: qvm-prefs usbVM -s pci_strictreset false These options allow the VM to ignore the error and the VM will start. -Please review the note on [this page](https://www.qubes-os.org/doc/Dom0Tools/QvmPrefs/) and be aware of the potential risk. +Please review the note on [this page](/doc/Dom0Tools/QvmPrefs/) and be aware of the potential risk. ### I assigned a PCI device to a qube, then unassigned it/shut down the qube. Why isn't the device available in dom0? diff --git a/basics_dev/gsoc.md b/basics_dev/gsoc.md index d73b0203..9ed852cc 100644 --- a/basics_dev/gsoc.md +++ b/basics_dev/gsoc.md @@ -479,7 +479,7 @@ details in [#2618](https://github.com/QubesOS/qubes-issues/issues/2618). **Brief explanation**: A long-term goal is to be able to build the entire OS and installation media in a completely bit-wise deterministic manner, but there are many baby steps to be taken along that path. See: -- "[Security challenges for the Qubes build process](https://www.qubes-os.org/news/2016/05/30/build-security/)" +- "[Security challenges for the Qubes build process](/news/2016/05/30/build-security/)" - [This mailing list post](https://groups.google.com/d/msg/qubes-devel/gq-wb9wTQV8/mdliS4P2BQAJ) - and [reproducible-builds.org](https://reproducible-builds.org/) @@ -487,7 +487,7 @@ for more information and qubes-specific background. **Expected results**: Significant progress towards making the Qubes build process deterministic. This would likely involve cooperation with and hacking on several upstream build tools to eliminate sources of variability. -**Knoledge prerequisite**: qubes-builder [[1]](https://www.qubes-os.org/doc/qubes-builder/) [[2]](https://www.qubes-os.org/doc/qubes-builder-details/) [[3]](https://github.com/QubesOS/qubes-builder/tree/master/doc), and efficient at introspecting complex systems: comfortable with tracing and debugging tools, ability to quickly identify and locate issues within a large codebase (upstream build tools), etc. +**Knoledge prerequisite**: qubes-builder [[1]](/doc/qubes-builder/) [[2]](/doc/qubes-builder-details/) [[3]](https://github.com/QubesOS/qubes-builder/tree/master/doc), and efficient at introspecting complex systems: comfortable with tracing and debugging tools, ability to quickly identify and locate issues within a large codebase (upstream build tools), etc. **Mentor**: [Marek Marczykowski-Górecki](/team/) @@ -513,17 +513,17 @@ We adapted some of the language here about GSoC from the [KDE GSoC page](https:/ [2017-archive]: https://summerofcode.withgoogle.com/archive/2017/organizations/5074771758809088/ [gsoc-qubes]: https://summerofcode.withgoogle.com/organizations/6239659689508864/ [gsoc]: https://summerofcode.withgoogle.com/ -[team]: https://www.qubes-os.org/team/ +[team]: /team/ [gsoc-faq]: https://developers.google.com/open-source/gsoc/faq -[contributing]: https://www.qubes-os.org/doc/contributing/#contributing-code -[patches]: https://www.qubes-os.org/doc/source-code/#how-to-send-patches -[code-signing]: https://www.qubes-os.org/doc/code-signing/ -[ml-devel]: https://www.qubes-os.org/mailing-lists/#qubes-devel +[contributing]: /doc/contributing/#contributing-code +[patches]: /doc/source-code/#how-to-send-patches +[code-signing]: /doc/code-signing/ +[ml-devel]: /mailing-lists/#qubes-devel [gsoc-participate]: https://developers.google.com/open-source/gsoc/ [gsoc-student]: https://developers.google.com/open-source/gsoc/resources/manual#student_manual [how-to-gsoc]: http://teom.org/blog/kde/how-to-write-a-kick-ass-proposal-for-google-summer-of-code/ [gsoc-submit]: https://summerofcode.withgoogle.com/ -[mailing-lists]: https://www.qubes-os.org/mailing-lists/ +[mailing-lists]: /mailing-lists/ [qubes-issues]: https://github.com/QubesOS/qubes-issues/issues [qubes-issues-suggested]: https://github.com/QubesOS/qubes-issues/issues?q=is%3Aissue%20is%3Aopen%20label%3A%22P%3A%20minor%22%20label%3A%22help%20wanted%22 -[qubes-builder]: https://www.qubes-os.org/doc/qubes-builder/ +[qubes-builder]: /doc/qubes-builder/ diff --git a/basics_user/contributing.md b/basics_user/contributing.md index b3e13b22..5a7568b1 100644 --- a/basics_user/contributing.md +++ b/basics_user/contributing.md @@ -75,6 +75,6 @@ be grateful to [receive your patch][patch]. [Facebook]: https://www.facebook.com/QubesOS [GitHub issues]: https://github.com/QubesOS/qubes-issues/issues [qubes-devel]: /mailing-lists/#qubes-devel -[Community-Developed Feature Tracker]: https://www.qubes-os.org/qubes-issues/ +[Community-Developed Feature Tracker]: /qubes-issues/ [Qubes download mirror]: /downloads/mirrors/ diff --git a/building/building-archlinux-template.md b/building/building-archlinux-template.md index f95186fc..ff701a4d 100644 --- a/building/building-archlinux-template.md +++ b/building/building-archlinux-template.md @@ -83,7 +83,7 @@ redirect_from: gpg --keyserver pgp.mit.edu --recv-keys 0xDDFA1A3E36879494 -* Verify its fingerprint, set as 'trusted'. [This is described here](https://www.qubes-os.org/doc/VerifyingSignatures). +* Verify its fingerprint, set as 'trusted'. [This is described here](/doc/VerifyingSignatures). * Download the Qubes developers' keys. diff --git a/building/qubes-builder.md b/building/qubes-builder.md index 8ee0172e..d5fe6e48 100644 --- a/building/qubes-builder.md +++ b/building/qubes-builder.md @@ -8,7 +8,7 @@ redirect_from: - /wiki/QubesBuilder/ --- -**Note: The build system has been improved since this how-to was last updated. The [Archlinux template building instructions](https://www.qubes-os.org/doc/building-archlinux-template/) contain more up-to-date and detailed information on how to use the build system.** +**Note: The build system has been improved since this how-to was last updated. The [Archlinux template building instructions](/doc/building-archlinux-template/) contain more up-to-date and detailed information on how to use the build system.** Building Qubes from scratch =========================== diff --git a/common-tasks/dispvm.md b/common-tasks/dispvm.md index 3dc72eaa..cda6ce0c 100644 --- a/common-tasks/dispvm.md +++ b/common-tasks/dispvm.md @@ -29,7 +29,7 @@ Thus if an AppVM uses sys-net as its NetVM, any DispVM launched from this AppVM You can change this behaviour for individual VMs: in Qubes VM Manager open VM Settings for the VM in question and go to the "Advanced" tab. Here you can edit the "NetVM for DispVM" setting to change the NetVM of any DispVM launched from that VM. -A Disposable VM launched from the Start Menu inherits the NetVM of the [DVM Template](https://www.qubes-os.org/doc/glossary/#dvm-template). +A Disposable VM launched from the Start Menu inherits the NetVM of the [DVM Template](/doc/glossary/#dvm-template). By default the DVM template is called `fedora-XX-dvm` (where `XX` is the Fedora version of the default TemplateVM). As an "internal" VM it is hidden in Qubes VM Manager, but can be shown by selecting "Show/Hide internal VMs". Note that changing the "NetVM for DispVM" setting for the DVM Template does *not* affect the NetVM of DispVMs launched from the Start Menu; only changing the DVM Template's own NetVM does. diff --git a/configuration/resize-disk-image.md b/configuration/resize-disk-image.md index 6e6b8e19..35159d7f 100644 --- a/configuration/resize-disk-image.md +++ b/configuration/resize-disk-image.md @@ -133,4 +133,4 @@ You will see that there is unallocated free space at the end of your primary dis You can use standard linux tools like fdisk and mkfs to make this space available. -[resizing the root disk image]: https://www.qubes-os.org/doc/resize-root-disk-image/ +[resizing the root disk image]: /doc/resize-root-disk-image/ diff --git a/configuration/secondary-storage.md b/configuration/secondary-storage.md index f04b6665..2c12b194 100644 --- a/configuration/secondary-storage.md +++ b/configuration/secondary-storage.md @@ -39,7 +39,7 @@ Known Issues dom0.) Do not attempt to detach these disks. (They will automatically be detached when you shut down the AppVM.) [[2]] -[Qubes Backup]: https://www.qubes-os.org/doc/BackupRestore/ -[TemplateVM]: https://www.qubes-os.org/doc/Templates/ +[Qubes Backup]: /doc/BackupRestore/ +[TemplateVM]: /doc/Templates/ [1]: https://groups.google.com/d/topic/qubes-users/EITd1kBHD30/discussion [2]: https://groups.google.com/d/topic/qubes-users/nDrOM7dzLNE/discussion diff --git a/customization/kde.md b/customization/kde.md index cee094a6..f0df5598 100644 --- a/customization/kde.md +++ b/customization/kde.md @@ -12,7 +12,7 @@ Installation ------------ Prior to R3.2, KDE was the default desktop environment in Qubes. Beginning with -R3.2, however, [XFCE is the new default desktop environment](https://www.qubes-os.org/doc/releases/3.2/release-notes/). Nonetheless, it is +R3.2, however, [XFCE is the new default desktop environment](/doc/releases/3.2/release-notes/). Nonetheless, it is still possible to install KDE by issuing this command in dom0: $ sudo qubes-dom0-update @kde-desktop-qubes diff --git a/customization/xfce.md b/customization/xfce.md index 64eb5c53..f9c8de96 100644 --- a/customization/xfce.md +++ b/customization/xfce.md @@ -15,7 +15,7 @@ XFCE installation in dom0 **Disclaimer: The article is obsolete for Qubes OS 3.2 and later.** Prior to R3.2, KDE was the default desktop environment in Qubes. Beginning with -R3.2 [XFCE is the new default desktop environment](https://www.qubes-os.org/doc/releases/3.2/release-notes/) and does not require manual installation. +R3.2 [XFCE is the new default desktop environment](/doc/releases/3.2/release-notes/) and does not require manual installation. Installation: diff --git a/installing/live-usb.md b/installing/live-usb.md index a4d3e9a4..43f499b4 100644 --- a/installing/live-usb.md +++ b/installing/live-usb.md @@ -121,5 +121,5 @@ Downloading and burning and `of` or specify an incorrect device, you could accidentally overwrite your primary system drive. Please be careful! -[project-page]: https://www.qubes-os.org/gsoc/ +[project-page]: /gsoc/ [gsoc-page]: https://summerofcode.withgoogle.com/organizations/6239659689508864/ diff --git a/managing-os/hvm.md b/managing-os/hvm.md index fc095ce2..1632a84d 100644 --- a/managing-os/hvm.md +++ b/managing-os/hvm.md @@ -23,7 +23,7 @@ to learn why it took so long for Qubes OS to support HVM domains (Qubes 1 only supported Linux based PV domains). As of Qubes 4, every VM is PVH by default, except those with attached PCI devices which are HVM. [See here](https://blog.invisiblethings.org/2017/07/31/qubes-40-rc1.html) for a discussion -of the switch to HVM from R3.2's PV, and [here](https://www.qubes-os.org/news/2018/01/11/qsb-37/) +of the switch to HVM from R3.2's PV, and [here](/news/2018/01/11/qsb-37/) for changing the default to PVH. Creating an HVM domain diff --git a/managing-os/templates/debian.md b/managing-os/templates/debian.md index d83fdc61..94bf1b22 100644 --- a/managing-os/templates/debian.md +++ b/managing-os/templates/debian.md @@ -114,5 +114,5 @@ More information * [Debian wiki](https://wiki.debian.org/Qubes) -[stretch]: https://www.qubes-os.org/doc/template/debian/upgrade-8-to-9/ +[stretch]: /doc/template/debian/upgrade-8-to-9/ diff --git a/privacy/anonymizing-your-mac-address.md b/privacy/anonymizing-your-mac-address.md index 3e7f0921..3dfb3783 100644 --- a/privacy/anonymizing-your-mac-address.md +++ b/privacy/anonymizing-your-mac-address.md @@ -16,7 +16,7 @@ privacy](https://tails.boum.org/contribute/design/MAC_address/#index1h1). Curren Newer versions of Network Manager have a robust set of options for randomizing MAC addresses, and can handle the entire process across reboots, sleep/wake cycles and different connection states. In particular, versions 1.4.2 and later should be well suited for Qubes. -Network Manager 1.4.2 or later is available from the Fedora 25 repository as well as the Debian 9 repository, which you can install by [upgrading a Debian 8 template to version 9.](https://www.qubes-os.org/doc/debian-template-upgrade-8/) +Network Manager 1.4.2 or later is available from the Fedora 25 repository as well as the Debian 9 repository, which you can install by [upgrading a Debian 8 template to version 9.](/doc/debian-template-upgrade-8/) In the Debian 9 or Fedora 25 template you intend to use as a NetVM, check that Network Manager version is now at least 1.4.2: diff --git a/privacy/tails.md b/privacy/tails.md index 76136479..646b4ffd 100644 --- a/privacy/tails.md +++ b/privacy/tails.md @@ -16,7 +16,7 @@ Despite this, in case that method becomes cumbersome, Tails can be used inside v To run Tails under Qubes: -1. Read about [creating and using HVM qubes](https://www.qubes-os.org/doc/hvm/) +1. Read about [creating and using HVM qubes](/doc/hvm/) 2. Download and verify Tails from [https://tails.boum.org](https://tails.boum.org) in a qube, (saved as `/home/user/Downloads/tails.iso` on qube "isoVM" for purposes of this guide). @@ -76,7 +76,7 @@ The Tails qube will not shut down cleanly. Kill it from the GUI Manager or ```qvm-kill Tails``` in Konsole. ### Security -You will probably want to implement [MAC spoofing](https://www.qubes-os.org/doc/anonymizing-your-mac-address/). +You will probably want to implement [MAC spoofing](/doc/anonymizing-your-mac-address/). There are added security concerns for Tails users when running it in a virtual machine. If you intend to do this, you should read [the warnings](https://tails.boum.org/doc/advanced_topics/virtualization/) from the Tails team about it. diff --git a/privacy/torvm.md b/privacy/torvm.md index bb1ddf13..d04de0f1 100644 --- a/privacy/torvm.md +++ b/privacy/torvm.md @@ -20,7 +20,7 @@ Qubes TorVM (qubes-tor) Qubes TorVM is a deprecated ProxyVM service that provides torified networking to all its clients. **If you are interested in TorVM, you will find the -[Whonix implementation in Qubes](https://www.qubes-os.org/doc/privacy/whonix/) a +[Whonix implementation in Qubes](/doc/privacy/whonix/) a more usable and robust solution for creating a torifying traffic proxy.** By default, any AppVM using the TorVM as its NetVM will be fully torified, so @@ -273,9 +273,9 @@ transparent torified solutions. Notably the following: [stream-isolation]: https://gitweb.torproject.org/torspec.git/blob/HEAD:/proposals/171-separate-streams.txt [stream-isolation-explained]: https://lists.torproject.org/pipermail/tor-talk/2012-May/024403.html [tor-threats]: https://www.torproject.org/projects/torbrowser/design/#adversary -[qubes-net]: https://www.qubes-os.org/doc/QubesNet/ +[qubes-net]: /doc/QubesNet/ [dns]: https://tails.boum.org/todo/support_arbitrary_dns_queries/ [tor-browser]: https://www.torproject.org/download/download-easy.html [tor-verify-sig]: https://www.torproject.org/docs/verifying-signatures.html -[dispvm]: https://www.qubes-os.org/doc/DisposableVms/ -[dispvm-customization]: https://www.qubes-os.org/doc/UserDoc/DispVMCustomization/ +[dispvm]: /doc/DisposableVms/ +[dispvm-customization]: /doc/UserDoc/DispVMCustomization/ diff --git a/releases/3.2/release-notes.md b/releases/3.2/release-notes.md index 7a083562..623936c9 100644 --- a/releases/3.2/release-notes.md +++ b/releases/3.2/release-notes.md @@ -24,7 +24,7 @@ You can get detailed description in [completed github issues][github-release-not Known issues ------------ -* [Fedora 23 reached EOL in December 2016](https://fedoraproject.org/wiki/End_of_life). There is a [manual procedure to upgrade your VMs](https://www.qubes-os.org/news/2016/11/15/fedora-24-template-available/). +* [Fedora 23 reached EOL in December 2016](https://fedoraproject.org/wiki/End_of_life). There is a [manual procedure to upgrade your VMs](/news/2016/11/15/fedora-24-template-available/). * Windows Tools: `qvm-block` does not work @@ -43,7 +43,7 @@ Installation instructions ------------------------- See [Installation Guide](/doc/installation-guide/). -After installation, [manually upgrade to Fedora 24](https://www.qubes-os.org/news/2016/11/15/fedora-24-template-available/). +After installation, [manually upgrade to Fedora 24](/news/2016/11/15/fedora-24-template-available/). Upgrading --------- diff --git a/releases/4.0/release-notes.md b/releases/4.0/release-notes.md index 8119b4b7..fedfde6c 100644 --- a/releases/4.0/release-notes.md +++ b/releases/4.0/release-notes.md @@ -78,4 +78,4 @@ We also provide [detailed instruction][upgrade-to-r4.0] for this procedure. [qsb-24]: https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-024-2016.txt [backup-format]: /doc/backup-emergency-restore-v4/ [api-doc]: https://dev.qubes-os.org/projects/qubes-core-admin/en/latest/ -[upgrade-to-r4.0]: https://www.qubes-os.org/doc/upgrade-to-r4.0/ +[upgrade-to-r4.0]: /doc/upgrade-to-r4.0/ diff --git a/security/security-guidelines.md b/security/security-guidelines.md index 1d143600..a1ec0d96 100644 --- a/security/security-guidelines.md +++ b/security/security-guidelines.md @@ -27,7 +27,7 @@ While your connection to the Qubes website and download mirrors is encrypted, me Signature verification allows us to validate for ourselves that these files were the ones authored and signed by their creators (in this case the Qubes development team). Because it's so easy for a hacker who manages to tamper with the downloaded iso files this way to patch in malware, it is of the utmost importance that you **verify the signature of the Qubes iso** you use to install Qubes. -See the page on [Verifying Signatures](https://www.qubes-os.org/security/verifying-signatures/) for more information and a tutorial on how to accomplish this. +See the page on [Verifying Signatures](/security/verifying-signatures/) for more information and a tutorial on how to accomplish this. Once you have Qubes installed, the standard program installation command for Fedora and Qubes repositories @@ -79,7 +79,7 @@ qubes-hcl-report where \ is the name of the VM within which the report will be written (but the report will also be displayed in the Dom0 terminal). If it displays that VT-d is active, you should be able to assign **PCIe devices to an HVM** and **enjoy DMA protection** for your driver domains, so you successfully passed this step. -If VT-d is not active, attempt to activate it by selecting the **VT-d flag** within the BIOS settings. If your processor/BIOS does not allow VT-d activation you still enjoy much better security than alternative systems, but you may be vulnerable to **DMA attacks**. Next time you buy a computer consult our **[HCL (Hardware Compatibility List)](https://www.qubes-os.org/hcl/)** and possibly contribute to it. +If VT-d is not active, attempt to activate it by selecting the **VT-d flag** within the BIOS settings. If your processor/BIOS does not allow VT-d activation you still enjoy much better security than alternative systems, but you may be vulnerable to **DMA attacks**. Next time you buy a computer consult our **[HCL (Hardware Compatibility List)](/hcl/)** and possibly contribute to it. Updating Software ----------------- diff --git a/security/yubi-key.md b/security/yubi-key.md index 7ec45fcb..9cc6ad03 100644 --- a/security/yubi-key.md +++ b/security/yubi-key.md @@ -11,7 +11,7 @@ Using YubiKey to Qubes authentication ===================================== You can use YubiKey to enhance Qubes user authentication, for example to mitigate -risk of snooping the password. This can also slightly improve security when you have [USB keyboard](https://www.qubes-os.org/doc/usb/#security-warning-about-usb-input-devices). +risk of snooping the password. This can also slightly improve security when you have [USB keyboard](/doc/usb/#security-warning-about-usb-input-devices). There (at least) two possible configurations: using OTP mode and using challenge-response mode. diff --git a/troubleshooting/install-nvidia-driver.md b/troubleshooting/install-nvidia-driver.md index f3b946e5..d52c79d7 100644 --- a/troubleshooting/install-nvidia-driver.md +++ b/troubleshooting/install-nvidia-driver.md @@ -21,7 +21,7 @@ Support for newer cards is limited until AMDGPU support in the 4.5+ kernel, whic Built in Intel graphics, Radeon graphics (between that 4000-9000 range), and perhaps some prebaked NVIDIA card support that i don't know about. Those are your best bet for great Qubes support. If you do happen to get proprietary drivers working on your Qubes system (via installing them). Please take the time to go to the -[Hardware Compatibility List (HCL)](https://www.qubes-os.org/doc/hcl/#generating-and-submitting-new-reports ) +[Hardware Compatibility List (HCL)](/doc/hcl/#generating-and-submitting-new-reports ) Add your computer, graphics card, and installation steps you did to get everything working. ## RpmFusion packages diff --git a/troubleshooting/macbook-troubleshooting.md b/troubleshooting/macbook-troubleshooting.md index b7f53c71..5e1d144f 100644 --- a/troubleshooting/macbook-troubleshooting.md +++ b/troubleshooting/macbook-troubleshooting.md @@ -135,7 +135,7 @@ Please see [this thread o the qubes-devel mailing list][macbook-air-2012-5-1]. [1]: https://github.com/QubesOS/qubes-issues/issues/794 [2]: https://github.com/QubesOS/qubes-issues/issues/1261 -[3]: https://www.qubes-os.org/doc/assigning-devices/ +[3]: /doc/assigning-devices/ [bluetooth-replacement]: https://www.ifixit.com/Guide/MacBook+Air+13-Inch+Mid+2011+AirPort-Bluetooth+Card+Replacement/6360 [macbook-air-2012-5-1]: https://groups.google.com/d/topic/qubes-devel/uLDYGdKk_Dk/discussion From 0c29e05f3ded851c0e6acb894dcbc33318277d31 Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Sat, 3 Feb 2018 15:08:05 -0600 Subject: [PATCH 57/67] Update Markdown Conventions - Add convention for using relative rather than absolute paths - Follow the convention to insert a newline at the end of each sentence - Note the class of exceptions to the aforementioned convention --- basics_user/doc-guidelines.md | 33 ++++++++++++++++++--------------- 1 file changed, 18 insertions(+), 15 deletions(-) diff --git a/basics_user/doc-guidelines.md b/basics_user/doc-guidelines.md index 2c34e0c4..27869f28 100644 --- a/basics_user/doc-guidelines.md +++ b/basics_user/doc-guidelines.md @@ -146,25 +146,25 @@ Style Guidelines Markdown Conventions -------------------- -All the documentation is written in Markdown for maximum accessibility. When -making contributions, please try to observe the following style conventions: +All the documentation is written in Markdown for maximum accessibility. +When making contributions, please try to observe the following style conventions: * Use spaces instead of tabs. - * Insert a newline at the end of each sentence. - * Rationale: This practice is most appropriate for source that consists - primarily of natural language text. It results in the most useful diffs - and facilitates translation into other languages while mostly preserving - source readability. - * If appropriate, make numerals in numbered lists match between Markdown - source and HTML output. - * Rationale: In the event that a user is required to read the Markdown source - directly, this will make it easier to follow, e.g., numbered steps in a set - of instructions. + * In order to enable offline browsing, use relative paths (e.g., `/doc/doc-guidelines/` instead of `https://www.qubes-os.org/doc/doc-guidelines/`, except when the source text will be reproduced outside of the Qubes website repo. + Examples of exceptions: + * [QSBs] (intended to be read as plain text) + * [News] posts (plain text is reproduced on the [mailing lists]) + * URLs that appear inside code blocks (e.g., in comments and document templates) + * Files like `README.md` and `CONTRIBUTING.md` + * Insert a newline at the end of each sentence, except when the text will be reproduced outside of the Qubes website repo (see previous item for examples). + * Rationale: This practice is most appropriate for source that consists primarily of natural language text. + It results in the most useful diffs and facilitates translation into other languages while mostly preserving source readability. + * If appropriate, make numerals in numbered lists match between Markdown source and HTML output. + * Rationale: In the event that a user is required to read the Markdown source directly, this will make it easier to follow, e.g., numbered steps in a set of instructions. * Use hanging indentations where appropriate. - * Use underline headings (`=====` and `-----`) if possible. If this is not - possible, use Atx-style headings on both the left and right sides - (`### H3 ###`). + * Use underline headings (`=====` and `-----`) if possible. + If this is not possible, use Atx-style headings on both the left and right sides (`### H3 ###`). * Use `[reference-style][ref]` links. `[ref]: https://daringfireball.net/projects/markdown/syntax#link` @@ -188,5 +188,8 @@ Please try to write good commit messages, according to the [gh-pull]: https://help.github.com/articles/using-pull-requests/ [GitHub]: https://github.com/ [mailing lists]: /mailing-lists/ +[QSBs]: /security/bulletins/ +[News]: /news/ [md]: https://daringfireball.net/projects/markdown/ [git-commit]: /doc/coding-style/#commit-message-guidelines + From 550e23b266757675bfa1fa3b84d16c3326193939 Mon Sep 17 00:00:00 2001 From: awokd <34515595+awokd@users.noreply.github.com> Date: Sun, 4 Feb 2018 15:18:20 +0000 Subject: [PATCH 58/67] yum -> dnf --- configuration/postfix.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/configuration/postfix.md b/configuration/postfix.md index 0bde2398..14d86a93 100644 --- a/configuration/postfix.md +++ b/configuration/postfix.md @@ -16,11 +16,11 @@ Postfix is full featured MTA (Message Transfer Agent). Here we will configure it Installation ------------ -`yum install postfix procmail make cyrus-sasl cyrus-sasl-plain` +`dnf install postfix procmail make cyrus-sasl cyrus-sasl-plain` Cyrus-sasl is installed to authenticate to remote servers. Procmail is not strictly necessary, but is useful to sort your incoming mail, for example to put each mailing list in its own directory. Make is also not necessary, but is used to keep Postfix lookup tables. -You should also check `alternatives` command, to see if it is the default `mta`. It probably is not. You may need to `yum remove ssmtp` or something +You should also check `alternatives` command, to see if it is the default `mta`. It probably is not. You may need to `dnf remove ssmtp` or something Configuration ------------- From 7b1b113bb9babac22acf00340b66703b1c7e06a6 Mon Sep 17 00:00:00 2001 From: awokd <34515595+awokd@users.noreply.github.com> Date: Sun, 4 Feb 2018 15:20:42 +0000 Subject: [PATCH 59/67] yum -> dnf --- configuration/fetchmail.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/configuration/fetchmail.md b/configuration/fetchmail.md index 0bdd128e..25bd4ab6 100644 --- a/configuration/fetchmail.md +++ b/configuration/fetchmail.md @@ -16,7 +16,7 @@ Fetchmail is standalone MRA (Mail Retrieval Agent) aka "IMAP/POP3 client". Its s Installation ------------ -`yum install fetchmail` +`dnf install fetchmail` Configuration ------------- From 84c626986d859f1f67181d42def4076dfb15c22f Mon Sep 17 00:00:00 2001 From: awokd <34515595+awokd@users.noreply.github.com> Date: Sun, 4 Feb 2018 18:02:12 +0000 Subject: [PATCH 60/67] add links to /doc/assigning-devices and fix qvm-pci attach long options --- about/faq.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/about/faq.md b/about/faq.md index e3a02b59..3f633494 100644 --- a/about/faq.md +++ b/about/faq.md @@ -345,14 +345,14 @@ Another solution would be to set the pci_strictreset option in dom0: - In Qubes R4.x, when attaching the PCI device to the VM (where `` can be obtained from running [qvm-pci](/doc/dom0-tools/qvm-pci/)): - qvm-pci attach -persistent -option no-strict-reset=true usbVM dom0: + qvm-pci attach --persistent --option no-strict-reset=true usbVM dom0: - In Qubes R3.x, by modifying the VM's properties: qvm-prefs usbVM -s pci_strictreset false These options allow the VM to ignore the error and the VM will start. -Please review the note on [this page](/doc/Dom0Tools/QvmPrefs/) and be aware of the potential risk. +Please review the notes on [this page](/doc/Dom0Tools/QvmPrefs/) and [here](/doc/assigning-devices/) and be aware of the potential risks. ### I assigned a PCI device to a qube, then unassigned it/shut down the qube. Why isn't the device available in dom0? @@ -371,6 +371,8 @@ or MOD=`modprobe -R $MODALIAS | head -n 1` echo 0000: > /sys/bus/pci/drivers/$MOD/bind +See also [here](/doc/assigning-devices/). + ### How do I install Flash in a Debian qube? The Debian way is to install the flashplugin-nonfree package. From d6e48fd63aaeadb9c5c96275262aeda7a77b6c22 Mon Sep 17 00:00:00 2001 From: awokd <34515595+awokd@users.noreply.github.com> Date: Sun, 4 Feb 2018 18:17:23 +0000 Subject: [PATCH 61/67] use correct term for Devices Widget --- about/faq.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/about/faq.md b/about/faq.md index 3f633494..556bfbae 100644 --- a/about/faq.md +++ b/about/faq.md @@ -415,7 +415,7 @@ For Fedora: The recommended approach is to pass only the specific partition you intend to use from [`sys-usb`](/doc/usb/) to another qube via [qvm-block](/doc/dom0-tools/qvm-block/). They will show up in the destination qube as `/dev/xvd*` and must be mounted manually. Another approach is to attach the entire USB drive to your destination qube. However, this could theoretically lead to an attack because it forces the destination qube to parse the device's partition table. If you believe your device is safe, you may proceed to attach it. -In Qubes 4.0, this is accomplished with the widget located in the tool tray (default top right corner, look for an icon with a yellow square). From the top part of the list, click on the drive you want to attach, then select the qube to attach it to. Although you can also attach the entire USB device to a qube by selecting it from the bottom part of the list, in general this approach should not be used because you are exposing the target qube to unnecessary additional attack surface. +In Qubes 4.0, this is accomplished with the Devices Widget located in the tool tray (default top right corner, look for an icon with a yellow square). From the top part of the list, click on the drive you want to attach, then select the qube to attach it to. Although you can also attach the entire USB device to a qube by selecting it from the bottom part of the list, in general this approach should not be used because you are exposing the target qube to unnecessary additional attack surface. In Qubes 3.2, you can use the Qubes VM Manager. Simply insert your USB drive, right-click on the desired qube in the Qubes VM Manager list, click Attach/detach block devices, and select your desired action and device. From 35b02c848cff6ca1786a9b9241c1fca8c73fbd9c Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Sun, 4 Feb 2018 17:32:30 -0600 Subject: [PATCH 62/67] Reorganize and update CLI tool references pages for 4.0 Requested by: QubesOS/qubes-issues#3495 Requests: QubesOS/qubes-issues#3538 --- doc.md | 6 ++- reference/dom0-tools.md | 37 ------------------ reference/tools.md | 13 +++++++ reference/tools/3.2/dom0.md | 39 +++++++++++++++++++ .../3.2/dom0}/qubes-dom0-update.md | 3 +- .../3.2/dom0}/qubes-prefs.md | 3 +- .../3.2/dom0}/qvm-add-appvm.md | 3 +- .../3.2/dom0}/qvm-add-template.md | 3 +- .../3.2/dom0}/qvm-backup-restore.md | 3 +- .../3.2/dom0}/qvm-backup.md | 3 +- .../3.2/dom0}/qvm-block.md | 4 +- .../3.2/dom0}/qvm-clone.md | 3 +- .../3.2/dom0}/qvm-create-default-dvm.md | 3 +- .../3.2/dom0}/qvm-create.md | 3 +- .../3.2/dom0}/qvm-firewall.md | 3 +- .../3.2/dom0}/qvm-grow-private.md | 3 +- .../3.2/dom0}/qvm-kill.md | 3 +- .../{dom0-tools => tools/3.2/dom0}/qvm-ls.md | 3 +- .../{dom0-tools => tools/3.2/dom0}/qvm-pci.md | 3 +- .../3.2/dom0}/qvm-prefs.md | 3 +- .../3.2/dom0}/qvm-remove.md | 3 +- .../3.2/dom0}/qvm-revert-template-changes.md | 3 +- .../{dom0-tools => tools/3.2/dom0}/qvm-run.md | 3 +- .../3.2/dom0}/qvm-service.md | 3 +- .../3.2/dom0}/qvm-shutdown.md | 3 +- .../3.2/dom0}/qvm-start.md | 3 +- .../3.2/dom0}/qvm-sync-appmenus.md | 3 +- .../3.2/dom0}/qvm-template-commit.md | 3 +- reference/tools/3.2/domU.md | 19 +++++++++ .../3.2/domU}/qvm-copy-to-vm.md | 3 +- .../3.2/domU}/qvm-open-in-dvm.md | 3 +- .../3.2/domU}/qvm-open-in-vm.md | 3 +- .../{vm-tools => tools/3.2/domU}/qvm-run.md | 3 +- reference/tools/4.0/dom0.md | 14 +++++++ reference/tools/4.0/domU.md | 14 +++++++ reference/tools/tools-3.2.md | 13 +++++++ reference/tools/tools-4.0.md | 13 +++++++ reference/vm-tools.md | 17 -------- 38 files changed, 186 insertions(+), 84 deletions(-) delete mode 100644 reference/dom0-tools.md create mode 100644 reference/tools.md create mode 100644 reference/tools/3.2/dom0.md rename reference/{dom0-tools => tools/3.2/dom0}/qubes-dom0-update.md (92%) rename reference/{dom0-tools => tools/3.2/dom0}/qubes-prefs.md (88%) rename reference/{dom0-tools => tools/3.2/dom0}/qvm-add-appvm.md (91%) rename reference/{dom0-tools => tools/3.2/dom0}/qvm-add-template.md (90%) rename reference/{dom0-tools => tools/3.2/dom0}/qvm-backup-restore.md (94%) rename reference/{dom0-tools => tools/3.2/dom0}/qvm-backup.md (89%) rename reference/{dom0-tools => tools/3.2/dom0}/qvm-block.md (90%) rename reference/{dom0-tools => tools/3.2/dom0}/qvm-clone.md (90%) rename reference/{dom0-tools => tools/3.2/dom0}/qvm-create-default-dvm.md (92%) rename reference/{dom0-tools => tools/3.2/dom0}/qvm-create.md (95%) rename reference/{dom0-tools => tools/3.2/dom0}/qvm-firewall.md (94%) rename reference/{dom0-tools => tools/3.2/dom0}/qvm-grow-private.md (87%) rename reference/{dom0-tools => tools/3.2/dom0}/qvm-kill.md (88%) rename reference/{dom0-tools => tools/3.2/dom0}/qvm-ls.md (93%) rename reference/{dom0-tools => tools/3.2/dom0}/qvm-pci.md (92%) rename reference/{dom0-tools => tools/3.2/dom0}/qvm-prefs.md (99%) rename reference/{dom0-tools => tools/3.2/dom0}/qvm-remove.md (90%) rename reference/{dom0-tools => tools/3.2/dom0}/qvm-revert-template-changes.md (86%) rename reference/{dom0-tools => tools/3.2/dom0}/qvm-run.md (95%) rename reference/{dom0-tools => tools/3.2/dom0}/qvm-service.md (98%) rename reference/{dom0-tools => tools/3.2/dom0}/qvm-shutdown.md (91%) rename reference/{dom0-tools => tools/3.2/dom0}/qvm-start.md (91%) rename reference/{dom0-tools => tools/3.2/dom0}/qvm-sync-appmenus.md (88%) rename reference/{dom0-tools => tools/3.2/dom0}/qvm-template-commit.md (86%) create mode 100644 reference/tools/3.2/domU.md rename reference/{vm-tools => tools/3.2/domU}/qvm-copy-to-vm.md (88%) rename reference/{vm-tools => tools/3.2/domU}/qvm-open-in-dvm.md (86%) rename reference/{vm-tools => tools/3.2/domU}/qvm-open-in-vm.md (86%) rename reference/{vm-tools => tools/3.2/domU}/qvm-run.md (89%) create mode 100644 reference/tools/4.0/dom0.md create mode 100644 reference/tools/4.0/domU.md create mode 100644 reference/tools/tools-3.2.md create mode 100644 reference/tools/tools-4.0.md delete mode 100644 reference/vm-tools.md diff --git a/doc.md b/doc.md index 154fc482..08ddea76 100644 --- a/doc.md +++ b/doc.md @@ -176,8 +176,10 @@ Troubleshooting Reference Pages --------------- - * [Dom0 Command-Line Tools](/doc/dom0-tools/) - * [DomU Command-Line Tools](/doc/vm-tools/) + * [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/) + * [Command-Line Tools: Qubes 4.0, domU](/doc/tools/4.0/domU/) * [Glossary of Qubes Terminology](/doc/glossary/) * [Qubes Service Framework](/doc/qubes-service/) * [Command Execution in VMs (and Qubes RPC)](/doc/qrexec/) diff --git a/reference/dom0-tools.md b/reference/dom0-tools.md deleted file mode 100644 index 458ec2ab..00000000 --- a/reference/dom0-tools.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -layout: doc -title: Dom0 Tools -permalink: /doc/dom0-tools/ -redirect_from: -- /en/doc/dom0-tools/ -- /doc/DomZeroTools/ -- /wiki/DomZeroTools/ ---- - -QVM-tools: - -- [qubes-dom0-update](/doc/dom0-tools/qubes-dom0-update/) -- [qubes-prefs](/doc/dom0-tools/qubes-prefs/) -- [qvm-add-appvm](/doc/dom0-tools/qvm-add-appvm/) -- [qvm-add-template](/doc/dom0-tools/qvm-add-template/) -- [qvm-backup-restore](/doc/dom0-tools/qvm-backup-restore/) -- [qvm-backup](/doc/dom0-tools/qvm-backup/) -- [qvm-block](/doc/dom0-tools/qvm-block/) -- [qvm-clone](/doc/dom0-tools/qvm-clone/) -- [qvm-create-default-dvm](/doc/dom0-tools/qvm-create-default-dvm/) -- [qvm-create](/doc/dom0-tools/qvm-create/) -- [qvm-firewall](/doc/dom0-tools/qvm-firewall/) -- [qvm-grow-private](/doc/dom0-tools/qvm-grow-private/) -- [qvm-ls](/doc/dom0-tools/qvm-ls/) -- [qvm-kill](/doc/dom0-tools/qvm-kill/) -- [qvm-pci](/doc/dom0-tools/qvm-pci/) -- [qvm-prefs](/doc/dom0-tools/qvm-prefs/) -- [qvm-remove](/doc/dom0-tools/qvm-remove/) -- [qvm-revert-template-changes](/doc/dom0-tools/qvm-revert-template-changes/) -- [qvm-run](/doc/dom0-tools/qvm-run/) -- [qvm-service](/doc/dom0-tools/qvm-service/) -- [qvm-shutdown](/doc/dom0-tools/qvm-shutdown/) -- [qvm-start](/doc/dom0-tools/qvm-start/) -- [qvm-sync-appmenus](/doc/dom0-tools/qvm-sync-appmenus/) -- [qvm-template-commit](/doc/dom0-tools/qvm-template-commit/) - diff --git a/reference/tools.md b/reference/tools.md new file mode 100644 index 00000000..5febc899 --- /dev/null +++ b/reference/tools.md @@ -0,0 +1,13 @@ +--- +layout: doc +title: Command-Line Tools +permalink: /doc/tools/ +--- + +Command-Line Tools +================== + +Please see the page for your version of Qubes OS: + + * [Qubes 4.0 Command-Line Tools](/doc/tools/4.0) + * [Qubes 3.2 Command-Line Tools](/doc/tools/3.2) diff --git a/reference/tools/3.2/dom0.md b/reference/tools/3.2/dom0.md new file mode 100644 index 00000000..331c0754 --- /dev/null +++ b/reference/tools/3.2/dom0.md @@ -0,0 +1,39 @@ +--- +layout: doc +title: Dom0 Command-Line Tools for Qubes 3.2 +permalink: /doc/tools/3.2/dom0/ +redirect_from: +- /doc/tools/3.2/dom0/ +- /en/doc/tools/3.2/dom0/ +- /doc/DomZeroTools/ +- /wiki/DomZeroTools/ +--- + +Dom0 Command-Line Tools for Qubes 3.2 +===================================== + + * [qubes-dom0-update](/doc/tools/3.2/dom0/qubes-dom0-update/) + * [qubes-prefs](/doc/tools/3.2/dom0/qubes-prefs/) + * [qvm-add-appvm](/doc/tools/3.2/dom0/qvm-add-appvm/) + * [qvm-add-template](/doc/tools/3.2/dom0/qvm-add-template/) + * [qvm-backup-restore](/doc/tools/3.2/dom0/qvm-backup-restore/) + * [qvm-backup](/doc/tools/3.2/dom0/qvm-backup/) + * [qvm-block](/doc/tools/3.2/dom0/qvm-block/) + * [qvm-clone](/doc/tools/3.2/dom0/qvm-clone/) + * [qvm-create-default-dvm](/doc/tools/3.2/dom0/qvm-create-default-dvm/) + * [qvm-create](/doc/tools/3.2/dom0/qvm-create/) + * [qvm-firewall](/doc/tools/3.2/dom0/qvm-firewall/) + * [qvm-grow-private](/doc/tools/3.2/dom0/qvm-grow-private/) + * [qvm-ls](/doc/tools/3.2/dom0/qvm-ls/) + * [qvm-kill](/doc/tools/3.2/dom0/qvm-kill/) + * [qvm-pci](/doc/tools/3.2/dom0/qvm-pci/) + * [qvm-prefs](/doc/tools/3.2/dom0/qvm-prefs/) + * [qvm-remove](/doc/tools/3.2/dom0/qvm-remove/) + * [qvm-revert-template-changes](/doc/tools/3.2/dom0/qvm-revert-template-changes/) + * [qvm-run](/doc/tools/3.2/dom0/qvm-run/) + * [qvm-service](/doc/tools/3.2/dom0/qvm-service/) + * [qvm-shutdown](/doc/tools/3.2/dom0/qvm-shutdown/) + * [qvm-start](/doc/tools/3.2/dom0/qvm-start/) + * [qvm-sync-appmenus](/doc/tools/3.2/dom0/qvm-sync-appmenus/) + * [qvm-template-commit](/doc/tools/3.2/dom0/qvm-template-commit/) + diff --git a/reference/dom0-tools/qubes-dom0-update.md b/reference/tools/3.2/dom0/qubes-dom0-update.md similarity index 92% rename from reference/dom0-tools/qubes-dom0-update.md rename to reference/tools/3.2/dom0/qubes-dom0-update.md index 03e3673e..97def7e6 100644 --- a/reference/dom0-tools/qubes-dom0-update.md +++ b/reference/tools/3.2/dom0/qubes-dom0-update.md @@ -1,8 +1,9 @@ --- layout: doc title: qubes-dom0-update -permalink: /doc/dom0-tools/qubes-dom0-update/ +permalink: /doc/tools/3.2/dom0/qubes-dom0-update/ redirect_from: +- /doc/dom0-tools/qubes-dom0-update/ - /en/doc/dom0-tools/qubes-dom0-update/ - /doc/Dom0Tools/QubesDom0Update/ - /wiki/Dom0Tools/QubesDom0Update/ diff --git a/reference/dom0-tools/qubes-prefs.md b/reference/tools/3.2/dom0/qubes-prefs.md similarity index 88% rename from reference/dom0-tools/qubes-prefs.md rename to reference/tools/3.2/dom0/qubes-prefs.md index fe19f160..5368466f 100644 --- a/reference/dom0-tools/qubes-prefs.md +++ b/reference/tools/3.2/dom0/qubes-prefs.md @@ -1,8 +1,9 @@ --- layout: doc title: qubes-prefs -permalink: /doc/dom0-tools/qubes-prefs/ +permalink: /doc/tools/3.2/dom0/qubes-prefs/ redirect_from: +- /doc/dom0-tools/qubes-prefs/ - /en/doc/dom0-tools/qubes-prefs/ - /doc/Dom0Tools/QubesPrefs/ - /wiki/Dom0Tools/QubesPrefs/ diff --git a/reference/dom0-tools/qvm-add-appvm.md b/reference/tools/3.2/dom0/qvm-add-appvm.md similarity index 91% rename from reference/dom0-tools/qvm-add-appvm.md rename to reference/tools/3.2/dom0/qvm-add-appvm.md index bd86d695..d061900e 100644 --- a/reference/dom0-tools/qvm-add-appvm.md +++ b/reference/tools/3.2/dom0/qvm-add-appvm.md @@ -1,8 +1,9 @@ --- layout: doc title: qvm-add-appvm -permalink: /doc/dom0-tools/qvm-add-appvm/ +permalink: /doc/tools/3.2/dom0/qvm-add-appvm/ redirect_from: +- /doc/dom0-tools/qvm-add-appvm/ - /en/doc/dom0-tools/qvm-add-appvm/ - /doc/Dom0Tools/QvmAddAppvm/ - /wiki/Dom0Tools/QvmAddAppvm/ diff --git a/reference/dom0-tools/qvm-add-template.md b/reference/tools/3.2/dom0/qvm-add-template.md similarity index 90% rename from reference/dom0-tools/qvm-add-template.md rename to reference/tools/3.2/dom0/qvm-add-template.md index 2bef4299..81badcb2 100644 --- a/reference/dom0-tools/qvm-add-template.md +++ b/reference/tools/3.2/dom0/qvm-add-template.md @@ -1,8 +1,9 @@ --- layout: doc title: qvm-add-template -permalink: /doc/dom0-tools/qvm-add-template/ +permalink: /doc/tools/3.2/dom0/qvm-add-template/ redirect_from: +- /doc/dom0-tools/qvm-add-template/ - /en/doc/dom0-tools/qvm-add-template/ - /doc/Dom0Tools/QvmAddTemplate/ - /wiki/Dom0Tools/QvmAddTemplate/ diff --git a/reference/dom0-tools/qvm-backup-restore.md b/reference/tools/3.2/dom0/qvm-backup-restore.md similarity index 94% rename from reference/dom0-tools/qvm-backup-restore.md rename to reference/tools/3.2/dom0/qvm-backup-restore.md index a1907025..5456f460 100644 --- a/reference/dom0-tools/qvm-backup-restore.md +++ b/reference/tools/3.2/dom0/qvm-backup-restore.md @@ -1,8 +1,9 @@ --- layout: doc title: qvm-backup-restore -permalink: /doc/dom0-tools/qvm-backup-restore/ +permalink: /doc/tools/3.2/dom0/qvm-backup-restore/ redirect_from: +- /doc/dom0-tools/qvm-backup-restore/ - /en/doc/dom0-tools/qvm-backup-restore/ - /doc/Dom0Tools/QvmBackupRestore/ - /wiki/Dom0Tools/QvmBackupRestore/ diff --git a/reference/dom0-tools/qvm-backup.md b/reference/tools/3.2/dom0/qvm-backup.md similarity index 89% rename from reference/dom0-tools/qvm-backup.md rename to reference/tools/3.2/dom0/qvm-backup.md index a260317b..e5ff645c 100644 --- a/reference/dom0-tools/qvm-backup.md +++ b/reference/tools/3.2/dom0/qvm-backup.md @@ -1,8 +1,9 @@ --- layout: doc title: qvm-backup -permalink: /doc/dom0-tools/qvm-backup/ +permalink: /doc/tools/3.2/dom0/qvm-backup/ redirect_from: +- /doc/dom0-tools/qvm-backup/ - /en/doc/dom0-tools/qvm-backup/ - /doc/Dom0Tools/QvmBackup/ - /wiki/Dom0Tools/QvmBackup/ diff --git a/reference/dom0-tools/qvm-block.md b/reference/tools/3.2/dom0/qvm-block.md similarity index 90% rename from reference/dom0-tools/qvm-block.md rename to reference/tools/3.2/dom0/qvm-block.md index efa3c1b1..25dcc759 100644 --- a/reference/dom0-tools/qvm-block.md +++ b/reference/tools/3.2/dom0/qvm-block.md @@ -1,8 +1,10 @@ --- layout: doc title: qvm-block -permalink: /doc/dom0-tools/qvm-block/ +permalink: /doc/tools/3.2/dom0/qvm-block/ redirect_from: +- /doc/dom0-tools/qvm-block/ +- /doc/dom0-tools/qvm-block/ - /en/doc/dom0-tools/qvm-block/ - /doc/Dom0Tools/QvmBlock/ - /wiki/Dom0Tools/QvmBlock/ diff --git a/reference/dom0-tools/qvm-clone.md b/reference/tools/3.2/dom0/qvm-clone.md similarity index 90% rename from reference/dom0-tools/qvm-clone.md rename to reference/tools/3.2/dom0/qvm-clone.md index c3abd934..9ea56033 100644 --- a/reference/dom0-tools/qvm-clone.md +++ b/reference/tools/3.2/dom0/qvm-clone.md @@ -1,8 +1,9 @@ --- layout: doc title: qvm-clone -permalink: /doc/dom0-tools/qvm-clone/ +permalink: /doc/tools/3.2/dom0/qvm-clone/ redirect_from: +- /doc/dom0-tools/qvm-clone/ - /en/doc/dom0-tools/qvm-clone/ - /doc/Dom0Tools/QvmClone/ - /wiki/Dom0Tools/QvmClone/ diff --git a/reference/dom0-tools/qvm-create-default-dvm.md b/reference/tools/3.2/dom0/qvm-create-default-dvm.md similarity index 92% rename from reference/dom0-tools/qvm-create-default-dvm.md rename to reference/tools/3.2/dom0/qvm-create-default-dvm.md index fe907fda..efd61e31 100644 --- a/reference/dom0-tools/qvm-create-default-dvm.md +++ b/reference/tools/3.2/dom0/qvm-create-default-dvm.md @@ -1,8 +1,9 @@ --- layout: doc title: qvm-create-default-dvm -permalink: /doc/dom0-tools/qvm-create-default-dvm/ +permalink: /doc/tools/3.2/dom0/qvm-create-default-dvm/ redirect_from: +- /doc/dom0-tools/qvm-create-default-dvm/ - /en/doc/dom0-tools/qvm-create-default-dvm/ - /doc/Dom0Tools/QvmCreateDefaultDvm/ - /wiki/Dom0Tools/QvmCreateDefaultDvm/ diff --git a/reference/dom0-tools/qvm-create.md b/reference/tools/3.2/dom0/qvm-create.md similarity index 95% rename from reference/dom0-tools/qvm-create.md rename to reference/tools/3.2/dom0/qvm-create.md index 037fcdba..ea8db752 100644 --- a/reference/dom0-tools/qvm-create.md +++ b/reference/tools/3.2/dom0/qvm-create.md @@ -1,8 +1,9 @@ --- layout: doc title: qvm-create -permalink: /doc/dom0-tools/qvm-create/ +permalink: /doc/tools/3.2/dom0/qvm-create/ redirect_from: +- /doc/dom0-tools/qvm-create/ - /en/doc/dom0-tools/qvm-create/ - /doc/Dom0Tools/QvmCreate/ - /wiki/Dom0Tools/QvmCreate/ diff --git a/reference/dom0-tools/qvm-firewall.md b/reference/tools/3.2/dom0/qvm-firewall.md similarity index 94% rename from reference/dom0-tools/qvm-firewall.md rename to reference/tools/3.2/dom0/qvm-firewall.md index ff1b5cab..bcc9cae2 100644 --- a/reference/dom0-tools/qvm-firewall.md +++ b/reference/tools/3.2/dom0/qvm-firewall.md @@ -1,8 +1,9 @@ --- layout: doc title: qvm-firewall -permalink: /doc/dom0-tools/qvm-firewall/ +permalink: /doc/tools/3.2/dom0/qvm-firewall/ redirect_from: +- /doc/dom0-tools/qvm-firewall/ - /en/doc/dom0-tools/qvm-firewall/ - /doc/Dom0Tools/QvmFirewall/ - /wiki/Dom0Tools/QvmFirewall/ diff --git a/reference/dom0-tools/qvm-grow-private.md b/reference/tools/3.2/dom0/qvm-grow-private.md similarity index 87% rename from reference/dom0-tools/qvm-grow-private.md rename to reference/tools/3.2/dom0/qvm-grow-private.md index 360a3a5e..6b93a87c 100644 --- a/reference/dom0-tools/qvm-grow-private.md +++ b/reference/tools/3.2/dom0/qvm-grow-private.md @@ -1,8 +1,9 @@ --- layout: doc title: qvm-grow-private -permalink: /doc/dom0-tools/qvm-grow-private/ +permalink: /doc/tools/3.2/dom0/qvm-grow-private/ redirect_from: +- /doc/dom0-tools/qvm-grow-private/ - /en/doc/dom0-tools/qvm-grow-private/ - /doc/Dom0Tools/QvmGrowPrivate/ - /wiki/Dom0Tools/QvmGrowPrivate/ diff --git a/reference/dom0-tools/qvm-kill.md b/reference/tools/3.2/dom0/qvm-kill.md similarity index 88% rename from reference/dom0-tools/qvm-kill.md rename to reference/tools/3.2/dom0/qvm-kill.md index cff5f038..9903453a 100644 --- a/reference/dom0-tools/qvm-kill.md +++ b/reference/tools/3.2/dom0/qvm-kill.md @@ -1,8 +1,9 @@ --- layout: doc title: qvm-kill -permalink: /doc/dom0-tools/qvm-kill/ +permalink: /doc/tools/3.2/dom0/qvm-kill/ redirect_from: +- /doc/dom0-tools/qvm-kill/ - /en/doc/dom0-tools/qvm-kill/ - /doc/Dom0Tools/QvmKill/ - /wiki/Dom0Tools/QvmKill/ diff --git a/reference/dom0-tools/qvm-ls.md b/reference/tools/3.2/dom0/qvm-ls.md similarity index 93% rename from reference/dom0-tools/qvm-ls.md rename to reference/tools/3.2/dom0/qvm-ls.md index 643a19ef..13f4917f 100644 --- a/reference/dom0-tools/qvm-ls.md +++ b/reference/tools/3.2/dom0/qvm-ls.md @@ -1,8 +1,9 @@ --- layout: doc title: qvm-ls -permalink: /doc/dom0-tools/qvm-ls/ +permalink: /doc/tools/3.2/dom0/qvm-ls/ redirect_from: +- /doc/dom0-tools/qvm-ls/ - /en/doc/dom0-tools/qvm-ls/ - /doc/Dom0Tools/QvmLs/ - /wiki/Dom0Tools/QvmLs/ diff --git a/reference/dom0-tools/qvm-pci.md b/reference/tools/3.2/dom0/qvm-pci.md similarity index 92% rename from reference/dom0-tools/qvm-pci.md rename to reference/tools/3.2/dom0/qvm-pci.md index 5dba5aee..d7aa69b1 100644 --- a/reference/dom0-tools/qvm-pci.md +++ b/reference/tools/3.2/dom0/qvm-pci.md @@ -1,8 +1,9 @@ --- layout: doc title: qvm-pci -permalink: /doc/dom0-tools/qvm-pci/ +permalink: /doc/tools/3.2/dom0/qvm-pci/ redirect_from: +- /doc/dom0-tools/qvm-pci/ - /en/doc/dom0-tools/qvm-pci/ - /doc/Dom0Tools/QvmPci/ - /wiki/Dom0Tools/QvmPci/ diff --git a/reference/dom0-tools/qvm-prefs.md b/reference/tools/3.2/dom0/qvm-prefs.md similarity index 99% rename from reference/dom0-tools/qvm-prefs.md rename to reference/tools/3.2/dom0/qvm-prefs.md index eb053384..32850812 100644 --- a/reference/dom0-tools/qvm-prefs.md +++ b/reference/tools/3.2/dom0/qvm-prefs.md @@ -1,8 +1,9 @@ --- layout: doc title: qvm-prefs -permalink: /doc/dom0-tools/qvm-prefs/ +permalink: /doc/tools/3.2/dom0/qvm-prefs/ redirect_from: +- /doc/dom0-tools/qvm-prefs/ - /en/doc/dom0-tools/qvm-prefs/ - /doc/Dom0Tools/QvmPrefs/ - /wiki/Dom0Tools/QvmPrefs/ diff --git a/reference/dom0-tools/qvm-remove.md b/reference/tools/3.2/dom0/qvm-remove.md similarity index 90% rename from reference/dom0-tools/qvm-remove.md rename to reference/tools/3.2/dom0/qvm-remove.md index 4e436dea..412ef8c3 100644 --- a/reference/dom0-tools/qvm-remove.md +++ b/reference/tools/3.2/dom0/qvm-remove.md @@ -1,8 +1,9 @@ --- layout: doc title: qvm-remove -permalink: /doc/dom0-tools/qvm-remove/ +permalink: /doc/tools/3.2/dom0/qvm-remove/ redirect_from: +- /doc/dom0-tools/qvm-remove/ - /en/doc/dom0-tools/qvm-remove/ - /doc/Dom0Tools/QvmRemove/ - /wiki/Dom0Tools/QvmRemove/ diff --git a/reference/dom0-tools/qvm-revert-template-changes.md b/reference/tools/3.2/dom0/qvm-revert-template-changes.md similarity index 86% rename from reference/dom0-tools/qvm-revert-template-changes.md rename to reference/tools/3.2/dom0/qvm-revert-template-changes.md index 355d2e26..a0f62648 100644 --- a/reference/dom0-tools/qvm-revert-template-changes.md +++ b/reference/tools/3.2/dom0/qvm-revert-template-changes.md @@ -1,8 +1,9 @@ --- layout: doc title: qvm-revert-template-changes -permalink: /doc/dom0-tools/qvm-revert-template-changes/ +permalink: /doc/tools/3.2/dom0/qvm-revert-template-changes/ redirect_from: +- /doc/dom0-tools/qvm-revert-template-changes/ - /en/doc/dom0-tools/qvm-revert-template-changes/ - /doc/Dom0Tools/QvmRevertTemplateChanges/ - /wiki/Dom0Tools/QvmRevertTemplateChanges/ diff --git a/reference/dom0-tools/qvm-run.md b/reference/tools/3.2/dom0/qvm-run.md similarity index 95% rename from reference/dom0-tools/qvm-run.md rename to reference/tools/3.2/dom0/qvm-run.md index eb7e8b8c..aee15e02 100644 --- a/reference/dom0-tools/qvm-run.md +++ b/reference/tools/3.2/dom0/qvm-run.md @@ -1,8 +1,9 @@ --- layout: doc title: qvm-run -permalink: /doc/dom0-tools/qvm-run/ +permalink: /doc/tools/3.2/dom0/qvm-run/ redirect_from: +- /doc/dom0-tools/qvm-run/ - /en/doc/dom0-tools/qvm-run/ - /doc/Dom0Tools/QvmRun/ - /wiki/Dom0Tools/QvmRun/ diff --git a/reference/dom0-tools/qvm-service.md b/reference/tools/3.2/dom0/qvm-service.md similarity index 98% rename from reference/dom0-tools/qvm-service.md rename to reference/tools/3.2/dom0/qvm-service.md index e077265b..1d5b8192 100644 --- a/reference/dom0-tools/qvm-service.md +++ b/reference/tools/3.2/dom0/qvm-service.md @@ -1,8 +1,9 @@ --- layout: doc title: qvm-service -permalink: /doc/dom0-tools/qvm-service/ +permalink: /doc/tools/3.2/dom0/qvm-service/ redirect_from: +- /doc/dom0-tools/qvm-service/ - /en/doc/dom0-tools/qvm-service/ - /doc/Dom0Tools/QvmService/ - /wiki/Dom0Tools/QvmService/ diff --git a/reference/dom0-tools/qvm-shutdown.md b/reference/tools/3.2/dom0/qvm-shutdown.md similarity index 91% rename from reference/dom0-tools/qvm-shutdown.md rename to reference/tools/3.2/dom0/qvm-shutdown.md index 1cd80810..d6769487 100644 --- a/reference/dom0-tools/qvm-shutdown.md +++ b/reference/tools/3.2/dom0/qvm-shutdown.md @@ -1,8 +1,9 @@ --- layout: doc title: qvm-shutdown -permalink: /doc/dom0-tools/qvm-shutdown/ +permalink: /doc/tools/3.2/dom0/qvm-shutdown/ redirect_from: +- /doc/dom0-tools/qvm-shutdown/ - /en/doc/dom0-tools/qvm-shutdown/ - /doc/Dom0Tools/QvmShutdown/ - /wiki/Dom0Tools/QvmShutdown/ diff --git a/reference/dom0-tools/qvm-start.md b/reference/tools/3.2/dom0/qvm-start.md similarity index 91% rename from reference/dom0-tools/qvm-start.md rename to reference/tools/3.2/dom0/qvm-start.md index c66afa89..fc3cbfb5 100644 --- a/reference/dom0-tools/qvm-start.md +++ b/reference/tools/3.2/dom0/qvm-start.md @@ -1,8 +1,9 @@ --- layout: doc title: qvm-start -permalink: /doc/dom0-tools/qvm-start/ +permalink: /doc/tools/3.2/dom0/qvm-start/ redirect_from: +- /doc/dom0-tools/qvm-start/ - /en/doc/dom0-tools/qvm-start/ - /doc/Dom0Tools/QvmStart/ - /wiki/Dom0Tools/QvmStart/ diff --git a/reference/dom0-tools/qvm-sync-appmenus.md b/reference/tools/3.2/dom0/qvm-sync-appmenus.md similarity index 88% rename from reference/dom0-tools/qvm-sync-appmenus.md rename to reference/tools/3.2/dom0/qvm-sync-appmenus.md index f1cee881..16095b72 100644 --- a/reference/dom0-tools/qvm-sync-appmenus.md +++ b/reference/tools/3.2/dom0/qvm-sync-appmenus.md @@ -1,8 +1,9 @@ --- layout: doc title: qvm-sync-appmenus -permalink: /doc/dom0-tools/qvm-sync-appmenus/ +permalink: /doc/tools/3.2/dom0/qvm-sync-appmenus/ redirect_from: +- /doc/dom0-tools/qvm-sync-appmenus/ - /en/doc/dom0-tools/qvm-sync-appmenus/ - /doc/Dom0Tools/QvmSyncAppmenus/ - /wiki/Dom0Tools/QvmSyncAppmenus/ diff --git a/reference/dom0-tools/qvm-template-commit.md b/reference/tools/3.2/dom0/qvm-template-commit.md similarity index 86% rename from reference/dom0-tools/qvm-template-commit.md rename to reference/tools/3.2/dom0/qvm-template-commit.md index c0cdd8e5..12d4b19c 100644 --- a/reference/dom0-tools/qvm-template-commit.md +++ b/reference/tools/3.2/dom0/qvm-template-commit.md @@ -1,8 +1,9 @@ --- layout: doc title: qvm-template-commit -permalink: /doc/dom0-tools/qvm-template-commit/ +permalink: /doc/tools/3.2/dom0/qvm-template-commit/ redirect_from: +- /doc/dom0-tools/qvm-template-commit/ - /en/doc/dom0-tools/qvm-template-commit/ - /doc/Dom0Tools/QvmTemplateCommit/ - /wiki/Dom0Tools/QvmTemplateCommit/ diff --git a/reference/tools/3.2/domU.md b/reference/tools/3.2/domU.md new file mode 100644 index 00000000..71ae0db8 --- /dev/null +++ b/reference/tools/3.2/domU.md @@ -0,0 +1,19 @@ +--- +layout: doc +title: DomU Command-Line Tools for Qubes 3.2 +permalink: /doc/tools/3.2/domU/ +redirect_from: +- /doc/tools/3.2/domU/ +- /en/doc/tools/3.2/domU/ +- /doc/VmTools/ +- /wiki/VmTools/ +--- + +DomU Command-Line Tools for Qubes 3.2 +===================================== + + * [qvm-copy-to-vm](/doc/tools/3.2/domU/qvm-copy-to-vm/) + * [qvm-open-in-dvm](/doc/tools/3.2/domU/qvm-open-in-dvm/) + * [qvm-open-in-vm](/doc/tools/3.2/domU/qvm-open-in-vm/) + * [qvm-run](/doc/tools/3.2/domU/qvm-run/) + diff --git a/reference/vm-tools/qvm-copy-to-vm.md b/reference/tools/3.2/domU/qvm-copy-to-vm.md similarity index 88% rename from reference/vm-tools/qvm-copy-to-vm.md rename to reference/tools/3.2/domU/qvm-copy-to-vm.md index e9ad5c17..2f720aa6 100644 --- a/reference/vm-tools/qvm-copy-to-vm.md +++ b/reference/tools/3.2/domU/qvm-copy-to-vm.md @@ -1,8 +1,9 @@ --- layout: doc title: qvm-copy-to-vm -permalink: /doc/vm-tools/qvm-copy-to-vm/ +permalink: /doc/tools/3.2/domU/qvm-copy-to-vm/ redirect_from: +- /doc/vm-tools/qvm-copy-to-vm/ - /en/doc/vm-tools/qvm-copy-to-vm/ - /doc/VmTools/QvmCopyToVm/ - /wiki/VmTools/QvmCopyToVm/ diff --git a/reference/vm-tools/qvm-open-in-dvm.md b/reference/tools/3.2/domU/qvm-open-in-dvm.md similarity index 86% rename from reference/vm-tools/qvm-open-in-dvm.md rename to reference/tools/3.2/domU/qvm-open-in-dvm.md index 17e77d82..53bd4cef 100644 --- a/reference/vm-tools/qvm-open-in-dvm.md +++ b/reference/tools/3.2/domU/qvm-open-in-dvm.md @@ -1,8 +1,9 @@ --- layout: doc title: qvm-open-in-dvm -permalink: /doc/vm-tools/qvm-open-in-dvm/ +permalink: /doc/tools/3.2/domU/qvm-open-in-dvm/ redirect_from: +- /doc/vm-tools/qvm-open-in-dvm/ - /en/doc/vm-tools/qvm-open-in-dvm/ - /doc/VmTools/QvmOpenInDvm/ - /wiki/VmTools/QvmOpenInDvm/ diff --git a/reference/vm-tools/qvm-open-in-vm.md b/reference/tools/3.2/domU/qvm-open-in-vm.md similarity index 86% rename from reference/vm-tools/qvm-open-in-vm.md rename to reference/tools/3.2/domU/qvm-open-in-vm.md index c8259c9b..80fa4a57 100644 --- a/reference/vm-tools/qvm-open-in-vm.md +++ b/reference/tools/3.2/domU/qvm-open-in-vm.md @@ -1,8 +1,9 @@ --- layout: doc title: qvm-open-in-vm -permalink: /doc/vm-tools/qvm-open-in-vm/ +permalink: /doc/tools/3.2/domU/qvm-open-in-vm/ redirect_from: +- /doc/vm-tools/qvm-open-in-vm/ - /en/doc/vm-tools/qvm-open-in-vm/ - /doc/VmTools/QvmOpenInVm/ - /wiki/VmTools/QvmOpenInVm/ diff --git a/reference/vm-tools/qvm-run.md b/reference/tools/3.2/domU/qvm-run.md similarity index 89% rename from reference/vm-tools/qvm-run.md rename to reference/tools/3.2/domU/qvm-run.md index 84a2a8bc..7ef27ea3 100644 --- a/reference/vm-tools/qvm-run.md +++ b/reference/tools/3.2/domU/qvm-run.md @@ -1,8 +1,9 @@ --- layout: doc title: qvm-run -permalink: /doc/vm-tools/qvm-run/ +permalink: /doc/tools/3.2/domU/qvm-run/ redirect_from: +- /doc/vm-tools/qvm-run/ - /en/doc/vm-tools/qvm-run/ - /doc/VmTools/QvmRun/ - /wiki/VmTools/QvmRun/ diff --git a/reference/tools/4.0/dom0.md b/reference/tools/4.0/dom0.md new file mode 100644 index 00000000..3fb9d427 --- /dev/null +++ b/reference/tools/4.0/dom0.md @@ -0,0 +1,14 @@ +--- +layout: doc +title: Dom0 Command-Line Tools for Qubes 4.0 +permalink: /doc/tools/4.0/dom0/ +--- + +Dom0 Command-Line Tools for Qubes 4.0 +===================================== + +Reference pages for these tools are being written. +This page will be updated when they're available. + +Tracking issue: + diff --git a/reference/tools/4.0/domU.md b/reference/tools/4.0/domU.md new file mode 100644 index 00000000..a2ac1716 --- /dev/null +++ b/reference/tools/4.0/domU.md @@ -0,0 +1,14 @@ +--- +layout: doc +title: DomU Command-Line Tools for Qubes 4.0 +permalink: /doc/tools/4.0/domU/ +--- + +DomU Command-Line Tools for Qubes 4.0 +===================================== + +Reference pages for these tools are being written. +This page will be updated when they're available. + +Tracking issue: + diff --git a/reference/tools/tools-3.2.md b/reference/tools/tools-3.2.md new file mode 100644 index 00000000..47ffd430 --- /dev/null +++ b/reference/tools/tools-3.2.md @@ -0,0 +1,13 @@ +--- +layout: doc +title: Qubes 3.2 Command-Line Tools +permalink: /doc/tools/3.2/ +--- + +Qubes 3.2 Command-Line Tools +============================ + +Please see the page for your desired domain: + + * [Dom0 Command-Line Tools](/doc/tools/3.2/dom0/) + * [DomU Command-Line Tools](/doc/tools/3.2/domU/) diff --git a/reference/tools/tools-4.0.md b/reference/tools/tools-4.0.md new file mode 100644 index 00000000..1bd1937e --- /dev/null +++ b/reference/tools/tools-4.0.md @@ -0,0 +1,13 @@ +--- +layout: doc +title: Qubes 4.0 Command-Line Tools +permalink: /doc/tools/4.0/ +--- + +Qubes 4.0 Command-Line Tools +============================ + +Please see the page for your desired domain: + + * [Dom0 Command-Line Tools](/doc/tools/4.0/dom0/) + * [DomU Command-Line Tools](/doc/tools/4.0/domU/) diff --git a/reference/vm-tools.md b/reference/vm-tools.md deleted file mode 100644 index bca5a278..00000000 --- a/reference/vm-tools.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -layout: doc -title: VM Tools -permalink: /doc/vm-tools/ -redirect_from: -- /en/doc/vm-tools/ -- /doc/VmTools/ -- /wiki/VmTools/ ---- - -VM tools: - -- [qvm-copy-to-vm](/doc/vm-tools/qvm-copy-to-vm/) -- [qvm-open-in-dvm](/doc/vm-tools/qvm-open-in-dvm/) -- [qvm-open-in-vm](/doc/vm-tools/qvm-open-in-vm/) -- [qvm-run](/doc/vm-tools/qvm-run/) - From 04c4b043dae34ff040ee2f745a1aa57e05528c7e Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Sun, 4 Feb 2018 17:46:19 -0600 Subject: [PATCH 63/67] Fix link --- basics_user/getting-started.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/basics_user/getting-started.md b/basics_user/getting-started.md index 7a8ebf85..691e8ebd 100644 --- a/basics_user/getting-started.md +++ b/basics_user/getting-started.md @@ -58,7 +58,7 @@ Qubes VM Manager and Command Line Tools All aspects of the Qubes system can be controlled using command line tools run under a dom0 console. To open a console window in dom0, either go to Start-\>System Tools-\>Konsole or press Alt-F2 and type `konsole`. -Various command line tools are described as part of this guide, and the whole reference can be found [here](/doc/dom0-tools/). +Various command line tools are described as part of this guide, and the whole reference can be found [here](/doc/tools/). ![r2b1-dom0-konsole.png](/attachment/wiki/GettingStarted/r2b1-dom0-konsole.png) From ac45c208f987719c328528dd50b843d2a0c6e4af Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Sun, 4 Feb 2018 18:00:34 -0600 Subject: [PATCH 64/67] Update 4.0 release schedule with 4.0-rc4 release date Closes #562 --- releases/4.0/schedule.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/releases/4.0/schedule.md b/releases/4.0/schedule.md index a7ddd34b..ccb5f505 100644 --- a/releases/4.0/schedule.md +++ b/releases/4.0/schedule.md @@ -21,5 +21,5 @@ This schedule is based on [Version Scheme](/doc/version-scheme/#release-schedule | 27 Nov 2017 | 4.0-rc3 release | | 11 Dec 2017 | decide whether 4.0-rc3 is the final 4.0 | | 1 Jan 2018 | current-testing freeze before 4.0-rc4 | -| 8 Jan 2018
TBD | 4.0-rc4 release | +| 8 Jan 2018
31 Jan 2018 | 4.0-rc4 release | | 22 Jan 2018
TBD | decide whether 4.0-rc4 is the final 4.0 | From a800ae9d1c43d9e4b8604e528f1478329ca4306c Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Sun, 4 Feb 2018 23:15:22 -0600 Subject: [PATCH 65/67] Clarify one-sentence-per-line convention To avoid misunderstanding, e.g.: https://github.com/QubesOS/qubes-doc/pull/565#issuecomment-362980018 --- basics_user/doc-guidelines.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/basics_user/doc-guidelines.md b/basics_user/doc-guidelines.md index 27869f28..428dd376 100644 --- a/basics_user/doc-guidelines.md +++ b/basics_user/doc-guidelines.md @@ -156,8 +156,8 @@ When making contributions, please try to observe the following style conventions * [News] posts (plain text is reproduced on the [mailing lists]) * URLs that appear inside code blocks (e.g., in comments and document templates) * Files like `README.md` and `CONTRIBUTING.md` - * Insert a newline at the end of each sentence, except when the text will be reproduced outside of the Qubes website repo (see previous item for examples). - * Rationale: This practice is most appropriate for source that consists primarily of natural language text. + * Insert a newline at, and only at, the end of each sentence, except when the text will be reproduced outside of the Qubes website repo (see previous item for examples). + * Rationale: This practice results in one sentence per line, which is most appropriate for source that consists primarily of natural language text. It results in the most useful diffs and facilitates translation into other languages while mostly preserving source readability. * If appropriate, make numerals in numbered lists match between Markdown source and HTML output. * Rationale: In the event that a user is required to read the Markdown source directly, this will make it easier to follow, e.g., numbered steps in a set of instructions. From 6dda05712e217e37a3975aa7af2c2b8f1469ce4c Mon Sep 17 00:00:00 2001 From: awokd <34515595+awokd@users.noreply.github.com> Date: Mon, 5 Feb 2018 15:15:13 +0000 Subject: [PATCH 66/67] add linebreaks, use US spelling of grey --- common-tasks/backup-restore.md | 141 +++++++++++++++++++++++---------- 1 file changed, 101 insertions(+), 40 deletions(-) diff --git a/common-tasks/backup-restore.md b/common-tasks/backup-restore.md index d07e1e1a..24be5e44 100644 --- a/common-tasks/backup-restore.md +++ b/common-tasks/backup-restore.md @@ -11,22 +11,27 @@ redirect_from: Qubes Backup, Restoration, and Migration ======================================== -**Caution:** The Qubes R3.2 backup system currently relies on a [weak key derivation scheme](https://github.com/QubesOS/qubes-issues/issues/971). Although resolved in R4.0 and higher with the switch to scrypt, it is *strongly recommended* that users select a *high-entropy* passphrase for use with Qubes backups. +**Caution:** The Qubes R3.2 backup system currently relies on a [weak key derivation scheme](https://github.com/QubesOS/qubes-issues/issues/971). +Although resolved in R4.0 and higher with the switch to scrypt, it is *strongly recommended* that users select a *high-entropy* passphrase for use with Qubes backups. With Qubes, it's easy to back up and restore your whole system, as well as to migrate between two physical machines. -As of Qubes R2B3, these functions are integrated into the Qubes VM Manager GUI. There are also two command-line tools available which perform the same functions: [qvm-backup](/doc/dom0-tools/qvm-backup/) and [qvm-backup-restore](/doc/dom0-tools/qvm-backup-restore/). +As of Qubes R2B3, these functions are integrated into the Qubes VM Manager GUI. +There are also two command-line tools available which perform the same functions: [qvm-backup](/doc/dom0-tools/qvm-backup/) and [qvm-backup-restore](/doc/dom0-tools/qvm-backup-restore/). Creating a Backup (R4.0 and later) ----------------- -1. Go to **Applications menu -> System Tools -> Backup Qubes**. This brings up the **Qubes Backup VMs** window. +1. Go to **Applications menu -> System Tools -> Backup Qubes**. +This brings up the **Qubes Backup VMs** window. -2. Move the VMs that you want to back up to the right-hand **Selected** column. VMs in the left-hand **Available** column will not be backed up. +2. Move the VMs that you want to back up to the right-hand **Selected** column. +VMs in the left-hand **Available** column will not be backed up. - You may choose whether to compress backups by checking or unchecking the **Compress the backup** box. Normally this should be left on unless you have a specific reason otherwise. + You may choose whether to compress backups by checking or unchecking the **Compress the backup** box. + Normally this should be left on unless you have a specific reason otherwise. Once you have selected all desired VMs, click **Next**. @@ -35,9 +40,14 @@ Creating a Backup (R4.0 and later) If you wish to send your backup to a (currently running) VM, select the VM in the drop-down box next to **Target AppVM**. If you wish to send your backup to a [USB mass storage device](/doc/usb/), you can use the directory selection widget to mount a connected device (under "Other locations" item on the left); or first mount the device in a VM, then select the mount point inside that VM as the backup destination. - You must also specify a directory on the device or in the VM, or a command to be executed in the VM as a destination for your backup. For example, if you wish to send your backup to the `~/backups` folder in the target VM, you would simply browse to it using the convenient directory selection dialog (`...`) at the right. This destination directory must already exist. If it does not exist, you must create it manually prior to backing up. + You must also specify a directory on the device or in the VM, or a command to be executed in the VM as a destination for your backup. + For example, if you wish to send your backup to the `~/backups` folder in the target VM, you would simply browse to it using the convenient directory selection dialog (`...`) at the right. + This destination directory must already exist. + If it does not exist, you must create it manually prior to backing up. - By specifying the appropriate directory as the destination in a VM, it is possible to send the backup directly to, e.g., a USB mass storage device attached to the VM. Likewise, it is possible to enter any command as a backup target by specifying the command as the destination in the VM. This can be used to send your backup directly to, e.g., a remote server using SSH. + By specifying the appropriate directory as the destination in a VM, it is possible to send the backup directly to, e.g., a USB mass storage device attached to the VM. + Likewise, it is possible to enter any command as a backup target by specifying the command as the destination in the VM. + This can be used to send your backup directly to, e.g., a remote server using SSH. **Note:** The supplied passphrase is used for **both** encryption/decryption and integrity verification. @@ -45,18 +55,24 @@ Creating a Backup (R4.0 and later) **Warning: Saving the settings will result in your backup passphrase being saved in plaintext in dom0, so consider your threat model before checking this box.** -4. You will now see the summary of VMs to be backed up. If there are any issues preventing the backup, they will be listed here and the **Next** button greyed out. +4. You will now see the summary of VMs to be backed up. +If there are any issues preventing the backup, they will be listed here and the **Next** button grayed out. -5. When you are ready, click **Next**. Qubes will proceed to create your backup. Once the progress bar has completed, you may click **Finish**. +5. When you are ready, click **Next**. +Qubes will proceed to create your backup. +Once the progress bar has completed, you may click **Finish**. Creating a Backup (R3.2 and earlier) ----------------- -1. In **Qubes VM Manager**, click **System** on the menu bar, then click **Backup VMs** in the drop-down list. This brings up the **Qubes Backup VMs** window. +1. In **Qubes VM Manager**, click **System** on the menu bar, then click **Backup VMs** in the drop-down list. +This brings up the **Qubes Backup VMs** window. -2. Move the VMs that you want to back up to the right-hand **Selected** column. VMs in the left-hand **Available** column will not be backed up. +2. Move the VMs that you want to back up to the right-hand **Selected** column. +VMs in the left-hand **Available** column will not be backed up. - **Note:** A VM must be shut down in order to be backed up. Currently running VMs appear in red. + **Note:** A VM must be shut down in order to be backed up. + Currently running VMs appear in red. Once you have selected all desired VMs, click **Next**. @@ -65,78 +81,114 @@ Creating a Backup (R3.2 and earlier) If you wish to send your backup to a (currently running) VM, select the VM in the drop-down box next to **Target AppVM**. If you wish to send your backup to a [USB mass storage device](/doc/usb/), you can use the directory selection widget to mount a connected device (under "Other locations" item on the left); or first mount the device in a VM, then select the mount point inside that VM as the backup destination. - You must also specify a directory on the device or in the VM, or a command to be executed in the VM as a destination for your backup. For example, if you wish to send your backup to the `~/backups` folder in the target VM, you would simply browse to it using the convenient directory selection dialog (`...`) at the right. If it does not exist, you must create it manually prior to backing up. + You must also specify a directory on the device or in the VM, or a command to be executed in the VM as a destination for your backup. + For example, if you wish to send your backup to the `~/backups` folder in the target VM, you would simply browse to it using the convenient directory selection dialog (`...`) at the right. + If it does not exist, you must create it manually prior to backing up. - By specifying the appropriate directory as the destination in a VM, it is possible to send the backup directly to, e.g., a USB mass storage device attached to the VM. Likewise, it is possible to enter any command as a backup target by specifying the command as the destination in the VM. This can be used to send your backup directly to, e.g., a remote server using SSH. + By specifying the appropriate directory as the destination in a VM, it is possible to send the backup directly to, e.g., a USB mass storage device attached to the VM. + Likewise, it is possible to enter any command as a backup target by specifying the command as the destination in the VM. + This can be used to send your backup directly to, e.g., a remote server using SSH. At this point, you must also choose whether to encrypt your backup by checking or unchecking the **Encrypt backup** box. **Note:** It is strongly recommended that you opt to encrypt all backups which will be sent to untrusted destinations! - **Note:** The supplied passphrase is used for **both** encryption/decryption and integrity verification. If you decide not to encrypt your backup (by unchecking the **Encrypt backup** box), the passphrase you supply will be used **only** for integrity verification. If you supply a passphrase but do not check the **Encrypt backup** box, your backup will **not** be encrypted! + **Note:** The supplied passphrase is used for **both** encryption/decryption and integrity verification. + If you decide not to encrypt your backup (by unchecking the **Encrypt backup** box), the passphrase you supply will be used **only** for integrity verification. + If you supply a passphrase but do not check the **Encrypt backup** box, your backup will **not** be encrypted! -4. You will now see the summary of VMs to be backed up. If there are any issues preventing the backup, they will be listed here and the **Next** button greyed out. +4. You will now see the summary of VMs to be backed up. +If there are any issues preventing the backup, they will be listed here and the **Next** button grayed out. -5. When you are ready, click **Next**. Qubes will proceed to create your backup. Once the progress bar has completed, you may click **Finish**. +5. When you are ready, click **Next**. +Qubes will proceed to create your backup. +Once the progress bar has completed, you may click **Finish**. Restoring from a Backup (R4.0 and later) ----------------------- -1. Go to **Applications menu -> System Tools -> Restore Backup**. This brings up the **Qubes Restore VMs** window. +1. Go to **Applications menu -> System Tools -> Restore Backup**. +This brings up the **Qubes Restore VMs** window. 2. Select the source location of the backup to be restored: - If your backup is located on a [USB mass storage device](/doc/usb/), attach it first to another VM or select `sys-usb` in the next item. - If your backup is located in a (currently running) VM, select the VM in the drop-down box next to **AppVM**. - You must also specify the directory and filename of the backup (or a command to be executed in a VM) in the **Backup file** field. If you followed the instructions in the previous section, "Creating a Backup," then your backup is most likely in the location you chose as the destination in step 3. For example, if you had chosen the `~/backups` directory of a VM as your destination in step 3, you would now select the same VM and again browse to (using `...`) the `backups` folder. Once you've located the backup file, double-click it or select it and hit **OK**. + You must also specify the directory and filename of the backup (or a command to be executed in a VM) in the **Backup file** field. + If you followed the instructions in the previous section, "Creating a Backup," then your backup is most likely in the location you chose as the destination in step 3. + For example, if you had chosen the `~/backups` directory of a VM as your destination in step 3, you would now select the same VM and again browse to (using `...`) the `backups` folder. + Once you've located the backup file, double-click it or select it and hit **OK**. 3. There are three options you may select when restoring from a backup: 1. **ignore missing templates and net VMs**: If any of the VMs in your backup depended upon a NetVM or TemplateVM that is not present in (i.e., "missing from") the current system, checking this box will ignore the fact that they are missing and restore the VMs anyway and set them to use the default NetVM and system default template. - 2. **ignore username mismatch**: This option applies only to the restoration of dom0's home directory. If your backup was created on a Qubes system which had a different dom0 username than the dom0 username of the current system, then checking this box will ignore the mismatch between the two usernames and proceed to restore the home directory anyway. - 3. **Verify backup integrity, do not restore the data**: This will scan the backup file for corrupted data. However, it does not currently detect if it is missing data as long as it is a correctly structured, non-corrupted backup file. See [issue #3498](https://github.com/QubesOS/qubes-issues/issues/3498) for more details. + 2. **ignore username mismatch**: This option applies only to the restoration of dom0's home directory. + If your backup was created on a Qubes system which had a different dom0 username than the dom0 username of the current system, then checking this box will ignore the mismatch between the two usernames and proceed to restore the home directory anyway. + 3. **Verify backup integrity, do not restore the data**: This will scan the backup file for corrupted data. + However, it does not currently detect if it is missing data as long as it is a correctly structured, non-corrupted backup file. + See [issue #3498](https://github.com/QubesOS/qubes-issues/issues/3498) for more details. -4. If your backup is encrypted, you must check the **Encrypted backup** box. If a passphrase was supplied during the creation of your backup (regardless of whether it is encrypted), then you must supply it here. +4. If your backup is encrypted, you must check the **Encrypted backup** box. +If a passphrase was supplied during the creation of your backup (regardless of whether it is encrypted), then you must supply it here. - **Note:** The passphrase which was supplied when the backup was created was used for **both** encryption/decryption and integrity verification. If the backup was not encrypted, the supplied passphrase is used only for integrity verification. All backups made from a Qubes R4.0 system will be encrypted. + **Note:** The passphrase which was supplied when the backup was created was used for **both** encryption/decryption and integrity verification. + If the backup was not encrypted, the supplied passphrase is used only for integrity verification. + All backups made from a Qubes R4.0 system will be encrypted. -5. You will now see the summary of VMs to be restored. If there are any issues preventing the restore, they will be listed here and the **Next** button greyed out. +5. You will now see the summary of VMs to be restored. +If there are any issues preventing the restore, they will be listed here and the **Next** button grayed out. -6. When you are ready, click **Next**. Qubes will proceed to restore from your backup. Once the progress bar has completed, you may click **Finish**. +6. When you are ready, click **Next**. +Qubes will proceed to restore from your backup. +Once the progress bar has completed, you may click **Finish**. Restoring from a Backup (R3.2 and earlier) ----------------------- -1. In **Qubes VM Manager**, click **System** on the menu bar, then click **Restore VMs from backup** in the drop-down list. This brings up the **Qubes Restore VMs** window. +1. In **Qubes VM Manager**, click **System** on the menu bar, then click **Restore VMs from backup** in the drop-down list. +This brings up the **Qubes Restore VMs** window. 2. Select the source location of the backup to be restored: - If your backup is located on a [USB mass storage device](/doc/usb/), attach it first to another VM or select `sys-usb` in the next item. - If your backup is located in a (currently running) VM, select the VM in the drop-down box next to **AppVM**. - You must also specify the directory and filename of the backup (or a command to be executed in a VM) in the **Backup file** field. If you followed the instructions in the previous section, "Creating a Backup," then your backup is most likely in the location you chose as the destination in step 3. For example, if you had chosen the `~/backups` directory of a VM as your destination in step 3, you would now select the same VM and again browse to (using `...`) the `backups` folder. Once you've located the backup file, double-click or select it and hit **OK**. + You must also specify the directory and filename of the backup (or a command to be executed in a VM) in the **Backup file** field. + If you followed the instructions in the previous section, "Creating a Backup," then your backup is most likely in the location you chose as the destination in step 3. + For example, if you had chosen the `~/backups` directory of a VM as your destination in step 3, you would now select the same VM and again browse to (using `...`) the `backups` folder. + Once you've located the backup file, double-click or select it and hit **OK**. 3. There are three options you may select when restoring from a backup: 1. **ignore missing**: If any of the VMs in your backup depended upon a NetVM, ProxyVM, or TemplateVM that is not present in (i.e., "missing from") the current system, checking this box will ignore the fact that they are missing and restore the VMs anyway and set them to use the default NetVM and system default template. - 2. **ignore username mismatch**: This option applies only to the restoration of dom0's home directory. If your backup was created on a Qubes system which had a different dom0 username than the dom0 username of the current system, then checking this box will ignore the mismatch between the two usernames and proceed to restore the home directory anyway. - 3. **Verify backup integrity, do not restore the data**: This will scan the backup file for corrupted data. However, it does not currently detect if it is missing data as long as it is a correctly structured, non-corrupted backup file. See [issue #3498](https://github.com/QubesOS/qubes-issues/issues/3498) for more details. + 2. **ignore username mismatch**: This option applies only to the restoration of dom0's home directory. + If your backup was created on a Qubes system which had a different dom0 username than the dom0 username of the current system, then checking this box will ignore the mismatch between the two usernames and proceed to restore the home directory anyway. + 3. **Verify backup integrity, do not restore the data**: This will scan the backup file for corrupted data. + However, it does not currently detect if it is missing data as long as it is a correctly structured, non-corrupted backup file. See [issue #3498](https://github.com/QubesOS/qubes-issues/issues/3498) for more details. -4. If your backup is encrypted, you must check the **Encrypted backup** box. If a passphrase was supplied during the creation of your backup (regardless of whether it is encrypted), then you must supply it here. +4. If your backup is encrypted, you must check the **Encrypted backup** box. +If a passphrase was supplied during the creation of your backup (regardless of whether it is encrypted), then you must supply it here. - **Note:** The passphrase which was supplied when the backup was created was used for **both** encryption/decryption and integrity verification. If the backup was not encrypted, the supplied passphrase is used only for integrity verification. + **Note:** The passphrase which was supplied when the backup was created was used for **both** encryption/decryption and integrity verification. + If the backup was not encrypted, the supplied passphrase is used only for integrity verification. - **Note:** A VM cannot be restored from a backup if a VM with the same name already exists on the current system. You must first remove or change the name of any VM with the same name in order to restore such a VM. + **Note:** A VM cannot be restored from a backup if a VM with the same name already exists on the current system. + You must first remove or change the name of any VM with the same name in order to restore such a VM. -5. You will now see the summary of VMs to be restored. If there are any issues preventing the restore, they will be listed here and the **Next** button greyed out. +5. You will now see the summary of VMs to be restored. +If there are any issues preventing the restore, they will be listed here and the **Next** button grayed out. -6. When you are ready, click **Next**. Qubes will proceed to restore from your backup. Once the progress bar has completed, you may click **Finish**. +6. When you are ready, click **Next**. +Qubes will proceed to restore from your backup. +Once the progress bar has completed, you may click **Finish**. Emergency Backup Recovery without Qubes --------------------------------------- -The Qubes backup system has been designed with emergency disaster recovery in mind. No special Qubes-specific tools are required to access data backed up by Qubes. In the event a Qubes system is unavailable, you can access your data on any GNU/Linux system with the following procedure. +The Qubes backup system has been designed with emergency disaster recovery in mind. +No special Qubes-specific tools are required to access data backed up by Qubes. +In the event a Qubes system is unavailable, you can access your data on any GNU/Linux system with the following procedure. Refer to the following for emergency restore of a backup created on: @@ -148,20 +200,29 @@ Refer to the following for emergency restore of a backup created on: Migrating Between Two Physical Machines --------------------------------------- -In order to migrate your Qubes system from one physical machine to another, simply follow the backup procedure on the old machine, [install Qubes](/downloads/) on the new machine, and follow the restoration procedure on the new machine. All of your settings and data will be preserved! +In order to migrate your Qubes system from one physical machine to another, simply follow the backup procedure on the old machine, [install Qubes](/downloads/) on the new machine, and follow the restoration procedure on the new machine. +All of your settings and data will be preserved! Choosing a Backup Passphrase ---------------------------- Here are some things to consider when selecting a passphrase for your backups: - * If you plan to store the backup for a long time or on third-party servers, you should make sure to use a very long, high-entropy passphrase. (Depending on the decryption passphrase you use for your system drive, this may necessitate selecting a stronger passphrase. If your system drive decryption passphrase is already sufficiently strong, it may not.) - * An adversary who has access to your backups may try to substitute one backup for another. For example, when you attempt to retrieve a recent backup, the adversary may instead give you a very old backup containing a compromised VM. If you're concerned about this type of attack, you may wish to use a different passphrase for each backup, e.g., by appending a number or date to the passphrase. - * If you're forced to enter your system drive decryption passphrase in plain view of others (where it can be shoulder-surfed), then you may want to use a different passphrase for your backups (even if your system drive decryption passphrase is already maximally strong). On the othe hand, if you're careful to avoid shoulder-surfing and/or have a passphrase that's difficult to detect via shoulder-surfing, then this may not be a problem for you. + * If you plan to store the backup for a long time or on third-party servers, you should make sure to use a very long, high-entropy passphrase. + (Depending on the decryption passphrase you use for your system drive, this may necessitate selecting a stronger passphrase. + If your system drive decryption passphrase is already sufficiently strong, it may not.) + * An adversary who has access to your backups may try to substitute one backup for another. + For example, when you attempt to retrieve a recent backup, the adversary may instead give you a very old backup containing a compromised VM. + If you're concerned about this type of attack, you may wish to use a different passphrase for each backup, e.g., by appending a number or date to the passphrase. + * If you're forced to enter your system drive decryption passphrase in plain view of others (where it can be shoulder-surfed), then you may want to use a different passphrase for your backups (even if your system drive decryption passphrase is already maximally strong). + On the othe hand, if you're careful to avoid shoulder-surfing and/or have a passphrase that's difficult to detect via shoulder-surfing, then this may not be a problem for you. Notes ----- - * The Qubes R3.2 and earlier backup system relies on `openssl enc`, which is known to use a very weak key derivation scheme. The Qubes backup system also uses the same passphrase for authentication and for encryption, which is problematic from a security perspective. Users are advised to use a very high entropy passphrase for Qubes backups. For a full discussion, see [this ticket](https://github.com/QubesOS/qubes-issues/issues/971) and [this thread](https://groups.google.com/d/msg/qubes-devel/CZ7WRwLXcnk/u_rZPoVxL5IJ). + * The Qubes R3.2 and earlier backup system relies on `openssl enc`, which is known to use a very weak key derivation scheme. + The Qubes backup system also uses the same passphrase for authentication and for encryption, which is problematic from a security perspective. + Users are advised to use a very high entropy passphrase for Qubes backups. + For a full discussion, see [this ticket](https://github.com/QubesOS/qubes-issues/issues/971) and [this thread](https://groups.google.com/d/msg/qubes-devel/CZ7WRwLXcnk/u_rZPoVxL5IJ). * For the technical details of the backup system, please refer to [this thread](https://groups.google.com/d/topic/qubes-devel/TQr_QcXIVww/discussion). * If working with symlinks, note the issues described in [this thread](https://groups.google.com/d/topic/qubes-users/EITd1kBHD30/discussion). From 6f98eb4083a71075d7d8a821ab50e1401b452bd9 Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Tue, 6 Feb 2018 01:38:31 -0600 Subject: [PATCH 67/67] Fix link --- security/firewall.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/security/firewall.md b/security/firewall.md index 6b9898b8..53f0d16b 100644 --- a/security/firewall.md +++ b/security/firewall.md @@ -53,7 +53,8 @@ This equates to somewhere between 35 and 39 rules. If this limit is exceeded, the qube will not start. It is possible to work around this limit by enforcing the rules on the qube itself -by putting appropriate rules in `/rw/config`. See [below](#where-to-put-firewall-rules). +by putting appropriate rules in `/rw/config`. +See the "Where to put firewall rules" sections below for [R4.0](#where-to-put-firewall-rules-r40) and [R3.2](#where-to-put-firewall-rules-r32). In complex cases, it might be appropriate to load a ruleset using `iptables-restore` called from `/rw/config/rc.local`.