From 82f91af805ec62a6a4551888028a7ca7c8a419dc Mon Sep 17 00:00:00 2001 From: dcame Date: Thu, 2 Jun 2016 22:01:37 -0700 Subject: [PATCH 001/708] Modernize all examples from R2 to R3.1 --- installing/verifying-signatures.md | 99 +++++++++++++++--------------- 1 file changed, 49 insertions(+), 50 deletions(-) diff --git a/installing/verifying-signatures.md b/installing/verifying-signatures.md index cc2dc875..c56e2696 100644 --- a/installing/verifying-signatures.md +++ b/installing/verifying-signatures.md @@ -98,11 +98,11 @@ Once you have obtained the Qubes Master Signing Key ([`0x36879494`](https://keys Now you can easily download any of the developer or release signing keys that happen to be used to sign particular ISO, RPM, TGZ files or git tags. -For example: Qubes OS Release 2 Signing Key ([`0x0A40E458`](https://keys.qubes-os.org/keys/qubes-release-2-signing-key.asc)) is used for all Release 2 ISO images. +For example: Qubes OS Release 3 Signing Key ([`0x03FA5082`](https://keys.qubes-os.org/keys/qubes-release-3-signing-key.asc)) is used for all Release 3 ISO images. - $ gpg --recv-keys 0x3F01DEF49719158EF86266F80C73B9D40A40E458 - gpg: requesting key 0A40E458 from hkp server keys.gnupg.net - gpg: key 0A40E458: public key "Qubes OS Release 2 Signing Key" imported + $ gpg --recv-keys 0xC52261BE0A823221D94CA1D1CB11CA1D03FA5082 + gpg: requesting key 03FA5082 from hkp server keys.gnupg.net + gpg: key 03FA5082: public key "Qubes OS Release 3 Signing Key" imported gpg: 3 marginal(s) needed, 1 complete(s) needed, PGP trust model gpg: depth: 0 valid: 1 signed: 1 trust: 0-, 0q, 0n, 0m, 0f, 1u gpg: depth: 1 valid: 1 signed: 0 trust: 1-, 0q, 0n, 0m, 0f, 0u @@ -113,23 +113,22 @@ You can also download all the currently used developers' signing keys and curren The developer signing keys are set to be valid for 1 year only, while the Qubes Master Signing Key ([`0x36879494`](https://keys.qubes-os.org/keys/qubes-master-signing-key.asc)) has no expiration date. This latter key was generated and is kept only within a dedicated, air-gapped "vault" machine, and the private portion will (hopefully) never leave this isolated machine. -You can now verify the ISO image (`Qubes-R2-x86_64-DVD.iso`) matches its signature (`Qubes-R2-x86_64-DVD.iso.asc`): +You can now verify the ISO image (`Qubes-R3.1-x86_64.iso`) matches its signature (`Qubes-R3.1-x86_64.iso.asc`): - $ gpg -v --verify Qubes-R2-x86_64-DVD.iso.asc Qubes-R2-x86_64-DVD.iso + $ gpg -v --verify Qubes-R3.1-x86_64.iso.asc Qubes-R3.1-x86_64.iso gpg: armor header: Version: GnuPG v1 - gpg: assuming signed data in `Qubes-R2-x86_64-DVD.iso' - gpg: Signature made Tue Sep 23 08:38:40 2014 UTC using RSA key ID 0A40E458 + gpg: Signature made Tue 08 Mar 2016 07:40:56 PM PST using RSA key ID 03FA5082 gpg: using PGP trust model - gpg: Good signature from "Qubes OS Release 2 Signing Key" - gpg: binary signature, digest algorithm SHA1 + gpg: Good signature from "Qubes OS Release 3 Signing Key" + gpg: binary signature, digest algorithm SHA256 -The Release 2 Signing Key ([`0x0A40E458`](https://keys.qubes-os.org/keys/qubes-release-2-signing-key.asc)) used to sign this ISO image should be signed by the Qubes Master Signing Key ([`0x36879494`](https://keys.qubes-os.org/keys/qubes-master-signing-key.asc)): +The Release 3 Signing Key ([`0x03FA5082`](https://keys.qubes-os.org/keys/qubes-release-3-signing-key.asc)) used to sign this ISO image should be signed by the Qubes Master Signing Key ([`0x36879494`](https://keys.qubes-os.org/keys/qubes-master-signing-key.asc)): - $ gpg --list-sig 0A40E458 - pub 4096R/0A40E458 2012-11-15 - uid Qubes OS Release 2 Signing Key - sig 36879494 2012-11-15 Qubes Master Signing Key - sig 3 0A40E458 2012-11-15 Qubes OS Release 2 Signing Key + $ gpg --list-sig 03FA5082 + pub 4096R/03FA5082 2014-11-19 + uid Qubes OS Release 3 Signing Key + sig 3 03FA5082 2014-11-19 Qubes OS Release 3 Signing Key + sig 36879494 2014-11-19 Qubes Master Signing Key Having problems verifying the ISO images? Make sure you have the corresponding release signing key and see this thread: @@ -138,58 +137,58 @@ Having problems verifying the ISO images? Make sure you have the corresponding r Verifying Digests ----------------- -Each ISO is accompanied by a plain text file ending in `.DIGESTS`. This file contains the output of running several different crytographic hash functions on the ISO in order to obtain alphanumeric outputs known as "digests." For example, `Qubes-R2-x86_64-DVD.iso` is accompanied by `Qubes-R2-x86_64-DVD.iso.DIGESTS` which has the following content: +Each ISO is accompanied by a plain text file ending in `.DIGESTS`. This file contains the output of running several different crytographic hash functions on the ISO in order to obtain alphanumeric outputs known as "digests." For example, `Qubes-R3.1-x86_64.iso` is accompanied by `Qubes-R3.1-x86_64.iso.DIGESTS` which has the following content: - -----BEGIN PGP SIGNED MESSAGE----- Hash: SHA256 - - 6f6ff24f2edec3a7607671001e694d8e *Qubes-R2-x86_64-DVD.iso - 0344e04a98b741c311936f3e2bb67fcebfc2be08 *Qubes-R2-x86_64-DVD.iso - 1fa056b73d8e2e93acdf3dcaface2515d61335e723d1d7d338241209119c10a3 *Qubes-R2-x86_64-DVD.iso - a49ff19c1ad8c51a50198ac51670cf7c71972b437fa59f2e9fc9432cce76f4529f10de1d576ac777cdd49b9325eb2f32347fd13e0f9b04f823a73e84c6ddd772 *Qubes-R2-x86_64-DVD.iso + + f99634b05d15f6bb2ac02ee03e4338a0 *Qubes-R3.1-x86_64.iso + 990b7765ee209b42b3cad78673463daae769c729 *Qubes-R3.1-x86_64.iso + 2d82a684d507ad5789ed83272af4311fd04375e782364d5dd9df4b3d7118cc28 *Qubes-R3.1-x86_64.iso + 083d6cfc3fb5dc97fd91d8f9f70301c154e3674114ff1727b0415c2c663b233c22e0830d0bfc1f7a532549d7e39c6ef5cfde6a90a650343b47ba57d3e8e92ca7 *Qubes-R3.1-x86_64.iso -----BEGIN PGP SIGNATURE----- Version: GnuPG v1 - - iQIcBAEBCAAGBQJVvUfGAAoJEAxzudQKQORYhj0P/1TTtDn0WtlfwvSOQ5m3ybeT - CiEv/wWZmZR2hfTOs1chlwt5PZFUCkAk6hbr7+AbJU3HurnmyK97ORtak0WcuBiO - 3MWKGiDaBGjKfYcv7YZWDcMRCjN69I4gq7lhXB2JC5pSnOkciD8xzSMAnyFz8Dnh - sHSGJIrOIeLhj0Jt90NGm2CKeQgKrbCGQWWqn/BRf40GXjkyGDSAj+Bsbnpn3LjE - kWOblX631PRi8eclD27/b5hsK/ur7RlpA0KKn7dJoTO2PikEZRoT7QgcIMxYWOja - GZhDi/5gWyttVmF1EszkwaYLAH3uqkZbgKHIsLwweTwXYxMqjobQ5dFkm0RCaXXg - wf/ayfyAIHCWYK0GvyHyAe7hs30UQ4Ssw0LDnnTsOwJYzxZpZqWhcg89EBMGdNgu - 5sghcj97VHjDI/zpRyTOAi1+8ZoG1FMsvmnlpghojXPcFGM1nldKs2k1XfGHdVrH - ucJfhQilhsGo65EiN+v9VS6tz5dDtX5+NnkkpR5mOx1+xwUf4n+F6cWyIiLKY6Se - byIN0dPtErZpq47w6bhLZ3Dd/frReG8Egmr7yLAqGHKmuwvmEUA6w6a2VzWQy5G4 - Smcj5kPHKWJ9SvAQHc7SoUmYqt2GEAKBi6CYb5Oeknf3vc4QUSPxF8KRiebUhTxc - ruycSbLkLklsDjfH0caD - =NVWj + + iQIcBAEBCAAGBQJW4AqUAAoJEMsRyh0D+lCCo+cP/A/96SmGSPmnMxIor0ODsZNh + HtGCfFPhB2KnpLMOVUMRidoMWTzL1+J7HpWYdOS7hPhlcbDfX4A0C4QCs4b0Wkc7 + npha/GabQuek0HSi2uKt2YQtADq9yPjpqhc3Q2crbnL9UPmKv/XdECfpnK9zSRAE + RKl7Uj5RAPuLQ7ee4uQ8lIXWUm6IljpHnm4cG+WP2QYLCkS8BWq18Bl9s0fKdj47 + JzIkhpyc6Vr9a7UBBxghF+Cb9WrPy22sTtE7eQYHRibh38xdMPOw0tb9F6AMAVeC + hK6+xJVz+7xERtRWTQPk4LOPeHIU21xJyVipkwb+T0SrQgsNwSXsSGPe0PiNU9Xk + khMbKGcbA+rnQiCS/9EKORNyULRAHvD6WXUqNyIS9trhcx49fxU8taPXKze947p1 + XvWbqBWHIcCvKVQ3t/okmNN7OXfUCIDJ9bx+qyoLsIU2BF/aZZv+5ijK26D3H+xQ + G+2DMIynDMOlHSioCM3I1M0Ml5sB21G0VMJF9r9r8RrDop5cVGdgksie0JvpZ/ep + N/L7ozf1gvrO2euVslelMOUJcBjeisT214g6/DNjQ9Ox5SkDWIXrS2ZtR/zToApg + x3T0IusOQQhdpC8I0nnXPL/tgyRV8UFNBhxIec7IKnGwvQlVYMFYVomPh7vJhfdl + GMMP3JlFAaxghZWU14+F + =FiJ5 -----END PGP SIGNATURE----- Four digests have been computed for this ISO. The hash functions used, in order from top to bottom, are MD5, SHA1, SHA256, and SHA512. One way to verify that the ISO you downloaded matches any of these is by using `openssl` from the command line: - $ openssl dgst -md5 Qubes-R2-x86_64-DVD.iso - MD5(Qubes-R2-x86_64-DVD.iso)= 6f6ff24f2edec3a7607671001e694d8e - $ openssl dgst -sha1 Qubes-R2-x86_64-DVD.iso - SHA1(Qubes-R2-x86_64-DVD.iso)= 0344e04a98b741c311936f3e2bb67fcebfc2be08 - $ openssl dgst -sha256 Qubes-R2-x86_64-DVD.iso - SHA256(Qubes-R2-x86_64-DVD.iso)= 1fa056b73d8e2e93acdf3dcaface2515d61335e723d1d7d338241209119c10a3 - $ openssl dgst -sha512 Qubes-R2-x86_64-DVD.iso - SHA512(Qubes-R2-x86_64-DVD.iso)= a49ff19c1ad8c51a50198ac51670cf7c71972b437fa59f2e9fc9432cce76f4529f10de1d576ac777cdd49b9325eb2f32347fd13e0f9b04f823a73e84c6ddd772 + $ openssl dgst -md5 Qubes-R3.1-x86_64.iso + MD5(Qubes-R3.1-x86_64.iso)= f99634b05d15f6bb2ac02ee03e4338a0 + $ openssl dgst -sha1 Qubes-R3.1-x86_64.iso + SHA1(Qubes-R3.1-x86_64.iso)= 990b7765ee209b42b3cad78673463daae769c729 + $ openssl dgst -sha256 Qubes-R3.1-x86_64.iso + SHA256(Qubes-R3.1-x86_64.iso)= 2d82a684d507ad5789ed83272af4311fd04375e782364d5dd9df4b3d7118cc28 + $ openssl dgst -sha512 Qubes-R3.1-x86_64.iso + SHA512(Qubes-R3.1-x86_64.iso)= + 083d6cfc3fb5dc97fd91d8f9f70301c154e3674114ff1727b0415c2c663b233c22e0830d0bfc1f7a532549d7e39c6ef5cfde6a90a650343b47ba57d3e8e92ca7 (Notice that the outputs match the values from the `.DIGESTS` file.) -However, it is possible that an attacker replaced `Qubes-R2-x86_64-DVD.iso` with a malicious ISO, computed the hash values for that ISO, and replaced the values in `Qubes-R2-x86_64-DVD.iso.DIGESTS` with his own set of values. Therefore, ideally, we should also verify the authenticity of the listed hash values. Since `Qubes-R2-x86_64-DVD.iso.DIGESTS` is a clearsigned PGP file, we can use `gpg` to verify it from the command line: +However, it is possible that an attacker replaced `Qubes-R3.1-x86_64.iso` with a malicious ISO, computed the hash values for that ISO, and replaced the values in `Qubes-R3.1-x86_64.iso.DIGESTS` with his own set of values. Therefore, ideally, we should also verify the authenticity of the listed hash values. Since `Qubes-R3.1-x86_64.iso.DIGESTS` is a clearsigned PGP file, we can use `gpg` to verify it from the command line: - $ gpg -v --verify Qubes-R2-x86_64-DVD.iso.DIGESTS + $ gpg -v --verify Qubes-R3.1-x86_64.iso.DIGESTS gpg: armor header: Hash: SHA256 gpg: armor header: Version: GnuPG v1 gpg: original file name='' - gpg: Signature made 2015-08-01T22:27:18 UTC using RSA key ID 0A40E458 + gpg: Signature made Wed 09 Mar 2016 03:35:48 AM PST using RSA key ID 03FA5082 gpg: using PGP trust model - gpg: Good signature from "Qubes OS Release 2 Signing Key" + gpg: Good signature from "Qubes OS Release 3 Signing Key" gpg: textmode signature, digest algorithm SHA256 -The signature is good. Assuming our copy of the `Qubes OS Release 2 Signing Key` is also authentic (see above), we can be confident that these hash values came from the Qubes devs. +The signature is good. Assuming our copy of the `Qubes OS Release 3 Signing Key` is also authentic (see above), we can be confident that these hash values came from the Qubes devs. Verifying Qubes Code -------------------- From d032507d55b8d9284d800ea93076341efe16b65c Mon Sep 17 00:00:00 2001 From: ttasket Date: Fri, 3 Jun 2016 08:13:51 -0400 Subject: [PATCH 002/708] Add instructions for re-install package I needed to reinstall in dom0 but didn't see the procedure here... Found it in the mailing list. --- common-tasks/software-update-dom0.md | 22 +++++++++++++++++++++- 1 file changed, 21 insertions(+), 1 deletion(-) diff --git a/common-tasks/software-update-dom0.md b/common-tasks/software-update-dom0.md index c9bd1dcb..ebf6a2f9 100644 --- a/common-tasks/software-update-dom0.md +++ b/common-tasks/software-update-dom0.md @@ -60,12 +60,32 @@ Of course, command line tools are still available for accomplishing various upda Yum will say that there is no update, but the package will nonetheless be downloaded to dom0. -1. Downgrade the packge: +2. Downgrade the package: ~~~ sudo yum downgrade package-version ~~~ +### How to re-install a package + +You can re-install in a similar fashion to downgrading. + +1. Download the package: + + ~~~ + sudo qubes-dom0-update package + ~~~ + + Yum will say that there is no update, but the package will nonetheless be downloaded to dom0. + +2. Re-install the package: + + ~~~ + sudo yum reinstall package + ~~~ + + Note that yum will only re-install if the installed and downloaded versions match. You can ensure they match by either updating the package to the latest version, or specifying the package version in the first step using the form _package-version_. + ### How to uninstall a package If you've installed a package such as anti-evil-maid, you can remove it with the following command: From aa858ba13a71f59f7a3eb21e9fec6ec9a3ae7688 Mon Sep 17 00:00:00 2001 From: Michael Carbone Date: Fri, 3 Jun 2016 16:02:08 +0000 Subject: [PATCH 003/708] improve readability --- privacy/tails.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/privacy/tails.md b/privacy/tails.md index 8227fed8..ec42f35e 100644 --- a/privacy/tails.md +++ b/privacy/tails.md @@ -9,13 +9,13 @@ redirect_from: Running Tails in Qubes ============================ -Tails is the amnesic incognito live system. Its aims are preserving privacy and anonymity. +[Tails](https://tails.boum.org) is the amnesic incognito live system. It is a live operating system that aims to preserve your privacy and anonymity. To run Tails under Qubes: 1. Read about [creating and using HVM qubes](https://www.qubes-os.org/doc/hvm/) -2. Download and verify Tails from http://tails.boum.org in a qube, (saved as `/home/user/Downloads/tails.iso` on qube "isoVM" for purposes of this guide). +2. Download and verify Tails from [https://tails.boum.org](https://tails.boum.org) in a qube, (saved as `/home/user/Downloads/tails.iso` on qube "isoVM" for purposes of this guide). 3. Create a HVM @@ -33,24 +33,24 @@ To run Tails under Qubes: 6. Once the Tails qube has started, configure networking in the qube. - - Check the IP address allocated to the qube - either from GUI Manager, or ```qvm-ls -n Tails``` in Konsole. (E.g. 10.137.1.101 with gateway 10.137.1.1) + - Check the IP address allocated to the qube - either from GUI Manager, or ```qvm-ls -n Tails``` in Konsole. (E.g. `10.137.1.101` with gateway `10.137.1.1`) - In the Tails qube, open systems menu in top-right corner. Select "Wired Settings", and change IPv4 configuration from "Automatic (DHCP)" to "Manual". - - Enter the Address: 10.137.1.101 in our example. - - Enter the Netmask: 255.255.255.0 - - Enter the Gateway: 10.137.1.1 in our example. - - Enter DNS: 10.137.1.1 in our example. + - Enter the Address: `10.137.1.101` in our example. + - Enter the Netmask: `255.255.255.0` + - Enter the Gateway: `10.137.1.1` in our example. + - Enter DNS: `10.137.1.1` in our example. - Click "Apply". You should now see "Connected". 7. Use Tails as normal. ## Usage Notes -###Display issues: +### Display issues: **Black screen on start up.** This was reported with earlier versions of Tails: I believe the problem is now fixed. If you do encounter this problem, you can try to constrain display settings by appending vga codes to the Tails boot parameters. -(If you do not know the codes, append vga=999, and a helpful prompt will appear.) +(If you do not know the codes, append `vga=999`, and a helpful prompt will appear.) N.B Tails 2.3 does not appear to honour the vga code. @@ -59,15 +59,15 @@ N.B Tails 2.3 does not appear to honour the vga code. This seems to arise because Tails sizes to the height of the screen, but there is a title bar at the top of the window. Either remove the title bar altogether, or move the window upwards using ALT+drag. -###Persistent Volume +### Persistent Volume The persistence tools will not work because Tails has not been launched from USB. The HVM disk(s) can be configured and mounted from within Tails to provide persistent storage. -###Shutdown +### Shutdown The Tails qube will not shut down cleanly. Kill it from the GUI Manager or ```qvm-kill Tails``` in Konsole. -###Security +### Security You will probably want to implement [MAC spoofing](https://www.qubes-os.org/doc/anonymizing-your-mac-address/). Read [the warnings](https://tails.boum.org/doc/advanced_topics/virtualization/) from the Tails team about operating in a virtual machine. From 97a8e60e83bd62ef05c1c6dcad4bd359feec7309 Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Fri, 3 Jun 2016 15:01:34 -0700 Subject: [PATCH 004/708] Restore PGP header --- installing/verifying-signatures.md | 1 + 1 file changed, 1 insertion(+) diff --git a/installing/verifying-signatures.md b/installing/verifying-signatures.md index c56e2696..14cbc946 100644 --- a/installing/verifying-signatures.md +++ b/installing/verifying-signatures.md @@ -139,6 +139,7 @@ Verifying Digests Each ISO is accompanied by a plain text file ending in `.DIGESTS`. This file contains the output of running several different crytographic hash functions on the ISO in order to obtain alphanumeric outputs known as "digests." For example, `Qubes-R3.1-x86_64.iso` is accompanied by `Qubes-R3.1-x86_64.iso.DIGESTS` which has the following content: + -----BEGIN PGP SIGNED MESSAGE----- Hash: SHA256 f99634b05d15f6bb2ac02ee03e4338a0 *Qubes-R3.1-x86_64.iso From 762f4f6a1382b9fd3ee50cbb5a52e0750f1b7c9d Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Fri, 3 Jun 2016 15:18:09 -0700 Subject: [PATCH 005/708] Minor formatting --- common-tasks/software-update-dom0.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/common-tasks/software-update-dom0.md b/common-tasks/software-update-dom0.md index ebf6a2f9..7490ba43 100644 --- a/common-tasks/software-update-dom0.md +++ b/common-tasks/software-update-dom0.md @@ -84,7 +84,7 @@ You can re-install in a similar fashion to downgrading. 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 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 From 9de28f5e38603e7d9885989cc0e515d3f658576f Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Fri, 3 Jun 2016 15:27:24 -0700 Subject: [PATCH 006/708] Change dd example device --- installing/installation-guide.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/installing/installation-guide.md b/installing/installation-guide.md index 761b5cb0..40f5452e 100644 --- a/installing/installation-guide.md +++ b/installing/installation-guide.md @@ -55,12 +55,13 @@ an installation medium.) If you prefer to use a USB drive, then you just need to copy the ISO onto the USB device, e.g. using `dd`: - dd if=Qubes-R3-x86_64.iso of=/dev/sda + dd if=Qubes-R3-x86_64.iso of=/dev/sdX Change `Qubes-R3-x86_64.iso` to the filename of the version you're installing, -and change `/dev/sda` to the correct target device. **Warning:** Choosing the -wrong device could result in data loss. Make sure to write to the entire device -(e.g., `/dev/sda`) rather than just a single partition (e.g., `/dev/sda1`). +and change `/dev/sdX` to the correct target device (e.g., `/dev/sda`). +**Warning:** Choosing the wrong device could result in data loss. Make sure to +write to the entire device (e.g., `/dev/sda`) rather than just a single +partition (e.g., `/dev/sda1`). On Windows, you can use the [Rufus] tool. Be sure to select "DD image" mode (you need to do that **after** selecting the Qubes ISO): From 4d9a505bea379a5eb7c02a82f9f283221ec9597f Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Sat, 4 Jun 2016 16:56:56 -0700 Subject: [PATCH 007/708] Add link to Feature Development Tracker --- doc.md | 1 + 1 file changed, 1 insertion(+) diff --git a/doc.md b/doc.md index 4d77fd14..4060e4c1 100644 --- a/doc.md +++ b/doc.md @@ -175,6 +175,7 @@ For Developers * [System Documentation](/doc/system-doc/) * [Developers' FAQ](/doc/devel-faq/) + * [Feature Development Tracker](/qubes-issues/) * [Reporting Security Issues](/security/) * [Reporting Bugs](/doc/reporting-bugs/) * [Source Code](/doc/source-code/) From a09ec964ad9447cbc7a7328ccebc16cd358c6dd5 Mon Sep 17 00:00:00 2001 From: ttasket Date: Sat, 4 Jun 2016 20:01:58 -0400 Subject: [PATCH 008/708] Automatic; No manual coding of IP addresses. This requires the user only to add a few lines to their ovpn config file, and copy a few scripts (verbatim). They do not have to figure out which IP addresses are appropriate and hard-code them--unless their VPN service is bereft of domain names. Even in that case, they can do it easily within the ovpn config file. This is much less error-prone and should work with a greater variety of services (large commercial services tend to change their IPs so using domain names and DHCP is preferable in that case). Also converted firewall section (3) to one code block for much less cutting/pasting. Comments are still there as shell comments. The only required template changes are adding openvpn itself and possibly disabling the default systemd service for it. Everything else should be there in /rw/config. This doesn't include extra firewall protections against inadvertent net access from within the VPN VM. I'm thinking of proposing those additions in a separate edit. --- configuration/vpn.md | 159 +++++++++++++++++++++++++++++-------------- 1 file changed, 107 insertions(+), 52 deletions(-) diff --git a/configuration/vpn.md b/configuration/vpn.md index 94ae2060..47e2bec6 100644 --- a/configuration/vpn.md +++ b/configuration/vpn.md @@ -42,7 +42,7 @@ Using a ProxyVM to set up a VPN client gives you the ability to: #### Setup a ProxyVM as a VPN gateway -**Using NetworkManager** +#### Using NetworkManager 1. Create a new VM and check the ProxyVM radio button. @@ -60,73 +60,128 @@ Using a ProxyVM to set up a VPN client gives you the ability to: 5. Optionally, you can install some [custom icons](https://github.com/Zrubi/qubes-artwork-proxy-vpn) for your VPN -**Using iptables and openvpn** - -You need an openvpn server and a DNS server accessible through the vpn (use one from your vpn provider / a public one). +#### Using iptables and openvpn 1. Create a new VM and check the ProxyVM radio button. ![Create\_New\_VM.png](/attachment/wiki/VPN/Create_New_VM.png) + + If your choice of template VM doesn't already have the `openvpn` package, you'll need to install it in the template first. You may also need to `systemctl disable` any openvpn service that comes with the package if you follow the instructions for autostart below. 2. Setup openvpn: - Copy your openvpn config file to `/home/user/vpn.cfg`. + Copy your openvpn config files to `/rw/config/openvpn/` folder. The example main config file is `openvpn-client.ovpn`. - It should have one line starting with `dev` and one starting with `proto`. - The first describes the connection type (`tun` or `tap`) and the second the used protocol (`tcp` or `udp`). - Depending on your connection type, openvpn will create a new network device (probably `tap0` or `tun0`). + It should have one line that reads `dev tun`. - It also contains a line `remote X.X.X.X 1194`, where `X.X.X.X` is the ip of your openvpn server. - - If it does not contain a line `redirect-gateway def1`, add it. - This will route all traffic through your vpn's network device, after a connection was created. - If the connection breaks down all traffic will be routed through the original network device (we will stop this with iptables). - - If your vpn config file contains `auth-user-pass`, change it to `auth-user-pass /home/user/auth.txt` and create a file `/home/user/auth.txt` containing the user name in the first line and the password in the second. - This will enable the vpn to login without requiring you to enter your username and password. - If a different authentication method is used, set it up to require no user input. - The vpn should now start by calling `sudo openvpn --config /home/user/vpn.cfg` and require no additional user input. - - In the following, we use the following placeholder: - `$DEV` For the device created for the connection. - `$PROT` For the protocol used for connection - `$SVR` For the openvpn server's ip. - `$DNS` For the dns server's ip. - - -3. Setup iptables: - Edit `/rw/config/qubes-firewall-user-script` and add: - - `iptables -P OUTPUT DROP` - This blocks all outgoing traffic, if not specified otherwise. + If it does not contain a line `redirect-gateway def1` you may wish to add it. This will route all traffic through your vpn's network device after a connection is created. However, many VPN services will push this instruction to your client automatically -- having a line that says `client` or `pull` in your openvpn config instructs your client to use parameters specified by the VPN server. - `iptables -I OUTPUT -o $DEV -j ACCEPT` - This allows the local system to connect through the vpn (you dont need this). - - `iptables -I OUTPUT -o eth0 -d $SVR -p $PROT --dport 1194 -j ACCEPT` - This allows your system to connect to the vpn server with the protocol `$PROT` under the port 1194. - - `iptables -I OUTPUT -o lo -j ACCEPT` - This allows connections from the system to the system. + NOTE: If the connection breaks down all traffic will by default be routed through the upstream network device eth0 (we will stop this with iptables in step 3). - `iptables -I FORWARD -o eth0 -j DROP` - `iptables -I FORWARD -i eth0 -j DROP` - This blocks forwarding of connections through your plain network device (in case the vpn tunnel breaks). + Also add the following to accomodate a DNS script: + ``` + script-security 2 + up 'qubes-vpn-handler.sh up' + down 'qubes-vpn-handler.sh down' + ``` - `iptables -t nat -I PR-QBS -p udp --dport 53 -j DNAT --to-destination $DNS` - `iptables -t nat -I PR-QBS -p tcp --dport 53 -j DNAT --to-destination $DNS` - This will rewrite the DNS destination, and the traffic will be routed down the vpn tunnel. (to prevent DNS leaks) +3. Setup iptables. + Edit the firewall script with `sudo nano /rw/config/qubes-firewall-user-script` and add: + ``` + #!/bin/bash + # First, block all outgoing traffic + iptables -P OUTPUT DROP + iptables -F OUTPUT + + # 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 openvpn will run as group `qvpn`. + iptables -A OUTPUT -p all -o eth0 -m owner --gid-owner qvpn \ + -m state --state NEW,ESTABLISHED -j ACCEPT + + # Allow queries to DNS server: + iptables -A OUTPUT -p udp -o eth0 --dport 53 -m state --state NEW,ESTABLISHED -j ACCEPT + iptables -A OUTPUT -p tcp -o eth0 --dport 53 -m state --state NEW,ESTABLISHED -j ACCEPT + + # Allow internal system connections: + iptables -I OUTPUT -o lo -j ACCEPT + + # 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 + ``` Now save `/rw/config/qubes-firewall-user-script` and make it executable: `sudo chmod +x /rw/config/qubes-firewall-user-script` + +4. Create the DNS-handling script. + Use `sudo nano /rw/config/openvpn/qubes-vpn-handler.sh` to edit and add: + ``` + #!/bin/bash + set -e + +# Pop-up notification variables +SPID=$(pgrep -U user -f dconf-service) +dbus=$(grep -z DBUS_SESSION_BUS_ADDRESS /proc/$SPID/environ|cut -d= -f2-) +export DBUS_SESSION_BUS_ADDRESS=$dbus + +case "$1" in + +up) + # To override DHCP DNS, assign static DNS addresses with 'setenv vpn_dns' in openvpn config; + # Format is 'X.X.X.X Y.Y.Y.Y [...]' with quotes. + if [[ -z $vpn_dns ]] ; then + # Parses DHCP options from openvpn to set DNS address translation: + for optionname in ${!foreign_option_*} ; do + option="${!optionname}" + unset fops; fops=($option) + if [ ${fops[1]} == "DNS" ] ; then vpn_dns="$vpn_dns ${fops[2]}" ; fi + done + fi + + iptables -t nat -F PR-QBS + if [[ -n $vpn_dns ]] ; then + # Set DNS address translation in firewall: + for addr in $vpn_dns; do + iptables -t nat -A PR-QBS -i vif+ -p udp --dport 53 -j DNAT --to $addr + iptables -t nat -A PR-QBS -i vif+ -p tcp --dport 53 -j DNAT --to $addr + done + su -c 'notify-send "$(hostname): LINK IS UP." --icon=network-idle' user + else + su -c 'notify-send "$(hostname): LINK UP, NO DNS!" --icon=dialog-error' user + fi + + ;; +down) + su -c 'notify-send "$(hostname): LINK IS DOWN !" --icon=dialog-error' user + ;; +esac +``` + + Now save the script and make it executable: + `sudo chmod +x /rw/config/openvpn/qubes-vpn-handler.sh` -4. Setup the vpn's autostart: - Edit to `/rw/config/rc.local`, make it executable (`sudo chmod +x /rw/config/rc.local`) and add: +5. Setup the VPN's autostart: + Use `sudo nano /rw/config/rc.local` to edit and add: + ``` + #!/bin/bash + groupadd -rf qvpn ; sleep 2s + sg qvpn -c 'openvpn --cd /rw/config/openvpn/ --config openvpn-client.ovpn \ + --daemon --writepid /var/run/openvpn/openvpn-client.pid' + ``` + Now save the script and make it executable: + `sudo chmod +x /rw/config/rc.local` + +6. Restart the new VM! - ln -s /home/user/vpn.cfg /etc/openvpn/vpn.conf; - systemctl --no-block start openvpn@vpn.service; - -5. Configure your AppVMs to use the new VM as a NetVM. +7. Configure your AppVMs to use the new VM as a NetVM. ![Settings-NetVM.png](/attachment/wiki/VPN/Settings-NetVM.png) -6. Optionally, you can install some [custom icons](https://github.com/Zrubi/qubes-artwork-proxy-vpn) for your VPN +8. Optionally, you can install some [custom icons](https://github.com/Zrubi/qubes-artwork-proxy-vpn) for your VPN From 88b4097c23e730edfdc39029e8f177bcca814d5d Mon Sep 17 00:00:00 2001 From: ttasket Date: Sat, 4 Jun 2016 22:46:18 -0400 Subject: [PATCH 009/708] Switch to 'su -' envs, quote vars, rm --dport 53 Thanks Marek! --- configuration/vpn.md | 19 +++++-------------- 1 file changed, 5 insertions(+), 14 deletions(-) diff --git a/configuration/vpn.md b/configuration/vpn.md index 47e2bec6..9f82012c 100644 --- a/configuration/vpn.md +++ b/configuration/vpn.md @@ -105,10 +105,6 @@ Using a ProxyVM to set up a VPN client gives you the ability to: iptables -A OUTPUT -p all -o eth0 -m owner --gid-owner qvpn \ -m state --state NEW,ESTABLISHED -j ACCEPT - # Allow queries to DNS server: - iptables -A OUTPUT -p udp -o eth0 --dport 53 -m state --state NEW,ESTABLISHED -j ACCEPT - iptables -A OUTPUT -p tcp -o eth0 --dport 53 -m state --state NEW,ESTABLISHED -j ACCEPT - # Allow internal system connections: iptables -I OUTPUT -o lo -j ACCEPT @@ -126,17 +122,12 @@ Using a ProxyVM to set up a VPN client gives you the ability to: #!/bin/bash set -e -# Pop-up notification variables -SPID=$(pgrep -U user -f dconf-service) -dbus=$(grep -z DBUS_SESSION_BUS_ADDRESS /proc/$SPID/environ|cut -d= -f2-) -export DBUS_SESSION_BUS_ADDRESS=$dbus - case "$1" in up) # To override DHCP DNS, assign static DNS addresses with 'setenv vpn_dns' in openvpn config; # Format is 'X.X.X.X Y.Y.Y.Y [...]' with quotes. - if [[ -z $vpn_dns ]] ; then + if [[ -z "$vpn_dns" ]] ; then # Parses DHCP options from openvpn to set DNS address translation: for optionname in ${!foreign_option_*} ; do option="${!optionname}" @@ -146,20 +137,20 @@ up) fi iptables -t nat -F PR-QBS - if [[ -n $vpn_dns ]] ; then + 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 + 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 + 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 + su - -c 'notify-send "$(hostname): LINK IS DOWN !" --icon=dialog-error' user ;; esac ``` From 9f512be79fe931f91e5cc36ea365c2b15b05b48d Mon Sep 17 00:00:00 2001 From: ttasket Date: Sun, 5 Jun 2016 02:50:54 -0400 Subject: [PATCH 010/708] fedora needs `PATH` assignment --- configuration/vpn.md | 1 + 1 file changed, 1 insertion(+) diff --git a/configuration/vpn.md b/configuration/vpn.md index 9f82012c..3eaf57c6 100644 --- a/configuration/vpn.md +++ b/configuration/vpn.md @@ -121,6 +121,7 @@ Using a ProxyVM to set up a VPN client gives you the ability to: ``` #!/bin/bash set -e + export PATH=$PATH:/usr/sbin:/sbin case "$1" in From fab1c3043c80989d52e615591e30569fc2a183c5 Mon Sep 17 00:00:00 2001 From: ttasket Date: Sun, 5 Jun 2016 02:57:51 -0400 Subject: [PATCH 011/708] quotes --- configuration/vpn.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/configuration/vpn.md b/configuration/vpn.md index 3eaf57c6..bce04f0c 100644 --- a/configuration/vpn.md +++ b/configuration/vpn.md @@ -121,7 +121,7 @@ Using a ProxyVM to set up a VPN client gives you the ability to: ``` #!/bin/bash set -e - export PATH=$PATH:/usr/sbin:/sbin + export PATH="$PATH:/usr/sbin:/sbin" case "$1" in From 9b2ce97fe8102885c8077aec92c43fe59063ecd8 Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Mon, 6 Jun 2016 02:31:37 -0700 Subject: [PATCH 012/708] Fix code block formatting (closes #161) --- configuration/vpn.md | 26 +++++++++++++++----------- 1 file changed, 15 insertions(+), 11 deletions(-) diff --git a/configuration/vpn.md b/configuration/vpn.md index bce04f0c..03f5c986 100644 --- a/configuration/vpn.md +++ b/configuration/vpn.md @@ -87,7 +87,7 @@ Using a ProxyVM to set up a VPN client gives you the ability to: 3. Setup iptables. Edit the firewall script with `sudo nano /rw/config/qubes-firewall-user-script` and add: - ``` + ~~~ #!/bin/bash # First, block all outgoing traffic iptables -P OUTPUT DROP @@ -112,20 +112,22 @@ Using a ProxyVM to set up a VPN client gives you the ability to: # (in case the vpn tunnel breaks): iptables -I FORWARD -o eth0 -j DROP iptables -I FORWARD -i eth0 -j DROP - ``` + ~~~ + Now save `/rw/config/qubes-firewall-user-script` and make it executable: `sudo chmod +x /rw/config/qubes-firewall-user-script` 4. Create the DNS-handling script. Use `sudo nano /rw/config/openvpn/qubes-vpn-handler.sh` to edit and add: - ``` + + ~~~ #!/bin/bash set -e export PATH="$PATH:/usr/sbin:/sbin" -case "$1" in + case "$1" in -up) + up) # To override DHCP DNS, assign static DNS addresses with 'setenv vpn_dns' in openvpn config; # Format is 'X.X.X.X Y.Y.Y.Y [...]' with quotes. if [[ -z "$vpn_dns" ]] ; then @@ -150,23 +152,25 @@ up) fi ;; -down) + down) su - -c 'notify-send "$(hostname): LINK IS DOWN !" --icon=dialog-error' user ;; -esac -``` + esac + ~~~ Now save the script and make it executable: `sudo chmod +x /rw/config/openvpn/qubes-vpn-handler.sh` 5. Setup the VPN's autostart: - Use `sudo nano /rw/config/rc.local` to edit and add: - ``` + Use `sudo nano /rw/config/rc.local` to edit and add: + + ~~~ #!/bin/bash groupadd -rf qvpn ; sleep 2s sg qvpn -c 'openvpn --cd /rw/config/openvpn/ --config openvpn-client.ovpn \ --daemon --writepid /var/run/openvpn/openvpn-client.pid' - ``` + ~~~ + Now save the script and make it executable: `sudo chmod +x /rw/config/rc.local` From a0bee729e147fd19cd32bf2a840ffbe37e6409b6 Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Mon, 6 Jun 2016 02:39:39 -0700 Subject: [PATCH 013/708] Clean up text and fix formatting (closes #162) --- configuration/vpn.md | 19 ++++++++++++------- 1 file changed, 12 insertions(+), 7 deletions(-) diff --git a/configuration/vpn.md b/configuration/vpn.md index 03f5c986..b718a9c8 100644 --- a/configuration/vpn.md +++ b/configuration/vpn.md @@ -40,7 +40,7 @@ Using a ProxyVM to set up a VPN client gives you the ability to: - Separate your VPN credentials from Your AppVM data. - Easily control which of your AppVMs are connected to your VPN by simply setting it as a NetVM of the desired AppVM. -#### Setup a ProxyVM as a VPN gateway +#### Set up a ProxyVM as a VPN gateway #### Using NetworkManager @@ -68,7 +68,8 @@ Using a ProxyVM to set up a VPN client gives you the ability to: If your choice of template VM doesn't already have the `openvpn` package, you'll need to install it in the template first. You may also need to `systemctl disable` any openvpn service that comes with the package if you follow the instructions for autostart below. -2. Setup openvpn: +2. Set up OpenVPN. + Copy your openvpn config files to `/rw/config/openvpn/` folder. The example main config file is `openvpn-client.ovpn`. It should have one line that reads `dev tun`. @@ -78,13 +79,15 @@ Using a ProxyVM to set up a VPN client gives you the ability to: NOTE: If the connection breaks down all traffic will by default be routed through the upstream network device eth0 (we will stop this with iptables in step 3). Also add the following to accomodate a DNS script: - ``` + + ~~~ script-security 2 up 'qubes-vpn-handler.sh up' down 'qubes-vpn-handler.sh down' - ``` + ~~~ + +3. Set up iptables. -3. Setup iptables. Edit the firewall script with `sudo nano /rw/config/qubes-firewall-user-script` and add: ~~~ @@ -110,7 +113,7 @@ Using a ProxyVM to set up a VPN client gives you the ability to: # Block forwarding of connections through upstream network device # (in case the vpn tunnel breaks): - iptables -I FORWARD -o eth0 -j DROP + iptables -I FORWARD -o eth0 -j DROP iptables -I FORWARD -i eth0 -j DROP ~~~ @@ -161,7 +164,8 @@ Using a ProxyVM to set up a VPN client gives you the ability to: Now save the script and make it executable: `sudo chmod +x /rw/config/openvpn/qubes-vpn-handler.sh` -5. Setup the VPN's autostart: +5. Set up the VPN's autostart. + Use `sudo nano /rw/config/rc.local` to edit and add: ~~~ @@ -181,3 +185,4 @@ Using a ProxyVM to set up a VPN client gives you the ability to: ![Settings-NetVM.png](/attachment/wiki/VPN/Settings-NetVM.png) 8. Optionally, you can install some [custom icons](https://github.com/Zrubi/qubes-artwork-proxy-vpn) for your VPN + From ffbe63ac8c6fa3feb06ab78ac88455cc90fb746a Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Mon, 6 Jun 2016 15:58:49 -0700 Subject: [PATCH 014/708] Create "Reinstall Whonix" page --- privacy/whonix-reinstall.md | 54 +++++++++++++++++++++++++++++++++++++ privacy/whonix.md | 3 ++- 2 files changed, 56 insertions(+), 1 deletion(-) create mode 100644 privacy/whonix-reinstall.md diff --git a/privacy/whonix-reinstall.md b/privacy/whonix-reinstall.md new file mode 100644 index 00000000..ba755a37 --- /dev/null +++ b/privacy/whonix-reinstall.md @@ -0,0 +1,54 @@ +--- +layout: doc +title: Reinstall Whonix in Qubes +permalink: /doc/whonix/reinstall/ +--- + +Reinstall Whonix in Qubes +=========================== + +If you suspect your Whonix templates are broken, misconfigured, or compromised, +or if you wish to do a clean reinstall in order to upgrade to a new version, you +can reinstall the Whonix templates from the Qubes repository. This procedure +involves [uninstalling] your Whonix templates, then [installing] them again. + +1. (Optional) Clone your existing `whonix-gw` and `whonix-ws` templates. + + This can be a good idea if you've customized the existing templates and want + to keep them. On the other hand, if you suspect that these templates are + broken, misconfigured, or compromised, you may want to remove them + without cloning them. + +2. (Optional) Temporarily change all VMs based on `whonix-gw` and `whonix-ws` to + another template (e.g., the ones created in the previous step). + + This can be a good idea if you have user data in these VMs that you want to + keep. On the other hand, if you suspect that these VMs (or the templates on + which they are based) are broken, misconfigured, or compromised, you may + want to remove them instead. You can do this in Qubes Manager by + right-clicking on the VM and clicking **Remove VM**, or you can use the + command `qvm-remove ` in dom0. + +3. Uninstall the Whonix templates from dom0: + + $ sudo yum remove qubes-template-whonix-gw + $ sudo yum remove qubes-template-whonix-ws + +4. Reinstall the Whonix templates in dom0: + + $ sudo qubes-dom0-update --enablerepo=qubes-templates-community \ + qubes-template-whonix-gw qubes-template-whonix-ws + +5. If you followed step 2, change the VMs from step 2 back to the new + `whonix-gw` and `whonix-ws`. If you instead removed all VMs based on the old + `whonix-gw` and `whonix-ws`, simply create your desired VMs from the new + templates. + + At a minimum, you'll want a ProxyVM (conventionally called `sys-whonix`) + based on `whonix-gw` and an AppVM based on `whonix-ws` that uses `sys-whonix` + as its NetVM. + + +[uninstalling]: /doc/whonix/uninstall/ +[installing]: /doc/whonix/install/ + diff --git a/privacy/whonix.md b/privacy/whonix.md index dfcca26e..dd60d58c 100644 --- a/privacy/whonix.md +++ b/privacy/whonix.md @@ -29,9 +29,10 @@ To install Whonix, you must have a working Qubes machine already. * [Install Whonix in Qubes](/doc/whonix/install/) * [Updating Whonix in Qubes](/doc/whonix/update/) -## Customizing & Uninstalling Whonix +## Customizing, Reinstalling, & Uninstalling Whonix * [Customizing Whonix](/doc/whonix/customize/) +* [Reinstall Whonix in Qubes](/doc/whonix/reinstall/) * [Uninstall Whonix from Qubes](/doc/whonix/uninstall/) *The following links are on Whonix's website and are technical.* From 9ab0bb9ac2fa7e37b51f3f0062e6bfcbbfe9db88 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Marczykowski-G=C3=B3recki?= Date: Tue, 7 Jun 2016 12:35:11 +0200 Subject: [PATCH 015/708] Update UEFI workaround for Qubes 3.2 QubesOS/qubes-issues#2046 --- troubleshooting/uefi-troubleshooting.md | 27 ++++++++++++++++++------- 1 file changed, 20 insertions(+), 7 deletions(-) diff --git a/troubleshooting/uefi-troubleshooting.md b/troubleshooting/uefi-troubleshooting.md index 7eebc7c9..f2882422 100644 --- a/troubleshooting/uefi-troubleshooting.md +++ b/troubleshooting/uefi-troubleshooting.md @@ -18,15 +18,28 @@ There is some [common bug in UEFI implementation](http://xen.markmail.org/messag 2. At the end of `chainloader` line add `/mapbs /noexitboot`. 3. Perform installation normally, but not reboot system at the end yet. 4. Go to `tty2` (Ctrl-Alt-F2). -5. Execute `mount | grep boot/efi` and note device name (first column). It should be something like `/dev/sda1`. -6. Execute `efibootmgr -v`, search for `Qubes` entry and note its number (it should be something like `Boot0001` - `0001` is an entry number). -7. Replace existing `Qubes` entry with modified one. Replace `XXXX` with entry number from previous step, `/dev/sda` with your disk name and `-p 1` with `/boot/efi` partition number): +5. Enable `/mapbs /noexitboot` on just installed system. This step differs between Qubes releases: + + * for Qubes 3.1: - efibootmgr -b XXXX -B - efibootmgr -v -c -u -L Qubes -l /EFI/qubes/xen.efi -d /dev/sda -p 1 "placeholder /mapbs /noexitboot" + 5. Execute `mount | grep boot/efi` and note device name (first column). It should be something like `/dev/sda1`. + 6. Execute `efibootmgr -v`, search for `Qubes` entry and note its number (it should be something like `Boot0001` - `0001` is an entry number). + 7. Replace existing `Qubes` entry with modified one. Replace `XXXX` with entry number from previous step, `/dev/sda` with your disk name and `-p 1` with `/boot/efi` partition number): -8. Compare new entry with the old one (printed in step 6) - it should only differ in additional options at the end. -9. Now you can reboot the system by issuing `reboot` command. + efibootmgr -b XXXX -B + efibootmgr -v -c -u -L Qubes -l /EFI/qubes/xen.efi -d /dev/sda -p 1 "placeholder /mapbs /noexitboot" + + 8. Compare new entry with the old one (printed in step 6) - it should only differ in additional options at the end. + 9. Now you can reboot the system by issuing `reboot` command. + + * for Qubes 3.2 or later: + + 5. Edit `/mnt/sysimage/boot/efi/EFI/qubes/xen.cfg` (you can use `vi` editor) and add to every kernel section: + + mapbs=1 + noexitboot=1 + + 9. Now you can reboot the system by issuing `reboot` command. System crash/restart when booting installer From 7aa10c45e33081801246e7f59c5c77b625f3614e Mon Sep 17 00:00:00 2001 From: Alexander Earnshaw Date: Wed, 8 Jun 2016 14:42:40 +0000 Subject: [PATCH 016/708] Adding USB Install Instructions Andrew, Here is the submission of the document in the format you requested. I have cut out the areas that cover the normal installation process and focused primary on the USB install topic. Let me know what you think. Thanks, Alexander --- installing/installation-guide.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/installing/installation-guide.md b/installing/installation-guide.md index 40f5452e..5b3b74d7 100644 --- a/installing/installation-guide.md +++ b/installing/installation-guide.md @@ -78,6 +78,23 @@ The installer loads Xen right at the beginning, so chances are high that if you can see the installer's graphical screen, Qubes will work on your system. :) +Installing QubesOS to a USB Drive +---------------------------------- + + Installing an operating system onto a USB drive can be a convenient and secure method of ensuring that your data is protected. Be advised that a minimum storage of 32 GB is required on the USB drive. This installation process may take longer than an installation on a standard hard disk. The installation process is identical to using a hard disk in conjunction with two exceptions: + +* Select the USB as the storage location for the OS. + +* Leave the option checked to “Automatically configure my Qubes installation to the disk(s) I selected and return me to the main menu”. + + +Any issues or questions please report to the Qubes team. + + + + + + Upgrading --------- From a7301797dce8eb6c9d2af1325e3e70d91b03c4c8 Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Wed, 8 Jun 2016 08:17:12 -0700 Subject: [PATCH 017/708] Clean up text --- installing/installation-guide.md | 20 +++++++++----------- 1 file changed, 9 insertions(+), 11 deletions(-) diff --git a/installing/installation-guide.md b/installing/installation-guide.md index 5b3b74d7..f6930014 100644 --- a/installing/installation-guide.md +++ b/installing/installation-guide.md @@ -78,21 +78,19 @@ The installer loads Xen right at the beginning, so chances are high that if you can see the installer's graphical screen, Qubes will work on your system. :) -Installing QubesOS to a USB Drive ----------------------------------- +Installing to a USB drive +------------------------- - Installing an operating system onto a USB drive can be a convenient and secure method of ensuring that your data is protected. Be advised that a minimum storage of 32 GB is required on the USB drive. This installation process may take longer than an installation on a standard hard disk. The installation process is identical to using a hard disk in conjunction with two exceptions: +Installing an operating system onto a USB drive can be a convenient and secure +method of ensuring that your data is protected. Be advised that a minimum +storage of 32 GB is required on the USB drive. This installation process may +take longer than an installation on a standard hard disk. The installation +process is identical to using a hard disk in conjunction with two exceptions: * Select the USB as the storage location for the OS. -* Leave the option checked to “Automatically configure my Qubes installation to the disk(s) I selected and return me to the main menu”. - - -Any issues or questions please report to the Qubes team. - - - - +* Leave the option checked to “Automatically configure my Qubes installation to +the disk(s) I selected and return me to the main menu”. Upgrading From 71e03102eb090d6678fa5baad80fa0cf0bd19fb8 Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Wed, 8 Jun 2016 08:32:49 -0700 Subject: [PATCH 018/708] Standardize list formatting --- troubleshooting/uefi-troubleshooting.md | 37 ++++++++++++------------- 1 file changed, 18 insertions(+), 19 deletions(-) diff --git a/troubleshooting/uefi-troubleshooting.md b/troubleshooting/uefi-troubleshooting.md index f2882422..f4b71aa3 100644 --- a/troubleshooting/uefi-troubleshooting.md +++ b/troubleshooting/uefi-troubleshooting.md @@ -8,38 +8,37 @@ Troubleshooting UEFI related problems ======================================== - Cannot start installation, hangs at four penguins after choosing "Test media and install Qubes OS" in GRUB menu --------------------- There is some [common bug in UEFI implementation](http://xen.markmail.org/message/f6lx2ab4o2fch35r), affecting mostly Lenovo systems, but probably some others too. You can try existing workaround: -1. In GRUB menu[1](#f1) press `e`. -2. At the end of `chainloader` line add `/mapbs /noexitboot`. -3. Perform installation normally, but not reboot system at the end yet. -4. Go to `tty2` (Ctrl-Alt-F2). -5. Enable `/mapbs /noexitboot` on just installed system. This step differs between Qubes releases: +01. In GRUB menu[1](#f1) press `e`. +02. At the end of `chainloader` line add `/mapbs /noexitboot`. +03. Perform installation normally, but not reboot system at the end yet. +04. Go to `tty2` (Ctrl-Alt-F2). +05. Enable `/mapbs /noexitboot` on just installed system. This step differs between Qubes releases: - * for Qubes 3.1: + **For Qubes 3.1:** - 5. Execute `mount | grep boot/efi` and note device name (first column). It should be something like `/dev/sda1`. - 6. Execute `efibootmgr -v`, search for `Qubes` entry and note its number (it should be something like `Boot0001` - `0001` is an entry number). - 7. Replace existing `Qubes` entry with modified one. Replace `XXXX` with entry number from previous step, `/dev/sda` with your disk name and `-p 1` with `/boot/efi` partition number): +06. Execute `mount | grep boot/efi` and note device name (first column). It should be something like `/dev/sda1`. +07. Execute `efibootmgr -v`, search for `Qubes` entry and note its number (it should be something like `Boot0001` - `0001` is an entry number). +08. Replace existing `Qubes` entry with modified one. Replace `XXXX` with entry number from previous step, `/dev/sda` with your disk name and `-p 1` with `/boot/efi` partition number): - efibootmgr -b XXXX -B - efibootmgr -v -c -u -L Qubes -l /EFI/qubes/xen.efi -d /dev/sda -p 1 "placeholder /mapbs /noexitboot" + efibootmgr -b XXXX -B + efibootmgr -v -c -u -L Qubes -l /EFI/qubes/xen.efi -d /dev/sda -p 1 "placeholder /mapbs /noexitboot" - 8. Compare new entry with the old one (printed in step 6) - it should only differ in additional options at the end. - 9. Now you can reboot the system by issuing `reboot` command. +09. Compare new entry with the old one (printed in step 6) - it should only differ in additional options at the end. +10. Now you can reboot the system by issuing `reboot` command. - * for Qubes 3.2 or later: + **For Qubes 3.2 or later:** - 5. Edit `/mnt/sysimage/boot/efi/EFI/qubes/xen.cfg` (you can use `vi` editor) and add to every kernel section: +11. Edit `/mnt/sysimage/boot/efi/EFI/qubes/xen.cfg` (you can use `vi` editor) and add to every kernel section: - mapbs=1 - noexitboot=1 + mapbs=1 + noexitboot=1 - 9. Now you can reboot the system by issuing `reboot` command. +12. Now you can reboot the system by issuing `reboot` command. System crash/restart when booting installer From 4fadbec0c9bcde79fa6b720491c04e1e17388b11 Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Thu, 9 Jun 2016 02:20:55 -0700 Subject: [PATCH 019/708] Document qvm-revert-template-changes Closes QubesOS/qubes-issues#2056 --- common-tasks/software-update-vm.md | 33 ++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) diff --git a/common-tasks/software-update-vm.md b/common-tasks/software-update-vm.md index 7811c416..b6878d9d 100644 --- a/common-tasks/software-update-vm.md +++ b/common-tasks/software-update-vm.md @@ -35,6 +35,39 @@ In order to permanently install new software, you should: - You will see now that all the AppVMs based on this template (by default all your VMs) will be marked as "outdated" in the manager. This is because their fielsystems have not been yet updated -- in order to do that, you must restart each VM. You don't need to restart all of them at the same time -- e.g. if you just need the newly installed software to be available in your 'personal' domain, then restart only this VM. You will restart others whenever this will be convenient to you. +Reverting changes to a TemplateVM +--------------------------------- + +Perhaps you've just updated your TemplateVM, and the update broke your template. +Or perhaps you've made a terrible mistake, like accidentally confirming the +installation of an unsigned package that could be malicious. Fortunately, +it's easy to revert changes to TemplateVMs using the +`qvm-revert-template-changes` command. + +**Important:** This command will roll back any changes made *during the last +time the TemplateVM was run, but **not** before.* This means that if you have +already restarted the TemplateVM, using this command is unlikely to help, and +you'll likely want to reinstall it from the repository instead. On the other +hand, if the template is already broken or compromised, it won't hurt to try +reverting first. Just make sure to **back up** all of your data and changes +first! + +For example, to revert changes to the `fedora-23` TemplateVM: + +1. Shut down all VMs based on `fedora-23`. +2. Shut down `fedora-23`. If you've already just shut it down, do **not** start + it again (see above). +3. In a dom0 terminal, type: + + qvm-revert-template-changes fedora-23 + + If you want to skip the confirmation check, you can add the `--force` option: + + qvm-revert-template-changes --force fedora-23 + +For the technical details about how this command works and the steps it +performs, see [here](/doc/template-implementation/#rollback-template-changes). + Notes on trusting your Template VM(s) ------------------------------------- From a8d09e79f22ba6fae188f60354247e725bb08004 Mon Sep 17 00:00:00 2001 From: Will Morrison Date: Sun, 12 Jun 2016 08:50:34 -0400 Subject: [PATCH 020/708] Spelling and grammatical changes in live-usb.md --- installing/live-usb.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/installing/live-usb.md b/installing/live-usb.md index ad630bfb..c3b25227 100644 --- a/installing/live-usb.md +++ b/installing/live-usb.md @@ -16,8 +16,8 @@ can continue to improve it. Introduction ------------ -We have faced several challenges when making this Live USB edition of Qubes OS, -which traditional Linux distros don't have to bother with: +When making this Live USB edition of Qubes OS, we faced several challenges which +traditional Linux distros don't have to bother with: 1. We needed to ensure Xen is properly started when booting the stick. In fact we still don't support UEFI boot for the stick for this reason, even though @@ -39,20 +39,20 @@ few tens of MBs per VM, sometimes even more. Also, each VM's private image, which essentially holds just the user home directory, typically starts with a few tens of MBs for an "empty VM". Now, while these represent rather insignificant numbers on a disk-basked system, in the case of a live USB all -these files must be stored in RAM, which is a scare resource on any OS, but +these files must be stored in RAM, which is a scarce resource on any OS, but especially on Qubes. We have implemented some quick optimizations in order to minimize the above problem, but this is still far from a proper solution. We're planning to work more on this next. -Now, there are three directions in how we want to work further on this Qubes +There are three directions in which we want to do further work on this Qubes Live USB variant: 1. Introduce an easy, clickable "install to disk" option, merging this with the Qubes installation ISO. So, e.g. make it possible to first see if the given - hardware is compatible with Qubes (run the HCL reporting tool) and only then - install on the main disk. Also, ensure UEFI boot works well. + hardware is compatible with Qubes (by running the HCL reporting tool) and + only then install on the main disk. Also, ensure UEFI boot works well. 2. Introduce options for persistence while still running this out of a USB stick. This would be achieved by allowing (select) VMs' private images to be @@ -74,7 +74,7 @@ Live USB variant: Current limitations ------------------- -(Remember that Qubes Live USB is currently in alpha, so please meter your +(Remember that Qubes Live USB is currently in alpha, so please meter your expectations accordingly.) 1. Currently just the 3 example VMs (untrusted, personal, work), plus the @@ -90,10 +90,10 @@ expectations accordingly.) from a large Qubes backup blob. 5. It's easy to generate Out Of Memory (OOM) in Dom0 by creating lots of VMs which are writing a lot into the VMs filesystem. -6. There is no DispVM savefile, so if one starts one the savefile must be - regenerated which takes about 1-2 minutes. -7. UEFI boot doesn't work, and if you try booting it via UEFI Xen will not be - started, rendering the whole experiment unusable. +6. There is no DispVM savefile, so if you start a DispVM the savefile must be + regenerated, which takes about 1-2 minutes. +7. UEFI boot doesn't work, and if you try booting Qubes Live USB via UEFI, Xen + will not be started, rendering the whole experiment unusable. Downloading and burning From 8741932d5936323a1fcbd7e4e20d44e14305b127 Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Sun, 12 Jun 2016 06:26:58 -0700 Subject: [PATCH 021/708] Generalize whonix-reinstall to apply to all templates --- managing-os/reinstall-template.md | 74 +++++++++++++++++++++++++++++++ privacy/whonix-reinstall.md | 54 ---------------------- 2 files changed, 74 insertions(+), 54 deletions(-) create mode 100644 managing-os/reinstall-template.md delete mode 100644 privacy/whonix-reinstall.md diff --git a/managing-os/reinstall-template.md b/managing-os/reinstall-template.md new file mode 100644 index 00000000..98c72bfc --- /dev/null +++ b/managing-os/reinstall-template.md @@ -0,0 +1,74 @@ +--- +layout: doc +title: How to Reinstall a TemplateVM +permalink: +redirect_from: +- /doc/whonix/reinstall/ +--- + +How to Reinstall a TemplateVM +============================= + +If you suspect your [TemplateVM] is broken, misconfigured, or compromised, +or if you wish to do a clean reinstall in order to upgrade to a new version, you +can reinstall any TemplateVM from the Qubes repository. In what follows, the +phrase "target TemplateVM" refers to whichever TemplateVM you want to reinsatll. +If you want to reinstall more than one TemplateVM, repeat these instructions for +each one. + +1. (Optional) Clone the existing target TemplateVM. + + This can be a good idea if you've customized the existing template and want + to keep your customizations. On the other hand, if you suspect that this + template is broken, misconfigured, or compromised, you may want to remove it + without cloning it. + +2. Create a temporary dummy template: + + mkdir /var/lib/qubes/vm-templates/dummy + touch /var/lib/qubes/vm-templates/dummy/{root.img,private.img} + qvm-add-template dummy + +3. Temporarily change all VMs based on the target TemplateVM to the new dummy + template, or remove them. + + This can be a good idea if you have user data in these VMs that you want to + keep. On the other hand, if you suspect that these VMs (or the templates on + which they are based) are broken, misconfigured, or compromised, you may + want to remove them instead. You can do this in Qubes Manager by + right-clicking on the VM and clicking **Remove VM**, or you can use the + command `qvm-remove ` in dom0. + + Using a dummy template as a temporary template is preferable to using another + real TemplateVM because you can't accidentally boot any VMs from the dummy + template. (There is no OS in the dummy template, so the boot will fail.) + +4. Uninstall the target TemplateVM from dom0: + + $ sudo yum remove + + For example, to uninstall the `whonix-gw` template: + + $ sudo yum remove qubes-template-whonix-gw + +5. Reinstall the target TemplateVM in dom0: + + $ sudo qubes-dom0-update --enablerepo= \ + + + For example, to install the `whonix-gw` template: + + $ sudo qubes-dom0-update --enablerepo=qubes-templates-community \ + qubes-template-whonix-gw + +6. If you temporarily changed all VMs based on the target TemplateVM to the + dummy template in step 3, change them back to the new target TemplateVM now. + If you instead removed all VMs based on the old target TemplateVM, you can + recreate your desired VMs from the newly reinstalled target TemplateVM now. + + At a minimum, you'll want a ProxyVM (conventionally called `sys-whonix`) + based on `whonix-gw` and an AppVM based on `whonix-ws` that uses `sys-whonix` + as its NetVM. + +[TemplateVM]: /doc/templates/ + diff --git a/privacy/whonix-reinstall.md b/privacy/whonix-reinstall.md deleted file mode 100644 index ba755a37..00000000 --- a/privacy/whonix-reinstall.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -layout: doc -title: Reinstall Whonix in Qubes -permalink: /doc/whonix/reinstall/ ---- - -Reinstall Whonix in Qubes -=========================== - -If you suspect your Whonix templates are broken, misconfigured, or compromised, -or if you wish to do a clean reinstall in order to upgrade to a new version, you -can reinstall the Whonix templates from the Qubes repository. This procedure -involves [uninstalling] your Whonix templates, then [installing] them again. - -1. (Optional) Clone your existing `whonix-gw` and `whonix-ws` templates. - - This can be a good idea if you've customized the existing templates and want - to keep them. On the other hand, if you suspect that these templates are - broken, misconfigured, or compromised, you may want to remove them - without cloning them. - -2. (Optional) Temporarily change all VMs based on `whonix-gw` and `whonix-ws` to - another template (e.g., the ones created in the previous step). - - This can be a good idea if you have user data in these VMs that you want to - keep. On the other hand, if you suspect that these VMs (or the templates on - which they are based) are broken, misconfigured, or compromised, you may - want to remove them instead. You can do this in Qubes Manager by - right-clicking on the VM and clicking **Remove VM**, or you can use the - command `qvm-remove ` in dom0. - -3. Uninstall the Whonix templates from dom0: - - $ sudo yum remove qubes-template-whonix-gw - $ sudo yum remove qubes-template-whonix-ws - -4. Reinstall the Whonix templates in dom0: - - $ sudo qubes-dom0-update --enablerepo=qubes-templates-community \ - qubes-template-whonix-gw qubes-template-whonix-ws - -5. If you followed step 2, change the VMs from step 2 back to the new - `whonix-gw` and `whonix-ws`. If you instead removed all VMs based on the old - `whonix-gw` and `whonix-ws`, simply create your desired VMs from the new - templates. - - At a minimum, you'll want a ProxyVM (conventionally called `sys-whonix`) - based on `whonix-gw` and an AppVM based on `whonix-ws` that uses `sys-whonix` - as its NetVM. - - -[uninstalling]: /doc/whonix/uninstall/ -[installing]: /doc/whonix/install/ - From 85c5eda80c0b61795fa75516f68948ceef1a62f7 Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Sun, 12 Jun 2016 07:45:37 -0700 Subject: [PATCH 022/708] Update manual USB qube creation instructions Also: Fix broken link to Assigning Devices page This commit updates the manual USB qube creation instructions based on user feedback from this discussion thread: https://groups.google.com/d/topic/qubes-users/mPPZy57kw0w/discussion --- common-tasks/usb.md | 28 ++++++++++++++++++++-------- 1 file changed, 20 insertions(+), 8 deletions(-) diff --git a/common-tasks/usb.md b/common-tasks/usb.md index d6e7ec4c..be2a4b6f 100644 --- a/common-tasks/usb.md +++ b/common-tasks/usb.md @@ -28,7 +28,7 @@ Qubes OS supports the ability to attach a USB drive (or just one or more of its partitions) to any qube easily, no matter which qube actually handles the USB controller. (The USB controller may be assigned on the **Devices** tab of a qube's settings page in Qubes VM Manager or by using the -[qvm-pci][assigning-devices] command. For guidance on finding the correct USB +[qvm-pci][Assigning Devices] command. For guidance on finding the correct USB controller, see [here][usb-controller].) USB drive mounting is integrated into the Qubes VM Manager GUI. Simply insert @@ -182,13 +182,25 @@ steps as root in dom0: Alternatively, you can create a USB qube manually as follows: - 1. In a dom0 terminal, type `lsusb` to check if you have a USB controller free - of input devices or programmable devices. If you find such free controller, - note its name and proceed to step 2. + 1. Read the [Assigning Devices] page to learn how to list and identify your + USB controllers. Carefully check whether you have a USB controller that + would be appropriate to assign to a USB qube. Note that it should be free + of input devices, programmable devices, and any other devices that must be + directly available to dom0. If you find a free controller, note its name + and proceed to step 2. 2. Create a new qube. Give it an appropriate name and color label - (recommended: `sys-usb`, red). - 3. In the qube's settings, go to the "Devices" tab. Find your USB controller - in the "Available" list. Move it to the "Selected" list. + (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 @@ -242,7 +254,7 @@ You can now use your USB keyboard. [mass-storage]: https://en.wikipedia.org/wiki/USB_mass_storage_device_class -[devices]: /doc/assigning-devices/ +[Assigning Devices]: /doc/assigning-devices/ [usb-controller]: /doc/assigning-devices/#finding-the-right-usb-controller [623]: https://github.com/QubesOS/qubes-issues/issues/623 [1072-comm1]: https://github.com/QubesOS/qubes-issues/issues/1072#issuecomment-124270051 From b633b720337f83d3c2731433b54b03705a16cde4 Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Sun, 12 Jun 2016 10:47:43 -0700 Subject: [PATCH 023/708] Remove old Whonix-specific sentence --- managing-os/reinstall-template.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/managing-os/reinstall-template.md b/managing-os/reinstall-template.md index 98c72bfc..8479a71f 100644 --- a/managing-os/reinstall-template.md +++ b/managing-os/reinstall-template.md @@ -66,9 +66,5 @@ each one. If you instead removed all VMs based on the old target TemplateVM, you can recreate your desired VMs from the newly reinstalled target TemplateVM now. - At a minimum, you'll want a ProxyVM (conventionally called `sys-whonix`) - based on `whonix-gw` and an AppVM based on `whonix-ws` that uses `sys-whonix` - as its NetVM. - [TemplateVM]: /doc/templates/ From 61407aec0a2a479383e17093ee08e42947d64430 Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Sun, 12 Jun 2016 10:53:03 -0700 Subject: [PATCH 024/708] Set permalink --- managing-os/reinstall-template.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/managing-os/reinstall-template.md b/managing-os/reinstall-template.md index 8479a71f..975cbd39 100644 --- a/managing-os/reinstall-template.md +++ b/managing-os/reinstall-template.md @@ -1,7 +1,7 @@ --- layout: doc title: How to Reinstall a TemplateVM -permalink: +permalink: /doc/reinstall-template/ redirect_from: - /doc/whonix/reinstall/ --- From 967765281085c70d64ce7ec5900f5b9569b3948e Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Sun, 12 Jun 2016 10:53:28 -0700 Subject: [PATCH 025/708] Add link to Reinstall page --- managing-os/templates.md | 1 + 1 file changed, 1 insertion(+) diff --git a/managing-os/templates.md b/managing-os/templates.md index 6837e739..39c09d60 100644 --- a/managing-os/templates.md +++ b/managing-os/templates.md @@ -27,6 +27,7 @@ available only as source code, which can be built using are available in source code form only. Take a look at the [Qubes Builder documentation](/doc/qubes-builder/) for instructions on how to compile them. +To reinstall a currently installed TemplateVM, see [here](/doc/reinstall-template/). ITL Supported templates ----------------------- From 485bd1d7f7ae3554495aa9ecf32c3b04017dbe12 Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Sun, 12 Jun 2016 10:53:51 -0700 Subject: [PATCH 026/708] Remove link to old Reinstall page --- privacy/whonix.md | 1 - 1 file changed, 1 deletion(-) diff --git a/privacy/whonix.md b/privacy/whonix.md index dd60d58c..06565e86 100644 --- a/privacy/whonix.md +++ b/privacy/whonix.md @@ -32,7 +32,6 @@ To install Whonix, you must have a working Qubes machine already. ## Customizing, Reinstalling, & Uninstalling Whonix * [Customizing Whonix](/doc/whonix/customize/) -* [Reinstall Whonix in Qubes](/doc/whonix/reinstall/) * [Uninstall Whonix from Qubes](/doc/whonix/uninstall/) *The following links are on Whonix's website and are technical.* From 4a50b0179ef715c51869644ed1dc482da3be7b27 Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Sun, 12 Jun 2016 10:54:07 -0700 Subject: [PATCH 027/708] Add ToC entry for new Reinstall page --- doc.md | 1 + 1 file changed, 1 insertion(+) diff --git a/doc.md b/doc.md index 4060e4c1..cbfdcbd8 100644 --- a/doc.md +++ b/doc.md @@ -63,6 +63,7 @@ Managing Operating Systems within Qubes * [Templates: Archlinux](/doc/templates/archlinux/) * [Templates: Ubuntu](/doc/templates/ubuntu/) * [Templates: Whonix](/doc/whonix/) + * [How to Reinstall a TemplateVM](/doc/reinstall-template) * [Installing and Using Windows-based AppVMs (Qubes R2 Beta 3 and later)](/doc/windows-appvms/) * [Creating and Using HVM and Windows Domains (Qubes R2+)](/doc/hvm/) * [Advanced options and troubleshooting of Qubes Tools for Windows (R3)](/doc/windows-tools-3/) From c664629e4b053f93ce41a0e7358846555a141ad9 Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Sun, 12 Jun 2016 11:31:52 -0700 Subject: [PATCH 028/708] Create section on dom0 testing repos --- common-tasks/software-update-dom0.md | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/common-tasks/software-update-dom0.md b/common-tasks/software-update-dom0.md index 7490ba43..2f22d011 100644 --- a/common-tasks/software-update-dom0.md +++ b/common-tasks/software-update-dom0.md @@ -94,6 +94,29 @@ If you've installed a package such as anti-evil-maid, you can remove it with the sudo yum remove anti-evil-maid ~~~ +### Testing repositories + +There are three Qubes dom0 testing repoistories: + +* `current-testing` -- testing packages that will eventually land in the stable + (`current`) repository +* `security-testing` -- a subset of `current-testing` that contains packages + that qualify as security fixes +* `unstable` -- packages that are not intended to land in the stable (`current`) + repository; mostly experimental debugging packages + +To temporarily enable any of these repos, use the `--enablerepo=` +option. Example commands: + +~~~ +sudo qubes-dom0-update --enablerepo=qubes-dom0-current-testing +sudo qubes-dom0-update --enablerepo=qubes-dom0-security-testing +sudo qubes-dom0-update --enablerepo=qubes-dom0-unstable +~~~ + +To enable any of these repos permanently, change the corresponding boolean in +`/etc/yum.repos.d/qubes-dom0.repo`. + ### Kernel Upgrade ### Install newer kernel. The following example installs kernel 3.19 and was tested on Qubes R3 RC1. From 1585c5cc6729ef971e01c806d447feda1a25ac52 Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Sun, 12 Jun 2016 11:32:25 -0700 Subject: [PATCH 029/708] Fix formatting --- common-tasks/software-update-dom0.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/common-tasks/software-update-dom0.md b/common-tasks/software-update-dom0.md index 2f22d011..a3dd7e45 100644 --- a/common-tasks/software-update-dom0.md +++ b/common-tasks/software-update-dom0.md @@ -90,9 +90,7 @@ You can re-install in a similar fashion to downgrading. If you've installed a package such as anti-evil-maid, you can remove it with the following command: - ~~~ sudo yum remove anti-evil-maid - ~~~ ### Testing repositories From 3abcd5776e008ac727f84fb9de8fbdf5c029c754 Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Sun, 12 Jun 2016 11:35:23 -0700 Subject: [PATCH 030/708] Use full repo names --- common-tasks/software-update-dom0.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/common-tasks/software-update-dom0.md b/common-tasks/software-update-dom0.md index a3dd7e45..27857056 100644 --- a/common-tasks/software-update-dom0.md +++ b/common-tasks/software-update-dom0.md @@ -96,11 +96,11 @@ If you've installed a package such as anti-evil-maid, you can remove it with the There are three Qubes dom0 testing repoistories: -* `current-testing` -- testing packages that will eventually land in the stable +* `qubes-dom0-current-testing` -- testing packages that will eventually land in the stable (`current`) repository -* `security-testing` -- a subset of `current-testing` that contains packages +* `qubes-dom0-security-testing` -- a subset of `qubes-dom0-current-testing` that contains packages that qualify as security fixes -* `unstable` -- packages that are not intended to land in the stable (`current`) +* `qubes-dom0-unstable` -- packages that are not intended to land in the stable (`qubes-dom0-current`) repository; mostly experimental debugging packages To temporarily enable any of these repos, use the `--enablerepo=` From 4f0aad927024dbcafff437c6e5e5b08adeccac6a Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Sun, 12 Jun 2016 11:39:09 -0700 Subject: [PATCH 031/708] Create section on VM testing repos --- common-tasks/software-update-vm.md | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/common-tasks/software-update-vm.md b/common-tasks/software-update-vm.md index b6878d9d..12e8866b 100644 --- a/common-tasks/software-update-vm.md +++ b/common-tasks/software-update-vm.md @@ -35,6 +35,30 @@ In order to permanently install new software, you should: - You will see now that all the AppVMs based on this template (by default all your VMs) will be marked as "outdated" in the manager. This is because their fielsystems have not been yet updated -- in order to do that, you must restart each VM. You don't need to restart all of them at the same time -- e.g. if you just need the newly installed software to be available in your 'personal' domain, then restart only this VM. You will restart others whenever this will be convenient to you. +Testing repositories +-------------------- + +There are three Qubes VM testing repoistories (where `*` denotes the Release): + +* `qubes-vm-*-current-testing` -- testing packages that will eventually land in the stable + (`current`) repository +* `qubes-vm-*-security-testing` -- a subset of `qubes-vm-*-current-testing` that contains packages + that qualify as security fixes +* `qubes-vm-*-unstable` -- packages that are not intended to land in the stable (`qubes-vm-*-current`) + repository; mostly experimental debugging packages + +To temporarily enable any of these repos, use the `--enablerepo=` +option. Example commands: + +~~~ +sudo dnf upgrade --enablerepo=qubes-vm-*-current-testing +sudo dnf upgrade --enablerepo=qubes-vm-*-security-testing +sudo dnf upgrade --enablerepo=qubes-vm-*-unstable +~~~ + +To enable or disable any of these repos permanently, change the corresponding boolean in +`/etc/yum.repos.d/qubes-*.repo`. + Reverting changes to a TemplateVM --------------------------------- From 5189bb00394d762922196848ac07083829cb9fde Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Sun, 12 Jun 2016 11:41:36 -0700 Subject: [PATCH 032/708] Clarify that testing repos can be enabled or disabled --- common-tasks/software-update-dom0.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/common-tasks/software-update-dom0.md b/common-tasks/software-update-dom0.md index 27857056..1f806b15 100644 --- a/common-tasks/software-update-dom0.md +++ b/common-tasks/software-update-dom0.md @@ -112,7 +112,7 @@ sudo qubes-dom0-update --enablerepo=qubes-dom0-security-testing sudo qubes-dom0-update --enablerepo=qubes-dom0-unstable ~~~ -To enable any of these repos permanently, change the corresponding boolean in +To enable or disable any of these repos permanently, change the corresponding boolean in `/etc/yum.repos.d/qubes-dom0.repo`. ### Kernel Upgrade ### From b4b3d282b98cb5d7d644bd02a6a3963ee7f32ff4 Mon Sep 17 00:00:00 2001 From: Jeepler Date: Mon, 13 Jun 2016 19:24:23 -0500 Subject: [PATCH 033/708] pentesting --- customization/dark-theme.md | 12 ++ managing-os/kali.md | 60 -------- managing-os/pentesting.md | 19 +++ managing-os/pentesting/blackarch.md | 96 ++++++++++++ managing-os/pentesting/kali.md | 230 ++++++++++++++++++++++++++++ managing-os/pentesting/ptf.md | 126 +++++++++++++++ 6 files changed, 483 insertions(+), 60 deletions(-) create mode 100644 customization/dark-theme.md delete mode 100644 managing-os/kali.md create mode 100644 managing-os/pentesting.md create mode 100644 managing-os/pentesting/blackarch.md create mode 100644 managing-os/pentesting/kali.md create mode 100644 managing-os/pentesting/ptf.md diff --git a/customization/dark-theme.md b/customization/dark-theme.md new file mode 100644 index 00000000..4dada153 --- /dev/null +++ b/customization/dark-theme.md @@ -0,0 +1,12 @@ +--- +layout: doc +title: Qubes OS Dark Theme +permalink: /doc/dark-theme/ +--- + +Dark KDE in dom0 +---------------- + + +Dark Qube (VM) +-------------- diff --git a/managing-os/kali.md b/managing-os/kali.md deleted file mode 100644 index 466f4806..00000000 --- a/managing-os/kali.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -layout: doc -title: How to create a Kali Linux VM -permalink: /doc/kali/ ---- - -How to Create a Kali Linux VM -============================= - -This guide is being created to give guidance on ways in which you could implement Kali Pen-Testing distrubution within Qubes-OS. - -There are multiple ways in which this can be achieved, for example you could create a HVM and use the ISO to install the system straight to that virtual machine. - - -Build Based on Debian Template ---- - -1 - Install debian-8 template (if not already installed) - -2 - Clone debian-8 template - -3 - Add kali repo to /etc/apt/sources.list: - - * deb http://http.kali.org/kali kali-rolling main non-free contrib - -4 - Find and add kali signing keys: - - * gpg --keyserver hkp://keys.gnupg.net --recv-key 7D8D0BF6 (this is the key ID I found on Kali web site) - - * gpg --list-keys --with-fingerprint 7D8D0BF6 - - * gpg --export --armor 7D8D0BF6 > kali.asc - - * sudo apt-key add kali.asc - - * sudo apt-key list - -5 - sudo apt-get update - -6 - sudo halt - -7 - backup template (cloned...) - -8 - sudo apt-get apt-get install kali-*** (or similar) --> installs fine but break the template X settings. As mentioned, X packaged need to be masked prior to this, I did not take the time to look-up how to do that... - -9 - Create a appvm from the kali template and attach necessary devices. - - -Note: - -If you do not want to modify the sources.list file and add the signing keys yourself, alternatively you can use KATOOLIN after cloning the Debian Template. Guide on how to use KATOOLIN - http://www.tecmint.com/install-kali-linux-tools-using-katoolin-on-ubuntu-debian/ - - - -Alternative Options to Kali ---- - -PenTester Framework (PTF) - - diff --git a/managing-os/pentesting.md b/managing-os/pentesting.md new file mode 100644 index 00000000..291a7a90 --- /dev/null +++ b/managing-os/pentesting.md @@ -0,0 +1,19 @@ +--- +layout: doc +title: Penetration Testing +permalink: /doc/pentesting/ +--- + +Penetration Testing +=================== + +"A penetration test, informally pen test, is an attack on a computer system that looks for security weaknesses, potentially gaining access to the computer's features and data." (source [Penetration test](https://en.wikipedia.org/wiki/Penetration_test)). + +Penetration Testing Distributions: +---------------------------------- + +The following install instructions explain how to setup a penetration testing distribution within Qubes OS. + +- [BlackArch](/doc/blackarch/) +- [Kali](/doc/kali/) +- [PenTester Framework (PTF)](/doc/ptf/) diff --git a/managing-os/pentesting/blackarch.md b/managing-os/pentesting/blackarch.md new file mode 100644 index 00000000..2db1ebac --- /dev/null +++ b/managing-os/pentesting/blackarch.md @@ -0,0 +1,96 @@ +--- +layout: doc +title: How to Create a BlackArch VM +permalink: /doc/blackarch/ +--- + +How to Create a BlackArch VM +============================ + +[BlackArch](http://www.blackarch.org) Linux is an [Arch Linux](http://www.archlinux.org/)-based distribution for penetration testers and security researchers. The repository contains [1434](http://www.blackarch.org/tools.html) tools. + +- List of [tools](http://www.blackarch.org/tools.html) +- [Installation Instructions](http://www.blackarch.org/downloads.html) + +Create ArchLinux Based BlackArch Template +----------------------------------------- + +0 - Create ArchlLinux Template + + - Follow the [Archlinux Template instructions](/doc/templates/archlinux/) + +1 - Update Template + +~~~ +sudo pacman -Syyu +~~~ + +2 - Clone template + +1. Via Qubes VM Manager + +2. Via command line + + ~~~ + qvm-clone archlinux blackarch + ~~~ + +3 - Install BlackArch repository + +~~~ +$ curl -O https://blackarch.org/strap.sh + +# The SHA1 sum should match: 86eb4efb68918dbfdd1e22862a48fda20a8145ff +$ sha1sum strap.sh + +# Set execute bit +$ chmod +x strap.sh + +# Run strap.sh +$ sudo ./strap.sh +~~~ + +4 - Install tools + + - install all tools + + ~~~ + sudo pacman -S blackarch + ~~~ + + - or by category: + + ~~~ + # list available categories + pacman -Sg | grep blackarch + + # install category + sudo pacman -S blackarch- + + # example + sudo pacman -S blackarch-forensic + ~~~ + + - or specific tool + + ~~~ + # Search for tool + pacman -Ss + + # Install tool + sudo pacman -S + + # Example + pacman -Ss burpsuite + sudo pacman -S burpsuite + ~~~ + +5 - Create a AppVMs based on the `ptf` template + + - (Optional) Attach necessary devices + +Alternative Options to BlackArch +-------------------------------- + + - [Kali](/doc/kali/) + - [PenTester Framework (PTF)](/doc/ptf/) diff --git a/managing-os/pentesting/kali.md b/managing-os/pentesting/kali.md new file mode 100644 index 00000000..36c95ab1 --- /dev/null +++ b/managing-os/pentesting/kali.md @@ -0,0 +1,230 @@ +--- +layout: doc +title: How to create a Kali Linux VM +permalink: /doc/kali/ +--- + +How to Create a Kali Linux VM +============================= + +This guide is being created to give guidance on ways in which you could create a [Kali Linux](https://www.kali.org/) penetration testing VM (Qube) in Qubes OS. + +Kali Linux is the most widely used penetration testing Linux distribution. + +There are multiple ways to create a Kali Linux VM. One way is to create a HVM and use the offical ISO to install the system or convert a [Virtual Image](https://www.offensive-security.com/kali-linux-vmware-virtualbox-image-download/). Another way is to clone the Qubes OS Debian image and turn it into a Kali Linux distribution. + +Kali Linux HVM +-------------- + +0 - Download the Kali installation DVD + +1 - Create a new HVM + +2 - Start the HVM with attached CD/DVD + +~~~ +qvm-start --cdrom :/home/user/Downloads/.iso +~~~ + +Create Debian Based Kali Template +--------------------------------- + +0 - (Optional) Install `debian-8` template (if not already installed) + +1 - Update your `debian-8` template + +~~~ +sudo apt-get update +sudo apt-get dist-upgrade +~~~ + +2 - Clone `debian-8` template (two options) + + 1. Via Qubes VM Manager + + ![Clone Debian Template](/attachment/wiki/Pentesting/Kali/clone-kali.png) + + 2. Via command line + + ~~~ + qvm-clone debian-8 kali + ~~~ + +3 - Start and upgrade the `kali` Template from Debian 8 to Debian 9 + +~~~ +user@kali:~$ sudo sed -i 's/jessie/stretch/g' /etc/apt/sources.list +user@kali:~$ sudo sed -i 's/jessie/stretch/g' /etc/apt/sources.list.d/qubes-r3.list +user@kali:~$ sudo apt-get update +user@kali:~$ sudo apt-get dist-upgrade +user@kali:~$ sudo apt-get autoremove +~~~ + +NOTICE: From now on there are two possible ways either doing everything manually or automatically with [Katoolin](https://github.com/LionSec/katoolin). + +Katoolin is a script (written in Python) which helps you to install Kali tools. + +4 *manually* - Add Kali Linux repositories + + 1. Add Kali Linux repositories to `/etc/apt/sources.list` + + ~~~ + deb http://http.kali.org/kali kali-rolling main contrib non-free + deb http://repo.kali.org/kali kali-bleeding-edge main + ~~~ + + 2. Add kali signing key + + - The signing key can be found here [Download Kali Linux Images Securely](https://www.kali.org/downloads/) + + ~~~ + sudo apt-key adv --keyserver hkp://keys.gnupg.net --recv-keys 7D8D0BF6 + sudo apt-get update + ~~~ + + + +4 *katoolin* - Install Katoolin and add Kali Linux repositories + + 1. Install Katoolin + + ~~~ + sudo apt-get install git + git clone https://github.com/LionSec/katoolin.git + sudo cp katoolin/katoolin.py /usr/bin/katoolin + sudo chmod +x /usr/bin/katoolin + rm -rf katoolin + ~~~ + + 2. Add Kali Linux repositories + + - start katoolin + + ~~~ + sudo katoolin + ~~~ + + - select 'Add Kali repositories & Update' + + ~~~ + 1) Add Kali repositories & Update + 2) View Categories + 3) Install classicmenu indicator + 4) Install Kali menu + 5) Help + + kat > 1 + ~~~ + + ![Add Kali repositories and Update menu](/attachment/wiki/Pentesting/Kali/katoolin-add-update-repo-menu.png) + + - select 'Add kali linux repositories' + + ~~~ + 1) Add kali linux repositories + 2) Update + 3) Remove all kali linux repositories + 4) View the contents of sources.list file + + What do you want to do ?> 1 + ~~~ + + ![Add Kali repositories](/attachment/wiki/Pentesting/Kali/katoolin-add-repos-menu.png) + + - update Kali repositories + + ~~~ + 1) Add kali linux repositories + 2) Update + 3) Remove all kali linux repositories + 4) View the contents of sources.list file + + What do you want to do ?> 2 + ~~~ + + - quit katoolin by pressing `CRTL` + `c` keys + + ~~~ + What do you want to do ?> ^CShutdown requested...Goodbye... + ~~~ + +5 - Cleanup and update `kali` template + +~~~ +sudo apt-get dist-upgrade +sudo apt-get autoremove +~~~ + + +6 - Shutdown and trim `kali` template + + - Shutdown `kali` template + + ~~~ + sudo shutdown -h now + ~~~ + + - In `dom0` console: + + ~~~ + qvm-trim-template kali + ~~~ + +7 - Start image + +8 *manually* - Install tools + + 1. List available packages + + ~~~ + sudo apt-cache search kali-linux + ~~~ + + 2. Select and install tools + + - install base system + + ~~~ + sudo apt-get install kali-linux + ~~~ + + - or install all tools + + ~~~ + sudo apt-get install kali-linux-full + ~~~ + + - or select specific (example): + + ~~~ + sudo apt-get install kali-linux-top10 kali-linux-web + ~~~ + +8 *katoolin* - Install tools + + 1. View Categories + + - start katoolin + + ~~~ + sudo katoolin + ~~~ + + - select `2) View Categories` + + 2. Select the categories/tools you want to install + + - For more information on how to use Katoolin see [How to Auto Install All Kali Linux Tools Using “Katoolin” on Debian/Ubuntu](http://www.tecmint.com/install-kali-linux-tools-using-katoolin-on-ubuntu-debian/) + + - **Note:** The `all` option does not work for `Information Gathering`, `Web Apps`, `Forensic Tools`, `Reverse Engineering` and `Extra`. + +9 - Create a AppVMs based on the `kali` template + + - (Optional) Attach necessary devices + + +Alternative Options to Kali +--------------------------- + +- [BlackArch](/doc/blackarch/) +- [PenTester Framework (PTF)](/doc/ptf/) diff --git a/managing-os/pentesting/ptf.md b/managing-os/pentesting/ptf.md new file mode 100644 index 00000000..d1597f25 --- /dev/null +++ b/managing-os/pentesting/ptf.md @@ -0,0 +1,126 @@ +--- +layout: doc +title: How to create Penetration Testers Framework (PTF) VM +permalink: /doc/ptf/ +--- + +How to create Penetration Testers Framework (PTF) VM +==================================================== + +"The PenTesters Framework (PTF) is a Python script designed for Debian/Ubuntu/ArchLinux based distributions to create a similar and familiar distribution for Penetration Testing. + +PTF attempts to install all of your penetration testing tools (latest and greatest), compile them, build them, and make it so that you can install/update your distribution on any machine." (source [PTF Readme](https://github.com/trustedsec/ptf/blob/master/README.md)) + +1 - Create PTF template + + 1. Follow the [Create Debian Based Kali Template](/doc/kali/) till step 7. + 2. (Optional) Rename the cloned template to `ptf` + +2 - Download PTF + +~~~ +sudo apt-get install git +cd /opt +sudo git clone https://github.com/trustedsec/ptf.git +~~~ + + - (Optional) Configure PTF + + 1. Go to configuration directory + + ~~~ + cd /opt/ptf/config + ~~~ + + 2. Edit the configuration file + + for example by using vim: + + ~~~ + sudo vim ptf.config + ~~~ + + The configuration options are described in the `ptf.config` file + +4 - Install PTF + +~~~ +cd /opt/ptf +sudo ./ptf +~~~ + +**Note:** the config file has to be in the same directory as the executable. It is not +possible to do sudo ptf/ptf + +PTF will put itself into `/usr/local/bin/ptf`. You can use `ptf` from now on. + +5 - Install/Update modules (tools) + + 1. Start PTF + + ~~~ + sudo ptf + ~~~ + + 2. Show available modules (tools) + + ~~~ + ptf> show modules + ~~~ + + 3. Install/Update modules (all/) + + - Install/Update all tools + + ~~~ + ptf> use modules/install_update_all + ~~~ + + - or by category Install/Update + + ~~~ + ptf> use modules/code-audit/install_update_all + ~~~ + + - or individually (example Metasploit) + + 1. Search for module + + ~~~ + ptf> search metasploit + [*] Search results below: + modules/exploitation/metasploit + ~~~ + + 2. Use module + + ~~~ + ptf> use modules/exploitation/metasploit + ptf:(modules/exploitation/metasploit)> + ~~~ + + 3. Install module + + ~~~ + ptf:(modules/exploitation/metasploit)>install + ~~~ + + 4. Run Metasploit + + ~~~ + ptf:(modules/exploitation/metasploit)>exit + ptf> quit + [*] Exiting PTF - the easy pentest platform creation framework. + ~$ sudo msfconsole + ~~~ + +6 - Create a AppVMs based on the `ptf` template + + - (Optional) Attach necessary devices + + +Alternative Options to PTF +-------------------------- + +- [BlackArch](/doc/blackarch/) +- [Kali](/doc/kali/) From 4f7ce4145ba1ff0752378a3ce2ef8a6a1d340a40 Mon Sep 17 00:00:00 2001 From: Jeepler Date: Tue, 14 Jun 2016 08:52:17 -0500 Subject: [PATCH 034/708] added reason in PTF for installing Debian testing first --- customization/dark-theme.md | 4 +++- managing-os/pentesting/ptf.md | 5 +++++ 2 files changed, 8 insertions(+), 1 deletion(-) diff --git a/customization/dark-theme.md b/customization/dark-theme.md index 4dada153..91bd5e58 100644 --- a/customization/dark-theme.md +++ b/customization/dark-theme.md @@ -1,6 +1,6 @@ --- layout: doc -title: Qubes OS Dark Theme +title: Dark Theme in Dom0 and DomU permalink: /doc/dark-theme/ --- @@ -8,5 +8,7 @@ Dark KDE in dom0 ---------------- + + Dark Qube (VM) -------------- diff --git a/managing-os/pentesting/ptf.md b/managing-os/pentesting/ptf.md index d1597f25..7f2f2abc 100644 --- a/managing-os/pentesting/ptf.md +++ b/managing-os/pentesting/ptf.md @@ -11,6 +11,11 @@ How to create Penetration Testers Framework (PTF) VM PTF attempts to install all of your penetration testing tools (latest and greatest), compile them, build them, and make it so that you can install/update your distribution on any machine." (source [PTF Readme](https://github.com/trustedsec/ptf/blob/master/README.md)) +**Note** PTF works on Debian testing as well as on Debian 8. PTF itself works with Debian 8, but the software tools will have missing dependencies. Metasploit for examples requires a newer Ruby version than Debian 8 has in the repositories. Therefor the best way to install PTF is by upgrading a Debian 8 into Debian testing with additional Kali repositories. Instead of installing the tools from Kali, PTF will install and update the newest tools. + +How to create Penetration Testers Framework (PTF) VM +---------------------------------------------------- + 1 - Create PTF template 1. Follow the [Create Debian Based Kali Template](/doc/kali/) till step 7. From 808df8591f9e27e75b281e19dc9c09072cea2e90 Mon Sep 17 00:00:00 2001 From: Jeepler Date: Tue, 14 Jun 2016 09:09:21 -0500 Subject: [PATCH 035/708] added image to PTF --- managing-os/pentesting/ptf.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/managing-os/pentesting/ptf.md b/managing-os/pentesting/ptf.md index 7f2f2abc..43dd9643 100644 --- a/managing-os/pentesting/ptf.md +++ b/managing-os/pentesting/ptf.md @@ -13,8 +13,8 @@ PTF attempts to install all of your penetration testing tools (latest and greate **Note** PTF works on Debian testing as well as on Debian 8. PTF itself works with Debian 8, but the software tools will have missing dependencies. Metasploit for examples requires a newer Ruby version than Debian 8 has in the repositories. Therefor the best way to install PTF is by upgrading a Debian 8 into Debian testing with additional Kali repositories. Instead of installing the tools from Kali, PTF will install and update the newest tools. -How to create Penetration Testers Framework (PTF) VM ----------------------------------------------------- +Create Debian Based Penetration Testers Framework (PTF) Template +---------------------------------------------------------------- 1 - Create PTF template @@ -67,6 +67,8 @@ PTF will put itself into `/usr/local/bin/ptf`. You can use `ptf` from now on. sudo ptf ~~~ + ![PTF start banner](/attachment/wiki/Pentesting/PTF/ptf-banner.png) + 2. Show available modules (tools) ~~~ From ee4c6a15874bd4d8021cadd99499300a5b113a5c Mon Sep 17 00:00:00 2001 From: Lorenzo Date: Wed, 15 Jun 2016 14:22:46 +0100 Subject: [PATCH 036/708] WORK IN PROGRESS - Updates and cleanups Updated instructions for installing Kali. General cleanups. --- managing-os/kali.md | 166 ++++++++++++++++++++++++++++++++++---------- 1 file changed, 129 insertions(+), 37 deletions(-) diff --git a/managing-os/kali.md b/managing-os/kali.md index 466f4806..cc302a1b 100644 --- a/managing-os/kali.md +++ b/managing-os/kali.md @@ -7,54 +7,146 @@ permalink: /doc/kali/ How to Create a Kali Linux VM ============================= -This guide is being created to give guidance on ways in which you could implement Kali Pen-Testing distrubution within Qubes-OS. +This guide will explain how to create your own [Kali] Linux VM as a VM +template. The basic idea is to personalize the template with the tools you need +and then spin up isolated appVMs based on the template. -There are multiple ways in which this can be achieved, for example you could create a HVM and use the ISO to install the system straight to that virtual machine. +The steps can be summarised as: + +1. Customize a Debian template with the Kali sources +3. Install the Kali tools +4. Use the template to build appVM so that you can maintain isolation between + e.g. pentesting jobs -Build Based on Debian Template ---- +**IMPORTANT NOTE** Following the instructions below and in particular installing kali-linux-full will **BREAK YOUR VM**. Don't do it. It needs further investigation. The problem is: -1 - Install debian-8 template (if not already installed) - -2 - Clone debian-8 template - -3 - Add kali repo to /etc/apt/sources.list: - - * deb http://http.kali.org/kali kali-rolling main non-free contrib - -4 - Find and add kali signing keys: - - * gpg --keyserver hkp://keys.gnupg.net --recv-key 7D8D0BF6 (this is the key ID I found on Kali web site) - - * gpg --list-keys --with-fingerprint 7D8D0BF6 - - * gpg --export --armor 7D8D0BF6 > kali.asc - - * sudo apt-key add kali.asc - - * sudo apt-key list - -5 - sudo apt-get update - -6 - sudo halt - -7 - backup template (cloned...) - -8 - sudo apt-get apt-get install kali-*** (or similar) --> installs fine but break the template X settings. As mentioned, X packaged need to be masked prior to this, I did not take the time to look-up how to do that... - -9 - Create a appvm from the kali template and attach necessary devices. + * Pinning down xorg doesn't allow installing kali-desktop (or something) which prevents kali-* -Note: +Steps to build a Kali template +------------------------------ -If you do not want to modify the sources.list file and add the signing keys yourself, alternatively you can use KATOOLIN after cloning the Debian Template. Guide on how to use KATOOLIN - http://www.tecmint.com/install-kali-linux-tools-using-katoolin-on-ubuntu-debian/ +### Get the GPG key + +1. You'll need to fetch the Kali GPG key from a dispVM as the template you'll + build won't have direct internet connectivity unless you enable it from the + firewall: + + # in the dispVM + gpg --keyserver hkp://keys.gnupg.net --recv-key 7D8D0BF6 + gpg --list-keys --with-fingerprint 7D8D0BF6 + gpg --export --armor 7D8D0BF6 > kali.asc + +2. Make sure the key ID is the valid one listed on the [Kali website]. Ideally, + verify the fingerprint through other channels. + +Once you have the key, keep the dispVM on as you'll need to copy the key over +to the Kali template. + +### Customize the template + +1. Install [the debian-8 template] (if not already installed) + +2. Clone the debian template and start a terminal in it: + + # from dom0: + qvm-clone debian-8 kali + +3. Add this line to the `/etc/apt/sources.list` file in the template: + + # in the 'kali' template + sudo -s + echo 'deb http://http.kali.org/kali kali-rolling main non-free contrib' >> /etc/apt/sources.list + +4. Copy the Kali key from the dispVM into the template: + + # in the dispVM + qvm-copy-to-vm kali kali.asc + + # in the kali template: + sudo -s + cat /home/user/QubesIncoming/kali/kali-key.asc | apt-key add - + + The last command should return `OK` on a line by itself. + +5. **Pin the X server** into the preferences file: this prevents Kali to installing + a new X.org server, for which there would be no qubes-tools available: + + # add the following lines to /etc/apt/preferences (you might have to + create it) + + Package: xserver-xorg* + Pin: release a=jessie + Pin-Priority: 900 + + Package: xorg* + Pin: release a=jessie + Pin-Priority: 900 + +5. Update the system: + + sudo apt-get update + +6. Now is a good time to stop the template, clone it and see if restarting it + allows you to run a terminal: + + # from dom0 + qvm-clone kali kali-tools + +### Install the Kali tools + +At this point you should have a working template and you can install the tools you need. + +Don't forget to [resize the template] if you plan on installing the full Kali distribution. For example to install `kali-linux-full` you must **grow** the size of the VM system from 10Gb to at least 20Gb. + +1. Install your tools of choice, for example: + + # in the kali-tools template + sudo apt-get install kali-linux-full + +2. If the update process went well, give it a try: shut down the `kali-tools` + template and create an appVM from it. + +3. When you are happy you can probably remove the `kali` template and its + backup copies; then use only `kali-tools` as a template. + + +Don't forget to back up your appVMs as [audio CDs]. + + +Troubleshooting +--------------- + +If the template doesn't start, give it a peek with the console: + + # from dom0 + sudo xl console kali + + +Installing via third-party scripts: Katoolin +-------------------------------------------- + +If you do not want to modify the `sources.list` file and add the signing keys +yourself, alternatively you can use [KATOOLIN] after cloning the Debian +Template. + +You should probably inspect the script and make sure it does what you want +before trusting it blindly. Alternative Options to Kali ---- +=========================== -PenTester Framework (PTF) + * PenTester Framework: [PTF] + +[kali]: https://www.kali.org/ +[kali website]: https://docs.kali.org/introduction/download-official-kali-linux-images. +[KATOOLIN]: http://www.tecmint.com/install-kali-linux-tools-using-katoolin-on-ubuntu-debian/ +[the debian-8 template]: https://www.qubes-os.org/doc/templates/debian/ +[PTF]: https://www.trustedsec.com/may-2015/new-tool-the-pentesters-framework-ptf-released/ +[audio CDs]: https://www.reddit.com/r/Nirvana/comments/3hmra1/the_main_character_in_the_tv_show_mr_robot_has_a/ +[resize the template]: https://www.qubes-os.org/doc/resize-disk-image/ From bf55feeddc374369fcd4c20864bf11951781620f Mon Sep 17 00:00:00 2001 From: Cyril LEVIS Date: Wed, 15 Jun 2016 21:01:14 +0200 Subject: [PATCH 037/708] add apt-get upgrade && apt-get dist-upgrade if not this does not work --- managing-os/kali.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/managing-os/kali.md b/managing-os/kali.md index cc302a1b..565ec3a6 100644 --- a/managing-os/kali.md +++ b/managing-os/kali.md @@ -88,6 +88,8 @@ to the Kali template. 5. Update the system: sudo apt-get update + sudo apt-get upgrade + sudo apt-get dist-upgrade 6. Now is a good time to stop the template, clone it and see if restarting it allows you to run a terminal: From b514a50560c8eecbd590a22e264195099415ff11 Mon Sep 17 00:00:00 2001 From: Jeepler Date: Wed, 15 Jun 2016 18:48:47 -0500 Subject: [PATCH 038/708] dark-theme finished; kali and ptf images paths adjusted; articles linked to doc.md --- customization/dark-theme.md | 204 ++++++++++++++++++++++++++++++++- doc.md | 5 +- managing-os/pentesting/kali.md | 6 +- managing-os/pentesting/ptf.md | 2 +- 4 files changed, 209 insertions(+), 8 deletions(-) diff --git a/customization/dark-theme.md b/customization/dark-theme.md index 91bd5e58..b82ba8a3 100644 --- a/customization/dark-theme.md +++ b/customization/dark-theme.md @@ -4,11 +4,209 @@ title: Dark Theme in Dom0 and DomU permalink: /doc/dark-theme/ --- -Dark KDE in dom0 +Dark Theme in Dom0 +================== + +Dark KDE in Dom0 ---------------- +The following text describes how to change the default light theme to a dark theme. This is just an example, feel free to adjust the appearance to your taste. + +The image below shows the default light theme after installation. +![begin light theme](/attachment/wiki/Dark-Theme/kde-fresh-installed-standard.png) + +This is the result after applying the steps described here. +![end result dark theme](/attachment/wiki/Dark-Theme/kde-end-result.png) + +1 - Change `Workspace Appearance` + + 1. Open the `Workspace Appearance` window + + ~~~ + Qubes Menu -> System Tools -> System Settings -> Workspace Appearance + ~~~ + + ![Workspace Appearance](/attachment/wiki/Dark-Theme/kde-app-appearance-menu-style.png) + + 2. Go to `Desktop Theme` + + ![Desktop Menu](/attachment/wiki/Dark-Theme/kde-appearance-settings-desktop-theme-oxygen.png) + + 3. Select `Oxygen` and `Apply` the change + +2 - (Optional) Remove blue glowing task items + +![blue glowing task bar items](/attachment/wiki/Dark-Theme/kde-taskbar-blue-glowing-border.png) + + 1. Adjust Oxygen `Details` + + ~~~ + Qubes Menu -> System Tools -> System Settings -> Workspace Appearance -> Desktop Theme -> Details (Tab) + ~~~ + + 2. Select `Oxygen` + + 3. Change `Theme Item -> Task Items` from `Oxygen Task Items` to `Air Task Items` + + ![Change Task items look](/attachment/wiki/Dark-Theme/kde-desktop-theme-details.png) + 4. Apply changes + + ![task bar items blue glowing removed](/attachment/wiki/Dark-Theme/kde-taskbar-blue-glowing-removed.png) + +3 - Change `Application Appearance` + + 1. Open the `Application Appearance` window + + ~~~ + Qubes Menu -> System Tools -> System Settings -> Application Appearance + ~~~ + + 2. Go to `Colors` + + ![colors tab](/attachment/wiki/Dark-Theme/kde-app-appearance-menu-colors.png) + + 3. Select `Obsidian Coast` + + ![set to Obsidian Coast](/attachment/wiki/Dark-Theme/kde-app-appearance-menu-colors-set.png) + + 4. Apply Changes + + Qubes VM Manager should now look like the image below. + + ![result black Qubes Manager](/attachment/wiki/Dark-Theme/kde-black-qubes-manager.png) + +**Note:** Chaning the `Window Decorations` from `Plastik for Qubes` will remove the border color and the VM name. The problem with `Plastik for Qubes` is it does not overwrite the background and text color for Minimize, Maximize and Close buttons. The three button are therefor hard to read. + +Dark XCFE in Dom0 +----------------- + +The following text describes how to change the default light theme to a dark theme. This is just an example, feel free to adjust the appearance to your taste. + +The image below shows the default light theme after installation. +![begin light theme](/attachment/wiki/Dark-Theme/xfce-fresh-installed.png) + +This is the result after applying the steps described here. +![end result dark theme](/attachment/wiki/Dark-Theme/xfce-end-result.png) + +1 - Change Appearance + + 1. Open the `Appearance` dialog + + ~~~ + Qubes Menu -> System Tools -> Appearance + ~~~ + + ![appearance dialog](/attachment/wiki/Dark-Theme/xfce-appearance-dialog.png) + + 2. Change Style to `Albatross` + +**Note:** The black appearance theme `Xfce-dusk` makes the VM names in the `Qubes OS Manager` unreadable. + +2 - *(Optional)* Change Window Manager Style + + 1. Open the `Window Manager` dialog + + ~~~ + Qubes Menu -> System Tools -> Appearance + ~~~ + + ![window manager dialog](/attachment/wiki/Dark-Theme/xfce-window-manager-theme.png) + + 2. Change the Theme in the `Style` Tab (e. g. Defcon-IV). All available themes work. +Dark App VM, Template VM, Standalone VM, HVM (Linux Gnome) +========================================================== -Dark Qube (VM) --------------- +Almost all Qubes VM's are based on the Gnome desktop. Therefor the description below is focused on the Gnome Desktop Environment. + +Using `Gnome-Tweak-Tool` +------------------------ + +The advantage of creating a dark themed Template VM is, that each AppVM which is derived from the Template VM will be dark themed by default. + +**Note:** Gnome-Tweak-Tool crashes under Archlinux. A workaround is to assign the AppVM to another TemplateVM (Debian, Fedora) which has Gnome-Tweak-Tool installed. Start the AppVM and configure the settings. Shutdown the machine and switch the template VM back to Archlinux. + +0 - Start VM + +**Note:** In case of App VM start the Template on which the AppVM is based on. + +1 - Install `Gnome-Tweak-Tool` + + 1. Fedora + + ~~~ + sudo dnf install gnome-tweak-tool + ~~~ + + 2. Debian + + ~~~ + sudo apt-get install gnome-tweak-tool + ~~~ + +2 - *(Only AppVM)* Stop template and start AppVM + +3 - Add `Gnome-Tweak-Tool` to the Application Menu + + 1. `Right-click` on VM entry in `Qubes VM Manager` select `Add/remove app shortcuts` + + 2. Select `Tweak Tool` and press the `>` button to add it + + ![Application Dialog](/attachment/wiki/Dark-Theme/dialog-add-gnome-tweak-tool.png) + +4 - Enable `Global Dark Theme` + + 1. *Debian only* + + ~~~ + cd ~/.config/ + mkdir gtk-3.0 + cd gtk-3.0/ + touch settings.ini + ~~~ + + 2. Start `Tweak Tool` from the VM application menu and set the `Global Dark Theme` switch to `on` + + ![Global Dark Theme enabled](/attachment/wiki/Dark-Theme/gnome-tweak-tool.png) + +5 - *(Optional)* Modify Firefox + +**Note:** Firefox uses GTK style settings by default. This can create side effects such as unusable forms or search fields. There are two different ways to avoid this. Either by using a add-on or by overwriting the defaults. + + - use the theme [GTK+ Dark Theme Global Fixes](https://userstyles.org/styles/111694/gtk-dark-theme-global-fixes) and the [Stylish](https://addons.mozilla.org/en-US/firefox/addon/stylish/) addon + + - or add the following line to `/rw/config/rc.local` + + ~~~ + sed -i.bak "s/Exec=firefox %u/Exec=bash -c 'GTK_THEME=Adwaita:light firefox %u'/g" /usr/share/applications/firefox.desktop + ~~~ + +6 - Restart VM or all application + +Manually +-------- + +Manually works for Debian, Fedora and Archlinux. + +0 - Start VM + +**Note:** In case of App VM start the Template on which the AppVM is based on. + +1 - Enable `Global Dark Theme` + +~~~ +cd ~/.config/ +mkdir gtk-3.0 +cd gtk-3.0/ +touch settings.ini +~~~ + +add the following lines to `settings.ini` + +~~~ +[Settings] +gtk-application-prefer-dark-theme=1 +~~~ + +2 - follow step 5 and 6 in: Using `Gnome-Tweak-Tool` diff --git a/doc.md b/doc.md index 4060e4c1..373a8c90 100644 --- a/doc.md +++ b/doc.md @@ -63,6 +63,9 @@ Managing Operating Systems within Qubes * [Templates: Archlinux](/doc/templates/archlinux/) * [Templates: Ubuntu](/doc/templates/ubuntu/) * [Templates: Whonix](/doc/whonix/) + * [Pentesting: BlackArch](/doc/pentesting/blackarch/) + * [Pentesting: Kali](/doc/pentesting/kali/) + * [Pentesting: PTF](/doc/pentesting/ptf/) * [Installing and Using Windows-based AppVMs (Qubes R2 Beta 3 and later)](/doc/windows-appvms/) * [Creating and Using HVM and Windows Domains (Qubes R2+)](/doc/hvm/) * [Advanced options and troubleshooting of Qubes Tools for Windows (R3)](/doc/windows-tools-3/) @@ -139,6 +142,7 @@ Customization Guides * [Installing XFCE in dom0](/doc/xfce/) * [Installing i3 in dom0](/doc/i3/) * [Language Localization](/doc/language-localization/) + * [Dark Theme in Dom0 and DomU](/doc/dark-theme/) Troubleshooting @@ -187,4 +191,3 @@ For Developers * [Qubes OS License](/doc/license/) * [Style Guide](/doc/style-guide/) * [Usability & UX](/doc/usability-ux/) - diff --git a/managing-os/pentesting/kali.md b/managing-os/pentesting/kali.md index 36c95ab1..fe8ed787 100644 --- a/managing-os/pentesting/kali.md +++ b/managing-os/pentesting/kali.md @@ -42,7 +42,7 @@ sudo apt-get dist-upgrade 1. Via Qubes VM Manager - ![Clone Debian Template](/attachment/wiki/Pentesting/Kali/clone-kali.png) + ![Clone Debian Template](/attachment/wiki/Kali/clone-kali.png) 2. Via command line @@ -116,7 +116,7 @@ Katoolin is a script (written in Python) which helps you to install Kali tools. kat > 1 ~~~ - ![Add Kali repositories and Update menu](/attachment/wiki/Pentesting/Kali/katoolin-add-update-repo-menu.png) + ![Add Kali repositories and Update menu](/attachment/wiki/Kali/katoolin-add-update-repo-menu.png) - select 'Add kali linux repositories' @@ -129,7 +129,7 @@ Katoolin is a script (written in Python) which helps you to install Kali tools. What do you want to do ?> 1 ~~~ - ![Add Kali repositories](/attachment/wiki/Pentesting/Kali/katoolin-add-repos-menu.png) + ![Add Kali repositories](/attachment/wiki/Kali/katoolin-add-repos-menu.png) - update Kali repositories diff --git a/managing-os/pentesting/ptf.md b/managing-os/pentesting/ptf.md index 43dd9643..96fd241f 100644 --- a/managing-os/pentesting/ptf.md +++ b/managing-os/pentesting/ptf.md @@ -67,7 +67,7 @@ PTF will put itself into `/usr/local/bin/ptf`. You can use `ptf` from now on. sudo ptf ~~~ - ![PTF start banner](/attachment/wiki/Pentesting/PTF/ptf-banner.png) + ![PTF start banner](/attachment/wiki/PTF/ptf-banner.png) 2. Show available modules (tools) From 8ce887cc0528c0ffa05e8223b77c83f6f75767f6 Mon Sep 17 00:00:00 2001 From: Jeepler Date: Wed, 15 Jun 2016 19:11:12 -0500 Subject: [PATCH 039/708] Warning for manual Kali linux installation added --- managing-os/pentesting/kali.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/managing-os/pentesting/kali.md b/managing-os/pentesting/kali.md index fe8ed787..20a04217 100644 --- a/managing-os/pentesting/kali.md +++ b/managing-os/pentesting/kali.md @@ -174,6 +174,8 @@ sudo apt-get autoremove 8 *manually* - Install tools +**Warning:** `kali-linux` and `kali-linux-full` does currently not work properly. Please use `Katoolin` or `PTF`. + 1. List available packages ~~~ From f3f96571b3833883c6ea2bd1f07c1fc38c62306d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Marczykowski-G=C3=B3recki?= Date: Fri, 17 Jun 2016 10:45:45 +0200 Subject: [PATCH 040/708] releases: R3.1 is released some time ago --- releases/3.1/release-notes.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/releases/3.1/release-notes.md b/releases/3.1/release-notes.md index 9a659b7d..c4506032 100644 --- a/releases/3.1/release-notes.md +++ b/releases/3.1/release-notes.md @@ -7,8 +7,6 @@ permalink: /doc/releases/3.1/release-notes/ Qubes R3.1 release notes ======================== -*this page is a draft for yet unreleased version* - New features since 3.0 ---------------------- From eac3ca277b0265b6e063717c2bc80b1d83f206a8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Marczykowski-G=C3=B3recki?= Date: Fri, 17 Jun 2016 10:46:32 +0200 Subject: [PATCH 041/708] releases/3.2: add draft release notes and preliminary schedule --- releases/3.2/release-notes.md | 60 +++++++++++++++++++++++++++++++++++ releases/3.2/schedule.md | 25 +++++++++++++++ 2 files changed, 85 insertions(+) create mode 100644 releases/3.2/release-notes.md create mode 100644 releases/3.2/schedule.md diff --git a/releases/3.2/release-notes.md b/releases/3.2/release-notes.md new file mode 100644 index 00000000..0f50a8c6 --- /dev/null +++ b/releases/3.2/release-notes.md @@ -0,0 +1,60 @@ +--- +layout: doc +title: Qubes R3.2 release notes +permalink: /doc/releases/3.2/release-notes/ +--- + +Qubes R3.2 release notes +======================== + +*this page is a draft for yet unreleased version* + +New features since 3.1 +---------------------- + +* Management Stack extended to support in-VM configuration - [documentation][salt-doc] +* PV USB - [documentation][usb] +* Dom0 update to Fedora 23 for better hardware support +* Kernel 4.4.x +* KDE 5 support +* Tiling window managers support: awesome, [i3][i3] +* More flexible Qubes RPC services - [related ticket][qrexec-argument], [documentation][qrexec-doc] + +You can get detailed description in [completed github issues][github-release-notes] + +Known issues +------------ + +* Installation image does not fit on DVD, requires either DVD DL, or USB stick (5GB or more) + +* Windows Tools: `qvm-block` does not work + +* Some icons in the Qubes Manager application might not be drawn correctly when using the Xfce4 environment in Dom0. If this bothers you, please use the KDE environment instead. + +* For other known issues take a look at [our tickets](https://github.com/QubesOS/qubes-issues/issues?q=is%3Aopen+is%3Aissue+milestone%3A%22Release+3.2%22+label%3Abug) + +It is advised to install updates just after system installation to apply bug fixes for (some of) the above problems. + +Downloads +--------- + +See [Qubes Downloads](/downloads/). + +Installation instructions +------------------------- + +See [Installation Guide](/doc/installation-guide/). + +Upgrading +--------- + +There is no in-place upgrade procedure. Proceed with install +from scratch and use [qubes backup and restore tools](/doc/backup-restore/) +for migrating of all of the user VMs. + +[salt-doc]: /doc/salt/ +[usb]: /doc/usb/ +[i3]: /doc/i3/ +[qrexec-argument]: https://github.com/QubesOS/qubes-issues/issues/1876 +[qrexec-doc]: /doc/qrexec3/#service-argument-in-policy +[github-release-notes]: https://github.com/QubesOS/qubes-issues/issues?q=is%3Aissue+sort%3Aupdated-desc+milestone%3A%22Release+3.2%22+label%3Arelease-notes+is%3Aclosed diff --git a/releases/3.2/schedule.md b/releases/3.2/schedule.md new file mode 100644 index 00000000..2eda856c --- /dev/null +++ b/releases/3.2/schedule.md @@ -0,0 +1,25 @@ +--- +layout: doc +title: Qubes R3.2 Release Schedule +permalink: /doc/releases/3.2/schedule/ +redirect_from: +- /en/doc/releases/3.2/schedule/ +--- + +Qubes R3.2 Release Schedule +=========================== + +This schedule is based on [Version Scheme](/doc/version-scheme/#tocAnchor-1-1-3). + + + +| Date | Stage | +| -----------:| --------------------------------------- | +| 17 Jun 2016 | 3.2-rc1 release | +| 15 Jul 2016 | decide whether 3.2-rc1 is the final 3.2 | From eb62b13c09ec10b0e993e607439b1457e18bcb66 Mon Sep 17 00:00:00 2001 From: Jeepler Date: Fri, 17 Jun 2016 10:47:33 -0500 Subject: [PATCH 042/708] linked pentesting --- doc.md | 1 + 1 file changed, 1 insertion(+) diff --git a/doc.md b/doc.md index c69d689e..32fe9a49 100644 --- a/doc.md +++ b/doc.md @@ -64,6 +64,7 @@ Managing Operating Systems within Qubes * [Templates: Ubuntu](/doc/templates/ubuntu/) * [Templates: Whonix](/doc/whonix/) * [How to Reinstall a TemplateVM](/doc/reinstall-template) + * [Pentesting](/doc/pentesting/) * [Pentesting: BlackArch](/doc/pentesting/blackarch/) * [Pentesting: Kali](/doc/pentesting/kali/) * [Pentesting: PTF](/doc/pentesting/ptf/) From c4dd8860fc81899ab7844081412755db67563a77 Mon Sep 17 00:00:00 2001 From: Jeepler Date: Fri, 17 Jun 2016 11:19:35 -0500 Subject: [PATCH 043/708] legal notice and general remainder --- managing-os/pentesting.md | 6 ++++++ managing-os/pentesting/blackarch.md | 8 ++++++++ managing-os/pentesting/kali.md | 8 ++++++++ managing-os/pentesting/ptf.md | 8 ++++++++ 4 files changed, 30 insertions(+) diff --git a/managing-os/pentesting.md b/managing-os/pentesting.md index 291a7a90..351618c5 100644 --- a/managing-os/pentesting.md +++ b/managing-os/pentesting.md @@ -4,6 +4,12 @@ title: Penetration Testing permalink: /doc/pentesting/ --- +**Legal notice:** + +The usage of penetration testing tools outside your own laboratory environment requires the permission of the organization you attack. Penetration testing without such a permission can have legal consequences. + +To avoid such legal conflicts please refer to the [Code of Ethics](https://www.eccouncil.org/Support/code-of-ethics). + Penetration Testing =================== diff --git a/managing-os/pentesting/blackarch.md b/managing-os/pentesting/blackarch.md index 2db1ebac..35377455 100644 --- a/managing-os/pentesting/blackarch.md +++ b/managing-os/pentesting/blackarch.md @@ -4,6 +4,14 @@ title: How to Create a BlackArch VM permalink: /doc/blackarch/ --- +**General Remainder:** + +- The installation scripts and provided tools may have bugs, be vulnerable to Man in the Middle (MitM) attacks or other vulnerabilities. + +- Adding additional repositories or tools for installing software extends your trust to those tool provider. + +Please keep in mind that using such a VM or VM's based on the template for security and privacy critical tasks is not recommended. + How to Create a BlackArch VM ============================ diff --git a/managing-os/pentesting/kali.md b/managing-os/pentesting/kali.md index 20a04217..90fd5a4d 100644 --- a/managing-os/pentesting/kali.md +++ b/managing-os/pentesting/kali.md @@ -4,6 +4,14 @@ title: How to create a Kali Linux VM permalink: /doc/kali/ --- +**General Remainder:** + +- The installation scripts and provided tools may have bugs, be vulnerable to Man in the Middle (MitM) attacks or other vulnerabilities. + +- Adding additional repositories or tools for installing software extends your trust to those tool provider. + +Please keep in mind that using such a VM or VM's based on the template for security and privacy critical tasks is not recommended. + How to Create a Kali Linux VM ============================= diff --git a/managing-os/pentesting/ptf.md b/managing-os/pentesting/ptf.md index 96fd241f..53ca68d5 100644 --- a/managing-os/pentesting/ptf.md +++ b/managing-os/pentesting/ptf.md @@ -4,6 +4,14 @@ title: How to create Penetration Testers Framework (PTF) VM permalink: /doc/ptf/ --- +**General Remainder:** + +- The installation scripts and provided tools may have bugs, be vulnerable to Man in the Middle (MitM) attacks or other vulnerabilities. + +- Adding additional repositories or tools for installing software extends your trust to those tool provider. + +Please keep in mind that using such a VM or VM's based on the template for security and privacy critical tasks is not recommended. + How to create Penetration Testers Framework (PTF) VM ==================================================== From 08d0d6a427ee40cbfcaf5b0f134ad6d7352fb3ea Mon Sep 17 00:00:00 2001 From: Jeepler Date: Fri, 17 Jun 2016 11:35:03 -0500 Subject: [PATCH 044/708] Qubes OS as hacking laboratory host --- managing-os/pentesting.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/managing-os/pentesting.md b/managing-os/pentesting.md index 351618c5..60452018 100644 --- a/managing-os/pentesting.md +++ b/managing-os/pentesting.md @@ -23,3 +23,11 @@ The following install instructions explain how to setup a penetration testing di - [BlackArch](/doc/blackarch/) - [Kali](/doc/kali/) - [PenTester Framework (PTF)](/doc/ptf/) + +Using Qubes OS to host a "hacking" laboratory +--------------------------------------------- + +Qubes OS is a hypervisor based operating system. Qubes OS can various operating systems such as Linux, Unix or Windows in parallel. Qubes OS can therefor be used to host your own "hacking" laboratory. + +- [Creating and Using HVM Domains](/doc/hvm-create/) +- [Templates](/doc/templates/) From b18cbeacbe9065587ec02c73dd8d6b2a863a1ea7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Marczykowski-G=C3=B3recki?= Date: Sat, 18 Jun 2016 01:28:14 +0200 Subject: [PATCH 045/708] Add USB passthrough documentation --- common-tasks/usb.md | 43 ++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 42 insertions(+), 1 deletion(-) diff --git a/common-tasks/usb.md b/common-tasks/usb.md index be2a4b6f..9710db90 100644 --- a/common-tasks/usb.md +++ b/common-tasks/usb.md @@ -252,6 +252,47 @@ Add a line like this one to the top of the file: You can now use your USB keyboard. +Attaching a single USB device to a qube (USB passthrough) +------------------------------------------------ + +Stating with Qubes 3.2, it is possible to attach a single USB device to any +Qube. While this is useful feature, it should be used with care, because there +are [many security implications][usb-challenges] from using USB devices and USB +passthrough will **expose your target qube** for most of them. If possible, use use +method specific for particular device type (for example block devices described +above), instead of this generic one. + +To use this feature, you need to install `qubes-usb-proxy` package in the +templates used for USB qube and qubes you want to connect USB devices to. + +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 -a conferences sys-usb:2-5 + [user@dom0 ~]$ qvm-usb + conferences:2-1 058f:3822 058f_USB_2.0_Camera + sys-usb:2-4 04ca:300d 04ca_300d + sys-usb:2-5 058f:3822 058f_USB_2.0_Camera (attached to conferences) + sys-usb:2-1 03f0:0641 PixArt_HP_X1200_USB_Optical_Mouse + +Now, you can use your USB device (camera in this case) in `conferences` qube. + +When you finish, detach the device: + + [user@dom0 ~]$ qvm-usb -d sys-usb:2-5 + [user@dom0 ~]$ qvm-usb + sys-usb:2-4 04ca:300d 04ca_300d + sys-usb:2-5 058f:3822 058f_USB_2.0_Camera + sys-usb:2-1 03f0:0641 PixArt_HP_X1200_USB_Optical_Mouse + +This feature is not yet available in Qubes Manager. + [mass-storage]: https://en.wikipedia.org/wiki/USB_mass_storage_device_class [Assigning Devices]: /doc/assigning-devices/ @@ -263,4 +304,4 @@ You can now use your USB keyboard. [faq-usbvm]: /doc/user-faq/#i-created-a-usbvm-and-assigned-usb-controllers-to-it-now-the-usbvm-wont-boot [1618]: https://github.com/QubesOS/qubes-issues/issues/1618 [input-proxy]: https://github.com/qubesos/qubes-app-linux-input-proxy - +[usb-challenges]: http://blog.invisiblethings.org/2011/05/31/usb-security-challenges.html From c366477e8e1a5eb602f4daa61ec61574d41cb393 Mon Sep 17 00:00:00 2001 From: Lorenzo Date: Sat, 18 Jun 2016 00:55:19 +0100 Subject: [PATCH 046/708] Added a few notes. --- managing-os/kali.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/managing-os/kali.md b/managing-os/kali.md index cc302a1b..cd692811 100644 --- a/managing-os/kali.md +++ b/managing-os/kali.md @@ -141,6 +141,15 @@ Alternative Options to Kali * PenTester Framework: [PTF] +Notes +----- + +Various things tried: + + * Forget about pinning: just dist-upgrade, then download qubes-core-agent, then BACKEND_VMM=xen dpkg-buildpackage -b -uc -us + * Also download requirements for debian bootstrapping from https://wiki.debian.org/BuildingTutorial + * And qubes-kernel-vm-support for vchan (I think) + [kali]: https://www.kali.org/ From 254f5e71a0cc4f225f53f070d9d838236ba94f36 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Marczykowski-G=C3=B3recki?= Date: Sat, 18 Jun 2016 10:27:58 +0200 Subject: [PATCH 047/708] Update 3.2 release schedule --- releases/3.2/schedule.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/releases/3.2/schedule.md b/releases/3.2/schedule.md index 2eda856c..008e6515 100644 --- a/releases/3.2/schedule.md +++ b/releases/3.2/schedule.md @@ -21,5 +21,5 @@ article td, article th { | Date | Stage | | -----------:| --------------------------------------- | -| 17 Jun 2016 | 3.2-rc1 release | +| 18 Jun 2016 | 3.2-rc1 release | | 15 Jul 2016 | decide whether 3.2-rc1 is the final 3.2 | From aadb35d62f38bff08c96820eb75cb033325b309e Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Mon, 20 Jun 2016 13:56:20 -0700 Subject: [PATCH 048/708] Move all developer documentation to main index QubesOS/qubes-issues#2070 --- {developers => basics_dev}/code-signing.md | 0 {developers => basics_dev}/coding-style.md | 0 {developers => basics_dev}/contributing.md | 0 {developers => basics_dev}/devel-books.md | 0 {developers => basics_dev}/devel-faq.md | 0 {developers => basics_dev}/doc-guidelines.md | 0 {developers => basics_dev}/license.md | 0 {developers => basics_dev}/reporting-bugs.md | 0 {developers => basics_dev}/source-code.md | 0 {developers => basics_dev}/style-guide.md | 0 {developers => basics_dev}/system-doc.md | 0 {developers => basics_dev}/usability-ux.md | 0 {basics => basics_user}/user-faq.md | 0 .../building-archlinux-template.md | 0 .../building-non-fedora-template.md | 0 .../development-workflow.md | 0 {developers/building => building}/kde-dom0.md | 0 {developers/building => building}/pvusb.md | 0 .../qubes-builder-details.md | 0 .../building => building}/qubes-builder.md | 0 .../qubes-r3-building.md | 0 .../automated-tests.md | 0 .../debugging => debugging}/profiling.md | 0 .../debugging => debugging}/test-bench.md | 0 .../debugging => debugging}/vm-interface.md | 0 .../windows-debugging.md | 0 doc.md | 49 +++++++++++++++++-- .../dom0-secure-updates.md | 0 {developers/services => services}/dvm-impl.md | 0 .../services => services}/qfilecopy.md | 0 .../services => services}/qfileexchgd.md | 0 {developers/services => services}/qmemman.md | 0 {developers/services => services}/qrexec2.md | 0 {developers/services => services}/qrexec3.md | 0 .../fundamentals => system}/architecture.md | 0 {developers/fundamentals => system}/gui.md | 0 .../fundamentals => system}/networking.md | 0 .../security-critical-code.md | 0 .../template-implementation.md | 0 39 files changed, 46 insertions(+), 3 deletions(-) rename {developers => basics_dev}/code-signing.md (100%) rename {developers => basics_dev}/coding-style.md (100%) rename {developers => basics_dev}/contributing.md (100%) rename {developers => basics_dev}/devel-books.md (100%) rename {developers => basics_dev}/devel-faq.md (100%) rename {developers => basics_dev}/doc-guidelines.md (100%) rename {developers => basics_dev}/license.md (100%) rename {developers => basics_dev}/reporting-bugs.md (100%) rename {developers => basics_dev}/source-code.md (100%) rename {developers => basics_dev}/style-guide.md (100%) rename {developers => basics_dev}/system-doc.md (100%) rename {developers => basics_dev}/usability-ux.md (100%) rename {basics => basics_user}/user-faq.md (100%) rename {developers/building => building}/building-archlinux-template.md (100%) rename {developers/building => building}/building-non-fedora-template.md (100%) rename {developers/building => building}/development-workflow.md (100%) rename {developers/building => building}/kde-dom0.md (100%) rename {developers/building => building}/pvusb.md (100%) rename {developers/building => building}/qubes-builder-details.md (100%) rename {developers/building => building}/qubes-builder.md (100%) rename {developers/building => building}/qubes-r3-building.md (100%) rename {developers/debugging => debugging}/automated-tests.md (100%) rename {developers/debugging => debugging}/profiling.md (100%) rename {developers/debugging => debugging}/test-bench.md (100%) rename {developers/debugging => debugging}/vm-interface.md (100%) rename {developers/debugging => debugging}/windows-debugging.md (100%) rename {developers/services => services}/dom0-secure-updates.md (100%) rename {developers/services => services}/dvm-impl.md (100%) rename {developers/services => services}/qfilecopy.md (100%) rename {developers/services => services}/qfileexchgd.md (100%) rename {developers/services => services}/qmemman.md (100%) rename {developers/services => services}/qrexec2.md (100%) rename {developers/services => services}/qrexec3.md (100%) rename {developers/fundamentals => system}/architecture.md (100%) rename {developers/fundamentals => system}/gui.md (100%) rename {developers/fundamentals => system}/networking.md (100%) rename {developers/fundamentals => system}/security-critical-code.md (100%) rename {developers/fundamentals => system}/template-implementation.md (100%) diff --git a/developers/code-signing.md b/basics_dev/code-signing.md similarity index 100% rename from developers/code-signing.md rename to basics_dev/code-signing.md diff --git a/developers/coding-style.md b/basics_dev/coding-style.md similarity index 100% rename from developers/coding-style.md rename to basics_dev/coding-style.md diff --git a/developers/contributing.md b/basics_dev/contributing.md similarity index 100% rename from developers/contributing.md rename to basics_dev/contributing.md diff --git a/developers/devel-books.md b/basics_dev/devel-books.md similarity index 100% rename from developers/devel-books.md rename to basics_dev/devel-books.md diff --git a/developers/devel-faq.md b/basics_dev/devel-faq.md similarity index 100% rename from developers/devel-faq.md rename to basics_dev/devel-faq.md diff --git a/developers/doc-guidelines.md b/basics_dev/doc-guidelines.md similarity index 100% rename from developers/doc-guidelines.md rename to basics_dev/doc-guidelines.md diff --git a/developers/license.md b/basics_dev/license.md similarity index 100% rename from developers/license.md rename to basics_dev/license.md diff --git a/developers/reporting-bugs.md b/basics_dev/reporting-bugs.md similarity index 100% rename from developers/reporting-bugs.md rename to basics_dev/reporting-bugs.md diff --git a/developers/source-code.md b/basics_dev/source-code.md similarity index 100% rename from developers/source-code.md rename to basics_dev/source-code.md diff --git a/developers/style-guide.md b/basics_dev/style-guide.md similarity index 100% rename from developers/style-guide.md rename to basics_dev/style-guide.md diff --git a/developers/system-doc.md b/basics_dev/system-doc.md similarity index 100% rename from developers/system-doc.md rename to basics_dev/system-doc.md diff --git a/developers/usability-ux.md b/basics_dev/usability-ux.md similarity index 100% rename from developers/usability-ux.md rename to basics_dev/usability-ux.md diff --git a/basics/user-faq.md b/basics_user/user-faq.md similarity index 100% rename from basics/user-faq.md rename to basics_user/user-faq.md diff --git a/developers/building/building-archlinux-template.md b/building/building-archlinux-template.md similarity index 100% rename from developers/building/building-archlinux-template.md rename to building/building-archlinux-template.md diff --git a/developers/building/building-non-fedora-template.md b/building/building-non-fedora-template.md similarity index 100% rename from developers/building/building-non-fedora-template.md rename to building/building-non-fedora-template.md diff --git a/developers/building/development-workflow.md b/building/development-workflow.md similarity index 100% rename from developers/building/development-workflow.md rename to building/development-workflow.md diff --git a/developers/building/kde-dom0.md b/building/kde-dom0.md similarity index 100% rename from developers/building/kde-dom0.md rename to building/kde-dom0.md diff --git a/developers/building/pvusb.md b/building/pvusb.md similarity index 100% rename from developers/building/pvusb.md rename to building/pvusb.md diff --git a/developers/building/qubes-builder-details.md b/building/qubes-builder-details.md similarity index 100% rename from developers/building/qubes-builder-details.md rename to building/qubes-builder-details.md diff --git a/developers/building/qubes-builder.md b/building/qubes-builder.md similarity index 100% rename from developers/building/qubes-builder.md rename to building/qubes-builder.md diff --git a/developers/building/qubes-r3-building.md b/building/qubes-r3-building.md similarity index 100% rename from developers/building/qubes-r3-building.md rename to building/qubes-r3-building.md diff --git a/developers/debugging/automated-tests.md b/debugging/automated-tests.md similarity index 100% rename from developers/debugging/automated-tests.md rename to debugging/automated-tests.md diff --git a/developers/debugging/profiling.md b/debugging/profiling.md similarity index 100% rename from developers/debugging/profiling.md rename to debugging/profiling.md diff --git a/developers/debugging/test-bench.md b/debugging/test-bench.md similarity index 100% rename from developers/debugging/test-bench.md rename to debugging/test-bench.md diff --git a/developers/debugging/vm-interface.md b/debugging/vm-interface.md similarity index 100% rename from developers/debugging/vm-interface.md rename to debugging/vm-interface.md diff --git a/developers/debugging/windows-debugging.md b/debugging/windows-debugging.md similarity index 100% rename from developers/debugging/windows-debugging.md rename to debugging/windows-debugging.md diff --git a/doc.md b/doc.md index cbfdcbd8..406170f6 100644 --- a/doc.md +++ b/doc.md @@ -10,6 +10,9 @@ redirect_from: - /wiki/QubesDocs/ --- +User Documentation +================== + The Basics ---------- @@ -170,11 +173,12 @@ Presentation Slides * [[PDF] LinuxCon 2014 -- Qubes OS R2 Tutorial](/attachment/wiki/slides/LinuxCon_2014_Qubes_Tutorial.pdf) * [[PDF] LinuxCon 2014 -- Qubes OS Keynote](/attachment/wiki/slides/LinuxCon_2014_Qubes_Keynote.pdf) +Developer Documentation +======================= -For Developers --------------- +The Basics +---------- - * [System Documentation](/doc/system-doc/) * [Developers' FAQ](/doc/devel-faq/) * [Feature Development Tracker](/qubes-issues/) * [Reporting Security Issues](/security/) @@ -189,3 +193,42 @@ For Developers * [Style Guide](/doc/style-guide/) * [Usability & UX](/doc/usability-ux/) +System +------ + * [Qubes OS Architecture Overview](/doc/architecture/) + * [Qubes OS Architecture Spec v0.3 [PDF]](/attachment/wiki/QubesArchitecture/arch-spec-0.3.pdf) + (The original 2009 document that started this all...) + * [Security-critical elements of Qubes OS](/doc/security-critical-code/) + * [Qrexec: command execution in VMs](/doc/qrexec3/) + * [Qubes GUI virtualization protocol](/doc/gui/) + * [Networking in Qubes](/doc/networking/) + * [Implementation of template sharing and updating](/doc/template-implementation/) + +Services +-------- + * [Inter-domain file copying](/doc/qfilecopy/) (deprecates [`qfileexchgd`](/doc/qfileexchgd/)) + * [Dynamic memory management in Qubes](/doc/qmemman/) + * [Implementation of DisposableVMs](/doc/dvm-impl/) + * [Article about disposable VMs](http://theinvisiblethings.blogspot.com/2010/06/disposable-vms.html) + * [Dom0 secure update mechanism](/doc/dom0-secure-updates/) + * VM secure update mechanism (forthcoming) + +Debugging +--------- + * [Profiling python code](/doc/profiling/) + * [Test environment in separate machine for automatic tests](/doc/test-bench/) + * [Automated tests](/doc/automated-tests/) + * [VM-dom0 internal configuration interface](/doc/vm-interface/) + * [Debugging Windows VMs](/doc/windows-debugging/) + +Building +-------- + * [Building Qubes](/doc/qubes-builder/) (["API" Details](/doc/qubes-builder-details/)) + * [Development Workflow](/doc/development-workflow/) + * [KDE Dom0 packages for Qubes](/doc/kde-dom0/) + * [Building Qubes OS 3.0 ISO](/doc/qubes-r3-building/) + * [Building USB passthrough support (experimental)](/doc/pvusb/) + * [Building a TemplateVM based on a new OS (ArchLinux example)](/doc/building-non-fedora-template/) + * [Building the Archlinux Template](/doc/building-archlinux-template/) + + diff --git a/developers/services/dom0-secure-updates.md b/services/dom0-secure-updates.md similarity index 100% rename from developers/services/dom0-secure-updates.md rename to services/dom0-secure-updates.md diff --git a/developers/services/dvm-impl.md b/services/dvm-impl.md similarity index 100% rename from developers/services/dvm-impl.md rename to services/dvm-impl.md diff --git a/developers/services/qfilecopy.md b/services/qfilecopy.md similarity index 100% rename from developers/services/qfilecopy.md rename to services/qfilecopy.md diff --git a/developers/services/qfileexchgd.md b/services/qfileexchgd.md similarity index 100% rename from developers/services/qfileexchgd.md rename to services/qfileexchgd.md diff --git a/developers/services/qmemman.md b/services/qmemman.md similarity index 100% rename from developers/services/qmemman.md rename to services/qmemman.md diff --git a/developers/services/qrexec2.md b/services/qrexec2.md similarity index 100% rename from developers/services/qrexec2.md rename to services/qrexec2.md diff --git a/developers/services/qrexec3.md b/services/qrexec3.md similarity index 100% rename from developers/services/qrexec3.md rename to services/qrexec3.md diff --git a/developers/fundamentals/architecture.md b/system/architecture.md similarity index 100% rename from developers/fundamentals/architecture.md rename to system/architecture.md diff --git a/developers/fundamentals/gui.md b/system/gui.md similarity index 100% rename from developers/fundamentals/gui.md rename to system/gui.md diff --git a/developers/fundamentals/networking.md b/system/networking.md similarity index 100% rename from developers/fundamentals/networking.md rename to system/networking.md diff --git a/developers/fundamentals/security-critical-code.md b/system/security-critical-code.md similarity index 100% rename from developers/fundamentals/security-critical-code.md rename to system/security-critical-code.md diff --git a/developers/fundamentals/template-implementation.md b/system/template-implementation.md similarity index 100% rename from developers/fundamentals/template-implementation.md rename to system/template-implementation.md From c93414f4c17ff1c7036b1aab89d787d1ad0eba36 Mon Sep 17 00:00:00 2001 From: Jeeppler Date: Sat, 25 Jun 2016 17:27:49 -0500 Subject: [PATCH 049/708] merge --- doc.md | 56 ++++++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 48 insertions(+), 8 deletions(-) diff --git a/doc.md b/doc.md index 32fe9a49..7e398ff1 100644 --- a/doc.md +++ b/doc.md @@ -10,6 +10,9 @@ redirect_from: - /wiki/QubesDocs/ --- +User Documentation +================== + The Basics ---------- @@ -64,10 +67,6 @@ Managing Operating Systems within Qubes * [Templates: Ubuntu](/doc/templates/ubuntu/) * [Templates: Whonix](/doc/whonix/) * [How to Reinstall a TemplateVM](/doc/reinstall-template) - * [Pentesting](/doc/pentesting/) - * [Pentesting: BlackArch](/doc/pentesting/blackarch/) - * [Pentesting: Kali](/doc/pentesting/kali/) - * [Pentesting: PTF](/doc/pentesting/ptf/) * [Installing and Using Windows-based AppVMs (Qubes R2 Beta 3 and later)](/doc/windows-appvms/) * [Creating and Using HVM and Windows Domains (Qubes R2+)](/doc/hvm/) * [Advanced options and troubleshooting of Qubes Tools for Windows (R3)](/doc/windows-tools-3/) @@ -144,7 +143,6 @@ Customization Guides * [Installing XFCE in dom0](/doc/xfce/) * [Installing i3 in dom0](/doc/i3/) * [Language Localization](/doc/language-localization/) - * [Dark Theme in Dom0 and DomU](/doc/dark-theme/) Troubleshooting @@ -175,11 +173,12 @@ Presentation Slides * [[PDF] LinuxCon 2014 -- Qubes OS R2 Tutorial](/attachment/wiki/slides/LinuxCon_2014_Qubes_Tutorial.pdf) * [[PDF] LinuxCon 2014 -- Qubes OS Keynote](/attachment/wiki/slides/LinuxCon_2014_Qubes_Keynote.pdf) +Developer Documentation +======================= -For Developers --------------- +The Basics +---------- - * [System Documentation](/doc/system-doc/) * [Developers' FAQ](/doc/devel-faq/) * [Feature Development Tracker](/qubes-issues/) * [Reporting Security Issues](/security/) @@ -193,3 +192,44 @@ For Developers * [Qubes OS License](/doc/license/) * [Style Guide](/doc/style-guide/) * [Usability & UX](/doc/usability-ux/) + +System +------ + * [Qubes OS Architecture Overview](/doc/architecture/) + * [Qubes OS Architecture Spec v0.3 [PDF]](/attachment/wiki/QubesArchitecture/arch-spec-0.3.pdf) + (The original 2009 document that started this all...) + * [Security-critical elements of Qubes OS](/doc/security-critical-code/) + * [Qrexec: command execution in VMs](/doc/qrexec3/) + * [Qubes GUI virtualization protocol](/doc/gui/) + * [Networking in Qubes](/doc/networking/) + * [Implementation of template sharing and updating](/doc/template-implementation/) + +Services +-------- + * [Inter-domain file copying](/doc/qfilecopy/) (deprecates [`qfileexchgd`](/doc/qfileexchgd/)) + * [Dynamic memory management in Qubes](/doc/qmemman/) + * [Implementation of DisposableVMs](/doc/dvm-impl/) + * [Article about disposable VMs](http://theinvisiblethings.blogspot.com/2010/06/disposable-vms.html) + * [Dom0 secure update mechanism](/doc/dom0-secure-updates/) + * VM secure update mechanism (forthcoming) + +Debugging +--------- + * [Profiling python code](/doc/profiling/) + * [Test environment in separate machine for automatic tests](/doc/test-bench/) + * [Automated tests](/doc/automated-tests/) + * [VM-dom0 internal configuration interface](/doc/vm-interface/) + * [Debugging Windows VMs](/doc/windows-debugging/) + +Building +-------- + * [Building Qubes](/doc/qubes-builder/) (["API" Details](/doc/qubes-builder-details/)) + * [Development Workflow](/doc/development-workflow/) + * [KDE Dom0 packages for Qubes](/doc/kde-dom0/) + * [Building Qubes OS 3.0 ISO](/doc/qubes-r3-building/) + * [Building USB passthrough support (experimental)](/doc/pvusb/) + * [Building a TemplateVM based on a new OS (ArchLinux example)](/doc/building-non-fedora-template/) + * [Building the Archlinux Template](/doc/building-archlinux-template/) + + + From a14e5f007d285f798d6365668b286f66671aae52 Mon Sep 17 00:00:00 2001 From: Jeeppler Date: Sat, 25 Jun 2016 17:30:32 -0500 Subject: [PATCH 050/708] merge --- doc.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/doc.md b/doc.md index 7e398ff1..873451cf 100644 --- a/doc.md +++ b/doc.md @@ -67,6 +67,10 @@ Managing Operating Systems within Qubes * [Templates: Ubuntu](/doc/templates/ubuntu/) * [Templates: Whonix](/doc/whonix/) * [How to Reinstall a TemplateVM](/doc/reinstall-template) + * [Pentesting](/doc/pentesting/) + * [Pentesting: BlackArch](/doc/pentesting/blackarch/) + * [Pentesting: Kali](/doc/pentesting/kali/) + * [Pentesting: PTF](/doc/pentesting/ptf/) * [Installing and Using Windows-based AppVMs (Qubes R2 Beta 3 and later)](/doc/windows-appvms/) * [Creating and Using HVM and Windows Domains (Qubes R2+)](/doc/hvm/) * [Advanced options and troubleshooting of Qubes Tools for Windows (R3)](/doc/windows-tools-3/) From 02c2621efcab1c6dd97817d3f69aecb78653b25a Mon Sep 17 00:00:00 2001 From: Jeeppler Date: Sat, 25 Jun 2016 18:08:11 -0500 Subject: [PATCH 051/708] Dark Theme layout fixes --- customization/dark-theme.md | 121 +++++++++++++++--------------------- doc.md | 1 + 2 files changed, 52 insertions(+), 70 deletions(-) diff --git a/customization/dark-theme.md b/customization/dark-theme.md index b82ba8a3..e1e53bdf 100644 --- a/customization/dark-theme.md +++ b/customization/dark-theme.md @@ -20,58 +20,55 @@ This is the result after applying the steps described here. 1 - Change `Workspace Appearance` - 1. Open the `Workspace Appearance` window +1. Open the `Workspace Appearance` window - ~~~ - Qubes Menu -> System Tools -> System Settings -> Workspace Appearance - ~~~ + Qubes Menu -> System Tools -> System Settings -> Workspace Appearance - ![Workspace Appearance](/attachment/wiki/Dark-Theme/kde-app-appearance-menu-style.png) + ![Workspace Appearance](/attachment/wiki/Dark-Theme/kde-app-appearance-menu-style.png) - 2. Go to `Desktop Theme` +2. Go to `Desktop Theme` - ![Desktop Menu](/attachment/wiki/Dark-Theme/kde-appearance-settings-desktop-theme-oxygen.png) + ![Desktop Menu](/attachment/wiki/Dark-Theme/kde-appearance-settings-desktop-theme-oxygen.png) - 3. Select `Oxygen` and `Apply` the change +3. Select `Oxygen` and `Apply` the change 2 - (Optional) Remove blue glowing task items ![blue glowing task bar items](/attachment/wiki/Dark-Theme/kde-taskbar-blue-glowing-border.png) - 1. Adjust Oxygen `Details` +1. Adjust Oxygen `Details` - ~~~ - Qubes Menu -> System Tools -> System Settings -> Workspace Appearance -> Desktop Theme -> Details (Tab) - ~~~ + Qubes Menu -> System Tools -> System Settings -> Workspace Appearance -> Desktop Theme -> Details (Tab) - 2. Select `Oxygen` +2. Select `Oxygen` - 3. Change `Theme Item -> Task Items` from `Oxygen Task Items` to `Air Task Items` +3. Change `Theme Item -> Task Items` from `Oxygen Task Items` to `Air Task Items` - ![Change Task items look](/attachment/wiki/Dark-Theme/kde-desktop-theme-details.png) - 4. Apply changes + ![Change Task items look](/attachment/wiki/Dark-Theme/kde-desktop-theme-details.png) + +4. Apply changes ![task bar items blue glowing removed](/attachment/wiki/Dark-Theme/kde-taskbar-blue-glowing-removed.png) 3 - Change `Application Appearance` - 1. Open the `Application Appearance` window +1. Open the `Application Appearance` window - ~~~ - Qubes Menu -> System Tools -> System Settings -> Application Appearance - ~~~ - 2. Go to `Colors` + Qubes Menu -> System Tools -> System Settings -> Application Appearance + + +2. Go to `Colors` ![colors tab](/attachment/wiki/Dark-Theme/kde-app-appearance-menu-colors.png) - 3. Select `Obsidian Coast` +3. Select `Obsidian Coast` ![set to Obsidian Coast](/attachment/wiki/Dark-Theme/kde-app-appearance-menu-colors-set.png) - 4. Apply Changes +4. Apply Changes - Qubes VM Manager should now look like the image below. + Qubes VM Manager should now look like the image below. ![result black Qubes Manager](/attachment/wiki/Dark-Theme/kde-black-qubes-manager.png) @@ -90,29 +87,25 @@ This is the result after applying the steps described here. 1 - Change Appearance - 1. Open the `Appearance` dialog +1. Open the `Appearance` dialog - ~~~ - Qubes Menu -> System Tools -> Appearance - ~~~ + Qubes Menu -> System Tools -> Appearance ![appearance dialog](/attachment/wiki/Dark-Theme/xfce-appearance-dialog.png) - 2. Change Style to `Albatross` +2. Change Style to `Albatross` **Note:** The black appearance theme `Xfce-dusk` makes the VM names in the `Qubes OS Manager` unreadable. 2 - *(Optional)* Change Window Manager Style - 1. Open the `Window Manager` dialog +1. Open the `Window Manager` dialog - ~~~ - Qubes Menu -> System Tools -> Appearance - ~~~ + Qubes Menu -> System Tools -> Appearance ![window manager dialog](/attachment/wiki/Dark-Theme/xfce-window-manager-theme.png) - 2. Change the Theme in the `Style` Tab (e. g. Defcon-IV). All available themes work. +2. Change the Theme in the `Style` Tab (e. g. Defcon-IV). All available themes work. Dark App VM, Template VM, Standalone VM, HVM (Linux Gnome) @@ -120,7 +113,7 @@ Dark App VM, Template VM, Standalone VM, HVM (Linux Gnome) Almost all Qubes VM's are based on the Gnome desktop. Therefor the description below is focused on the Gnome Desktop Environment. -Using `Gnome-Tweak-Tool` +Using "Gnome-Tweak-Tool" ------------------------ The advantage of creating a dark themed Template VM is, that each AppVM which is derived from the Template VM will be dark themed by default. @@ -133,54 +126,46 @@ The advantage of creating a dark themed Template VM is, that each AppVM which is 1 - Install `Gnome-Tweak-Tool` - 1. Fedora +1. Fedora - ~~~ - sudo dnf install gnome-tweak-tool - ~~~ + sudo dnf install gnome-tweak-tool - 2. Debian +2. Debian - ~~~ - sudo apt-get install gnome-tweak-tool - ~~~ + sudo apt-get install gnome-tweak-tool 2 - *(Only AppVM)* Stop template and start AppVM 3 - Add `Gnome-Tweak-Tool` to the Application Menu - 1. `Right-click` on VM entry in `Qubes VM Manager` select `Add/remove app shortcuts` +1. `Right-click` on VM entry in `Qubes VM Manager` select `Add/remove app shortcuts` - 2. Select `Tweak Tool` and press the `>` button to add it +2. Select `Tweak Tool` and press the `>` button to add it - ![Application Dialog](/attachment/wiki/Dark-Theme/dialog-add-gnome-tweak-tool.png) + ![Application Dialog](/attachment/wiki/Dark-Theme/dialog-add-gnome-tweak-tool.png) 4 - Enable `Global Dark Theme` - 1. *Debian only* +1. *Debian only* - ~~~ - cd ~/.config/ - mkdir gtk-3.0 - cd gtk-3.0/ - touch settings.ini - ~~~ + cd ~/.config/ + mkdir gtk-3.0 + cd gtk-3.0/ + touch settings.ini - 2. Start `Tweak Tool` from the VM application menu and set the `Global Dark Theme` switch to `on` +2. Start `Tweak Tool` from the VM application menu and set the `Global Dark Theme` switch to `on` - ![Global Dark Theme enabled](/attachment/wiki/Dark-Theme/gnome-tweak-tool.png) + ![Global Dark Theme enabled](/attachment/wiki/Dark-Theme/gnome-tweak-tool.png) 5 - *(Optional)* Modify Firefox **Note:** Firefox uses GTK style settings by default. This can create side effects such as unusable forms or search fields. There are two different ways to avoid this. Either by using a add-on or by overwriting the defaults. - - use the theme [GTK+ Dark Theme Global Fixes](https://userstyles.org/styles/111694/gtk-dark-theme-global-fixes) and the [Stylish](https://addons.mozilla.org/en-US/firefox/addon/stylish/) addon +- use the theme [GTK+ Dark Theme Global Fixes](https://userstyles.org/styles/111694/gtk-dark-theme-global-fixes) and the [Stylish](https://addons.mozilla.org/en-US/firefox/addon/stylish/) addon - - or add the following line to `/rw/config/rc.local` +- or add the following line to `/rw/config/rc.local` - ~~~ - sed -i.bak "s/Exec=firefox %u/Exec=bash -c 'GTK_THEME=Adwaita:light firefox %u'/g" /usr/share/applications/firefox.desktop - ~~~ + sed -i.bak "s/Exec=firefox %u/Exec=bash -c 'GTK_THEME=Adwaita:light firefox %u'/g" /usr/share/applications/firefox.desktop 6 - Restart VM or all application @@ -195,18 +180,14 @@ Manually works for Debian, Fedora and Archlinux. 1 - Enable `Global Dark Theme` -~~~ -cd ~/.config/ -mkdir gtk-3.0 -cd gtk-3.0/ -touch settings.ini -~~~ + cd ~/.config/ + mkdir gtk-3.0 + cd gtk-3.0/ + touch settings.ini add the following lines to `settings.ini` -~~~ -[Settings] -gtk-application-prefer-dark-theme=1 -~~~ + [Settings] + gtk-application-prefer-dark-theme=1 2 - follow step 5 and 6 in: Using `Gnome-Tweak-Tool` diff --git a/doc.md b/doc.md index 873451cf..4aee11e7 100644 --- a/doc.md +++ b/doc.md @@ -147,6 +147,7 @@ Customization Guides * [Installing XFCE in dom0](/doc/xfce/) * [Installing i3 in dom0](/doc/i3/) * [Language Localization](/doc/language-localization/) + * [Dark Theme in Dom0 and DomU](/doc/dark-theme/) Troubleshooting From 4db5ca5184341ba3798f5ec902351b57860a4988 Mon Sep 17 00:00:00 2001 From: Jeeppler Date: Sat, 25 Jun 2016 19:20:13 -0500 Subject: [PATCH 052/708] layout fixes, indentation and small typo fixes --- customization/dark-theme.md | 140 +++++++++-------- managing-os/pentesting.md | 11 +- managing-os/pentesting/blackarch.md | 90 +++++------ managing-os/pentesting/kali.md | 226 ++++++++++++---------------- managing-os/pentesting/ptf.md | 120 ++++++--------- 5 files changed, 255 insertions(+), 332 deletions(-) diff --git a/customization/dark-theme.md b/customization/dark-theme.md index e1e53bdf..5599a848 100644 --- a/customization/dark-theme.md +++ b/customization/dark-theme.md @@ -18,61 +18,59 @@ The image below shows the default light theme after installation. This is the result after applying the steps described here. ![end result dark theme](/attachment/wiki/Dark-Theme/kde-end-result.png) -1 - Change `Workspace Appearance` +1. Change `Workspace Appearance` -1. Open the `Workspace Appearance` window + 1. Open the `Workspace Appearance` window - Qubes Menu -> System Tools -> System Settings -> Workspace Appearance + Qubes Menu -> System Tools -> System Settings -> Workspace Appearance - ![Workspace Appearance](/attachment/wiki/Dark-Theme/kde-app-appearance-menu-style.png) + ![Workspace Appearance](/attachment/wiki/Dark-Theme/kde-app-appearance-menu-style.png) -2. Go to `Desktop Theme` + 2. Go to `Desktop Theme` - ![Desktop Menu](/attachment/wiki/Dark-Theme/kde-appearance-settings-desktop-theme-oxygen.png) + ![Desktop Menu](/attachment/wiki/Dark-Theme/kde-appearance-settings-desktop-theme-oxygen.png) -3. Select `Oxygen` and `Apply` the change + 3. Select `Oxygen` and `Apply` the change -2 - (Optional) Remove blue glowing task items +2. (Optional) Remove blue glowing task items -![blue glowing task bar items](/attachment/wiki/Dark-Theme/kde-taskbar-blue-glowing-border.png) + ![blue glowing task bar items](/attachment/wiki/Dark-Theme/kde-taskbar-blue-glowing-border.png) -1. Adjust Oxygen `Details` + 1. Adjust Oxygen `Details` - Qubes Menu -> System Tools -> System Settings -> Workspace Appearance -> Desktop Theme -> Details (Tab) + Qubes Menu -> System Tools -> System Settings -> Workspace Appearance -> Desktop Theme -> Details (Tab) -2. Select `Oxygen` + 2. Select `Oxygen` -3. Change `Theme Item -> Task Items` from `Oxygen Task Items` to `Air Task Items` + 3. Change `Theme Item -> Task Items` from `Oxygen Task Items` to `Air Task Items` - ![Change Task items look](/attachment/wiki/Dark-Theme/kde-desktop-theme-details.png) + ![Change Task items look](/attachment/wiki/Dark-Theme/kde-desktop-theme-details.png) -4. Apply changes + 4. Apply changes - ![task bar items blue glowing removed](/attachment/wiki/Dark-Theme/kde-taskbar-blue-glowing-removed.png) + ![task bar items blue glowing removed](/attachment/wiki/Dark-Theme/kde-taskbar-blue-glowing-removed.png) -3 - Change `Application Appearance` +3. Change `Application Appearance` -1. Open the `Application Appearance` window + 1. Open the `Application Appearance` window + Qubes Menu -> System Tools -> System Settings -> Application Appearance - Qubes Menu -> System Tools -> System Settings -> Application Appearance + 2. Go to `Colors` + ![colors tab](/attachment/wiki/Dark-Theme/kde-app-appearance-menu-colors.png) -2. Go to `Colors` + 3. Select `Obsidian Coast` - ![colors tab](/attachment/wiki/Dark-Theme/kde-app-appearance-menu-colors.png) + ![set to Obsidian Coast](/attachment/wiki/Dark-Theme/kde-app-appearance-menu-colors-set.png) -3. Select `Obsidian Coast` + 4. Apply Changes - ![set to Obsidian Coast](/attachment/wiki/Dark-Theme/kde-app-appearance-menu-colors-set.png) + Qubes VM Manager should now look like the image below. -4. Apply Changes + ![result black Qubes Manager](/attachment/wiki/Dark-Theme/kde-black-qubes-manager.png) - Qubes VM Manager should now look like the image below. - - ![result black Qubes Manager](/attachment/wiki/Dark-Theme/kde-black-qubes-manager.png) - -**Note:** Chaning the `Window Decorations` from `Plastik for Qubes` will remove the border color and the VM name. The problem with `Plastik for Qubes` is it does not overwrite the background and text color for Minimize, Maximize and Close buttons. The three button are therefor hard to read. +**Note:** Chaning the `Window Decorations` from `Plastik for Qubes` will remove the border color and the VM name. The problem with `Plastik for Qubes` is, that it does not overwrite the background and text color for Minimize, Maximize and Close buttons. The three button are therefor hard to read. Dark XCFE in Dom0 ----------------- @@ -85,27 +83,27 @@ The image below shows the default light theme after installation. This is the result after applying the steps described here. ![end result dark theme](/attachment/wiki/Dark-Theme/xfce-end-result.png) -1 - Change Appearance +1. Change Appearance -1. Open the `Appearance` dialog + 1. Open the `Appearance` dialog - Qubes Menu -> System Tools -> Appearance + Qubes Menu -> System Tools -> Appearance - ![appearance dialog](/attachment/wiki/Dark-Theme/xfce-appearance-dialog.png) + ![appearance dialog](/attachment/wiki/Dark-Theme/xfce-appearance-dialog.png) -2. Change Style to `Albatross` + 2. Change Style to `Albatross` -**Note:** The black appearance theme `Xfce-dusk` makes the VM names in the `Qubes OS Manager` unreadable. + **Note:** The black appearance theme `Xfce-dusk` makes the VM names in the `Qubes OS Manager` unreadable. -2 - *(Optional)* Change Window Manager Style +2. *(Optional)* Change Window Manager Style -1. Open the `Window Manager` dialog + 1. Open the `Window Manager` dialog - Qubes Menu -> System Tools -> Appearance + Qubes Menu -> System Tools -> Appearance - ![window manager dialog](/attachment/wiki/Dark-Theme/xfce-window-manager-theme.png) + ![window manager dialog](/attachment/wiki/Dark-Theme/xfce-window-manager-theme.png) -2. Change the Theme in the `Style` Tab (e. g. Defcon-IV). All available themes work. + 2. Change the Theme in the `Style` Tab (e. g. Defcon-IV). All available themes work. Dark App VM, Template VM, Standalone VM, HVM (Linux Gnome) @@ -120,74 +118,74 @@ The advantage of creating a dark themed Template VM is, that each AppVM which is **Note:** Gnome-Tweak-Tool crashes under Archlinux. A workaround is to assign the AppVM to another TemplateVM (Debian, Fedora) which has Gnome-Tweak-Tool installed. Start the AppVM and configure the settings. Shutdown the machine and switch the template VM back to Archlinux. -0 - Start VM +1. Start VM -**Note:** In case of App VM start the Template on which the AppVM is based on. + **Note:** In case of App VM start the Template on which the AppVM is based on. -1 - Install `Gnome-Tweak-Tool` +2. Install `Gnome-Tweak-Tool` -1. Fedora + - Fedora - sudo dnf install gnome-tweak-tool + sudo dnf install gnome-tweak-tool -2. Debian + - Debian - sudo apt-get install gnome-tweak-tool + sudo apt-get install gnome-tweak-tool -2 - *(Only AppVM)* Stop template and start AppVM +3. *(Only AppVM)* Stop template and start AppVM -3 - Add `Gnome-Tweak-Tool` to the Application Menu +4. Add `Gnome-Tweak-Tool` to the Application Menu -1. `Right-click` on VM entry in `Qubes VM Manager` select `Add/remove app shortcuts` + 1. `Right-click` on VM entry in `Qubes VM Manager` select `Add/remove app shortcuts` -2. Select `Tweak Tool` and press the `>` button to add it + 2. Select `Tweak Tool` and press the `>` button to add it - ![Application Dialog](/attachment/wiki/Dark-Theme/dialog-add-gnome-tweak-tool.png) + ![Application Dialog](/attachment/wiki/Dark-Theme/dialog-add-gnome-tweak-tool.png) -4 - Enable `Global Dark Theme` +5. Enable `Global Dark Theme` -1. *Debian only* + 1. *Debian only* - cd ~/.config/ - mkdir gtk-3.0 - cd gtk-3.0/ - touch settings.ini + cd ~/.config/ + mkdir gtk-3.0 + cd gtk-3.0/ + touch settings.ini -2. Start `Tweak Tool` from the VM application menu and set the `Global Dark Theme` switch to `on` + 2. Start `Tweak Tool` from the VM application menu and set the `Global Dark Theme` switch to `on` - ![Global Dark Theme enabled](/attachment/wiki/Dark-Theme/gnome-tweak-tool.png) + ![Global Dark Theme enabled](/attachment/wiki/Dark-Theme/gnome-tweak-tool.png) -5 - *(Optional)* Modify Firefox +6. *(Optional)* Modify Firefox -**Note:** Firefox uses GTK style settings by default. This can create side effects such as unusable forms or search fields. There are two different ways to avoid this. Either by using a add-on or by overwriting the defaults. + **Note:** Firefox uses GTK style settings by default. This can create side effects such as unusable forms or search fields. There are two different ways to avoid this. Either by using a add-on or by overwriting the defaults. -- use the theme [GTK+ Dark Theme Global Fixes](https://userstyles.org/styles/111694/gtk-dark-theme-global-fixes) and the [Stylish](https://addons.mozilla.org/en-US/firefox/addon/stylish/) addon + - use the theme [GTK+ Dark Theme Global Fixes](https://userstyles.org/styles/111694/gtk-dark-theme-global-fixes) and the [Stylish](https://addons.mozilla.org/en-US/firefox/addon/stylish/) addon -- or add the following line to `/rw/config/rc.local` + - or add the following line to `/rw/config/rc.local` - sed -i.bak "s/Exec=firefox %u/Exec=bash -c 'GTK_THEME=Adwaita:light firefox %u'/g" /usr/share/applications/firefox.desktop + sed -i.bak "s/Exec=firefox %u/Exec=bash -c 'GTK_THEME=Adwaita:light firefox %u'/g" /usr/share/applications/firefox.desktop -6 - Restart VM or all application +7. Restart VM or all application Manually -------- Manually works for Debian, Fedora and Archlinux. -0 - Start VM +1. Start VM -**Note:** In case of App VM start the Template on which the AppVM is based on. + **Note:** In case of App VM start the Template on which the AppVM is based on. -1 - Enable `Global Dark Theme` +2. Enable `Global Dark Theme` cd ~/.config/ mkdir gtk-3.0 cd gtk-3.0/ touch settings.ini -add the following lines to `settings.ini` + add the following lines to `settings.ini` [Settings] gtk-application-prefer-dark-theme=1 -2 - follow step 5 and 6 in: Using `Gnome-Tweak-Tool` +3. follow step 6 and 7 in: Using `Gnome-Tweak-Tool` diff --git a/managing-os/pentesting.md b/managing-os/pentesting.md index 60452018..e3377206 100644 --- a/managing-os/pentesting.md +++ b/managing-os/pentesting.md @@ -8,15 +8,15 @@ permalink: /doc/pentesting/ The usage of penetration testing tools outside your own laboratory environment requires the permission of the organization you attack. Penetration testing without such a permission can have legal consequences. -To avoid such legal conflicts please refer to the [Code of Ethics](https://www.eccouncil.org/Support/code-of-ethics). +To avoid such legal conflicts please refer to the [EC-Council: Code of Ethics](https://www.eccouncil.org/Support/code-of-ethics). Penetration Testing =================== "A penetration test, informally pen test, is an attack on a computer system that looks for security weaknesses, potentially gaining access to the computer's features and data." (source [Penetration test](https://en.wikipedia.org/wiki/Penetration_test)). -Penetration Testing Distributions: ----------------------------------- +Penetration Testing Distributions +--------------------------------- The following install instructions explain how to setup a penetration testing distribution within Qubes OS. @@ -27,7 +27,4 @@ The following install instructions explain how to setup a penetration testing di Using Qubes OS to host a "hacking" laboratory --------------------------------------------- -Qubes OS is a hypervisor based operating system. Qubes OS can various operating systems such as Linux, Unix or Windows in parallel. Qubes OS can therefor be used to host your own "hacking" laboratory. - -- [Creating and Using HVM Domains](/doc/hvm-create/) -- [Templates](/doc/templates/) +Qubes OS is a hypervisor based operating system. Qubes OS can host various operating systems such as Linux, Unix or Windows and run them parallel. Qubes OS can therefor be used to host your own "hacking" laboratory. diff --git a/managing-os/pentesting/blackarch.md b/managing-os/pentesting/blackarch.md index 35377455..8a390e35 100644 --- a/managing-os/pentesting/blackarch.md +++ b/managing-os/pentesting/blackarch.md @@ -23,82 +23,72 @@ How to Create a BlackArch VM Create ArchLinux Based BlackArch Template ----------------------------------------- -0 - Create ArchlLinux Template +1. Create ArchlLinux Template - - Follow the [Archlinux Template instructions](/doc/templates/archlinux/) + - Follow the [Archlinux Template instructions](/doc/templates/archlinux/) -1 - Update Template -~~~ -sudo pacman -Syyu -~~~ +2. Update Template -2 - Clone template + sudo pacman -Syyu -1. Via Qubes VM Manager +3. Clone template -2. Via command line + 1. Via Qubes VM Manager - ~~~ - qvm-clone archlinux blackarch - ~~~ + 2. Via command line -3 - Install BlackArch repository + qvm-clone archlinux blackarch -~~~ -$ curl -O https://blackarch.org/strap.sh +4. Install BlackArch repository -# The SHA1 sum should match: 86eb4efb68918dbfdd1e22862a48fda20a8145ff -$ sha1sum strap.sh + $ curl -O https://blackarch.org/strap.sh -# Set execute bit -$ chmod +x strap.sh + # The SHA1 sum should match: 86eb4efb68918dbfdd1e22862a48fda20a8145ff + $ sha1sum strap.sh -# Run strap.sh -$ sudo ./strap.sh -~~~ + # Set execute bit + $ chmod +x strap.sh -4 - Install tools + # Run strap.sh + $ sudo ./strap.sh - - install all tools +5. Install tools - ~~~ - sudo pacman -S blackarch - ~~~ + - install all tools - - or by category: + sudo pacman -S blackarch - ~~~ - # list available categories - pacman -Sg | grep blackarch + - or by category: - # install category - sudo pacman -S blackarch- + # list available categories + pacman -Sg | grep blackarch - # example - sudo pacman -S blackarch-forensic - ~~~ + # install category + sudo pacman -S blackarch- - - or specific tool + # example + sudo pacman -S blackarch-forensic - ~~~ - # Search for tool - pacman -Ss + - or specific tool - # Install tool - sudo pacman -S + # Search for tool + pacman -Ss - # Example - pacman -Ss burpsuite - sudo pacman -S burpsuite - ~~~ + # Install tool + sudo pacman -S -5 - Create a AppVMs based on the `ptf` template + # Example + pacman -Ss burpsuite + sudo pacman -S burpsuite - - (Optional) Attach necessary devices +6. Create a AppVMs based on the `ptf` template + + - (Optional) Attach necessary devices Alternative Options to BlackArch -------------------------------- - - [Kali](/doc/kali/) - - [PenTester Framework (PTF)](/doc/ptf/) +- [Kali](/doc/kali/) +- [PenTester Framework (PTF)](/doc/ptf/) +- [Pentesting](/doc/pentesting/) diff --git a/managing-os/pentesting/kali.md b/managing-os/pentesting/kali.md index 90fd5a4d..b349aa0e 100644 --- a/managing-os/pentesting/kali.md +++ b/managing-os/pentesting/kali.md @@ -24,213 +24,172 @@ There are multiple ways to create a Kali Linux VM. One way is to create a HVM an Kali Linux HVM -------------- -0 - Download the Kali installation DVD +1. Download the Kali installation DVD -1 - Create a new HVM +2. Create a new HVM -2 - Start the HVM with attached CD/DVD +3. Start the HVM with attached CD/DVD -~~~ -qvm-start --cdrom :/home/user/Downloads/.iso -~~~ + qvm-start --cdrom :/home/user/Downloads/.iso Create Debian Based Kali Template --------------------------------- -0 - (Optional) Install `debian-8` template (if not already installed) +1. *(Optional)* Install `debian-8` template (if not already installed) -1 - Update your `debian-8` template +2. Update your `debian-8` template -~~~ -sudo apt-get update -sudo apt-get dist-upgrade -~~~ + sudo apt-get update + sudo apt-get dist-upgrade -2 - Clone `debian-8` template (two options) +3. Clone `debian-8` template (two options) - 1. Via Qubes VM Manager + 1. Via Qubes VM Manager - ![Clone Debian Template](/attachment/wiki/Kali/clone-kali.png) + ![Clone Debian Template](/attachment/wiki/Kali/clone-kali.png) - 2. Via command line + 2. Via command line - ~~~ - qvm-clone debian-8 kali - ~~~ + qvm-clone debian-8 kali -3 - Start and upgrade the `kali` Template from Debian 8 to Debian 9 +4. Start and upgrade the `kali` Template from Debian 8 to Debian 9 -~~~ -user@kali:~$ sudo sed -i 's/jessie/stretch/g' /etc/apt/sources.list -user@kali:~$ sudo sed -i 's/jessie/stretch/g' /etc/apt/sources.list.d/qubes-r3.list -user@kali:~$ sudo apt-get update -user@kali:~$ sudo apt-get dist-upgrade -user@kali:~$ sudo apt-get autoremove -~~~ + sudo sed -i 's/jessie/stretch/g' /etc/apt/sources.list + sudo sed -i 's/jessie/stretch/g' /etc/apt/sources.list.d/qubes-r3.list + sudo apt-get update + sudo apt-get dist-upgrade + sudo apt-get autoremove -NOTICE: From now on there are two possible ways either doing everything manually or automatically with [Katoolin](https://github.com/LionSec/katoolin). + **Note:** From now on there are two possible ways either doing everything manually or automatically with [Katoolin](https://github.com/LionSec/katoolin). -Katoolin is a script (written in Python) which helps you to install Kali tools. + Katoolin is a script (written in Python) which helps you to install Kali tools. -4 *manually* - Add Kali Linux repositories +5. *manually* - Add Kali Linux repositories - 1. Add Kali Linux repositories to `/etc/apt/sources.list` + 1. Add Kali Linux repositories to `/etc/apt/sources.list` - ~~~ - deb http://http.kali.org/kali kali-rolling main contrib non-free - deb http://repo.kali.org/kali kali-bleeding-edge main - ~~~ + deb http://http.kali.org/kali kali-rolling main contrib non-free + deb http://repo.kali.org/kali kali-bleeding-edge main - 2. Add kali signing key + 2. Add kali signing key - - The signing key can be found here [Download Kali Linux Images Securely](https://www.kali.org/downloads/) + - The signing key can be found here [Download Kali Linux Images Securely](https://www.kali.org/downloads/) - ~~~ - sudo apt-key adv --keyserver hkp://keys.gnupg.net --recv-keys 7D8D0BF6 - sudo apt-get update - ~~~ + sudo apt-key adv --keyserver hkp://keys.gnupg.net --recv-keys 7D8D0BF6 + sudo apt-get update -4 *katoolin* - Install Katoolin and add Kali Linux repositories +6. *katoolin* - Install Katoolin and add Kali Linux repositories - 1. Install Katoolin + 1. Install Katoolin - ~~~ - sudo apt-get install git - git clone https://github.com/LionSec/katoolin.git - sudo cp katoolin/katoolin.py /usr/bin/katoolin - sudo chmod +x /usr/bin/katoolin - rm -rf katoolin - ~~~ + sudo apt-get install git + git clone https://github.com/LionSec/katoolin.git + sudo cp katoolin/katoolin.py /usr/bin/katoolin + sudo chmod +x /usr/bin/katoolin + rm -rf katoolin - 2. Add Kali Linux repositories + 2. Add Kali Linux repositories - - start katoolin + - start katoolin - ~~~ - sudo katoolin - ~~~ + sudo katoolin - - select 'Add Kali repositories & Update' + - select 'Add Kali repositories & Update' - ~~~ - 1) Add Kali repositories & Update - 2) View Categories - 3) Install classicmenu indicator - 4) Install Kali menu - 5) Help + 1) Add Kali repositories & Update + 2) View Categories + 3) Install classicmenu indicator + 4) Install Kali menu + 5) Help - kat > 1 - ~~~ + kat > 1 - ![Add Kali repositories and Update menu](/attachment/wiki/Kali/katoolin-add-update-repo-menu.png) + ![Add Kali repositories and Update menu](/attachment/wiki/Kali/katoolin-add-update-repo-menu.png) - - select 'Add kali linux repositories' + - select 'Add kali linux repositories' - ~~~ - 1) Add kali linux repositories - 2) Update - 3) Remove all kali linux repositories - 4) View the contents of sources.list file + 1) Add kali linux repositories + 2) Update + 3) Remove all kali linux repositories + 4) View the contents of sources.list file - What do you want to do ?> 1 - ~~~ + What do you want to do ?> 1 - ![Add Kali repositories](/attachment/wiki/Kali/katoolin-add-repos-menu.png) + ![Add Kali repositories](/attachment/wiki/Kali/katoolin-add-repos-menu.png) - - update Kali repositories + - update Kali repositories - ~~~ - 1) Add kali linux repositories - 2) Update - 3) Remove all kali linux repositories - 4) View the contents of sources.list file - What do you want to do ?> 2 - ~~~ + 1) Add kali linux repositories + 2) Update + 3) Remove all kali linux repositories + 4) View the contents of sources.list file - - quit katoolin by pressing `CRTL` + `c` keys + What do you want to do ?> 2 - ~~~ - What do you want to do ?> ^CShutdown requested...Goodbye... - ~~~ + - quit katoolin by pressing `CRTL` + `c` keys -5 - Cleanup and update `kali` template + What do you want to do ?> ^CShutdown requested...Goodbye... -~~~ -sudo apt-get dist-upgrade -sudo apt-get autoremove -~~~ +7. Cleanup and update `kali` template + sudo apt-get dist-upgrade + sudo apt-get autoremove -6 - Shutdown and trim `kali` template +8. Shutdown and trim `kali` template - - Shutdown `kali` template + - Shutdown `kali` template - ~~~ - sudo shutdown -h now - ~~~ + sudo shutdown -h now - - In `dom0` console: + - In `dom0` console: - ~~~ - qvm-trim-template kali - ~~~ + qvm-trim-template kali -7 - Start image +9. Start image -8 *manually* - Install tools +10. *manually* - Install tools -**Warning:** `kali-linux` and `kali-linux-full` does currently not work properly. Please use `Katoolin` or `PTF`. + **Warning:** `kali-linux` and `kali-linux-full` does currently not work properly. Please use `Katoolin` or `PTF`. - 1. List available packages + 1. List available packages - ~~~ - sudo apt-cache search kali-linux - ~~~ + sudo apt-cache search kali-linux - 2. Select and install tools + 2. Select and install tools - - install base system + - install base system - ~~~ - sudo apt-get install kali-linux - ~~~ + sudo apt-get install kali-linux - - or install all tools + - or install all tools - ~~~ - sudo apt-get install kali-linux-full - ~~~ + sudo apt-get install kali-linux-full - - or select specific (example): + - or select specific (example): - ~~~ - sudo apt-get install kali-linux-top10 kali-linux-web - ~~~ + sudo apt-get install kali-linux-top10 kali-linux-web +11. *katoolin* - Install tools -8 *katoolin* - Install tools + 1. View Categories - 1. View Categories + - start katoolin - - start katoolin + sudo katoolin - ~~~ - sudo katoolin - ~~~ + - select `2) View Categories` - - select `2) View Categories` + 2. Select the categories/tools you want to install - 2. Select the categories/tools you want to install + - For more information on how to use Katoolin see [How to Auto Install All Kali Linux Tools Using “Katoolin” on Debian/Ubuntu](http://www.tecmint.com/install-kali-linux-tools-using-katoolin-on-ubuntu-debian/) - - For more information on how to use Katoolin see [How to Auto Install All Kali Linux Tools Using “Katoolin” on Debian/Ubuntu](http://www.tecmint.com/install-kali-linux-tools-using-katoolin-on-ubuntu-debian/) + - **Note:** The `all` option does not work for `Information Gathering`, `Web Apps`, `Forensic Tools`, `Reverse Engineering` and `Extra`. - - **Note:** The `all` option does not work for `Information Gathering`, `Web Apps`, `Forensic Tools`, `Reverse Engineering` and `Extra`. +12. Create a AppVMs based on the `kali` template -9 - Create a AppVMs based on the `kali` template - - - (Optional) Attach necessary devices + - (Optional) Attach necessary devices Alternative Options to Kali @@ -238,3 +197,4 @@ Alternative Options to Kali - [BlackArch](/doc/blackarch/) - [PenTester Framework (PTF)](/doc/ptf/) +- [Pentesting](/doc/pentesting/) diff --git a/managing-os/pentesting/ptf.md b/managing-os/pentesting/ptf.md index 53ca68d5..67755050 100644 --- a/managing-os/pentesting/ptf.md +++ b/managing-os/pentesting/ptf.md @@ -24,114 +24,91 @@ PTF attempts to install all of your penetration testing tools (latest and greate Create Debian Based Penetration Testers Framework (PTF) Template ---------------------------------------------------------------- -1 - Create PTF template +1. Create PTF template - 1. Follow the [Create Debian Based Kali Template](/doc/kali/) till step 7. - 2. (Optional) Rename the cloned template to `ptf` + 1. Follow [Create Debian Based Kali Template](/doc/kali/) till step 7. -2 - Download PTF + 2. (Optional) Rename the cloned template to `ptf` -~~~ -sudo apt-get install git -cd /opt -sudo git clone https://github.com/trustedsec/ptf.git -~~~ +2. Download PTF - - (Optional) Configure PTF + sudo apt-get install git + cd /opt + sudo git clone https://github.com/trustedsec/ptf.git - 1. Go to configuration directory + - (Optional) Configure PTF - ~~~ - cd /opt/ptf/config - ~~~ + 1. Go to configuration directory - 2. Edit the configuration file + cd /opt/ptf/config - for example by using vim: + 2. Edit the configuration file - ~~~ - sudo vim ptf.config - ~~~ + for example by using vim: - The configuration options are described in the `ptf.config` file + sudo vim ptf.config -4 - Install PTF + the configuration options are described in the `ptf.config` file -~~~ -cd /opt/ptf -sudo ./ptf -~~~ +3. Install PTF -**Note:** the config file has to be in the same directory as the executable. It is not + cd /opt/ptf + sudo ./ptf + + **Note:** the config file has to be in the same directory as the executable. It is not possible to do sudo ptf/ptf -PTF will put itself into `/usr/local/bin/ptf`. You can use `ptf` from now on. + PTF will put itself into `/usr/local/bin/ptf`. You can use `ptf` from now on. -5 - Install/Update modules (tools) +4. Install/Update modules (tools) - 1. Start PTF + 1. Start PTF - ~~~ - sudo ptf - ~~~ + sudo ptf - ![PTF start banner](/attachment/wiki/PTF/ptf-banner.png) + ![PTF start banner](/attachment/wiki/PTF/ptf-banner.png) - 2. Show available modules (tools) + 2. Show available modules (tools) - ~~~ - ptf> show modules - ~~~ + ptf> show modules - 3. Install/Update modules (all/) + 3. Install/Update modules (all/) - - Install/Update all tools + - Install/Update all tools - ~~~ - ptf> use modules/install_update_all - ~~~ + ptf> use modules/install_update_all - - or by category Install/Update + - or by category Install/Update - ~~~ - ptf> use modules/code-audit/install_update_all - ~~~ + ptf> use modules/code-audit/install_update_all - - or individually (example Metasploit) + - or individually (example Metasploit) - 1. Search for module + 1. Search for module - ~~~ - ptf> search metasploit - [*] Search results below: - modules/exploitation/metasploit - ~~~ + ptf> search metasploit + [*] Search results below: + modules/exploitation/metasploit - 2. Use module + 2. Use module - ~~~ - ptf> use modules/exploitation/metasploit - ptf:(modules/exploitation/metasploit)> - ~~~ + ptf> use modules/exploitation/metasploit + ptf:(modules/exploitation/metasploit)> - 3. Install module + 3. Install module - ~~~ - ptf:(modules/exploitation/metasploit)>install - ~~~ + ptf:(modules/exploitation/metasploit)>install - 4. Run Metasploit + 4. Run Metasploit - ~~~ - ptf:(modules/exploitation/metasploit)>exit - ptf> quit - [*] Exiting PTF - the easy pentest platform creation framework. - ~$ sudo msfconsole - ~~~ + ptf:(modules/exploitation/metasploit)>exit + ptf> quit + [*] Exiting PTF - the easy pentest platform creation framework. + sudo msfconsole -6 - Create a AppVMs based on the `ptf` template +5. Create a AppVMs based on the `ptf` template - - (Optional) Attach necessary devices + - (Optional) Attach necessary devices Alternative Options to PTF @@ -139,3 +116,4 @@ Alternative Options to PTF - [BlackArch](/doc/blackarch/) - [Kali](/doc/kali/) +- [Pentesting](/doc/pentesting/) From 7ee58d27d0bad369d1eea513c160972daefcd99c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Marczykowski-G=C3=B3recki?= Date: Sun, 26 Jun 2016 12:26:14 +0200 Subject: [PATCH 053/708] Upgrade R3.1->R3.2 instruction --- installing/upgrade/upgrade-to-r3.2.md | 135 ++++++++++++++++++++++++++ 1 file changed, 135 insertions(+) create mode 100644 installing/upgrade/upgrade-to-r3.2.md diff --git a/installing/upgrade/upgrade-to-r3.2.md b/installing/upgrade/upgrade-to-r3.2.md new file mode 100644 index 00000000..86f8f993 --- /dev/null +++ b/installing/upgrade/upgrade-to-r3.2.md @@ -0,0 +1,135 @@ +--- +layout: doc +title: Upgrading to R3.2 +permalink: /doc/upgrade-to-r3.2/ +redirect_from: +- /en/doc/upgrade-to-r3.2/ +- /doc/UpgradeToR3.2/ +- /doc/UpgradeToR3.2rc1/ +--- + +Upgrading Qubes R3.1 to R3.2 +====================================== + +**Caution: The procedure to upgrade from R3.1 to R3.2 is experimental!** + +**Before attempting either an in-place upgrade or a clean installation, we +strongly recommend that users [back up their systems](/doc/backup-restore/).** + +Current Qubes R3.1 systems can be upgraded in-place to the latest R3.2 +by following the procedure below. + +Upgrading dom0 +-------------- + +1. Close Qubes Manager (right click on its tray icon -\> Exit) + +2. Open a terminal in Dom0. (E.g., Start -\> System Settings -\> Konsole.) + +3. Install `qubes-release` package carrying R3.2 repository information. + + sudo qubes-dom0-update --enablerepo=qubes*testing --releasever=3.2 qubes-release + + If you made any manual changes to repository definitions, new definitions + will be installed as `/etc/yum.repos.d/qubes-dom0.repo.rpmnew` (you'll see + a message about it during package installation). In such a case, you need + to manually apply the changes to `/etc/yum.repos.d/qubes-dom0.repo` or + simply replace it with .rpmnew file. + +4. Upgrade dom0 to R3.2: + + sudo qubes-dom0-update + +4. If the previous step completed successfully, your `qubes-core-dom0` version + should be `3.2.3` or higher. If it's not, repeat the previous step with the + `--clean` option. + +5. Update configuration files. + + Some of configuration files were saved with `.rpmnew` extension as the + actual files were modified. During upgrade, you'll see information about + such cases, like: + + warning: /etc/salt/minion.d/f_defaults.conf created as /etc/salt/minion.d/f_defaults.conf.rpmnew + + This will happen for every configuration you have modified manually and for + a few that has been modified by Qubes scripts. If you are not sure what to + do about them, below is a list of commands to deal with few common cases + (either keep the old one, or replace with the new one): + + rm -f /etc/group.rpmnew + rm -f /etc/shadow.rpmnew + rm -f /etc/qubes/guid.conf.rpmnew + mv -f /etc/nsswitch.conf{.rpmnew,} + mv -f /etc/pam.d/postlogin{.rpmnew,} + mv -f /etc/salt/minion.d/f_defaults.conf{.rpmnew,} + mv -f /etc/dracut.conf{.rpmnew,} + +5. Reboot dom0. + +Please note that if you use [Anti Evil Maid](/doc/anti-evil-maid), it won't be +able to unseal the passphrase the first time the system boots after performing +this in-place upgrade procedure since the Xen, kernel, and initramfs binaries +will have changed. Once the system boots up again, you can reseal your Anti Evil +Maid passphrase to the new configuration. Please consult the Anti Evil Maid +[documentation](/doc/anti-evil-maid) for instructions on how to do that. + +At first login after upgrade you may got a message like this: + + Your saved session type 'kde-plasma' is not valid any more. + Please select a new one, otherwise 'default' will be used. + +This is result of upgrade KDE4 (`kde-plasma`) to KDE5 (`plasma`). Simply choose +your favorite desktop environment and continue. + + +Upgrade all Template and Standalone VM(s) +----------------------------------------- + +By default, in Qubes R3.1, there are few TemplateVMs and no StandaloneVMs. +However, users are free to create StandaloneVMs More information on using +multiple TemplateVMs, as well as StandaloneVMs, can be found +[here](/doc/software-update-vm/). The steps described in this section should be +repeated in **all** the user's Template and Standalone VMs. + + +### Upgrade Fedora templates: ### + +1. Open a terminal in the TemplateVM (or StandaloneVM). (E.g., use Qubes VM + Manager's right-click menu, choose "Run Command in VM," and type + `gnome-terminal` there.) + +2. Install the `qubes-upgrade-vm` package: + + sudo dnf install --enablerepo=qubes*testing --refresh qubes-upgrade-vm + +3. Proceed with a normal upgrade in the template: + + sudo dnf upgrade --refresh + +4. Shut down the template VM. + + +### Upgrade Debian (and Whonix) templates: ### + +1. Open a terminal in the TemplateVM (or StandaloneVM). (E.g., use Qubes VM + Manager's right-click menu, choose "Run Command in VM," and type + `gnome-terminal` there.) + +2. Update repository definition: + + sudo cp /etc/apt/sources.list.d/qubes-r3.list /etc/apt/sources.list.d/qubes-r3-upgrade.list + sudo sed -i 's/r3.1/r3.2/' /etc/apt/sources.list.d/qubes-r3-upgrade.list + +3. Proceed with a normal update in the template: + + sudo apt-get update + sudo apt-get dist-upgrade + +4. Remove unnecessary now file: + + sudo rm -f /etc/apt/sources.list.d/qubes-r3-upgrade.list + +5. Shut down the template VM. + + From edf1bf98793650e2d2ee225dbda1243dbc988df7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Marczykowski-G=C3=B3recki?= Date: Sun, 26 Jun 2016 12:26:34 +0200 Subject: [PATCH 054/708] Minor clarification for pvgrub instruction --- configuration/managing-vm-kernel.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/configuration/managing-vm-kernel.md b/configuration/managing-vm-kernel.md index 61a27be5..8da4b078 100644 --- a/configuration/managing-vm-kernel.md +++ b/configuration/managing-vm-kernel.md @@ -239,8 +239,10 @@ sudo yum install qubes-kernel-vm-support grub2-tools Then install whatever kernel you want. If you are using distribution kernel package (`kernel` package), initramfs and kernel module should be handled -automatically. If you are using manually build kernel, you need to handle this -on your own. Take a look at `dkms` and `dracut` documentation. +automatically, but you need to ensure you have `kernel-devel` package for the +same kernel version installed. If you are using manually build kernel, you need +to handle this on your own. Take a look at `dkms` and `dracut` documentation. +Especially `dkms autoinstall` command may be useful. When kernel is installed, you need to create GRUB configuration. You may want to adjust some settings in `/etc/default/grub`, for example lower From b5ff9c06452054175ccd8a453bbdaf4c9da6b7b9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Marczykowski-G=C3=B3recki?= Date: Sun, 26 Jun 2016 12:31:03 +0200 Subject: [PATCH 055/708] Include R3.1->R3.2 upgrade instruction in release notes --- releases/3.2/release-notes.md | 21 +++++++++++++++++++-- 1 file changed, 19 insertions(+), 2 deletions(-) diff --git a/releases/3.2/release-notes.md b/releases/3.2/release-notes.md index 0f50a8c6..35f79d4a 100644 --- a/releases/3.2/release-notes.md +++ b/releases/3.2/release-notes.md @@ -48,13 +48,30 @@ See [Installation Guide](/doc/installation-guide/). Upgrading --------- -There is no in-place upgrade procedure. Proceed with install -from scratch and use [qubes backup and restore tools](/doc/backup-restore/) +### From R3.1 + +The easiest and safest way to upgrade to Qubes R3.2 is to install it from +scratch and use [qubes backup and restore tools][backup] for +migrating of all of the user VMs. + +Users of Qubes R3.1 can also upgrade using [this +procedure][upgrade]. + +### From R3.0 or earlier + +When upgrading from earlier versions the easiest and safest way is to install +it from scratch and use [qubes backup and restore tools][backup] for migrating of all of the user VMs. +Alternatively you can [upgrade to R3.1 using][upgrade-r3.1] first, then follow +the instructions above. This will be time consuming process. + [salt-doc]: /doc/salt/ [usb]: /doc/usb/ [i3]: /doc/i3/ +[upgrade]: /doc/upgrade-to-r3.2/ +[upgrade-r3.1]: /doc/releases/3.1/release-notes/#upgrading +[backup]: /doc/backup-restore/ [qrexec-argument]: https://github.com/QubesOS/qubes-issues/issues/1876 [qrexec-doc]: /doc/qrexec3/#service-argument-in-policy [github-release-notes]: https://github.com/QubesOS/qubes-issues/issues?q=is%3Aissue+sort%3Aupdated-desc+milestone%3A%22Release+3.2%22+label%3Arelease-notes+is%3Aclosed From 8205de0441025692fd4df0eae6dc5554a4fa26c9 Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Mon, 27 Jun 2016 11:53:54 -0700 Subject: [PATCH 056/708] Fix broken link to Kali page --- managing-os/pentesting/kali.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/managing-os/pentesting/kali.md b/managing-os/pentesting/kali.md index b349aa0e..fa5ea89e 100644 --- a/managing-os/pentesting/kali.md +++ b/managing-os/pentesting/kali.md @@ -1,7 +1,9 @@ --- layout: doc title: How to create a Kali Linux VM -permalink: /doc/kali/ +permalink: /doc/pentesting/kali/ +redirect_from: +- /doc/kali/ --- **General Remainder:** From 3dd67019c604e51718a088df126723f90fdf5289 Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Mon, 27 Jun 2016 11:57:40 -0700 Subject: [PATCH 057/708] Fix broken link to BlackArch page --- managing-os/pentesting/blackarch.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/managing-os/pentesting/blackarch.md b/managing-os/pentesting/blackarch.md index 8a390e35..01e6b679 100644 --- a/managing-os/pentesting/blackarch.md +++ b/managing-os/pentesting/blackarch.md @@ -1,7 +1,9 @@ --- layout: doc title: How to Create a BlackArch VM -permalink: /doc/blackarch/ +permalink: /doc/pentesting/blackarch/ +redirect_from: +- /doc/blackarch/ --- **General Remainder:** From 8dd4aed8e851c6e35674359295582cecf75ea385 Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Mon, 27 Jun 2016 11:57:54 -0700 Subject: [PATCH 058/708] Fix broken link to PTF page --- managing-os/pentesting/ptf.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/managing-os/pentesting/ptf.md b/managing-os/pentesting/ptf.md index 67755050..4d836877 100644 --- a/managing-os/pentesting/ptf.md +++ b/managing-os/pentesting/ptf.md @@ -1,7 +1,9 @@ --- layout: doc title: How to create Penetration Testers Framework (PTF) VM -permalink: /doc/ptf/ +permalink: /doc/pentesting/ptf/ +redirect_from: +- /doc/ptf/ --- **General Remainder:** From 878ca47dac7dc74c2f105560a3031ab19c94312d Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Mon, 27 Jun 2016 11:59:48 -0700 Subject: [PATCH 059/708] Update links from Kali page to other pentesting pages --- managing-os/pentesting/kali.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/managing-os/pentesting/kali.md b/managing-os/pentesting/kali.md index fa5ea89e..69a6fb0f 100644 --- a/managing-os/pentesting/kali.md +++ b/managing-os/pentesting/kali.md @@ -197,6 +197,6 @@ Create Debian Based Kali Template Alternative Options to Kali --------------------------- -- [BlackArch](/doc/blackarch/) -- [PenTester Framework (PTF)](/doc/ptf/) +- [BlackArch](/doc/pentesting/blackarch/) +- [PenTester Framework (PTF)](/doc/pentesting/ptf/) - [Pentesting](/doc/pentesting/) From f34b145c71573a543fa175cecca5fd1f24eaaa25 Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Mon, 27 Jun 2016 12:00:45 -0700 Subject: [PATCH 060/708] Update links from BlackArge page to other pentesting pages --- managing-os/pentesting/blackarch.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/managing-os/pentesting/blackarch.md b/managing-os/pentesting/blackarch.md index 01e6b679..80d76bf6 100644 --- a/managing-os/pentesting/blackarch.md +++ b/managing-os/pentesting/blackarch.md @@ -91,6 +91,6 @@ Create ArchLinux Based BlackArch Template Alternative Options to BlackArch -------------------------------- -- [Kali](/doc/kali/) -- [PenTester Framework (PTF)](/doc/ptf/) +- [Kali](/doc/pentesting/kali/) +- [PenTester Framework (PTF)](/doc/pentesting/ptf/) - [Pentesting](/doc/pentesting/) From 808852b60bbeef084cbd2b98d5101a58e25bc7bf Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Mon, 27 Jun 2016 12:01:03 -0700 Subject: [PATCH 061/708] Update links from PTF page to other pentesting pages --- managing-os/pentesting/ptf.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/managing-os/pentesting/ptf.md b/managing-os/pentesting/ptf.md index 4d836877..0e3cb216 100644 --- a/managing-os/pentesting/ptf.md +++ b/managing-os/pentesting/ptf.md @@ -28,7 +28,7 @@ Create Debian Based Penetration Testers Framework (PTF) Template 1. Create PTF template - 1. Follow [Create Debian Based Kali Template](/doc/kali/) till step 7. + 1. Follow [Create Debian Based Kali Template](/doc/pentesting/kali/) till step 7. 2. (Optional) Rename the cloned template to `ptf` @@ -116,6 +116,6 @@ possible to do sudo ptf/ptf Alternative Options to PTF -------------------------- -- [BlackArch](/doc/blackarch/) -- [Kali](/doc/kali/) +- [BlackArch](/doc/pentesting/blackarch/) +- [Kali](/doc/pentesting/kali/) - [Pentesting](/doc/pentesting/) From 97696026f3830a72c78a1f34117132c0b46bbaee Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Mon, 27 Jun 2016 12:02:13 -0700 Subject: [PATCH 062/708] Update links from Pentesting page to all subpages --- managing-os/pentesting.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/managing-os/pentesting.md b/managing-os/pentesting.md index e3377206..a4751f41 100644 --- a/managing-os/pentesting.md +++ b/managing-os/pentesting.md @@ -20,9 +20,9 @@ Penetration Testing Distributions The following install instructions explain how to setup a penetration testing distribution within Qubes OS. -- [BlackArch](/doc/blackarch/) -- [Kali](/doc/kali/) -- [PenTester Framework (PTF)](/doc/ptf/) +- [BlackArch](/doc/pentesting/blackarch/) +- [Kali](/doc/pentesting/kali/) +- [PenTester Framework (PTF)](/doc/pentesting/ptf/) Using Qubes OS to host a "hacking" laboratory --------------------------------------------- From 49603789d29339c405d96032288ffa38cd65bd66 Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Mon, 27 Jun 2016 12:22:42 -0700 Subject: [PATCH 063/708] Clarify how to add parameters to xen.cfg Thank you to Jeremy Rand for clarifying this step of the instructions: https://groups.google.com/d/msg/qubes-users/VeqDPHiaKwM/j4xt1lSOCAAJ --- troubleshooting/uefi-troubleshooting.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/troubleshooting/uefi-troubleshooting.md b/troubleshooting/uefi-troubleshooting.md index f4b71aa3..25d0c5b7 100644 --- a/troubleshooting/uefi-troubleshooting.md +++ b/troubleshooting/uefi-troubleshooting.md @@ -38,6 +38,11 @@ There is some [common bug in UEFI implementation](http://xen.markmail.org/messag mapbs=1 noexitboot=1 + **Note:** You must add these parameters on two separate new lines (one + paramater on each line) at the end of each section that includes a kernel + line (i.e., all sections except the first one, since it doesn't have a + kernel line). + 12. Now you can reboot the system by issuing `reboot` command. From 820825873b17c2fb13eeda7727354800a21ee89f Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Tue, 28 Jun 2016 05:38:27 -0700 Subject: [PATCH 064/708] Create Manual Encryption Configuration page --- installing/encryption-config.md | 73 +++++++++++++++++++++++++++++++++ 1 file changed, 73 insertions(+) create mode 100644 installing/encryption-config.md diff --git a/installing/encryption-config.md b/installing/encryption-config.md new file mode 100644 index 00000000..e0627451 --- /dev/null +++ b/installing/encryption-config.md @@ -0,0 +1,73 @@ +--- +layout: doc +title: Manual Encryption Configuration +permalink: /doc/encryption-config/ +--- + +Manual Encryption Configuration +=============================== + +The Qubes installer uses `cryptsetup` (LUKS/dm-crypt) under the hood. You can +configure the encryption options before installing Qubes as follows: + +01. Boot into the installer. Wait for first GUI screen to appear where it asks + about language/localization . +02. Press `Ctrl+Alt+F2` on your keyboard to escape to a shell session. (If you + are on a laptop, and your laptop keyboard des not work properly, you may have + to plug in a USB keyboard.) +03. Check and adjust the partitioning on the drive you plan to install to with + `parted`. For example, you can leave the partition table as `msdos/MBR` type, + then create a 500 MB ext4 boot partition, a 10 GB swap partition, and use the + rest of the drive (minus overprovisioning space for SSDs) for the root + partition. +04. Run to set the LUKS options as you like and set the passphrase: + + # cryptsetup luksFormat + + For example: + + # cryptsetup -v --hash sha512 --cipher aes-xts-plain64 --key-size 512 --use-random --iter-time 5000 --verify-passphrase luksFormat /dev/sda2 + +05. (Optional) Make sure the new container works: + + # cryptsetup open /dev/sda2 test + # mkfs.ext4 /dev/mapper/test + # mount /dev/mapper/test /mnt/test + # umount /dev/mapper/test + # cryptsetup close test + +06. Everything should be set with the preparation, so press `Ctrl+Alt+F7` to go + back to the GUI installer. +07. Continue installing as usual. When you get to the disk + partitioning/allocation part, pay attention. +08. When you select the disk, it may complain about only having a few MB of + space. Uncheck the "Encrypt and ask me about the passphrase later" box and + press the "Custom" button. +09. In this menu, you should see the unencrypted boot partition and the encrypted + LUKS partitions you created earlier. You must unlock the LUKS partition here, + i.e. enter passphrases. +10. Set the mount points on these partitions once they are decrypted. (This part + may be a bit glitchy, but you should be able to get it working after a + reboot.) For example, set the mount point for the primary LUKS partition as + `/`. Make sure the "Encrypted" box stays checked and that you check the + "Format" box (required for the root partition). Similarly, set `/boot` as + the mount point for the unencrypted boot partition and `swap` as the mount + point for the swap partition. +11. Now the install should complete without any other issues. When it's + finished, you'll have LUKS-encrypted partitions with the options you chose + above. You can verify this command in dom0: + + sudo cryptsetup luksDump + + For example: + + sudo cryptsetup luksDump /dev/sda2 + +----- + +These instructions were adapted from those provided by Qubes user [Jake] on the +`qubes-users` [mailing list]. + +[Jake]: https://groups.google.com/d/msg/qubes-users/cykOGRa0Im0/vK7j8aQOXkYJ +[mailing list]: /mailing-lists/ + From 2d144c81e161ad3f91908f994d4ed87b9cae69ce Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Tue, 28 Jun 2016 05:38:43 -0700 Subject: [PATCH 065/708] Add Manual Encryption Configuration page to ToC --- doc.md | 1 + 1 file changed, 1 insertion(+) diff --git a/doc.md b/doc.md index 4aee11e7..e98206ce 100644 --- a/doc.md +++ b/doc.md @@ -40,6 +40,7 @@ Installing & Upgrading Qubes * [Try Qubes without installing: Qubes Live USB (alpha)](/doc/live-usb/) * [Supported Versions](/doc/supported-versions/) * [Version Scheme](/doc/version-scheme/) + * [Manual Encryption Configuration](/doc/encryption-config/) Common Tasks ------------ From 92b985d07941b05be1204ae8aa38d5b9e5190631 Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Tue, 28 Jun 2016 05:43:14 -0700 Subject: [PATCH 066/708] Replace "sudo" with root prompt for consistency --- installing/encryption-config.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/installing/encryption-config.md b/installing/encryption-config.md index e0627451..8756fd46 100644 --- a/installing/encryption-config.md +++ b/installing/encryption-config.md @@ -57,11 +57,11 @@ configure the encryption options before installing Qubes as follows: finished, you'll have LUKS-encrypted partitions with the options you chose above. You can verify this command in dom0: - sudo cryptsetup luksDump + # cryptsetup luksDump For example: - sudo cryptsetup luksDump /dev/sda2 + # cryptsetup luksDump /dev/sda2 ----- From c495fbc007aeecca73be06f25b31184163d09a19 Mon Sep 17 00:00:00 2001 From: Jon Osterman Date: Wed, 29 Jun 2016 08:30:00 +0200 Subject: [PATCH 067/708] missing 'sudo' in documentation --- customization/i3.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/customization/i3.md b/customization/i3.md index 00d17801..02f9c819 100644 --- a/customization/i3.md +++ b/customization/i3.md @@ -14,12 +14,12 @@ redirect_from: i3 is part of the testing repository (as of Qubes R3.1) and can be installed from there using the dom0 update mechanism. - $ qubes-dom0-update --enablerepo=qubes-dom0-current-testing i3 + $ sudo qubes-dom0-update --enablerepo=qubes-dom0-current-testing i3 Qubes-specific configuation is available in a separate package and can be installed optionally. Otherwise you can write your own configuration (see below). - $ qubes-dom0-update --enablerepo=qubes-dom0-current-testing i3-settings-qubes + $ sudo qubes-dom0-update --enablerepo=qubes-dom0-current-testing i3-settings-qubes That's it. After logging out, you can select i3 in the login manager. From c1dc6f0d6ebaa946db62e9355d8175532fd5261d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Marczykowski-G=C3=B3recki?= Date: Fri, 1 Jul 2016 10:32:36 +0200 Subject: [PATCH 068/708] usb: add note about requiring USB VM for USB passthrough --- 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 9710db90..cc73583e 100644 --- a/common-tasks/usb.md +++ b/common-tasks/usb.md @@ -263,7 +263,8 @@ method specific for particular device type (for example block devices described above), instead of this generic one. To use this feature, you need to install `qubes-usb-proxy` package in the -templates used for USB qube and qubes you want to connect USB devices to. +templates used for USB qube and qubes you want to connect USB devices to. Note +you cannot pass through devices from dom0 (in other words: USB VM is required). Listing available USB devices: From d864239cde6c4d5cf6dc2fd2cf50ebf426a98a5d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Marczykowski-G=C3=B3recki?= Date: Fri, 1 Jul 2016 20:14:50 +0200 Subject: [PATCH 069/708] Fix Xfce installation instruction --- customization/xfce.md | 10 +--------- 1 file changed, 1 insertion(+), 9 deletions(-) diff --git a/customization/xfce.md b/customization/xfce.md index 60370e65..d7df7bb8 100644 --- a/customization/xfce.md +++ b/customization/xfce.md @@ -14,17 +14,9 @@ XFCE installation in dom0 **Disclaimer: XFCE isn't fully integrated with Qubes environment, it still requires notable amount of manual configuration after install** -Requirements (as of 10/24/2012): - -- qubes-core-dom0-2.0.37 (not released yet, possible to build from "master" branch of marmarek's repo) - Installation: - qubes-dom0-update --enablerepo=qubes-dom0-unstable @XFCE - -Then you need to create /etc/sysconfig/desktop to stay with KDM, as GDM still starts invalid Xorg startup script: - - DISPLAYMANAGER=KDE + sudo qubes-dom0-update @xfce-desktop-qubes Reboot the system. At system startup, select "Xfce session" in login screen (menu on the right bottom corner of the screen). From 2956651dc11499e28c574916a728b0466afb2ff8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Marczykowski-G=C3=B3recki?= Date: Sat, 2 Jul 2016 00:59:32 +0200 Subject: [PATCH 070/708] Update 3.2 schedule --- releases/3.2/schedule.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/releases/3.2/schedule.md b/releases/3.2/schedule.md index 008e6515..b5c97973 100644 --- a/releases/3.2/schedule.md +++ b/releases/3.2/schedule.md @@ -22,4 +22,7 @@ article td, article th { | Date | Stage | | -----------:| --------------------------------------- | | 18 Jun 2016 | 3.2-rc1 release | -| 15 Jul 2016 | decide whether 3.2-rc1 is the final 3.2 | +| 2 Jul 2016 | decide whether 3.2-rc1 is the final 3.2 | +| 16 Jul 2016 | current-testing freeze before 3.2-rc2 | +| 23 Jul 2016 | 3.2-rc2 release | +| 5 Aug 2016 | decide whether 3.2-rc2 is the final 3.2 | From 91bf798efb050bf3c14a06b28808e74eb1a9b2ec Mon Sep 17 00:00:00 2001 From: Tom Koch Date: Sun, 3 Jul 2016 02:18:46 -0500 Subject: [PATCH 071/708] Update upgrade-to-r3.2 w/ solution to screensaver I got locked out during install and found that it was likely due to a PAM issue during the upgrade command. This should resolve that. Also, could be more clear how to check the installed version of qubes-core-dom0, so I added an explanation. https://superuser.com/questions/460075/why-does-xscreensaver-not-allow-me-to-enter-my-password --- installing/upgrade/upgrade-to-r3.2.md | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/installing/upgrade/upgrade-to-r3.2.md b/installing/upgrade/upgrade-to-r3.2.md index 86f8f993..8f8f6722 100644 --- a/installing/upgrade/upgrade-to-r3.2.md +++ b/installing/upgrade/upgrade-to-r3.2.md @@ -39,12 +39,16 @@ Upgrading dom0 4. Upgrade dom0 to R3.2: sudo qubes-dom0-update + + You may wish to disable the screensaver "Lock screen" feature for this step, as + during the update XScreensaver may encounter an "Authentication failed" issue, + requiring a hard reboot. Alternatively, you may simply move the mouse regularly. + +5. If the previous step completed successfully, your `qubes-core-dom0` version + should be `3.2.3` or higher. This can be verified with the command `yum info + qubes-core-dom0`. If it's not, repeat the previous step with the `--clean` option. -4. If the previous step completed successfully, your `qubes-core-dom0` version - should be `3.2.3` or higher. If it's not, repeat the previous step with the - `--clean` option. - -5. Update configuration files. +6. Update configuration files. Some of configuration files were saved with `.rpmnew` extension as the actual files were modified. During upgrade, you'll see information about @@ -65,7 +69,7 @@ Upgrading dom0 mv -f /etc/salt/minion.d/f_defaults.conf{.rpmnew,} mv -f /etc/dracut.conf{.rpmnew,} -5. Reboot dom0. +7. Reboot dom0. Please note that if you use [Anti Evil Maid](/doc/anti-evil-maid), it won't be able to unseal the passphrase the first time the system boots after performing From 0f917b3ee3f77d45cce2b4e80f361344f66590bf Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Mon, 4 Jul 2016 04:47:32 -0700 Subject: [PATCH 072/708] Clarify that Qubes uses FDE by default QubesOS/qubes-issues#2151 --- installing/encryption-config.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/installing/encryption-config.md b/installing/encryption-config.md index 8756fd46..cbeb655b 100644 --- a/installing/encryption-config.md +++ b/installing/encryption-config.md @@ -7,8 +7,12 @@ permalink: /doc/encryption-config/ Manual Encryption Configuration =============================== +Qubes OS uses full disk encryption (FDE) by default. If you are an advanced +user who wishes to customize your encryption parameters during installation, +this page can help. + The Qubes installer uses `cryptsetup` (LUKS/dm-crypt) under the hood. You can -configure the encryption options before installing Qubes as follows: +configure the encryption options while installing Qubes as follows: 01. Boot into the installer. Wait for first GUI screen to appear where it asks about language/localization . From 1f12352489d89e28402bb17f99403e6388f9f228 Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Mon, 4 Jul 2016 05:01:47 -0700 Subject: [PATCH 073/708] Add FAQ entry explicitly stating that Qubes uses FDE Fixes QubesOS/qubes-issues#2151 --- basics_user/user-faq.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/basics_user/user-faq.md b/basics_user/user-faq.md index 49df1290..b921112b 100644 --- a/basics_user/user-faq.md +++ b/basics_user/user-faq.md @@ -15,6 +15,7 @@ Qubes Users' FAQ --------------------------------------- * [Is Qubes just another Linux distribution?](#is-qubes-just-another-linux-distribution) * [How is Qubes different from other security solutions?](#how-is-qubes-different-from-other-security-solutions) + * [Does Qubes use full disk encryption (FDE)?](#does-qubes-use-full-disk-encryption-fde) * [What is the main concept behind Qubes?](#what-is-the-main-concept-behind-qubes) * [What about other approaches to security?](#what-about-other-approaches-to-security) * [What about safe languages and formally verified microkernels?](#what-about-safe-languages-and-formally-verified-microkernels) @@ -66,6 +67,10 @@ If you really want to call it a distribution, then it's more of a "Xen distribut Please see [this article](http://theinvisiblethings.blogspot.com/2012/09/how-is-qubes-os-different-from.html) for a thorough discussion. +### Does Qubes use full disk encryption (FDE)? + +Yes, of course! Full disk encryption is enabled by default. Specifically, we use [`LUKS`](https://en.wikipedia.org/wiki/Linux_Unified_Key_Setup)/[`dm-crypt`](https://en.wikipedia.org/wiki/Dm-crypt). You can even [manually configure your encryption parameters](/doc/encryption-config/), if you like! + ### What is the main concept behind Qubes? To build security on the “Security by Compartmentalization (or Isolation)” principle. From ba35305883a3ee2c05a370d830f549b4c927e021 Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Tue, 5 Jul 2016 03:11:10 -0700 Subject: [PATCH 074/708] Add Marek's RMLL 2016 slides --- doc.md | 1 + 1 file changed, 1 insertion(+) diff --git a/doc.md b/doc.md index e98206ce..01687f01 100644 --- a/doc.md +++ b/doc.md @@ -178,6 +178,7 @@ Presentation Slides ------------------- * [[PDF] LinuxCon 2014 -- Qubes OS R2 Tutorial](/attachment/wiki/slides/LinuxCon_2014_Qubes_Tutorial.pdf) * [[PDF] LinuxCon 2014 -- Qubes OS Keynote](/attachment/wiki/slides/LinuxCon_2014_Qubes_Keynote.pdf) + * [[PDF] RMLL 2016 -- Improving client systems security with Qubes OS](/attachment/wiki/slides/RMLL_2016_Improving-client-systems-security.pdf) Developer Documentation ======================= From b4ade4156f1dc107c88a812b577b15bbcbe0ee05 Mon Sep 17 00:00:00 2001 From: Michael Carbone Date: Tue, 5 Jul 2016 11:38:17 +0000 Subject: [PATCH 075/708] added content --- security/split-bitcoin.md | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/security/split-bitcoin.md b/security/split-bitcoin.md index bddd5f90..e3a85fe4 100644 --- a/security/split-bitcoin.md +++ b/security/split-bitcoin.md @@ -11,10 +11,34 @@ How to Set Up a Split Bitcoin Wallet in Qubes What is a "Split" Bitcoin Wallet? --------------------------------- +A "split" bitcoin wallet is a strategy of protecting your bitcoin by having your wallet split into an offline "[cold storage](https://en.bitcoin.it/wiki/Cold_storage)" wallet and an online "watching only" wallet. A "Watching" Wallet and a "Cold" Wallet --------------------------------------- +1. Create a Debian 8 backports template using the Qubes VM Manager or running + `qvm-clone debian-8 debian-8-backports` in dom0. +2. Add backports to the sources for the new template by opening a terminal in + the new template, run `sudo vi /etc/apt/sources.list` and add + `deb http://http.debian.net/debian jessie-backports main`. + + (If you are new to `vi` text editing, type `i` to be able to edit, and when + done editing press `ESC` then type `:x` and press `ENTER`.) + +3. Update source list: `sudo apt-get update`. + +4. Install `electrum` from backports: + `sudo apt-get -t jessie-backports install electrum`. + +5. shut down your `debian-8-backports` template + +6. create an `offline-bitcoin` qube based on `debian-8-backports` using the Qubes VM Manager or running `qvm-create -t debian-8-backports -l black offline-bitcoin` and `qvm-prefs -s offline-bitcoin netvm none` in dom0. + +7. follow the [electrum documentation in creating an offline wallet](http://docs.electrum.org/en/latest/coldstorage.html#create-an-offline-wallet) + +8. create a `watching-bitcoin` qubes based on `debian-8-backports` connecting to the internet how ever you prefer using the Qubes VM Manager or running for example `qvm-create -t debian-8-backports -l green watching-bitcoin` and `qvm-prefs -s watching-bitcoin netvm sys-whonix` in dom0. + +9. follow the [electrum documentation in creating an online watching-only wallet](http://docs.electrum.org/en/latest/coldstorage.html#create-a-watching-only-version-of-your-wallet) From 176d9394df62e2c5c49aeda4b667c620f6c4c8f4 Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Tue, 5 Jul 2016 06:54:44 -0700 Subject: [PATCH 076/708] Add Split Bitcoin page to ToC QubesOS/qubes-users#1966 --- doc.md | 1 + 1 file changed, 1 insertion(+) diff --git a/doc.md b/doc.md index 01687f01..b7352121 100644 --- a/doc.md +++ b/doc.md @@ -95,6 +95,7 @@ Security Guides * [Installing Anti Evil Maid](/doc/anti-evil-maid/) * [Using Multi-factor Authentication with Qubes](/doc/multifactor-authentication/) * [Using GPG more securely in Qubes: Split GPG](/doc/split-gpg/) + * [How to Set Up a Split Bitcoin Wallet in Qubes](/doc/split-bitcoin/) * [Configuring YubiKey for user authentication](/doc/yubi-key/) * [Note regarding password-less root access in VM](/doc/vm-sudo/) From fabb7b17d33a57b0bbf1b869c1769c4e069b0916 Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Fri, 8 Jul 2016 20:39:18 -0700 Subject: [PATCH 077/708] Add notes regarding private and public key management --- security/split-bitcoin.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/security/split-bitcoin.md b/security/split-bitcoin.md index e3a85fe4..bb284fa0 100644 --- a/security/split-bitcoin.md +++ b/security/split-bitcoin.md @@ -42,3 +42,15 @@ A "Watching" Wallet and a "Cold" Wallet 9. follow the [electrum documentation in creating an online watching-only wallet](http://docs.electrum.org/en/latest/coldstorage.html#create-a-watching-only-version-of-your-wallet) +Important Notes +--------------- + +* The private keys (xpriv) should never be moved outside of `offline-bitcoin`. +* For copying out the public keys (xpub), Qubes provides two secure, convenient + methods: the [inter-VM clipboard] and [inter-VM file copy] tools. Compared to + traditional physically air-gapped machines, these tools makes it very easy to + copy out public keys. + +[inter-VM clipboard]: /doc/copy-paste/ +[inter-VM file copy]: /doc/copying-files/ + From 14b8144fb7b431e59e3b9d7280005aab032f1394 Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Mon, 11 Jul 2016 20:18:27 -0700 Subject: [PATCH 078/708] Add entry for building Qubes-supported templates https://groups.google.com/d/msg/qubes-users/yZdtdu5DUJ8/DRy8LEs_BgAJ --- doc.md | 1 + 1 file changed, 1 insertion(+) diff --git a/doc.md b/doc.md index b7352121..ead50d1f 100644 --- a/doc.md +++ b/doc.md @@ -236,6 +236,7 @@ Building * [KDE Dom0 packages for Qubes](/doc/kde-dom0/) * [Building Qubes OS 3.0 ISO](/doc/qubes-r3-building/) * [Building USB passthrough support (experimental)](/doc/pvusb/) + * [Building Qubes Templates](https://github.com/QubesOS/qubes-template-configs) * [Building a TemplateVM based on a new OS (ArchLinux example)](/doc/building-non-fedora-template/) * [Building the Archlinux Template](/doc/building-archlinux-template/) From ab15b144f89156c1a81de54ddf2f456313208d56 Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Wed, 13 Jul 2016 04:21:37 -0700 Subject: [PATCH 079/708] Revise and update Qubes Security Pack page MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Add instructions for verifying Git tags * Explain rationale for providing two methods of verification * Update warrant canary link (Canary Watch has shut down) * State that the QSP now contains Bitcoin fund info * Fix "ó" in Marek's name * Remove full CLI prompt (for uniformity with rest of site) * Remove instructions for reading text files (unnecessary) * Reorder list of QSP contents (move PGP keys to top, since verification of everything else depends on them) --- security/security-pack.md | 75 ++++++++++++++++++++++----------------- 1 file changed, 43 insertions(+), 32 deletions(-) diff --git a/security/security-pack.md b/security/security-pack.md index 560ddce6..aaf6afab 100644 --- a/security/security-pack.md +++ b/security/security-pack.md @@ -6,6 +6,12 @@ redirect_from: - /en/doc/security-pack/ - /doc/SecurityPack/ - /wiki/SecurityPack/ +- /qsp/ +- /sec-pack/ +- /secpack/ +- /doc/qsp/ +- /doc/sec-pack/ +- /doc/secpack/ --- Qubes Security Pack @@ -13,9 +19,10 @@ Qubes Security Pack The **Qubes Security Pack (QSP)** is a Git repository which contains: - * [Qubes Security Bulletins (QSBs)](/doc/security-bulletins/) * [Qubes PGP keys](https://keys.qubes-os.org/keys/) - * [Qubes warrant canaries](https://canarywatch.org/qubesOS/) + * [Qubes Security Bulletins (QSBs)](/doc/security-bulletins/) + * [Qubes warrant canaries](https://github.com/QubesOS/qubes-secpack/tree/master/canaries) + * [Qubes Bitcoin donation fund information](/donate/) * Security-related information and announcements (e.g., key revocations) The official location of the QSP is: @@ -126,7 +133,7 @@ its contents, and reading them. 1. Clone the QSP repo. - [user@qubes ~]$ git clone https://github.com/QubesOS/qubes-secpack.git + $ git clone https://github.com/QubesOS/qubes-secpack.git Cloning into 'qubes-secpack'... remote: Counting objects: 195, done. remote: Total 195 (delta 0), reused 0 (delta 0) @@ -136,7 +143,7 @@ its contents, and reading them. 2. Import the included PGP keys. - [user@qubes ~]$ gpg --import qubes-secpack/keys/*/* + $ gpg --import qubes-secpack/keys/*/* gpg: directory `/home/user/.gnupg' created gpg: new configuration file `/home/user/.gnupg/gpg.conf' created gpg: WARNING: options in `/home/user/.gnupg/gpg.conf' are not yet active during this run @@ -151,14 +158,14 @@ its contents, and reading them. gpg: key B298547C: public key "Marek Marczykowski (Qubes OS signing key) " imported gpg: key AB5EEF90: public key "Marek Marczykowski (Qubes OS signing key) " imported gpg: key A603BCB6: public key "Marek Marczykowski (Qubes OS signing key) " imported - gpg: key 42CFA724: public key "Marek Marczykowski-G�recki (Qubes OS signing key) " imported + gpg: key 42CFA724: public key "Marek Marczykowski-Górecki (Qubes OS signing key) " imported gpg: key 15CE40BF: public key "Wojciech Zygmunt Porczyk (Qubes OS signing key) " imported gpg: key 36879494: public key "Qubes Master Signing Key" imported gpg: key 211093A7: public key "Qubes OS Release 1 Signing Key" imported gpg: key 0A40E458: public key "Qubes OS Release 2 Signing Key" imported gpg: key 03FA5082: public key "Qubes OS Release 3 Signing Key" imported gpg: key 92C7B3DC: public key "Joanna Rutkowska (Qubes Security Pack Signing Key) " imported - gpg: key 1830E06A: public key "Marek Marczykowski-G�recki (Qubes security pack) " imported + gpg: key 1830E06A: public key "Marek Marczykowski-Górecki (Qubes security pack) " imported gpg: key 3F48CB21: public key "Qubes OS Security Team " imported gpg: Total number processed: 17 gpg: imported: 17 (RSA: 17) @@ -166,7 +173,7 @@ its contents, and reading them. 3. Verify and trust the Qubes Master Signing Key. - [user@qubes ~]$ gpg --edit-key 36879494 + $ gpg --edit-key 36879494 gpg (GnuPG) 1.4.18; Copyright (C) 2014 Free Software Foundation, Inc. This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law. @@ -215,34 +222,38 @@ its contents, and reading them. step, ensuring they match. You can read more about digital signatures and key verification [here](/doc/verifying-signatures/). - 4. Verify and read the canaries. + 4. Verify signed Git tags. - [user@qubes ~]$ cd qubes-secpack/canaries/ - [user@qubes canaries]$ gpg --verify canary-001-2015.txt.sig.joanna canary-001-2015.txt + $ cd qubes-secpack/ + $ git tag -v `git describe` + object 2bb7f0b966593d8ed74e140a04d60c68b96b164e + type commit + tag joanna_sec_2bb7f0b9 + tagger Joanna Rutkowska 1468335706 +0000 + + Tag for commit 2bb7f0b966593d8ed74e140a04d60c68b96b164e + gpg: Signature made 2016-07-12T08:01:46 PDT + gpg: using RSA key 0x4E6829BC92C7B3DC + gpg: Good signature from "Joanna Rutkowska (Qubes Security Pack Signing Key) " [full] + + (The final line of output confirms that the signature is good.) + + 5. Verify detached PGP signatures. + + $ cd canaries/ + $ gpg --verify canary-001-2015.txt.sig.joanna canary-001-2015.txt gpg: Signature made Mon Jan 5 20:21:40 2015 UTC using RSA key ID 92C7B3DC gpg: Good signature from "Joanna Rutkowska (Qubes Security Pack Signing Key) " - [user@qubes canaries]$ gpg --verify canary-001-2015.txt.sig.marmarek canary-001-2015.txt + $ gpg --verify canary-001-2015.txt.sig.marmarek canary-001-2015.txt gpg: Signature made Mon Jan 5 20:13:37 2015 UTC using RSA key ID 1830E06A - gpg: Good signature from "Marek Marczykowski-G�recki (Qubes security pack) " - [user@qubes canaries]$ cat canary-001-2015.txt - - - ---===[ Qubes Canary #1 ]===--- - - [...] + gpg: Good signature from "Marek Marczykowski-Górecki (Qubes security pack) " - 5. Verify and read the QSBs. + (The fourth and final lines of output confirm that the two signatures are + good.) + +The same procedures can be applied to any directory or file in the QSP. Two +methods of verification (signed Git tags and deatched PGP signatures) are +provided to ensure that the system is robust (e.g., against a potential failure +in Git tag-based verification) and to give users more options to verify the +files. - [user@qubes canaries]$ cd ../QSBs/ - [user@qubes QSBs]$ gpg --verify qsb-013-2015.txt.sig.joanna qsb-013-2015.txt - gpg: Signature made Mon Jan 5 21:22:14 2015 UTC using RSA key ID 92C7B3DC - gpg: Good signature from "Joanna Rutkowska (Qubes Security Pack Signing Key) " - [user@qubes QSBs]$ gpg --verify qsb-013-2015.txt.sig.marmarek qsb-013-2015.txt - gpg: Signature made Mon Jan 5 21:38:11 2015 UTC using RSA key ID 1830E06A - gpg: Good signature from "Marek Marczykowski-G�recki (Qubes security pack) " - [user@qubes QSBs]$ cat qsb-013-2015.txt - - - ---===[ Qubes Security Bulletin #13 ]===--- - - [...] From d32a01330165be69b987e47c93ec36284275bfe6 Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Wed, 13 Jul 2016 04:34:51 -0700 Subject: [PATCH 080/708] Avoid implying that the fund is only for donations --- security/security-pack.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/security/security-pack.md b/security/security-pack.md index aaf6afab..6a4ba689 100644 --- a/security/security-pack.md +++ b/security/security-pack.md @@ -22,7 +22,7 @@ The **Qubes Security Pack (QSP)** is a Git repository which contains: * [Qubes PGP keys](https://keys.qubes-os.org/keys/) * [Qubes Security Bulletins (QSBs)](/doc/security-bulletins/) * [Qubes warrant canaries](https://github.com/QubesOS/qubes-secpack/tree/master/canaries) - * [Qubes Bitcoin donation fund information](/donate/) + * [Qubes Bitcoin fund information](https://github.com/QubesOS/qubes-secpack/tree/master/fund) * Security-related information and announcements (e.g., key revocations) The official location of the QSP is: From 45cffd68543447c81d9922572d52e408b7ff5e65 Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Fri, 15 Jul 2016 11:39:52 -0700 Subject: [PATCH 081/708] Create "What is a DMA attack?" entry (Marek's answer) https://groups.google.com/d/msg/qubes-users/u5ddOVkUN7o/PAVMwDY9BwAJ --- basics_user/user-faq.md | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/basics_user/user-faq.md b/basics_user/user-faq.md index b921112b..0ed37bcf 100644 --- a/basics_user/user-faq.md +++ b/basics_user/user-faq.md @@ -38,6 +38,7 @@ Qubes Users' FAQ * [How much memory is recommended for Qubes?](#how-much-memory-is-recommended-for-qubes) * [Can I install Qubes on a system without VT-x?](#can-i-install-qubes-on-a-system-without-vt-x) * [Can I install Qubes on a system without VT-d?](#can-i-install-qubes-on-a-system-without-vt-d) + * [What is a DMA attack?](#what-is-a-dma-attack) * [Can I use AMD-v instead of VT-x?](#can-i-use-amd-v-instead-of-vt-x) * [Can I install Qubes in a virtual machine (e.g., on VMWare)?](#can-i-install-qubes-in-a-virtual-machine-eg-on-vmware) * [Why does my network adapter not work?](#why-does-my-network-adapter-not-work) @@ -177,6 +178,27 @@ Yes. Xen doesn't use VT-x (or AMD-v) for PV guest virtualization. (It uses ring0 Yes. You can even run a NetVM, but you will not benefit from DMA protection for driver domains. On a system without VT-d, everything should work in the same way, except there will be no real security benefit to having a separate NetVM, as an attacker could always use a simple DMA attack to go from the NetVM to Dom0. **Nonetheless, all of Qubes' other security mechanisms, such as qube separation, work without VT-d. Therefore, a system running Qubes will still be significantly more secure than one running Windows, Mac, or Linux, even if it lacks VT-d.** +### What is a DMA attack? + +DMA is mechanism for PCI devices to access system memory (read/write). +Without VT-d, any PCI device can access all the memory, regardless to +which VM it is assigned (or if it is left in dom0). Most PCI devices allow the +driver to request an arbitrary DMA operation (like "put received network packets +at this address in memory", or "get this memory area and send it to the +network"). So, without VT-d, it gives unlimited access to the whole +system. Now, it is only a matter of knowing where to read/write to take +over the system, instead of just crashing. But since you can read the +whole memory, it isn't that hard. + +Now, how does this apply to Qubes OS? The above attack requires access to a PCI +device, which means that it can be performed only from NetVM / UsbVM, so +someone must first break into one of those VMs. But this isn't that hard, +because there is a lot of complex code handling network traffic. Recent +bugs includes DHCP client, DNS client, etc. Most attacks on NetVM / +UsbVM (but not all!) require being somewhat close to the target system - +for example connected to the same WiFi network, or in the case of a UsbVM, +having physical acccess to a USB port. + ### Can I use AMD-v instead of VT-x? See [this message](http://groups.google.com/group/qubes-devel/msg/6412170cfbcb4cc5). From deec6ad508164eed35b5d883af86aeb0ce3a47a7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Marczykowski-G=C3=B3recki?= Date: Sun, 17 Jul 2016 00:42:02 +0200 Subject: [PATCH 082/708] Adjust R3.2 release schedule --- releases/3.2/schedule.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/releases/3.2/schedule.md b/releases/3.2/schedule.md index b5c97973..e4585a33 100644 --- a/releases/3.2/schedule.md +++ b/releases/3.2/schedule.md @@ -23,6 +23,6 @@ article td, article th { | -----------:| --------------------------------------- | | 18 Jun 2016 | 3.2-rc1 release | | 2 Jul 2016 | decide whether 3.2-rc1 is the final 3.2 | -| 16 Jul 2016 | current-testing freeze before 3.2-rc2 | -| 23 Jul 2016 | 3.2-rc2 release | -| 5 Aug 2016 | decide whether 3.2-rc2 is the final 3.2 | +| 16 Jul 2016
20 Jul 2016 | current-testing freeze before 3.2-rc2 | +| 23 Jul 2016
27 Jul 2016 | 3.2-rc2 release | +| 5 Aug 2016
9 Jul 2016 | decide whether 3.2-rc2 is the final 3.2 | From c44b8a13c9afa20cdb4cd4f8a69e45493eac7f8f Mon Sep 17 00:00:00 2001 From: clayton Date: Tue, 19 Jul 2016 20:09:06 +0800 Subject: [PATCH 083/708] Add a specific note about where to put iptables in /rw/config/ --- security/qubes-firewall.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/security/qubes-firewall.md b/security/qubes-firewall.md index 980888ad..f90ec8ae 100644 --- a/security/qubes-firewall.md +++ b/security/qubes-firewall.md @@ -315,3 +315,11 @@ fi This time testing should allow connectivity to the service as long as the service is up :-) + +Where to put firewall rules +--------------------------- + +Implicit in the above example, but worth calling attention to: for all +VMs EXCEPT proxy VMs, iptables commands should be added to the +'/rw/config/rc.local' script. For proxy VMs, iptables commands should +be added to '/rw/config/qubes_firewall_user_script'. From 90c142db2c452c0ad668d27f8b6f04d21225dece Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Marczykowski-G=C3=B3recki?= Date: Wed, 20 Jul 2016 13:06:56 +0200 Subject: [PATCH 084/708] Describe how to generate initramfs and build u2mfn on Debian VM --- configuration/managing-vm-kernel.md | 24 ++++++++++++++++++++++-- 1 file changed, 22 insertions(+), 2 deletions(-) diff --git a/configuration/managing-vm-kernel.md b/configuration/managing-vm-kernel.md index 8da4b078..5f4f0e8b 100644 --- a/configuration/managing-vm-kernel.md +++ b/configuration/managing-vm-kernel.md @@ -280,8 +280,28 @@ Ignore warnings about `version '...' has bad syntax`. Then install whatever kernel you want. If you are using distribution kernel package (`linux-image-amd64` package), initramfs and kernel module should be -handled automatically. If you are using manually build kernel, you need to -handle this on your own. Take a look at `dkms` and `initramfs-tools` documentation. +handled automatically. If not, or you are building kernel manually, do this on +using `dkms` and `initramfs-tools`: + + sudo dkms autoinstall -k # replace this with actual kernel version + sudo update-initramfs -u + +The output should look like this: + + $ sudo dkms autoinstall -k 3.16.0-4-amd64 + + u2mfn: + Running module version sanity check. + - Original module + - No original module exists within this kernel + - Installation + - Installing to /lib/modules/3.16.0-4-amd64/updates/dkms/ + + depmod.... + + DKMS: install completed. + $ sudo update-initramfs -u + update-initramfs: Generating /boot/initrd.img-3.16.0-4-amd64 When kernel is installed, you need to create GRUB configuration. You may want to adjust some settings in `/etc/default/grub`, for example lower From e259037ec337a1d7ffd6b81fd5ddb5b4112824a6 Mon Sep 17 00:00:00 2001 From: clayton Date: Wed, 20 Jul 2016 20:26:17 +0800 Subject: [PATCH 085/708] more /rw/config/ script tweaks --- configuration/config-files.md | 4 +++- configuration/http-filtering-proxy.md | 6 +++--- security/qubes-firewall.md | 21 ++++++++++++--------- 3 files changed, 18 insertions(+), 13 deletions(-) diff --git a/configuration/config-files.md b/configuration/config-files.md index faa5695b..64062c0e 100644 --- a/configuration/config-files.md +++ b/configuration/config-files.md @@ -13,6 +13,7 @@ Qubes specific VM config files ============================== Those files are placed in /rw, which survives VM restart, so can be used to customize single VM (not all VMs based on the same template). +The scripts here all run as root. - `/rw/config/rc.local` - script run at VM startup. Good place to change some service settings, replace config files with its copy stored in /rw/config etc. Example usage: @@ -23,7 +24,8 @@ Those files are placed in /rw, which survives VM restart, so can be used to cust ~~~ - `/rw/config/qubes-ip-change-hook` - script run in NetVM after external IP change (or connection to the network) -- `/rw/config/qubes-firewall-user-script` - script run in ProxyVM after firewall update. Good place to write own custom firewall rules + +- `/rw/config/qubes-firewall-user-script` - script run in ProxyVM after each firewall update. Good place to write own custom firewall rules - `/rw/config/suspend-module-blacklist` - list of modules (one per line) to be unloaded before system going to sleep. The file is used only in VM with some PCI devices attached. Supposed to be used for problematic device drivers. Note that scripts need to be executable (chmod +x) to be used. diff --git a/configuration/http-filtering-proxy.md b/configuration/http-filtering-proxy.md index cd6de109..e695d025 100644 --- a/configuration/http-filtering-proxy.md +++ b/configuration/http-filtering-proxy.md @@ -162,7 +162,7 @@ Setup to restart all proxy processes. 7. To make sure that the proxy is started automatically when the AppVM - starts change `/rw/config/qubes_firewall_user_script` to include the + starts change `/rw/config/qubes-firewall-user-script` to include the following line: /rw/config/tinyproxy/proxyctl.py update @@ -174,8 +174,8 @@ Setup Make sure that the script is owned by root and executable: - sudo chown root:root /rw/config/qubes_firewall_user_script - sudo chmod 755 /rw/config/qubes_firewall_user_script + sudo chown root:root /rw/config/qubes-firewall-user-script + sudo chmod 755 /rw/config/qubes-firewall-user-script 8. In Qubes VM manager adjust Firewall rules for each AppVM with a proxy. In a typical case when only HTTP proxy should be used for diff --git a/security/qubes-firewall.md b/security/qubes-firewall.md index f90ec8ae..fc689513 100644 --- a/security/qubes-firewall.md +++ b/security/qubes-firewall.md @@ -86,7 +86,7 @@ sudo iptables -I FORWARD 2 -s -d -j ACCEPT issues from VM A. Note however, that this doesn't allow you to reach A from B -- for this you would need another rule, with A and B addresses swapped. * If everything works as expected, then the above iptables rule(s) should be - written into firewall VM's `qubes_firewall_user_script` script which is run + written into firewall VM's `qubes-firewall-user-script` script which is run on every firewall update. This is necessary, because Qubes orders every firewall VM to update all the rules whenever new VM is started in the system. If we didn't enter our rules into this "hook" script, then shortly our custom @@ -97,8 +97,8 @@ sudo iptables -I FORWARD 2 -s -d -j ACCEPT ~~~ [user@firewallvm ~]$ sudo bash -[root@firewallvm user]# echo "iptables -I FORWARD 2 -s 10.137.2.25 -d 10.137.2.6 -j ACCEPT" >> /rw/config/qubes_firewall_user_script -[root@firewallvm user]# chmod +x /rw/config/qubes_firewall_user_script +[root@firewallvm user]# echo "iptables -I FORWARD 2 -s 10.137.2.25 -d 10.137.2.6 -j ACCEPT" >> /rw/config/qubes-firewall-user-script +[root@firewallvm user]# chmod +x /rw/config/qubes-firewall-user-script ~~~ Port forwarding to a VM from the outside world @@ -235,7 +235,7 @@ the service remove the ` -s 192.168.0.1/24 ` Once you have confirmed that the counters increase, store these command in -'/rw/config/qubes_firewall_user_script' +'/rw/config/qubes-firewall-user-script' ~~~ #!/bin/sh @@ -284,7 +284,7 @@ fi Finally make this file executable (so it runs at every Firewall VM update) ~~~ -sudo chmod +x /rw/config/qubes_firewall_user_script +sudo chmod +x /rw/config/qubes-firewall-user-script ~~~ **3. Allow packets into the VM to reach the service** @@ -319,7 +319,10 @@ service is up :-) Where to put firewall rules --------------------------- -Implicit in the above example, but worth calling attention to: for all -VMs EXCEPT proxy VMs, iptables commands should be added to the -'/rw/config/rc.local' script. For proxy VMs, iptables commands should -be added to '/rw/config/qubes_firewall_user_script'. +Implicit in the above example [scripts](/doc/config-files/), but worth +calling attention to: for all VMs EXCEPT proxy VMs, iptables commands +should be added to the '/rw/config/rc.local' script. For proxy VMs +(sys-firewall inclusive) iptables commands should be added to +'/rw/config/qubes-firewall-user-script'. This is because a proxy VM is +constantly adjusting it's firewall, and therefore initial settings from +rc.local do not persist. From 602bcf9fe27114cb8942837e78764c06dde69fdd Mon Sep 17 00:00:00 2001 From: clayton Date: Thu, 21 Jul 2016 14:59:06 +0800 Subject: [PATCH 086/708] No content changes -- hard wrap excessively long Markdown lines only. --- configuration/config-files.md | 44 ++++++++++++++++++++++++++--------- 1 file changed, 33 insertions(+), 11 deletions(-) diff --git a/configuration/config-files.md b/configuration/config-files.md index 64062c0e..43485c5a 100644 --- a/configuration/config-files.md +++ b/configuration/config-files.md @@ -12,10 +12,13 @@ redirect_from: Qubes specific VM config files ============================== -Those files are placed in /rw, which survives VM restart, so can be used to customize single VM (not all VMs based on the same template). +Those files are placed in /rw, which survives VM restart, so can be +used to customize single VM (not all VMs based on the same template). The scripts here all run as root. -- `/rw/config/rc.local` - script run at VM startup. Good place to change some service settings, replace config files with its copy stored in /rw/config etc. Example usage: +- `/rw/config/rc.local` - script run at VM startup. Good place to +change some service settings, replace config files with its copy stored +in /rw/config etc. Example usage: ~~~ # Store bluetooth keys in /rw to keep them across VM restarts @@ -23,17 +26,26 @@ The scripts here all run as root. ln -s /rw/config/var-lib-bluetooth /var/lib/bluetooth ~~~ -- `/rw/config/qubes-ip-change-hook` - script run in NetVM after external IP change (or connection to the network) +- `/rw/config/qubes-ip-change-hook` - script run in NetVM after +external IP change (or connection to the network) -- `/rw/config/qubes-firewall-user-script` - script run in ProxyVM after each firewall update. Good place to write own custom firewall rules -- `/rw/config/suspend-module-blacklist` - list of modules (one per line) to be unloaded before system going to sleep. The file is used only in VM with some PCI devices attached. Supposed to be used for problematic device drivers. +- `/rw/config/qubes-firewall-user-script` - script run in ProxyVM +after each firewall update. Good place to write own custom firewall +rules + +- `/rw/config/suspend-module-blacklist` - list of modules (one per +line) to be unloaded before system going to sleep. The file is used +only in VM with some PCI devices attached. Supposed to be used for +problematic device drivers. Note that scripts need to be executable (chmod +x) to be used. GUI and audio configuration in dom0 =================================== -GUI configuration file `/etc/qubes/guid.conf` in one of few not managed by qubes-prefs nor Qubes Manager tool. Sample config (included in default installation): +GUI configuration file `/etc/qubes/guid.conf` in one of few not managed +by qubes-prefs nor Qubes Manager tool. Sample config (included in +default installation): ~~~ # Sample configuration file for Qubes GUI daemon @@ -63,9 +75,19 @@ VM: { Currently supported settings: -- `allow_fullscreen` - allow VM to request its windows to go fullscreen (without any colorful frame). Regardless of this setting, you can also set window fullscreen using trusted window manager settings (right click on title bar). -- `allow_utf8_titles` - allow to use UTF-8 in window titles, otherwise non-ASCII characters are replaced by underscore. -- `secure_copy_sequence` and `secure_paste_sequence` - key sequences used to trigger secure copy and paste -- `windows_count_limit` - limit on concurrent windows count. -- `audio_low_latency` - force low-latency audio mode (about 40ms compared to 200-500ms by default). Note that this will cause much higher CPU usage in dom0. +- `allow_fullscreen` - allow VM to request its windows to go +fullscreen (without any colorful frame). Regardless of this setting, +you can also set window fullscreen using trusted window manager +settings (right click on title bar). +- `allow_utf8_titles` - allow to use UTF-8 in window titles, +otherwise non-ASCII characters are replaced by underscore. + +- `secure_copy_sequence` and `secure_paste_sequence` - key sequences +used to trigger secure copy and paste + +- `windows_count_limit` - limit on concurrent windows count. + +- `audio_low_latency` - force low-latency audio mode (about 40ms +compared to 200-500ms by default). Note that this will cause much +higher CPU usage in dom0. From d97b9361cb4a97cb2cbe662b1bc78359b85d385b Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Thu, 21 Jul 2016 14:52:42 -0700 Subject: [PATCH 087/708] Add link to Corridor doc in Whonix wiki --- privacy/whonix.md | 1 + 1 file changed, 1 insertion(+) diff --git a/privacy/whonix.md b/privacy/whonix.md index 06565e86..fb72cda1 100644 --- a/privacy/whonix.md +++ b/privacy/whonix.md @@ -39,6 +39,7 @@ To install Whonix, you must have a working Qubes machine already. * [Security Advice for after installing Whonix on Qubes](https://www.whonix.org/wiki/Post_Install_Advice) * [How to set up Tor Bridges in Whonix on Qubes](https://www.whonix.org/wiki/Bridges#How_to_use_bridges_in_Whonix) * [Using Multiple Whonix-Workstations with Whonix on Qubes](https://www.whonix.org/wiki/Multiple_Whonix-Workstations#Qubes-Whonix) +* [How to use Corridor (a Tor traffic whitelisting gateway) with Whonix](https://www.whonix.org/wiki/Corridor) ## Support for Whonix From 4485a457e53d7d229cbd074525e607df677449d8 Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Thu, 21 Jul 2016 15:02:25 -0700 Subject: [PATCH 088/708] Fix (presumable) typo: "Jul" -> "Aug" --- releases/3.2/schedule.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/releases/3.2/schedule.md b/releases/3.2/schedule.md index e4585a33..5f1c6745 100644 --- a/releases/3.2/schedule.md +++ b/releases/3.2/schedule.md @@ -25,4 +25,4 @@ article td, article th { | 2 Jul 2016 | decide whether 3.2-rc1 is the final 3.2 | | 16 Jul 2016
20 Jul 2016 | current-testing freeze before 3.2-rc2 | | 23 Jul 2016
27 Jul 2016 | 3.2-rc2 release | -| 5 Aug 2016
9 Jul 2016 | decide whether 3.2-rc2 is the final 3.2 | +| 5 Aug 2016
9 Aug 2016 | decide whether 3.2-rc2 is the final 3.2 | From 859af9be0354bd86a9f356dd65d1b0750c507827 Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Thu, 21 Jul 2016 15:09:30 -0700 Subject: [PATCH 089/708] Fix formatting and orthography --- security/qubes-firewall.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/security/qubes-firewall.md b/security/qubes-firewall.md index fc689513..5d2c9152 100644 --- a/security/qubes-firewall.md +++ b/security/qubes-firewall.md @@ -320,9 +320,10 @@ Where to put firewall rules --------------------------- Implicit in the above example [scripts](/doc/config-files/), but worth -calling attention to: for all VMs EXCEPT proxy VMs, iptables commands -should be added to the '/rw/config/rc.local' script. For proxy VMs -(sys-firewall inclusive) iptables commands should be added to -'/rw/config/qubes-firewall-user-script'. This is because a proxy VM is -constantly adjusting it's firewall, and therefore initial settings from -rc.local do not persist. +calling attention to: for all VMs *except* ProxyVMs, iptables commands +should be added to the `/rw/config/rc.local` script. For ProxyVMs +(`sys-firewall` inclusive), iptables commands should be added to +`/rw/config/qubes-firewall-user-script`. This is because a ProxyVM is +constantly adjusting its firewall, and therefore initial settings from +`rc.local` do not persist. + From 61ce38bb6d2a499978efb1ecb8c03208300ca3b1 Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Mon, 25 Jul 2016 03:31:49 -0700 Subject: [PATCH 090/708] Organize certified laptops by release branch * Librem 13 is certified for R3.x but not R4.x * R4.x has updated requirements (link to post) * There are no R4.x-certified laptops yet --- hardware/certified-laptops.md | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) diff --git a/hardware/certified-laptops.md b/hardware/certified-laptops.md index 4bd061b6..44b7fa9f 100644 --- a/hardware/certified-laptops.md +++ b/hardware/certified-laptops.md @@ -26,8 +26,10 @@ the hardware will not being modified in any way (malicious or not). For more general information about choosing hardware for Qubes, please see the [System Requirements] and the [Hardware Compatibility List]. -Purism Librem 13 ----------------- +Certified for Qubes R3.x +------------------------ + +### Purism Librem 13 ### [![image of Librem 13](/attachment/site/qubes-plus-purism.png)](https://puri.sm/librem-13/) @@ -49,9 +51,15 @@ compatibility with Qubes: sudo qubes-dom0-update --enablerepo=qubes-dom0-unstable kernel +Certified for Qubes R4.x +------------------------ + +There are [updated requirements] for Qubes R4.x certification. Currently, no +laptops are certified for Qubes R4.x. This page will be updated once +R4.x-certified laptops are available. [System Requirements]: /doc/system-requirements/ [Hardware Compatibility List]: /hcl/ [Hardware Certification]: /hardware-certification/ - +[updated requirements]: /news/2016/07/21/new-hw-certification-for-q4/ From 4e745b374eb5364193e7f95aa38455e626a76e1f Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Wed, 27 Jul 2016 13:49:58 -0700 Subject: [PATCH 091/708] Add QSB 24 to Security Bulletins page --- security/security-bulletins.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/security/security-bulletins.md b/security/security-bulletins.md index 7ff11e5e..119da338 100644 --- a/security/security-bulletins.md +++ b/security/security-bulletins.md @@ -62,3 +62,8 @@ Qubes Security Bulletins are published through the [Qubes Security Pack](/doc/se - [Qubes Security Bulletin \#22](https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-022-2015.txt) (Critical Xen bug in PV memory virtualization code (XSA 148)) - [Qubes Security Bulletin \#23](https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-023-2015.txt) (Race condition bugs in Xen code (XSA-155 and XSA-166), other Xen bugs) +2016 +---- + +- [Qubes Security Bulletin \#24](https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-024-2016.txt) (Critical Xen bug in PV memory virtualization code (XSA 182)) + From 8b488234ebe13da95e32b8482d061183e6e403ec Mon Sep 17 00:00:00 2001 From: xloem <0xloem@gmail.com> Date: Fri, 29 Jul 2016 19:56:25 +0000 Subject: [PATCH 092/708] Fix for #2206 --- security/qubes-firewall.md | 39 ++++++++++++++++++++++++++------------ 1 file changed, 27 insertions(+), 12 deletions(-) diff --git a/security/qubes-firewall.md b/security/qubes-firewall.md index 5d2c9152..cdd9bcfb 100644 --- a/security/qubes-firewall.md +++ b/security/qubes-firewall.md @@ -82,23 +82,38 @@ In order to allow networking between VM A and B follow those steps: sudo iptables -I FORWARD 2 -s -d -j ACCEPT ~~~ +* In VM B's terminal enter the following iptables rule: + +~~~ +sudo iptables -I INPUT -s -j ACCEPT +~~~ + * Now you should be able to reach the VM B from A -- test it using e.g. ping - issues from VM A. Note however, that this doesn't allow you to reach A from - B -- for this you would need another rule, with A and B addresses swapped. -* If everything works as expected, then the above iptables rule(s) should be + issued from VM A. Note however, that this doesn't allow you to reach A from + B -- for this you would need two more rules, with A and B swapped. +* If everything works as expected, then the above iptables rules should be written into firewall VM's `qubes-firewall-user-script` script which is run - on every firewall update. This is necessary, because Qubes orders every - firewall VM to update all the rules whenever new VM is started in the system. - If we didn't enter our rules into this "hook" script, then shortly our custom - rules would disappear and inter-VM networking would stop working. Here's an - example how to update the script (note that, by default, there is no script - file present, so we likely will be creating it, unless we had some other + on every firewall update, and A and B's `rc.local` script which is run when + the vm is launched. The `qubes-firewall-user-script` is necessary because Qubes + orders every firewall VM to update all the rules whenever new VM is started in + the system. If we didn't enter our rules into this "hook" script, then shortly + our custom rules would disappear and inter-VM networking would stop working. + Here's an example how to update the script (note that, by default, there is no + script file present, so we likely will be creating it, unless we had some other custom rules defines earlier in this firewallvm): ~~~ -[user@firewallvm ~]$ sudo bash -[root@firewallvm user]# echo "iptables -I FORWARD 2 -s 10.137.2.25 -d 10.137.2.6 -j ACCEPT" >> /rw/config/qubes-firewall-user-script -[root@firewallvm user]# chmod +x /rw/config/qubes-firewall-user-script +[user@sys-firewall ~]$ sudo bash +[root@sys-firewall user]# echo "iptables -I FORWARD 2 -s 10.137.2.25 -d 10.137.2.6 -j ACCEPT" >> /rw/config/qubes-firewall-user-script +[root@sys-firewall user]# chmod +x /rw/config/qubes-firewall-user-script +~~~ + +* Here is an example how to update `rc.local`: + +~~~ +[user@B ~]$ sudo bash +[root@B user]# echo "iptables -I INPUT -s 10.137.2.25 -j ACCEPT" >> /rw/config/rc.local +[root@B user]# chmod +x /rw/config/rc.local ~~~ Port forwarding to a VM from the outside world From 4f5adaf94d73227d27882507fbf12e792efc63b2 Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Sat, 30 Jul 2016 16:55:25 -0700 Subject: [PATCH 093/708] Provide location of XML file containing firewall rules --- security/qubes-firewall.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/security/qubes-firewall.md b/security/qubes-firewall.md index cdd9bcfb..6d5feca5 100644 --- a/security/qubes-firewall.md +++ b/security/qubes-firewall.md @@ -37,7 +37,10 @@ connection. This means it will not work for servers using load balancing. More on this in the message quoted below. Alternatively, one can use the `qvm-firewall` command from Dom0 to edit the -firewall rules by hand: +firewall rules by hand. The firewall rules for each VM are saved in an XML file +in that VM's directory in dom0: + + /var/lib/qubes/appvms//firewall.xml Reconnecting VMs after a NetVM reboot ---------------------------------------- From 15d418b778a8879323091c79fdc1084decb890cb Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Sun, 31 Jul 2016 14:42:36 -0700 Subject: [PATCH 094/708] Explain hiding USB devices from dom0 See: https://groups.google.com/d/msg/qubes-users/wc0-RK1alx4/p_-VIV5NDAAJ --- common-tasks/usb.md | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/common-tasks/usb.md b/common-tasks/usb.md index cc73583e..76298705 100644 --- a/common-tasks/usb.md +++ b/common-tasks/usb.md @@ -209,6 +209,31 @@ Alternatively, you can create a USB qube manually as follows: If the USB qube will not start, see [here][faq-usbvm]. +### Hide all USB devices from dom0 ### + +Even if you create a USB qube, there will be a brief period of time during the +boot process during which dom0 will be exposed to your USB 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 devices 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 devices 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. + Supported USB device types -------------------------- @@ -303,6 +328,7 @@ This feature is not yet available in Qubes Manager. [1072-comm2]: https://github.com/QubesOS/qubes-issues/issues/1072#issuecomment-124119309 [1082]: https://github.com/QubesOS/qubes-issues/issues/1082 [faq-usbvm]: /doc/user-faq/#i-created-a-usbvm-and-assigned-usb-controllers-to-it-now-the-usbvm-wont-boot +[AEM]: /doc/anti-evil-maid/ [1618]: https://github.com/QubesOS/qubes-issues/issues/1618 [input-proxy]: https://github.com/qubesos/qubes-app-linux-input-proxy [usb-challenges]: http://blog.invisiblethings.org/2011/05/31/usb-security-challenges.html From a4ff57fa980b58c33605ef2d27e1ee39c8e5f07a Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Sun, 31 Jul 2016 14:52:52 -0700 Subject: [PATCH 095/708] Clarify hiding USB controllers from dom0 * Fix terminology ("devices" vs. "controllers") * Note that the setting is automatic beginning in R3.2 (QubesOS/qubes-issues#2172) --- common-tasks/usb.md | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/common-tasks/usb.md b/common-tasks/usb.md index 76298705..6f9990a7 100644 --- a/common-tasks/usb.md +++ b/common-tasks/usb.md @@ -209,23 +209,23 @@ Alternatively, you can create a USB qube manually as follows: If the USB qube will not start, see [here][faq-usbvm]. -### Hide all USB devices from dom0 ### +### Hide all USB controllers from dom0 ### Even if you create a USB qube, there will be a brief period of time during the -boot process during which dom0 will be exposed to your USB 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: +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 devices from dom0. +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 devices from dom0 is as follows: +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`. @@ -234,6 +234,8 @@ The procedure to hide all USB devices from dom0 is as follows: 5. Run the command `grub2-mkconfig -o /boot/grub2/grub.cfg` in dom0. 6. Reboot. +(Note: Beginning with R3.2, `rd.qubes.hide_all_usb` is set automatically if you +opt to create a USB qube during installation.) Supported USB device types -------------------------- From 9c0a94240686a87b00568eff36fde20a5d403601 Mon Sep 17 00:00:00 2001 From: Thom Wiggers Date: Wed, 3 Aug 2016 00:39:13 +0200 Subject: [PATCH 096/708] There is in fact a progress indicator in 3.2-rc2 --- managing-os/templates/fedora-minimal.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/managing-os/templates/fedora-minimal.md b/managing-os/templates/fedora-minimal.md index 5b77088a..7aea2fbd 100644 --- a/managing-os/templates/fedora-minimal.md +++ b/managing-os/templates/fedora-minimal.md @@ -25,7 +25,7 @@ It can be installed via the following command: [user@dom0 ~]$ sudo qubes-dom0-update qubes-template-fedora-23-minimal ~~~ -Download will take a while and there will be no progress indicator. +The download may take a while. Usage ----- From 99566ff769de19910544c52d051a4b38b2b10185 Mon Sep 17 00:00:00 2001 From: Thom Wiggers Date: Wed, 3 Aug 2016 23:29:58 +0200 Subject: [PATCH 097/708] Explicitly install required dependencies --- configuration/postfix.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/configuration/postfix.md b/configuration/postfix.md index d4565edf..0c0884b9 100644 --- a/configuration/postfix.md +++ b/configuration/postfix.md @@ -16,9 +16,11 @@ Postfix is full featured MTA (Message Transfer Agent). Here we will configure it Installation ------------ -`yum install postfix procmail make` +`yum install postfix procmail make cyrus-sasl cyrus-sasl-plain` -Procmail is not strictly necessary, but is useful to sort your incoming mail, for example to put each mailing list in its own directory. Make is also not necessary, but is used to keep Postfix lookup tables. You should also check `alternatives` command, to see if it is the default `mta`. It probably is not. You may need to `yum remove ssmtp` or something. +Cyrus-sasl is installed to authenticate to remote servers. Procmail is not strictly necessary, but is useful to sort your incoming mail, for example to put each mailing list in its own directory. Make is also not necessary, but is used to keep Postfix lookup tables. + +You should also check `alternatives` command, to see if it is the default `mta`. It probably is not. You may need to `yum remove ssmtp` or something Configuration ------------- From 704f95484aecb3bebb74451a34fcd487d15a1c93 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Marczykowski-G=C3=B3recki?= Date: Thu, 4 Aug 2016 12:54:56 +0200 Subject: [PATCH 098/708] Fix ToC in managing-vm-kernel --- configuration/managing-vm-kernel.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/configuration/managing-vm-kernel.md b/configuration/managing-vm-kernel.md index 5f4f0e8b..a80384a6 100644 --- a/configuration/managing-vm-kernel.md +++ b/configuration/managing-vm-kernel.md @@ -7,7 +7,7 @@ redirect_from: --- VM kernel managed by dom0 -------------------------- +========================= By default VMs kernels are provided by dom0. This means that: @@ -47,7 +47,7 @@ updatevm : sys-firewall ~~~ Installing different kernel using Qubes kernel package -================================== +---------------------------------- VM kernels are packages by Qubes team in `kernel-qubes-vm` packages. Generally system will keep the 3 newest available versions. You can list them with the `rpm` command: @@ -135,7 +135,7 @@ In the above example, it tries to remove 3.18.10-2.pvops.qubes kernel (to keep o The newly installed package is set as default VM kernel. Installing different VM kernel based on dom0 kernel -=================================================== +--------------------------------------------------- It is possible to package kernel installed in dom0 as VM kernel. This makes it possible to use VM kernel, which is not packaged by Qubes team. This includes: @@ -203,7 +203,7 @@ mke2fs 1.42.12 (29-Aug-2014) ~~~ Using kernel installed in the VM -================================ +-------------------------------- **This option is available only in Qubes R3.1 or newer** From a859dcedd171ce6f5786db8cc1bc6d5461c64e55 Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Thu, 4 Aug 2016 19:24:33 -0700 Subject: [PATCH 099/708] Add note about upgrading to non-repo kernels --- common-tasks/software-update-dom0.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/common-tasks/software-update-dom0.md b/common-tasks/software-update-dom0.md index 1f806b15..0d71468c 100644 --- a/common-tasks/software-update-dom0.md +++ b/common-tasks/software-update-dom0.md @@ -131,6 +131,10 @@ sudo grub2-mkconfig -o /boot/grub2/grub.cfg Reboot required. +If you wish to upgrade to a kernel that is not available from the repos, then +there is no easy way to do so, but [it may still be possible if you're willing +to do a lot of work yourself](https://groups.google.com/d/msg/qubes-users/m8sWoyV58_E/HYdReRIYBAAJ). + ### Upgrading over Tor ### Requires installed [Whonix](/doc/privacy/whonix/). From 67c3e186768adde02cc175dbfef4918545a8cd0b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Marczykowski-G=C3=B3recki?= Date: Fri, 5 Aug 2016 20:21:11 +0200 Subject: [PATCH 100/708] upgrade-to-r3.2: add additional step for Debian-based UpdateVM yum in Debian is much older and can't deal with some dependencies. --- installing/upgrade/upgrade-to-r3.2.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/installing/upgrade/upgrade-to-r3.2.md b/installing/upgrade/upgrade-to-r3.2.md index 8f8f6722..2f281f98 100644 --- a/installing/upgrade/upgrade-to-r3.2.md +++ b/installing/upgrade/upgrade-to-r3.2.md @@ -36,6 +36,23 @@ Upgrading dom0 to manually apply the changes to `/etc/yum.repos.d/qubes-dom0.repo` or simply replace it with .rpmnew file. + If you are using Debian-based VM as UpdateVM (`sys-firewall` by default), + you need to download few more packages manually, but **do not install + them** yet: + + sudo qubes-dom0-update systemd-compat-libs perl-libwww-perl perl-Term-ANSIColor perl-Term-Cap gdk-pixbuf2-xlib speexdsp qubes-mgmt-salt-admin-tools + (...) + Transaction Summary + =============================================================== + Install 15 Packages (+ 31 Dependent packages) + Upgrade 4 Packages (+200 Dependent packages) + + Total download size: 173 M + Is this ok [y/d/N]: n + Exiting on user command + Your transaction was saved, rerun it with: + yum load-transaction /tmp/yum_save_tx..... + 4. Upgrade dom0 to R3.2: sudo qubes-dom0-update From ca6bdb34b1e16d606dc048ffd1283aeaf3539b40 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Marczykowski-G=C3=B3recki?= Date: Fri, 5 Aug 2016 21:35:42 +0200 Subject: [PATCH 101/708] r3.2: update schedule --- releases/3.2/schedule.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/releases/3.2/schedule.md b/releases/3.2/schedule.md index 5f1c6745..86e47c92 100644 --- a/releases/3.2/schedule.md +++ b/releases/3.2/schedule.md @@ -26,3 +26,7 @@ article td, article th { | 16 Jul 2016
20 Jul 2016 | current-testing freeze before 3.2-rc2 | | 23 Jul 2016
27 Jul 2016 | 3.2-rc2 release | | 5 Aug 2016
9 Aug 2016 | decide whether 3.2-rc2 is the final 3.2 | +| 24 Aug 2016 | current-testing freeze before 3.2-rc3 | +| 31 Aug 2016 | 3.2-rc3 release | + +If there will be no critical bugs, 3.2-rc3 may be released earlier. From 627e84a038639cd2a34093c27df5e181560b6393 Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Fri, 5 Aug 2016 19:56:16 -0700 Subject: [PATCH 102/708] Explain how to verify hashes with *sum programs --- installing/verifying-signatures.md | 19 ++++++++++++++++++- 1 file changed, 18 insertions(+), 1 deletion(-) diff --git a/installing/verifying-signatures.md b/installing/verifying-signatures.md index 14cbc946..33360274 100644 --- a/installing/verifying-signatures.md +++ b/installing/verifying-signatures.md @@ -164,7 +164,24 @@ Each ISO is accompanied by a plain text file ending in `.DIGESTS`. This file con =FiJ5 -----END PGP SIGNATURE----- -Four digests have been computed for this ISO. The hash functions used, in order from top to bottom, are MD5, SHA1, SHA256, and SHA512. One way to verify that the ISO you downloaded matches any of these is by using `openssl` from the command line: +Four digests have been computed for this ISO. The hash functions used, in order from top to bottom, are MD5, SHA1, SHA256, and SHA512. One way to verify that the ISO you downloaded matches any of these hash values is by using the respective `*sum` programs: + + $ md5sum -c Qubes-R3.1-x86_64.iso.DIGESTS + Qubes-R3.1-x86_64.iso: OK + md5sum: WARNING: 23 lines are improperly formatted + $ sha1sum -c Qubes-R3.1-x86_64.iso.DIGESTS + Qubes-R3.1-x86_64.iso: OK + sha1sum: WARNING: 23 lines are improperly formatted + $ sha256sum -c Qubes-R3.1-x86_64.iso.DIGESTS + Qubes-R3.1-x86_64.iso: OK + sha256sum: WARNING: 23 lines are improperly formatted + $ sha512sum -c Qubes-R3.1-x86_64.iso.DIGESTS + Qubes-R3.1-x86_64.iso: OK + sha512sum: WARNING: 23 lines are improperly formatted + +The `OK` response tells us that the hash value for that particular hash function matches. The program also warns us that there are 23 improperly formatted lines, but this is to be expected. This is because each file contains lines for several different hash values (as mentioned above), but each `*sum` program verifies only the line for its own hash function. In addition, there are lines for the PGP signature which the `*sum` does not know how to read. + +Another way is to use `openssl` to compute each hash value, then compare them to the contents of the `.DIGESTS` file.: $ openssl dgst -md5 Qubes-R3.1-x86_64.iso MD5(Qubes-R3.1-x86_64.iso)= f99634b05d15f6bb2ac02ee03e4338a0 From 83bd0ec13c31f70ad94ca2d6240722874d228823 Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Fri, 5 Aug 2016 20:08:18 -0700 Subject: [PATCH 103/708] Wrap lines and fix typo --- installing/verifying-signatures.md | 146 +++++++++++++++++++++++------ 1 file changed, 119 insertions(+), 27 deletions(-) diff --git a/installing/verifying-signatures.md b/installing/verifying-signatures.md index 33360274..6aed712c 100644 --- a/installing/verifying-signatures.md +++ b/installing/verifying-signatures.md @@ -14,30 +14,67 @@ On Digital Signatures and Key Verification What Digital Signatures Can and Cannot Prove -------------------------------------------- -Most people – even programmers – are confused about the basic concepts underlying digital signatures. Therefore, most people should read this section, even if it looks trivial at first sight. +Most people – even programmers – are confused about the basic concepts +underlying digital signatures. Therefore, most people should read this section, +even if it looks trivial at first sight. -Digital signatures can prove both **authenticity** and **integrity** to a reasonable degree of certainty. **Authenticity** ensures that a given file was indeed created by the person who signed it (i.e., that it was not forged by a third party). **Integrity** ensures that the contents of the file have not been tampered with (i.e., that a third party has not undetectably altered its contents *en route*). +Digital signatures can prove both **authenticity** and **integrity** to a +reasonable degree of certainty. **Authenticity** ensures that a given file was +indeed created by the person who signed it (i.e., that it was not forged by a +third party). **Integrity** ensures that the contents of the file have not been +tampered with (i.e., that a third party has not undetectably altered its +contents *en route*). -Digital signatures **cannot** prove any other property, e.g., that the signed file is not malicious. In fact, there is nothing that could stop someone from signing a malicious program (and it happens from time to time in reality). +Digital signatures **cannot** prove any other property, e.g., that the signed +file is not malicious. In fact, there is nothing that could stop someone from +signing a malicious program (and it happens from time to time in reality). -The point is, of course, that people must choose who they will trust (e.g., Linus Torvalds, Microsoft, the Qubes Project, etc.) and assume that if a given file was signed by a trusted party, then it should not be malicious or buggy in some horrible way. But the decision of whether to trust any given party is beyond the scope of digital signatures. It's more of a sociological and political decision. +The point is, of course, that people must choose who they will trust (e.g., +Linus Torvalds, Microsoft, the Qubes Project, etc.) and assume that if a given +file was signed by a trusted party, then it should not be malicious or buggy in +some horrible way. But the decision of whether to trust any given party is +beyond the scope of digital signatures. It's more of a sociological and +political decision. -Once we make the decision to trust certain parties, digital signatures are useful, because they make it possible for us to limit our trust only to those few parties we choose and not to worry about all the "Bad Things That Can Happen In The Middle" between us and them, e.g., server compromises (qubes-os.org will surely be compromised one day), dishonest IT staff at the hosting company, dishonest staff at the ISPs, Wi-Fi attacks, etc. +Once we make the decision to trust certain parties, digital signatures are +useful, because they make it possible for us to limit our trust only to those +few parties we choose and not to worry about all the "Bad Things That Can +Happen In The Middle" between us and them, e.g., server compromises +(qubes-os.org will surely be compromised one day), dishonest IT staff at the +hosting company, dishonest staff at the ISPs, Wi-Fi attacks, etc. -By verifying all the files we download which purport to be authored by a party we've chosen to trust, we eliminate concerns about the bad things discussed above, since we can easily detect whether any files have been tampered with (and subsequently choose to refrain from executing, installing, or opening them). +By verifying all the files we download which purport to be authored by a party +we've chosen to trust, we eliminate concerns about the bad things discussed +above, since we can easily detect whether any files have been tampered with +(and subsequently choose to refrain from executing, installing, or opening +them). -However, for digital signatures to make any sense, we must ensure that the public keys we use for signature verification are indeed the original ones. Anybody can generate a GPG key pair that purports to belong to "The Qubes Project," but of course only the key pair that we (i.e., the Qubes developers) generated is the legitimate one. The next section explains how to verify the validity of the Qubes signing keys. +However, for digital signatures to make any sense, we must ensure that the +public keys we use for signature verification are indeed the original ones. +Anybody can generate a GPG key pair that purports to belong to "The Qubes +Project," but of course only the key pair that we (i.e., the Qubes developers) +generated is the legitimate one. The next section explains how to verify the +validity of the Qubes signing keys. Importing Qubes Signing Keys ---------------------------- -Every file published by the Qubes Project (ISO, RPM, TGZ files and git repositories) is digitally signed by one of the developer or release signing keys. Each such key is signed by the Qubes Master Signing Key ([`0x36879494`](https://keys.qubes-os.org/keys/qubes-master-signing-key.asc)). +Every file published by the Qubes Project (ISO, RPM, TGZ files and git +repositories) is digitally signed by one of the developer or release signing +keys. Each such key is signed by the Qubes Master Signing Key +([`0x36879494`](https://keys.qubes-os.org/keys/qubes-master-signing-key.asc)). -The public portion of the Qubes Master Signing Key can be imported directly from a [ keyserver](https://en.wikipedia.org/wiki/Key_server_%28cryptographic%29#Keyserver_examples) (specified on first use with --keyserver URI, keyserver saved in `~/.gnupg/gpg.conf`), e.g., +The public portion of the Qubes Master Signing Key can be imported directly +from a [ +keyserver](https://en.wikipedia.org/wiki/Key_server_%28cryptographic%29#Keyserver_examples) +(specified on first use with --keyserver URI, keyserver saved in +`~/.gnupg/gpg.conf`), e.g., gpg --keyserver pool.sks-keyservers.net --recv-keys 0x427F11FD0FAA4B080123F01CDDFA1A3E36879494 -or downloaded [here](https://keys.qubes-os.org/keys/qubes-master-signing-key.asc) and imported with gpg, +or downloaded +[here](https://keys.qubes-os.org/keys/qubes-master-signing-key.asc) and +imported with gpg, $ gpg --import ./qubes-master-signing-key.asc @@ -45,15 +82,30 @@ or fetched directly with gpg. $ gpg --fetch-keys https://keys.qubes-os.org/keys/qubes-master-signing-key.asc -For additional security we also publish the fingerprint of the Qubes Master Signing Key ([`0x36879494`](https://keys.qubes-os.org/keys/qubes-master-signing-key.asc)) here in this document: +For additional security we also publish the fingerprint of the Qubes Master +Signing Key +([`0x36879494`](https://keys.qubes-os.org/keys/qubes-master-signing-key.asc)) +here in this document: pub 4096R/36879494 2010-04-01 Key fingerprint = 427F 11FD 0FAA 4B08 0123 F01C DDFA 1A3E 3687 9494 uid Qubes Master Signing Key -There should also be a copy of this key at the project's main website, in the [Qubes Security Pack](/doc/security-pack/), and in the archives of the project's [developer](https://groups.google.com/forum/#!msg/qubes-devel/RqR9WPxICwg/kaQwknZPDHkJ) and [user](https://groups.google.com/d/msg/qubes-users/CLnB5uFu_YQ/ZjObBpz0S9UJ) mailing lists. +There should also be a copy of this key at the project's main website, in the +[Qubes Security Pack](/doc/security-pack/), and in the archives of the +project's +[developer](https://groups.google.com/forum/#!msg/qubes-devel/RqR9WPxICwg/kaQwknZPDHkJ) +and +[user](https://groups.google.com/d/msg/qubes-users/CLnB5uFu_YQ/ZjObBpz0S9UJ) +mailing lists. -Once you have obtained the Qubes Master Signing Key ([`0x36879494`](https://keys.qubes-os.org/keys/qubes-master-signing-key.asc)), you should verify the fingerprint of this key very carefully by obtaining copies of the fingerprint from trustworthy independent sources and comparing them to the downloaded key's fingerprint to ensure they match. Then set its trust level to "ultimate" (oh, well), so that it can be used to automatically verify all the keys signed by the Qubes Master Signing Key: +Once you have obtained the Qubes Master Signing Key +([`0x36879494`](https://keys.qubes-os.org/keys/qubes-master-signing-key.asc)), +you should verify the fingerprint of this key very carefully by obtaining +copies of the fingerprint from trustworthy independent sources and comparing +them to the downloaded key's fingerprint to ensure they match. Then set its +trust level to "ultimate" (oh, well), so that it can be used to automatically +verify all the keys signed by the Qubes Master Signing Key: $ gpg --edit-key 0x36879494 @@ -96,9 +148,12 @@ Once you have obtained the Qubes Master Signing Key ([`0x36879494`](https://keys gpg> q -Now you can easily download any of the developer or release signing keys that happen to be used to sign particular ISO, RPM, TGZ files or git tags. +Now you can easily download any of the developer or release signing keys that +happen to be used to sign particular ISO, RPM, TGZ files or git tags. -For example: Qubes OS Release 3 Signing Key ([`0x03FA5082`](https://keys.qubes-os.org/keys/qubes-release-3-signing-key.asc)) is used for all Release 3 ISO images. +For example: Qubes OS Release 3 Signing Key +([`0x03FA5082`](https://keys.qubes-os.org/keys/qubes-release-3-signing-key.asc)) +is used for all Release 3 ISO images. $ gpg --recv-keys 0xC52261BE0A823221D94CA1D1CB11CA1D03FA5082 gpg: requesting key 03FA5082 from hkp server keys.gnupg.net @@ -109,11 +164,21 @@ For example: Qubes OS Release 3 Signing Key ([`0x03FA5082`](https://keys.qubes-o gpg: Total number processed: 1 gpg: imported: 1 (RSA: 1) -You can also download all the currently used developers' signing keys and current and older release signing keys (and also a copy of the Qubes Master Signing Key) from the [keys directory on our server](https://keys.qubes-os.org/keys/) and from the [Qubes Security Pack](/doc/security-pack/). +You can also download all the currently used developers' signing keys and +current and older release signing keys (and also a copy of the Qubes Master +Signing Key) from the [keys directory on our +server](https://keys.qubes-os.org/keys/) and from the [Qubes Security +Pack](/doc/security-pack/). -The developer signing keys are set to be valid for 1 year only, while the Qubes Master Signing Key ([`0x36879494`](https://keys.qubes-os.org/keys/qubes-master-signing-key.asc)) has no expiration date. This latter key was generated and is kept only within a dedicated, air-gapped "vault" machine, and the private portion will (hopefully) never leave this isolated machine. +The developer signing keys are set to be valid for 1 year only, while the Qubes +Master Signing Key +([`0x36879494`](https://keys.qubes-os.org/keys/qubes-master-signing-key.asc)) +has no expiration date. This latter key was generated and is kept only within a +dedicated, air-gapped "vault" machine, and the private portion will (hopefully) +never leave this isolated machine. -You can now verify the ISO image (`Qubes-R3.1-x86_64.iso`) matches its signature (`Qubes-R3.1-x86_64.iso.asc`): +You can now verify the ISO image (`Qubes-R3.1-x86_64.iso`) matches its +signature (`Qubes-R3.1-x86_64.iso.asc`): $ gpg -v --verify Qubes-R3.1-x86_64.iso.asc Qubes-R3.1-x86_64.iso gpg: armor header: Version: GnuPG v1 @@ -122,7 +187,10 @@ You can now verify the ISO image (`Qubes-R3.1-x86_64.iso`) matches its signature gpg: Good signature from "Qubes OS Release 3 Signing Key" gpg: binary signature, digest algorithm SHA256 -The Release 3 Signing Key ([`0x03FA5082`](https://keys.qubes-os.org/keys/qubes-release-3-signing-key.asc)) used to sign this ISO image should be signed by the Qubes Master Signing Key ([`0x36879494`](https://keys.qubes-os.org/keys/qubes-master-signing-key.asc)): +The Release 3 Signing Key +([`0x03FA5082`](https://keys.qubes-os.org/keys/qubes-release-3-signing-key.asc)) +used to sign this ISO image should be signed by the Qubes Master Signing Key +([`0x36879494`](https://keys.qubes-os.org/keys/qubes-master-signing-key.asc)): $ gpg --list-sig 03FA5082 pub 4096R/03FA5082 2014-11-19 @@ -130,14 +198,19 @@ The Release 3 Signing Key ([`0x03FA5082`](https://keys.qubes-os.org/keys/qubes-r sig 3 03FA5082 2014-11-19 Qubes OS Release 3 Signing Key sig 36879494 2014-11-19 Qubes Master Signing Key -Having problems verifying the ISO images? Make sure you have the corresponding release signing key and see this thread: +Having problems verifying the ISO images? Make sure you have the corresponding +release signing key and see this thread: [https://groups.google.com/group/qubes-devel/browse\_thread/thread/4bdec1cd19509b38/9f8e219c41e1b232](https://groups.google.com/group/qubes-devel/browse_thread/thread/4bdec1cd19509b38/9f8e219c41e1b232) Verifying Digests ----------------- -Each ISO is accompanied by a plain text file ending in `.DIGESTS`. This file contains the output of running several different crytographic hash functions on the ISO in order to obtain alphanumeric outputs known as "digests." For example, `Qubes-R3.1-x86_64.iso` is accompanied by `Qubes-R3.1-x86_64.iso.DIGESTS` which has the following content: +Each ISO is accompanied by a plain text file ending in `.DIGESTS`. This file +contains the output of running several different crytographic hash functions on +the ISO in order to obtain alphanumeric outputs known as "digests." For +example, `Qubes-R3.1-x86_64.iso` is accompanied by +`Qubes-R3.1-x86_64.iso.DIGESTS` which has the following content: -----BEGIN PGP SIGNED MESSAGE----- Hash: SHA256 @@ -164,7 +237,10 @@ Each ISO is accompanied by a plain text file ending in `.DIGESTS`. This file con =FiJ5 -----END PGP SIGNATURE----- -Four digests have been computed for this ISO. The hash functions used, in order from top to bottom, are MD5, SHA1, SHA256, and SHA512. One way to verify that the ISO you downloaded matches any of these hash values is by using the respective `*sum` programs: +Four digests have been computed for this ISO. The hash functions used, in order +from top to bottom, are MD5, SHA1, SHA256, and SHA512. One way to verify that +the ISO you downloaded matches any of these hash values is by using the +respective `*sum` programs: $ md5sum -c Qubes-R3.1-x86_64.iso.DIGESTS Qubes-R3.1-x86_64.iso: OK @@ -179,9 +255,16 @@ Four digests have been computed for this ISO. The hash functions used, in order Qubes-R3.1-x86_64.iso: OK sha512sum: WARNING: 23 lines are improperly formatted -The `OK` response tells us that the hash value for that particular hash function matches. The program also warns us that there are 23 improperly formatted lines, but this is to be expected. This is because each file contains lines for several different hash values (as mentioned above), but each `*sum` program verifies only the line for its own hash function. In addition, there are lines for the PGP signature which the `*sum` does not know how to read. +The `OK` response tells us that the hash value for that particular hash +function matches. The program also warns us that there are 23 improperly +formatted lines, but this is to be expected. This is because each file contains +lines for several different hash values (as mentioned above), but each `*sum` +program verifies only the line for its own hash function. In addition, there +are lines for the PGP signature which the `*sum` programs do not know how to +read. -Another way is to use `openssl` to compute each hash value, then compare them to the contents of the `.DIGESTS` file.: +Another way is to use `openssl` to compute each hash value, then compare them +to the contents of the `.DIGESTS` file.: $ openssl dgst -md5 Qubes-R3.1-x86_64.iso MD5(Qubes-R3.1-x86_64.iso)= f99634b05d15f6bb2ac02ee03e4338a0 @@ -195,7 +278,12 @@ Another way is to use `openssl` to compute each hash value, then compare them to (Notice that the outputs match the values from the `.DIGESTS` file.) -However, it is possible that an attacker replaced `Qubes-R3.1-x86_64.iso` with a malicious ISO, computed the hash values for that ISO, and replaced the values in `Qubes-R3.1-x86_64.iso.DIGESTS` with his own set of values. Therefore, ideally, we should also verify the authenticity of the listed hash values. Since `Qubes-R3.1-x86_64.iso.DIGESTS` is a clearsigned PGP file, we can use `gpg` to verify it from the command line: +However, it is possible that an attacker replaced `Qubes-R3.1-x86_64.iso` with +a malicious ISO, computed the hash values for that ISO, and replaced the values +in `Qubes-R3.1-x86_64.iso.DIGESTS` with his own set of values. Therefore, +ideally, we should also verify the authenticity of the listed hash values. +Since `Qubes-R3.1-x86_64.iso.DIGESTS` is a clearsigned PGP file, we can use +`gpg` to verify it from the command line: $ gpg -v --verify Qubes-R3.1-x86_64.iso.DIGESTS gpg: armor header: Hash: SHA256 @@ -206,12 +294,16 @@ However, it is possible that an attacker replaced `Qubes-R3.1-x86_64.iso` with a gpg: Good signature from "Qubes OS Release 3 Signing Key" gpg: textmode signature, digest algorithm SHA256 -The signature is good. Assuming our copy of the `Qubes OS Release 3 Signing Key` is also authentic (see above), we can be confident that these hash values came from the Qubes devs. +The signature is good. Assuming our copy of the `Qubes OS Release 3 Signing +Key` is also authentic (see above), we can be confident that these hash values +came from the Qubes devs. Verifying Qubes Code -------------------- -Developers who fetch code from our Git server should always verify tags on the latest commit. Any commits that are not followed by a signed tag should not be trusted! +Developers who fetch code from our Git server should always verify tags on the +latest commit. Any commits that are not followed by a signed tag should not be +trusted! To verify a signature on a git tag, you can use: From 0ae2e722172d185a6cbef5fc102ac5612dfc35c5 Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Fri, 5 Aug 2016 20:28:34 -0700 Subject: [PATCH 104/708] Use long form PGP key IDs and reference-style links --- installing/verifying-signatures.md | 63 +++++++++++++----------------- 1 file changed, 28 insertions(+), 35 deletions(-) diff --git a/installing/verifying-signatures.md b/installing/verifying-signatures.md index 6aed712c..214cf878 100644 --- a/installing/verifying-signatures.md +++ b/installing/verifying-signatures.md @@ -61,20 +61,16 @@ Importing Qubes Signing Keys Every file published by the Qubes Project (ISO, RPM, TGZ files and git repositories) is digitally signed by one of the developer or release signing -keys. Each such key is signed by the Qubes Master Signing Key -([`0x36879494`](https://keys.qubes-os.org/keys/qubes-master-signing-key.asc)). +keys. Each such key is signed by the [Qubes Master Signing Key] +(`0xDDFA1A3E36879494`). The public portion of the Qubes Master Signing Key can be imported directly -from a [ -keyserver](https://en.wikipedia.org/wiki/Key_server_%28cryptographic%29#Keyserver_examples) -(specified on first use with --keyserver URI, keyserver saved in -`~/.gnupg/gpg.conf`), e.g., +from a [keyserver] (specified on first use with `--keyserver `, keyserver +saved in `~/.gnupg/gpg.conf`), e.g., gpg --keyserver pool.sks-keyservers.net --recv-keys 0x427F11FD0FAA4B080123F01CDDFA1A3E36879494 -or downloaded -[here](https://keys.qubes-os.org/keys/qubes-master-signing-key.asc) and -imported with gpg, +or downloaded [here][Qubes Master Signing Key] and imported with gpg, $ gpg --import ./qubes-master-signing-key.asc @@ -83,24 +79,17 @@ or fetched directly with gpg. $ gpg --fetch-keys https://keys.qubes-os.org/keys/qubes-master-signing-key.asc For additional security we also publish the fingerprint of the Qubes Master -Signing Key -([`0x36879494`](https://keys.qubes-os.org/keys/qubes-master-signing-key.asc)) -here in this document: +Signing Key here in this document: pub 4096R/36879494 2010-04-01 Key fingerprint = 427F 11FD 0FAA 4B08 0123 F01C DDFA 1A3E 3687 9494 uid Qubes Master Signing Key There should also be a copy of this key at the project's main website, in the -[Qubes Security Pack](/doc/security-pack/), and in the archives of the -project's -[developer](https://groups.google.com/forum/#!msg/qubes-devel/RqR9WPxICwg/kaQwknZPDHkJ) -and -[user](https://groups.google.com/d/msg/qubes-users/CLnB5uFu_YQ/ZjObBpz0S9UJ) -mailing lists. +[Qubes Security Pack], and in the archives of the project's [developer] and +[user] [mailing lists]. -Once you have obtained the Qubes Master Signing Key -([`0x36879494`](https://keys.qubes-os.org/keys/qubes-master-signing-key.asc)), +Once you have obtained the Qubes Master Signing Key, you should verify the fingerprint of this key very carefully by obtaining copies of the fingerprint from trustworthy independent sources and comparing them to the downloaded key's fingerprint to ensure they match. Then set its @@ -151,9 +140,8 @@ verify all the keys signed by the Qubes Master Signing Key: Now you can easily download any of the developer or release signing keys that happen to be used to sign particular ISO, RPM, TGZ files or git tags. -For example: Qubes OS Release 3 Signing Key -([`0x03FA5082`](https://keys.qubes-os.org/keys/qubes-release-3-signing-key.asc)) -is used for all Release 3 ISO images. +For example, the Qubes OS [Release 3 Signing Key] (`0xCB11CA1D03FA5082`) is +used for all Release 3 ISO images: $ gpg --recv-keys 0xC52261BE0A823221D94CA1D1CB11CA1D03FA5082 gpg: requesting key 03FA5082 from hkp server keys.gnupg.net @@ -166,16 +154,12 @@ is used for all Release 3 ISO images. You can also download all the currently used developers' signing keys and current and older release signing keys (and also a copy of the Qubes Master -Signing Key) from the [keys directory on our -server](https://keys.qubes-os.org/keys/) and from the [Qubes Security -Pack](/doc/security-pack/). +Signing Key) from the [Qubes OS Keyserver] and from the [Qubes Security Pack]. The developer signing keys are set to be valid for 1 year only, while the Qubes -Master Signing Key -([`0x36879494`](https://keys.qubes-os.org/keys/qubes-master-signing-key.asc)) -has no expiration date. This latter key was generated and is kept only within a -dedicated, air-gapped "vault" machine, and the private portion will (hopefully) -never leave this isolated machine. +Master Signing Key has no expiration date. This latter key was generated and is +kept only within a dedicated, air-gapped "vault" machine, and the private +portion will (hopefully) never leave this isolated machine. You can now verify the ISO image (`Qubes-R3.1-x86_64.iso`) matches its signature (`Qubes-R3.1-x86_64.iso.asc`): @@ -187,10 +171,8 @@ signature (`Qubes-R3.1-x86_64.iso.asc`): gpg: Good signature from "Qubes OS Release 3 Signing Key" gpg: binary signature, digest algorithm SHA256 -The Release 3 Signing Key -([`0x03FA5082`](https://keys.qubes-os.org/keys/qubes-release-3-signing-key.asc)) -used to sign this ISO image should be signed by the Qubes Master Signing Key -([`0x36879494`](https://keys.qubes-os.org/keys/qubes-master-signing-key.asc)): +The Release 3 Signing Key used to sign this ISO image should be signed by the +Qubes Master Signing Key: $ gpg --list-sig 03FA5082 pub 4096R/03FA5082 2014-11-19 @@ -308,3 +290,14 @@ trusted! To verify a signature on a git tag, you can use: $ git tag -v + + +[Qubes Master Signing Key]: https://keys.qubes-os.org/keys/qubes-master-signing-key.asc +[keyserver]: https://en.wikipedia.org/wiki/Key_server_%28cryptographic%29#Keyserver_examples +[Qubes Security Pack]: /doc/security-pack/ +[developer]: https://groups.google.com/forum/#!msg/qubes-devel/RqR9WPxICwg/kaQwknZPDHkJ +[user]: https://groups.google.com/d/msg/qubes-users/CLnB5uFu_YQ/ZjObBpz0S9UJ +[mailing lists]: /mailing-lists/ +[Release 3 Signing Key]: https://keys.qubes-os.org/keys/qubes-release-3-signing-key.asc +[Qubes OS Keyserver]: https://keys.qubes-os.org/keys/ + From e0f787f0cb651382a8d214ad7f0be149bcb2b240 Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Fri, 5 Aug 2016 20:37:52 -0700 Subject: [PATCH 105/708] Fix links to devel and user key messages --- installing/verifying-signatures.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/installing/verifying-signatures.md b/installing/verifying-signatures.md index 214cf878..833642a2 100644 --- a/installing/verifying-signatures.md +++ b/installing/verifying-signatures.md @@ -86,8 +86,8 @@ Signing Key here in this document: uid Qubes Master Signing Key There should also be a copy of this key at the project's main website, in the -[Qubes Security Pack], and in the archives of the project's [developer] and -[user] [mailing lists]. +[Qubes Security Pack], and in the archives of the project's +[developer][devel-master-key-msg] and [user][user-master-key-msg] [mailing lists]. Once you have obtained the Qubes Master Signing Key, you should verify the fingerprint of this key very carefully by obtaining @@ -295,8 +295,8 @@ To verify a signature on a git tag, you can use: [Qubes Master Signing Key]: https://keys.qubes-os.org/keys/qubes-master-signing-key.asc [keyserver]: https://en.wikipedia.org/wiki/Key_server_%28cryptographic%29#Keyserver_examples [Qubes Security Pack]: /doc/security-pack/ -[developer]: https://groups.google.com/forum/#!msg/qubes-devel/RqR9WPxICwg/kaQwknZPDHkJ -[user]: https://groups.google.com/d/msg/qubes-users/CLnB5uFu_YQ/ZjObBpz0S9UJ +[devel-master-key-msg]: https://groups.google.com/d/msg/qubes-devel/RqR9WPxICwg/kaQwknZPDHkJ +[user-master-key-msg]: https://groups.google.com/d/msg/qubes-users/CLnB5uFu_YQ/ZjObBpz0S9UJ [mailing lists]: /mailing-lists/ [Release 3 Signing Key]: https://keys.qubes-os.org/keys/qubes-release-3-signing-key.asc [Qubes OS Keyserver]: https://keys.qubes-os.org/keys/ From 1cc40df1c08930d997eaa9e2e911345a6f34b2c4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Marczykowski-G=C3=B3recki?= Date: Sat, 6 Aug 2016 17:11:26 +0200 Subject: [PATCH 106/708] Update vm-interface page --- debugging/vm-interface.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/debugging/vm-interface.md b/debugging/vm-interface.md index 7f801102..6332b7b4 100644 --- a/debugging/vm-interface.md +++ b/debugging/vm-interface.md @@ -15,7 +15,7 @@ VM Configuration Interface Qubes VM have some settings set by dom0 based on VM settings. There are multiple configuration channels, which includes: - XenStore -- QubesDB - replacing most of xenstore (in R3 only) +- QubesDB - replacing most of xenstore (in R3 or later) - Qubes RPC (called at VM startup, or when configuration changed) - GUI protocol @@ -26,6 +26,10 @@ Keys exposed by dom0 to VM (only Qubes specific included): - `qubes-vm-type` - VM type, the same as `type` field in `qvm-prefs`. One of `AppVM`, `ProxyVM`, `NetVM`, `TemplateVM`, `HVM`, `TemplateHVM` - `qubes-vm-updatable` - flag whether VM is updatable (whether changes in root.img will survive VM restart). One of `True`, `False` +- `qubes-vm-persistence` - what data do persist between VM restarts: + - `full` - all disks + - `rw-only` - only `/rw` disk + - `none` - none - `qubes-timezone - name of timezone based on dom0 timezone. For example `Europe/Warsaw` - `qubes-keyboard` - keyboard layout based on dom0 layout. Its syntax is suitable for `xkbcomp` command (after expanding escape sequences like `\n` or `\t`). This is meant only as some default value, VM can ignore this option and choose its own keyboard layout (this is what keyboard setting from Qubes Manager does). This entry is created as part of gui-daemon initialization (so not available when gui-daemon disabled, or not started yet). - `qubes-debug-mode` - flag whether VM have debug mode enabled (qvm-prefs setting). One of `1`, `0` @@ -55,7 +59,7 @@ Qubes RPC Services called by dom0 to provide some VM configuration: -- `qubes.SetMonitorLayout` - provide list of monitors, one in a line, each line contains four numbers: `width height X Y` +- `qubes.SetMonitorLayout` - provide list of monitors, one in a line, each line contains four numbers: `width height X Y width_mm height_mm` (physical dimensions - `width_mm` and `height_mm` - are optional) - `qubes.WaitForSession` - called to wait for full VM startup - `qubes.GetAppmenus` - receive appmenus from given VM (template); TODO: describe format here - `qubes.GetImageRGBA` - receive image/application icon. Protocol: From 4e4ecad0becf663ab2904c58f51d27bea34cb2b8 Mon Sep 17 00:00:00 2001 From: crat0z Date: Mon, 8 Aug 2016 16:47:35 -0400 Subject: [PATCH 107/708] Add Dom0 prompt for root in Debian/Whonix VMs --- security/vm-sudo.md | 21 ++++++++++++++++++++- 1 file changed, 20 insertions(+), 1 deletion(-) diff --git a/security/vm-sudo.md b/security/vm-sudo.md index d632c643..f4677a58 100644 --- a/security/vm-sudo.md +++ b/security/vm-sudo.md @@ -104,7 +104,7 @@ While ITL still supports the statement above, some Qubes users may want to enabl (Note: any VMs you would like still to have password-less root access (e.g. TemplateVMs) can be specified in the second file with "\ dom0 allow") -2. Configuring TemplateVM to prompt Dom0 for any authorization request: +2. a) Configuring Fedora TemplateVM to prompt Dom0 for any authorization request: - In /etc/pam.d/system-auth, replace all lines beginning with "auth" with one line: auth [success=done default=die] pam_exec.so seteuid /usr/lib/qubes/qrexec-client-vm dom0 qubes.VMAuth /usr/bin/grep -q ^1$ @@ -118,6 +118,25 @@ While ITL still supports the statement above, some Qubes users may want to enabl [root@fedora-20-x64]# rm /etc/polkit-1/rules.d/00-qubes-allow-all.rules [root@fedora-20-x64]# rm /etc/polkit-1/localauthority/50-local.d/qubes-allow-all.pkla +2. b) Configuring Debian/Whonix TemplateVM to prompt Dom0 for any authorization request: + - In /etc/pam.d/common-auth, replace all lines beginning with "auth" with one line: + + auth [success=done default=die] pam_exec.so seteuid /usr/lib/qubes/qrexec-client-vm dom0 qubes.VMAuth /bin/grep -q ^1$ + + - Require authentication for sudo. Replace the first line of /etc/sudoers.d/qubes with: + + user ALL=(ALL) ALL + + - Disable PolKit's default-allow behavior: + + [root@debian-8]# rm /etc/polkit-1/rules.d/00-qubes-allow-all.rules + [root@debian-8]# rm /etc/polkit-1/localauthority/50-local.d/qubes-allow-all.pkla + + - In /etc/pam.d/su, comment out this line near the bottom of the file: + + auth sufficient pam_permit.so + + Dom0 password-less root access ------------------------------ From bc2ac3609e8b0a31fc8c158d40290939e98666a5 Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Tue, 9 Aug 2016 10:19:43 -0700 Subject: [PATCH 108/708] Add Release 3.2 entry --- installing/supported-versions.md | 1 + 1 file changed, 1 insertion(+) diff --git a/installing/supported-versions.md b/installing/supported-versions.md index a68399c0..dfe3d4d0 100644 --- a/installing/supported-versions.md +++ b/installing/supported-versions.md @@ -27,6 +27,7 @@ All available current and past downloads can be found [here](/downloads/). | Release 2 | 2014-09-26 | 2016-04-01 | Old, unsupported | | Release 3.0 | 2015-10-01 | 2016-09-09 | Old, supported | | Release 3.1 | 2016-03-09 | TBA | Current, supported | +| Release 3.2 | TBA | TBA | In testing | | Release 4.0 | TBA | TBA | In development | From a1b244d17071eafd5d5770b1c11b781fe9d7b320 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Marczykowski-G=C3=B3recki?= Date: Tue, 9 Aug 2016 20:39:13 +0200 Subject: [PATCH 109/708] upgrade-to-r3.2: one more package to download manually on Debian updatevm It's lvm2 this time. --- installing/upgrade/upgrade-to-r3.2.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/installing/upgrade/upgrade-to-r3.2.md b/installing/upgrade/upgrade-to-r3.2.md index 2f281f98..a9796b6b 100644 --- a/installing/upgrade/upgrade-to-r3.2.md +++ b/installing/upgrade/upgrade-to-r3.2.md @@ -40,11 +40,11 @@ Upgrading dom0 you need to download few more packages manually, but **do not install them** yet: - sudo qubes-dom0-update systemd-compat-libs perl-libwww-perl perl-Term-ANSIColor perl-Term-Cap gdk-pixbuf2-xlib speexdsp qubes-mgmt-salt-admin-tools + sudo qubes-dom0-update systemd-compat-libs perl-libwww-perl perl-Term-ANSIColor perl-Term-Cap gdk-pixbuf2-xlib speexdsp qubes-mgmt-salt-admin-tools lvm2 (...) Transaction Summary =============================================================== - Install 15 Packages (+ 31 Dependent packages) + Install 16 Packages (+ 31 Dependent packages) Upgrade 4 Packages (+200 Dependent packages) Total download size: 173 M From 073f12fc94da2e91ff9fbcc8e99a3fdc7342e6fe Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Wed, 10 Aug 2016 00:52:22 -0700 Subject: [PATCH 110/708] Add table showing dom0 OS used in each release --- installing/supported-versions.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/installing/supported-versions.md b/installing/supported-versions.md index dfe3d4d0..4437f52b 100644 --- a/installing/supported-versions.md +++ b/installing/supported-versions.md @@ -31,6 +31,20 @@ All available current and past downloads can be found [here](/downloads/). | Release 4.0 | TBA | TBA | In development | +Dom0 +---- +The table below shows the OS used for dom0 in each Qubes OS release. + +| Qubes OS Version | Dom0 OS | +| ---------------- | --------- | +| Release 1 | Fedora 13 | +| Release 2 | Fedora 18 | +| Release 3.0 | Fedora 20 | +| Release 3.1 | Fedora 20 | +| Release 3.2 | Fedora 23 | +| Release 4.0 | TBA | + + Templates --------- The table below shows the [template](/doc/templates/) versions supported by each From 43b6abb1062e56680031680b641a17192ad551da Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Wed, 10 Aug 2016 01:04:47 -0700 Subject: [PATCH 111/708] Revise text * Explain ISO availability and add link to FTP subdomain * "template" -> "TemplateVM" * Use reference-style links --- installing/supported-versions.md | 20 +++++++++++++------- 1 file changed, 13 insertions(+), 7 deletions(-) diff --git a/installing/supported-versions.md b/installing/supported-versions.md index 4437f52b..05f0c906 100644 --- a/installing/supported-versions.md +++ b/installing/supported-versions.md @@ -18,8 +18,9 @@ Supported Versions Qubes OS -------- Qubes OS releases are supported for **six months** after each subsequent major -or minor release. The version scheme is explained [here](/doc/version-scheme/). -All available current and past downloads can be found [here](/downloads/). +or minor release (see [Version Scheme]). The current release and past major +releases are always available on the [Downloads] page, while all ISOs, including +past minor releases, are available from our [FTP server]. | Qubes OS Version | Start Date | End Date | Status | | ---------------- | ---------- | ---------- | --------------------------- | @@ -45,11 +46,10 @@ The table below shows the OS used for dom0 in each Qubes OS release. | Release 4.0 | TBA | -Templates ---------- -The table below shows the [template](/doc/templates/) versions supported by each -Qubes OS release. Currently, only Fedora and Debian templates are officially -supported. +TemplateVMs +----------- +The table below shows the [TemplateVM] versions supported by each Qubes OS +release. Currently, only Fedora and Debian TemplateVMs are officially supported. | Qubes OS Version | Fedora Versions | Debian Versions | | ---------------- | --------------- | --------------------------------------------- | @@ -63,3 +63,9 @@ supported. \* Denotes versions for which we have published the packages but have not done extensive testing. + +[Version Scheme]: /doc/version-scheme/ +[Downloads]: /downloads/ +[FTP server]: https://ftp.qubes-os.org/ +[TemplateVM]: /doc/templates/ + From ad048f147a969cc3c20241c47392548f64973dbd Mon Sep 17 00:00:00 2001 From: acarlisle28 Date: Wed, 10 Aug 2016 15:44:41 +0100 Subject: [PATCH 112/708] Update archlinux.md Because "thru" = "through," sorry to be a GN --- managing-os/templates/archlinux.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/managing-os/templates/archlinux.md b/managing-os/templates/archlinux.md index f9c0bcba..636ce1aa 100644 --- a/managing-os/templates/archlinux.md +++ b/managing-os/templates/archlinux.md @@ -23,7 +23,7 @@ Main maintainer of this template is [Olivier Médoc](mailto:o_medoc@yahoo.fr). ## Instructions ##
-**These are the instructions for Qubes 3.1. They will take you step by step thru the entire process start to finish** +**These are the instructions for Qubes 3.1. They will take you step by step through the entire process start to finish** *Note: Currently there are no binary packages and it must be compiled from source using the instructions below.* @@ -388,7 +388,7 @@ Please check out: [XYNE's (dev) Powerpill](http://xyne.archlinux.ca/projects/powerpill/) -**Important Note:** Until Powerpill is configured you will have to open network access to the template to get the initial packages etc downloaded. You can use the "allow full access for" a given time period in the FW settings of the template in the VMM or open up the various services thru the same window. Remember to change it back if you choose the later route. Actions needing network access will be noted with (needs network access) +**Important Note:** Until Powerpill is configured you will have to open network access to the template to get the initial packages etc downloaded. You can use the "allow full access for" a given time period in the FW settings of the template in the VMM or open up the various services through the same window. Remember to change it back if you choose the later route. Actions needing network access will be noted with (needs network access)

@@ -676,9 +676,9 @@ Note: For info on Reflector and its configs: [Reflector](https://wiki.archlinux. * There May also be a similar issue of dependencies with Xorg. -* Upgrade Relfector functionality to allow its use thru the QUPS +* Upgrade Relfector functionality to allow its use through the QUPS -* Pacman functionality changes and allows it to be directly configured to work thru QUPS. +* Pacman functionality changes and allows it to be directly configured to work through QUPS.
From d900d3b4b888499e605e3c9845bd403c942712de Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Wed, 10 Aug 2016 10:10:19 -0700 Subject: [PATCH 113/708] Add section on installing KDE (R3.2 and later) --- customization/kde.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/customization/kde.md b/customization/kde.md index bbba0dcf..c471bb90 100644 --- a/customization/kde.md +++ b/customization/kde.md @@ -8,6 +8,16 @@ redirect_from: /en/doc/kde/ Using KDE in dom0 ================= +Installation +------------ + +Prior to R3.2, KDE was the default desktop environment in Qubes. Beginning with +R3.2, however, XFCE is the new default desktop environment. Nonetheless, it is +still possible to install KDE by issuing this command in dom0: + + $ sudo qubes-dom0-update @kde-desktop-qubes + + Window Management ----------------- From 45b2ccc7b03d8feda7326d06eadaa111803b0321 Mon Sep 17 00:00:00 2001 From: John Bernard Date: Mon, 15 Aug 2016 11:50:11 -0500 Subject: [PATCH 114/708] Fix broken link The URL https://www.networkworld.com/news/2007/080207-black-hat-virtual-machine-rootkit-detection.html is a broken link -- presenting an error "Page not found" upon request. However, there exists an archive of this article on archive.org, and I have updated the URL to point to the archive. --- security/security-guidelines.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/security/security-guidelines.md b/security/security-guidelines.md index e955c986..42d0a3f7 100644 --- a/security/security-guidelines.md +++ b/security/security-guidelines.md @@ -105,7 +105,7 @@ Assigning USB keyboard will **deprive Dom0 VM of a keyboard**. Since a USB contr But **if you need to use a USB keyboard or mouse**, identify the USB controller in which you have your keyboard/mouse plugged in and do NOT assign it to a VM. Also makes sure you know all the other USB ports for that controller, and use them carefully, with the knowledge **you are exposing Dom0** (ie NO bluetooth device on it). -All USB devices should be assumed as **side channel attack vectors** (mic via sound), others via power usage so user may prefer to remove them. [See this about rootkits](https://www.networkworld.com/news/2007/080207-black-hat-virtual-machine-rootkit-detection.html) +All USB devices should be assumed as **side channel attack vectors** (mic via sound), others via power usage so user may prefer to remove them. [See this about rootkits](https://web.archive.org/web/20070829112704/http://www.networkworld.com/news/2007/080207-black-hat-virtual-machine-rootkit-detection.html) The **web-cam** also may involve a risk, so better to physically cover it with a adhesive tape if you do not use it. If you need it, you have **to assign it to a VM** and cover it with a cap or an elastic band when not in use. Attaching a **microphone** using Qubes VM Manager also may be risky, so attach it only when required. From 315ce7b7fc72190d442eb546737eaedd9b929b5c Mon Sep 17 00:00:00 2001 From: Andrew Date: Mon, 15 Aug 2016 15:48:05 -0400 Subject: [PATCH 115/708] Same issue for thinkpad x200 I updated the document to show that the Thinkpad X200 also has the same issue. Small edit: line 14 changed 'VT-D' to 'VT-d' for consistency. --- troubleshooting/thinkpad_x201.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/troubleshooting/thinkpad_x201.md b/troubleshooting/thinkpad_x201.md index 5ee5fd6d..37931d3a 100644 --- a/troubleshooting/thinkpad_x201.md +++ b/troubleshooting/thinkpad_x201.md @@ -1,6 +1,6 @@ --- layout: doc -title: Getting Lenovo Thinkpad X201 to work +title: Getting Lenovo Thinkpad X201 & X200 to work permalink: /doc/thinkpad_x201/ redirect_from: - /en/doc/thinkpad_x201/ @@ -8,10 +8,10 @@ redirect_from: - /wiki/Thinkpad_X201/ --- -Instructions for getting your Lenovo Thinkpad X201 laptop working with Qubes/Linux +Instructions for getting your Lenovo Thinkpad X201 & X200 laptop working with Qubes/Linux ========================================================================= -For being able to boot the installer from USB, you have to disable VT-D in the BIOS. +For being able to boot the installer from USB, you have to disable VT-d in the BIOS. Enter the BIOS by hitting F1, go to Config - CPU and then disable there VT-d. After the installation, you have to set a startup-parameter for Xen, to be able to activate VT-d again: From c46cd728cc71706b6c3e867331255c0e1a52f9e8 Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Mon, 15 Aug 2016 18:42:35 -0700 Subject: [PATCH 116/708] Update with link to Windows-based AppVMs page --- managing-os/hvm.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/managing-os/hvm.md b/managing-os/hvm.md index 2f2fc478..3017ae9c 100644 --- a/managing-os/hvm.md +++ b/managing-os/hvm.md @@ -94,7 +94,7 @@ Now, one should configure the networking within the HVM according to those setti Using Template-based HVM domains -------------------------------- -TODO (Coming in Qubes R2 beta 3). +Please see our dedicated page on [installing and using Windows-based AppVMs](/doc/windows-appvms/). Cloning HVM domains ------------------- From cce10079b322f8e898cb2b4e23b48c4886aac4d9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Marczykowski-G=C3=B3recki?= Date: Wed, 17 Aug 2016 01:01:42 +0200 Subject: [PATCH 117/708] qrexec: add info about new DispVM options in Qubes 4.0 --- services/qrexec3.md | 35 +++++++++++++++++++++++++++++++---- 1 file changed, 31 insertions(+), 4 deletions(-) diff --git a/services/qrexec3.md b/services/qrexec3.md index 62cb43d9..d1aa3edb 100644 --- a/services/qrexec3.md +++ b/services/qrexec3.md @@ -127,10 +127,12 @@ means "new VM created for this particular request," so it is never a source of request). Currently there is no way to specify source VM by type. Whenever a rpc request for action X is received, the first line in `/etc/qubes-rpc/policy/X` that match srcvm/destvm is consulted to determine -whether to allow rpc, what user account the program should run in target -VM under, and what VM to redirect the execution to. If the policy file does -not exits, user is prompted to create one; if still there is no policy file -after prompting, the action is denied. +whether to allow rpc, what user account the program should run in target VM +under, and what VM to redirect the execution to. Note that if the request is +redirected (`target=` parameter), policy action remains the same - even if +there is another rule which would otherwise deny such request. If the policy +file does not exits, user is prompted to create one; if still there is no +policy file after prompting, the action is denied. In the target VM, the `/etc/qubes-rpc/RPC_ACTION_NAME` must exist, containing the file name of the program that will be invoked, or being that program itself @@ -156,6 +158,31 @@ be fatal to Qubes security. On the other hand, this mechanism allows to delegate processing of untrusted input to less privileged (or throwaway) AppVMs, thus wise usage of it increases security. +### Extra keywords available in Qubes 4.0 and later + +**This section is about not yet released version, some details may change** + +In Qubes 4.0, target VM can be specified also as `$dispvm:DISP_VM`, which is +very similar to `$dispvm` but force using particular VM (`DISP_VM`) as a base +VM to be started as Disposable VM. For example: + + anon-whonix $dispvm:anon-whonix-dvm allow + +Adding such policy itself will not force usage of this particular `DISP_VM` - +it will only allow it when specified by the caller. But `$dispvm:DISP_VM` can +also be used as target in request redirection, so _it is possible_ to force +particular `DISP_VM` usage, when caller didn't specified it: + + anon-whonix $dispvm allow,target=$dispvm:anon-whonix-dvm + +Note that without redirection, this rule would allow using default Disposable +VM (`default_dispvm` VM property, which itself defaults to global +`default_dispvm` property). +Also note that the request will be allowed (`allow` action) even if there is no +second rule allowing calls to `$dispvm:anon-whonix-dvm`, or even if +there is a rule explicitly denying it. This is because the redirection happen +_after_ considering the action. + ### Service argument in policy Sometimes just service name isn't enough to make reasonable qrexec policy. One From d8634ac814b9f5424da23ff49816b564352b6de3 Mon Sep 17 00:00:00 2001 From: Valentin Lorentz Date: Fri, 19 Aug 2016 19:56:24 +0200 Subject: [PATCH 118/708] =?UTF-8?q?Fix=20broken=20link=20to=20=E2=80=9CCom?= =?UTF-8?q?pacting=20templates=20root.img=E2=80=9D.?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- common-tasks/software-update-vm.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/common-tasks/software-update-vm.md b/common-tasks/software-update-vm.md index 12e8866b..235bd062 100644 --- a/common-tasks/software-update-vm.md +++ b/common-tasks/software-update-vm.md @@ -22,7 +22,7 @@ The default template is called **fedora-14-x64** in Qubes R1 and **fedora-20-x64 The side effect of this mechanism is, of course, that if you install any software in your AppVM, more specifically in any directory other than `/home` or `/usr/local` then it will disappear after the AppVM reboot (as the root filesystem for this AppVM will again be "taken" from the Template VM). **This means one normally install software in the Template VM, not in AppVMs.** -Unlike VM private filesystems, the template VM root filesystem does not support discard, so deleting files does not free the space in dom0. See [these instructions](/doc/FedoraTemplateUpgrade/#compacting-templates-rootimg) to recover space in dom0. +Unlike VM private filesystems, the template VM root filesystem does not support discard, so deleting files does not free the space in dom0. See [these instructions](/doc/fedora-template-upgrade-18/#compacting-templates-rootimg) to recover space in dom0. Installing (or updating) software in the template VM ---------------------------------------------------- From 182d1dff0fc6df369fd3a4aa14ea541f61b7fa78 Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Fri, 19 Aug 2016 11:02:10 -0700 Subject: [PATCH 119/708] Use instructions for latest stable, supported template --- common-tasks/software-update-vm.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/common-tasks/software-update-vm.md b/common-tasks/software-update-vm.md index 235bd062..44f125fa 100644 --- a/common-tasks/software-update-vm.md +++ b/common-tasks/software-update-vm.md @@ -22,7 +22,7 @@ The default template is called **fedora-14-x64** in Qubes R1 and **fedora-20-x64 The side effect of this mechanism is, of course, that if you install any software in your AppVM, more specifically in any directory other than `/home` or `/usr/local` then it will disappear after the AppVM reboot (as the root filesystem for this AppVM will again be "taken" from the Template VM). **This means one normally install software in the Template VM, not in AppVMs.** -Unlike VM private filesystems, the template VM root filesystem does not support discard, so deleting files does not free the space in dom0. See [these instructions](/doc/fedora-template-upgrade-18/#compacting-templates-rootimg) to recover space in dom0. +Unlike VM private filesystems, the template VM root filesystem does not support discard, so deleting files does not free the space in dom0. See [these instructions](/doc/fedora-template-upgrade-21/#compacting-the-upgraded-template) to recover space in dom0. Installing (or updating) software in the template VM ---------------------------------------------------- From 000997da5387537bd063bc8f4cd24ca0a69cca12 Mon Sep 17 00:00:00 2001 From: JeremyRand Date: Sun, 21 Aug 2016 01:10:07 +0000 Subject: [PATCH 120/708] Fix typo in "encryption config" docs. --- installing/encryption-config.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/installing/encryption-config.md b/installing/encryption-config.md index cbeb655b..3aedaeb2 100644 --- a/installing/encryption-config.md +++ b/installing/encryption-config.md @@ -17,7 +17,7 @@ configure the encryption options while installing Qubes as follows: 01. Boot into the installer. Wait for first GUI screen to appear where it asks about language/localization . 02. Press `Ctrl+Alt+F2` on your keyboard to escape to a shell session. (If you - are on a laptop, and your laptop keyboard des not work properly, you may have + are on a laptop, and your laptop keyboard does not work properly, you may have to plug in a USB keyboard.) 03. Check and adjust the partitioning on the drive you plan to install to with `parted`. For example, you can leave the partition table as `msdos/MBR` type, From bfec50ea3db7d9fb97e0ebdb96e1d5fa50a7966e Mon Sep 17 00:00:00 2001 From: timove Date: Tue, 23 Aug 2016 21:48:29 +0200 Subject: [PATCH 121/708] fixed a typo in reinstall-template.md --- managing-os/reinstall-template.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/managing-os/reinstall-template.md b/managing-os/reinstall-template.md index 975cbd39..d41391f6 100644 --- a/managing-os/reinstall-template.md +++ b/managing-os/reinstall-template.md @@ -12,7 +12,7 @@ How to Reinstall a TemplateVM If you suspect your [TemplateVM] is broken, misconfigured, or compromised, or if you wish to do a clean reinstall in order to upgrade to a new version, you can reinstall any TemplateVM from the Qubes repository. In what follows, the -phrase "target TemplateVM" refers to whichever TemplateVM you want to reinsatll. +phrase "target TemplateVM" refers to whichever TemplateVM you want to reinstall. If you want to reinstall more than one TemplateVM, repeat these instructions for each one. From 045cc661546edc397274bccfdb3cf7b285001883 Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Wed, 24 Aug 2016 14:59:14 -0700 Subject: [PATCH 122/708] Create Signal guide --- privacy/signal.md | 79 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 79 insertions(+) create mode 100644 privacy/signal.md diff --git a/privacy/signal.md b/privacy/signal.md new file mode 100644 index 00000000..b8f74c63 --- /dev/null +++ b/privacy/signal.md @@ -0,0 +1,79 @@ +--- +layout: doc +title: Signal +permalink: /doc/signal/ +--- + +Signal +====== + +What is [Signal]? + +[According to Wikipedia:][signal-wikipedia] + +> Signal is an encrypted instant messaging and voice calling application +> for Android and iOS. It uses end-to-end encryption to secure all +> communications to other Signal users. Signal can be used to send and receive +> encrypted instant messages, group messages, attachments and media messages. +> Users can independently verify the identity of their messaging correspondents +> by comparing key fingerprints out-of-band. During calls, users can check the +> integrity of the data channel by checking if two words match on both ends of +> the call. +> +> Signal is developed by Open Whisper Systems. The clients are published as free +> and open-source software under the GPLv3 license. + +How to install Signal in Qubes +------------------------------ + +If you're a Signal user on Android, you can now have Signal inside Qubes. + +1. Install the Chromium browser in a TemplateVM. +2. Shut down the TemplateVM. +3. Create a new AppVM based on this TemplateVM. +4. Launch Chromium browser in the new AppVM, type `chrome://extensions/` in the + address bar, and follow the link to the Chrome app store. +4. In the app store, search for "Signal Private Messenger" and install the app. +5. The app launches automatically on first install. Follow the prompts to "link" + this app with your phone. +6. Signal should now work in your AppVM. + +Creating a Shortcut in KDE +-------------------------- + +Let's make Signal a bit more usable by creating a shortcut in our desktop +panel that launches Signal directly. This assumes that you're using KDE in Dom0 +and that your AppVM is named `Signal`. + +1. Create a Chromium shortcut (Q -> Domain: Signal -> Signal: Add more + shortcuts... -> Select "Chromium web browser") +2. Follow [these instructions][shortcut] to create a desktop shortcut. +3. Right-click on Chromium icon in panel and select "Icon Settings". +4. Change the "Command" field of the "Application" tab to: + + qvm-run -a --tray Signal '/usr/lib64/chromium-browser/chromium-browser.sh --profile-directory=Default --app-id=' + + **Note:** Another method (more "correct" but less straightforward) is to [use + the way Qubes handles shortcuts internally to create a `.desktop` + file][shortcut-desktop]. +5. (Optional) Copy the Signal app icon file from the Signal AppVM to dom0. + (**Warning**: copying untrusted files to dom0 is dangerous! Do this only if + you understand and accept the risks!) + + [user@dom0]$ qvm-run --pass-io Signal 'cat /home/user/.local/share/icons/hicolor/48x48/apps/chrome--Default.png' > /home/users/signal-icon.png +6. (Optional) Change your new shortcut's icon from Chrome to Signal by pointing + it to `/home/users/signal-icon.png`. + +----- + +These instructions were contributed by Qubes community member Alex (IX4 Svs) in +a [message] to the `qubes-users` [mailing list]. Thanks, Alex! + + +[Signal]: https://whispersystems.org/ +[signal-wikipedia]: https://en.wikipedia.org/wiki/Signal_(software) +[shortcut]: http://support.whispersystems.org/hc/en-us/articles/216839277-Where-is-Signal-Desktop-on-my-computer- +[shortcut-desktop]: /doc/managing-appvm-shortcuts/#tocAnchor-1-1-1 +[message]: https://groups.google.com/d/msg/qubes-users/rMMgeR-KLbU/XXOFri26BAAJ +[mailing list]: /mailing-lists/ + From 642098d4ac994f9488bdd38710a1266e9125c086 Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Wed, 24 Aug 2016 14:59:44 -0700 Subject: [PATCH 123/708] Add Signal guide to index --- doc.md | 1 + 1 file changed, 1 insertion(+) diff --git a/doc.md b/doc.md index ead50d1f..7764b428 100644 --- a/doc.md +++ b/doc.md @@ -108,6 +108,7 @@ Privacy Guides * [Anonymizing your MAC Address](/doc/anonymizing-your-mac-address/) * [TorVM](/doc/torvm/) * [Martus](/doc/martus/) + * [Martus](/doc/signal/) Configuration Guides From 2bf9ae2aec8f278ef3db331c10f013dfbe20fd8b Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Wed, 24 Aug 2016 15:01:49 -0700 Subject: [PATCH 124/708] Fix typo --- doc.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc.md b/doc.md index 7764b428..39c2dd84 100644 --- a/doc.md +++ b/doc.md @@ -108,7 +108,7 @@ Privacy Guides * [Anonymizing your MAC Address](/doc/anonymizing-your-mac-address/) * [TorVM](/doc/torvm/) * [Martus](/doc/martus/) - * [Martus](/doc/signal/) + * [Signal](/doc/signal/) Configuration Guides From 55aa8be670698a33d548ad66da65290654b858e7 Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Fri, 26 Aug 2016 23:58:02 -0700 Subject: [PATCH 125/708] Strengthen disclaimer; clean up text and formatting --- security/vm-sudo.md | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) diff --git a/security/vm-sudo.md b/security/vm-sudo.md index f4677a58..7449654f 100644 --- a/security/vm-sudo.md +++ b/security/vm-sudo.md @@ -95,16 +95,21 @@ Below is a complete list of configuration made according to the above statement, Replacing password-less root access with Dom0 user prompt --------------------------------------------------------- -While ITL still supports the statement above, some Qubes users may want to enable user/root isolation in VMs anyway. We do not support it in any of our packages, but of course nothing can stop the user from making some modifications his or her own system. A list of steps to do so is provided here without guarantee of completeness (read: **do not rely on this for extra security**): +While ITL supports the statement above, some Qubes users may wish to enable +user/root isolation in VMs anyway. We do not support it in any of our packages, +but of course nothing is preventing the user from modifying his or her own +system. A list of steps to do so is provided here **without any guarantee of +safety, accuracy, or completeness. Proceed at your own risk. Do not rely on +this for extra security.** -1. Adding Dom0 "VMAuth" service: +1. Adding Dom0 "VMAuth" service: [root@dom0 /]# echo -n "/usr/bin/echo 1" >/etc/qubes-rpc/qubes.VMAuth [root@dom0 /]# echo -n "$anyvm dom0 ask" >/etc/qubes-rpc/policy/qubes.VMAuth - (Note: any VMs you would like still to have password-less root access (e.g. TemplateVMs) can be specified in the second file with "\ dom0 allow") + (Note: any VMs you would like still to have password-less root access (e.g. TemplateVMs) can be specified in the second file with "\ dom0 allow") -2. a) Configuring Fedora TemplateVM to prompt Dom0 for any authorization request: +2. Configuring Fedora TemplateVM to prompt Dom0 for any authorization request: - In /etc/pam.d/system-auth, replace all lines beginning with "auth" with one line: auth [success=done default=die] pam_exec.so seteuid /usr/lib/qubes/qrexec-client-vm dom0 qubes.VMAuth /usr/bin/grep -q ^1$ @@ -118,7 +123,7 @@ While ITL still supports the statement above, some Qubes users may want to enabl [root@fedora-20-x64]# rm /etc/polkit-1/rules.d/00-qubes-allow-all.rules [root@fedora-20-x64]# rm /etc/polkit-1/localauthority/50-local.d/qubes-allow-all.pkla -2. b) Configuring Debian/Whonix TemplateVM to prompt Dom0 for any authorization request: +3. Configuring Debian/Whonix TemplateVM to prompt Dom0 for any authorization request: - In /etc/pam.d/common-auth, replace all lines beginning with "auth" with one line: auth [success=done default=die] pam_exec.so seteuid /usr/lib/qubes/qrexec-client-vm dom0 qubes.VMAuth /bin/grep -q ^1$ From c2a78ccbe2279971fbb6ecf9db9e4ed13000fe26 Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Sat, 27 Aug 2016 22:28:49 -0700 Subject: [PATCH 126/708] Update GRUB menu step https://groups.google.com/d/msg/qubes-users/FbLWKeD7ddc/Adi3j7xcAQAJ --- troubleshooting/uefi-troubleshooting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/troubleshooting/uefi-troubleshooting.md b/troubleshooting/uefi-troubleshooting.md index 25d0c5b7..137dff13 100644 --- a/troubleshooting/uefi-troubleshooting.md +++ b/troubleshooting/uefi-troubleshooting.md @@ -13,7 +13,7 @@ Cannot start installation, hangs at four penguins after choosing "Test media and There is some [common bug in UEFI implementation](http://xen.markmail.org/message/f6lx2ab4o2fch35r), affecting mostly Lenovo systems, but probably some others too. You can try existing workaround: -01. In GRUB menu[1](#f1) press `e`. +01. In GRUB menu[1](#f1), select "Troubleshoot", then "Boot from device", then press `e`. 02. At the end of `chainloader` line add `/mapbs /noexitboot`. 03. Perform installation normally, but not reboot system at the end yet. 04. Go to `tty2` (Ctrl-Alt-F2). From 04b6bbc4832937ad179210eaa440a5370ba48992 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rafa=C5=82=20Wojdy=C5=82a?= Date: Wed, 31 Aug 2016 17:05:46 +0200 Subject: [PATCH 127/708] QWT installation: change order of operation to be more natural --- managing-os/windows-appvms.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/managing-os/windows-appvms.md b/managing-os/windows-appvms.md index ab46af5d..7945a2c5 100644 --- a/managing-os/windows-appvms.md +++ b/managing-os/windows-appvms.md @@ -51,6 +51,8 @@ sudo qubes-dom0-update --enablerepo=qubes-dom0-current-testing qubes-windows-too This package brings the ISO with Qubes Windows Tools that is passed to the VM when `--install-windows-tools` is specified for the `qvm-start` command. Please note that none of this software ever runs in Dom0 or any other part of the system except for the Windows AppVM in which it is to be installed. +Before proceeding with the installation we need to disable Windows mechanism that allows only signed drivers to be installed, because currently (beta releases) the drivers we provide as part of the Windows Tools are not digitally signed with a publicly recognizable certificate. How to do that is explained in the `README` file also located on the installation CDROM. In the future this step will not be necessary anymore, because we will sign our drivers with a publicly verifiable certificate. However, it should be noted that even now, the fact that those drivers are not digitally signed, this doesn't affect security of the Windows VM in 'any' way. This is because the actual installation ISO (the `qubes-windows-tools-*.iso` file) is distributed as a signed RPM package and its signature is verified by the `qubes-dom0-update` utility once it's being installed in Dom0. The only downside of those drivers not being signed is the inconvenience to the user that he or she must disable the signature enforcement policy before installing the tools. + To install the Qubes Windows Tools in a Windows VM one should start the VM passing the additional option `--install-windows-tools`: ~~~ @@ -59,8 +61,6 @@ qvm-start lab-win7 --install-windows-tools Once the Windows VM boots, a CDROM should appear in the 'My Computer' menu (typically as `D:`) with a setup program in its main directory. -Before proceeding with the installation we need to disable Windows mechanism that allows only signed drivers to be installed, because currently (beta releases) the drivers we provide as part of the Windows Tools are not digitally signed with a publicly recognizable certificate. How to do that is explained in the `README` file also located on the installation CDROM. In the future this step will not be necessary anymore, because we will sign our drivers with a publicly verifiable certificate. However, it should be noted that even now, the fact that those drivers are not digitally signed, this doesn't affect security of the Windows VM in 'any' way. This is because the actual installation ISO (the `qubes-windows-tools-*.iso` file) is distributed as a signed RPM package and its signature is verified by the `qubes-dom0-update` utility once it's being installed in Dom0. The only downside of those drivers not being signed is the inconvenience to the user that he or she must disable the signature enforcement policy before installing the tools. - After successful installation, the Windows VM must be shut down and started again. Qubes (R2 Beta 3 and later releases) will automatically detect the tools has been installed in the VM and will set appropriate properties for the VM, such as `qrexec_installed`, `guiagent_installed`, and `default_user`. This can be verified (but is not required) using qvm-prefs command: From 12c36a002f9698f824b94375d95b7df5d432c805 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rafa=C5=82=20Wojdy=C5=82a?= Date: Wed, 31 Aug 2016 17:09:41 +0200 Subject: [PATCH 128/708] QWT installation: add explicit instructions for disabling driver signature enforcement --- managing-os/windows-appvms.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/managing-os/windows-appvms.md b/managing-os/windows-appvms.md index 7945a2c5..1574e390 100644 --- a/managing-os/windows-appvms.md +++ b/managing-os/windows-appvms.md @@ -51,7 +51,13 @@ sudo qubes-dom0-update --enablerepo=qubes-dom0-current-testing qubes-windows-too This package brings the ISO with Qubes Windows Tools that is passed to the VM when `--install-windows-tools` is specified for the `qvm-start` command. Please note that none of this software ever runs in Dom0 or any other part of the system except for the Windows AppVM in which it is to be installed. -Before proceeding with the installation we need to disable Windows mechanism that allows only signed drivers to be installed, because currently (beta releases) the drivers we provide as part of the Windows Tools are not digitally signed with a publicly recognizable certificate. How to do that is explained in the `README` file also located on the installation CDROM. In the future this step will not be necessary anymore, because we will sign our drivers with a publicly verifiable certificate. However, it should be noted that even now, the fact that those drivers are not digitally signed, this doesn't affect security of the Windows VM in 'any' way. This is because the actual installation ISO (the `qubes-windows-tools-*.iso` file) is distributed as a signed RPM package and its signature is verified by the `qubes-dom0-update` utility once it's being installed in Dom0. The only downside of those drivers not being signed is the inconvenience to the user that he or she must disable the signature enforcement policy before installing the tools. +Before proceeding with the installation we need to disable Windows mechanism that allows only signed drivers to be installed, because currently (beta releases) the drivers we provide as part of the Windows Tools are not digitally signed with a publicly recognizable certificate. To do that: + +- Start command prompt as Administrator, i.e. right click on the Command Prompt icon and choose "Run as administrator" +- In the command prompt type `bcdedit /set testsigning on` +- Reboot your Windows VM + +In the future this step will not be necessary anymore, because we will sign our drivers with a publicly verifiable certificate. However, it should be noted that even now, the fact that those drivers are not digitally signed, this doesn't affect security of the Windows VM in 'any' way. This is because the actual installation ISO (the `qubes-windows-tools-*.iso` file) is distributed as a signed RPM package and its signature is verified by the `qubes-dom0-update` utility once it's being installed in Dom0. The only downside of those drivers not being signed is the inconvenience to the user that he or she must disable the signature enforcement policy before installing the tools. To install the Qubes Windows Tools in a Windows VM one should start the VM passing the additional option `--install-windows-tools`: From 3755c5aa6659173d58f2bdad6e590b696e0050c4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rafa=C5=82=20Wojdy=C5=82a?= Date: Wed, 31 Aug 2016 17:16:51 +0200 Subject: [PATCH 129/708] QWT installation: add note about multiple reboots --- managing-os/windows-appvms.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/managing-os/windows-appvms.md b/managing-os/windows-appvms.md index 1574e390..0f8e26af 100644 --- a/managing-os/windows-appvms.md +++ b/managing-os/windows-appvms.md @@ -67,7 +67,7 @@ qvm-start lab-win7 --install-windows-tools Once the Windows VM boots, a CDROM should appear in the 'My Computer' menu (typically as `D:`) with a setup program in its main directory. -After successful installation, the Windows VM must be shut down and started again. +After successful installation, the Windows VM must be shut down and started again, possibly a couple of times (see [this page](/doc/WindowsTools/) for detailed configuration options). Qubes (R2 Beta 3 and later releases) will automatically detect the tools has been installed in the VM and will set appropriate properties for the VM, such as `qrexec_installed`, `guiagent_installed`, and `default_user`. This can be verified (but is not required) using qvm-prefs command: From 3d8346f42d272d9304843b01c6cd8fd25d0cf3dd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rafa=C5=82=20Wojdy=C5=82a?= Date: Wed, 31 Aug 2016 17:18:56 +0200 Subject: [PATCH 130/708] QWT installation: small clarification --- managing-os/windows-appvms.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/managing-os/windows-appvms.md b/managing-os/windows-appvms.md index 0f8e26af..82e3fa14 100644 --- a/managing-os/windows-appvms.md +++ b/managing-os/windows-appvms.md @@ -75,7 +75,7 @@ Qubes (R2 Beta 3 and later releases) will automatically detect the tools has bee qvm-prefs ~~~ -NOTE: it is recommended to increase the default value of `qrexec_timeout` property from 60 (seconds) to, for example, 300. During one of the first reboots after Windows Tools installation Windows user profiles are moved onto the private VM's virtual disk (private.img) and this operation can take some time. Moving profiles is performed in an early boot phase when qrexec is not yet running, so timeout may occur with the default value. To change the property use this command in dom0: +NOTE: it is recommended to increase the default value of Windows VM's `qrexec_timeout` property from 60 (seconds) to, for example, 300. During one of the first reboots after Windows Tools installation Windows user profiles are moved onto the private VM's virtual disk (private.img) and this operation can take some time. Moving profiles is performed in an early boot phase when qrexec is not yet running, so timeout may occur with the default value. To change the property use this command in dom0: ~~~ qvm-prefs -s qrexec_timeout 300 From 49b57d6b3e9dc3f7ee457ebd71513853ce26ac70 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rafa=C5=82=20Wojdy=C5=82a?= Date: Wed, 31 Aug 2016 17:31:05 +0200 Subject: [PATCH 131/708] QWT: add note about full desktop being the default mode --- managing-os/windows-appvms.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/managing-os/windows-appvms.md b/managing-os/windows-appvms.md index 82e3fa14..24cfea3e 100644 --- a/managing-os/windows-appvms.md +++ b/managing-os/windows-appvms.md @@ -110,10 +110,10 @@ To simulate CTRL-ALT-DELETE in the HVM (SAS, Secure Attention Sequence), press C ![windows-seamless-7.png](/attachment/wiki/WindowsAppVms/windows-seamless-7.png) -Forcing Windows AppVM into full desktop mode --------------------------------------------- +Changing between seamless and full desktop mode +----------------------------------------------- -You can switch between seamless and "full desktop" mode for Windows HVMs in their settings in Qubes Manager. +You can switch between seamless and "full desktop" mode for Windows HVMs in their settings in Qubes Manager. The latter is the default. Using template-based Windows AppVMs (Qubes R2 Beta 3 and later) --------------------------------------------------------------- From ce665ef013d19a539894efc39e740a5ec2337dbb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rafa=C5=82=20Wojdy=C5=82a?= Date: Wed, 31 Aug 2016 17:37:53 +0200 Subject: [PATCH 132/708] Windows templates: don't encourage totally disabling updates --- managing-os/windows-appvms.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/managing-os/windows-appvms.md b/managing-os/windows-appvms.md index 24cfea3e..73364f49 100644 --- a/managing-os/windows-appvms.md +++ b/managing-os/windows-appvms.md @@ -129,7 +129,7 @@ qvm-create --hvm-template win7-x64-template -l green - The private disk is initialized and formatted on the first reboot after tools installation. It can't be done **during** the installation because Xen mass storage drivers are not yet active. - User profiles are moved to the private disk on the next reboot after the private disk is initialized. Reboot is required because the "mover utility" runs very early in the boot process so OS can't yet lock any files in there. This can take some time depending on the profiles' size and because the GUI agent is not yet active dom0/Qubes Manager may complain that the AppVM failed to boot. That's a false alarm (you can increase AppVM's default boot timeout using `qvm-prefs`), the VM should appear "green" in Qubes Manager shortly after. -It also makes sense to disable Automatic Updates for all the Windows-based AppVMs -- of course this should be done in the Template VM, not in individual AppVMs, because the system-wide setting are stored in the root filesystem (which holds the system-wide registry hives). +It also makes sense to disable Automatic Updates for all the template-based AppVMs -- of course this should be done in the Template VM, not in individual AppVMs, because the system-wide setting are stored in the root filesystem (which holds the system-wide registry hives). Then, periodically check for updates in the Template VM and the changes will be carried over to any child AppVMs. Once the template has been created and installed it is easy to create AppVMs based on: From 8192057b2aea87ba4aa97dde9449c8b93bb7b7e1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rafa=C5=82=20Wojdy=C5=82a?= Date: Wed, 31 Aug 2016 17:57:03 +0200 Subject: [PATCH 133/708] QWT: update state of disk PV drivers --- managing-os/windows-tools-3.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/managing-os/windows-tools-3.md b/managing-os/windows-tools-3.md index 879602b8..f94d3a5f 100644 --- a/managing-os/windows-tools-3.md +++ b/managing-os/windows-tools-3.md @@ -32,7 +32,7 @@ Qubes Windows Tools (QWT for short) contain several components than can be enabl **In testing VMs only** it's probably a good idea to install a VNC server before installing QWT. If something goes very wrong with the Qubes gui agent, a VNC server should still allow access to the OS. -**NOTE**: Xen PV disk drivers are not installed by default. This is because they seem to cause severe problems, including disk image/files corruption in Qubes HVMs. We're investigating this. *However*, the problem doesn't always occur in tests -- disk drivers often work *if they are installed separately after the main portion of QWT is up and running*. **Do this at your own risk** of course, but we welcome reports of success/failure in any case. With disk PV drivers absent `qvm-block` will not work for the VM, but you can still use standard Qubes inter-VM file copying mechanisms. +**NOTE**: Xen PV disk drivers are not installed by default. This is because they seem to cause problems (BSOD). We're working with upstream devs to fix this. *However*, the BSOD seems to only occur after the first boot and everything works fine after that. **Enable the drivers at your own risk** of course, but we welcome reports of success/failure in any case (backup your VM first!). With disk PV drivers absent `qvm-block` will not work for the VM, but you can still use standard Qubes inter-VM file copying mechanisms. Verbose installation -------------------- From ff92813e577dab163abedaa54159fa82b817d3b6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Marczykowski-G=C3=B3recki?= Date: Wed, 31 Aug 2016 18:01:02 +0200 Subject: [PATCH 134/708] Update R3.2 release notes --- releases/3.2/release-notes.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/releases/3.2/release-notes.md b/releases/3.2/release-notes.md index 35f79d4a..cb723cef 100644 --- a/releases/3.2/release-notes.md +++ b/releases/3.2/release-notes.md @@ -16,7 +16,8 @@ New features since 3.1 * PV USB - [documentation][usb] * Dom0 update to Fedora 23 for better hardware support * Kernel 4.4.x -* KDE 5 support +* Default desktop environment switched to Xfce4 +* KDE 5 support (but it is no longer the default one) * Tiling window managers support: awesome, [i3][i3] * More flexible Qubes RPC services - [related ticket][qrexec-argument], [documentation][qrexec-doc] @@ -25,8 +26,6 @@ You can get detailed description in [completed github issues][github-release-not Known issues ------------ -* Installation image does not fit on DVD, requires either DVD DL, or USB stick (5GB or more) - * Windows Tools: `qvm-block` does not work * Some icons in the Qubes Manager application might not be drawn correctly when using the Xfce4 environment in Dom0. If this bothers you, please use the KDE environment instead. From 9b9098932b8596601336eea28b626decb6ea0d6b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Marczykowski-G=C3=B3recki?= Date: Wed, 31 Aug 2016 18:01:48 +0200 Subject: [PATCH 135/708] Document qubes.ResizeDisk service. --- debugging/vm-interface.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/debugging/vm-interface.md b/debugging/vm-interface.md index 6332b7b4..098bf5bd 100644 --- a/debugging/vm-interface.md +++ b/debugging/vm-interface.md @@ -78,6 +78,9 @@ Services called by dom0 to provide some VM configuration: - `qubes.SetGuiMode` - called in HVM to switch between fullscreen and seamless GUI mode. The service receives a single word on stdin - either `FULLSCREEN` or `SEAMLESS` +- `qubes.ResizeDisk` - called to inform that underlying disk was resized. + Name of disk image is passed on standard input (`root`, `private`, `volatile`, + or other). This is used starting with Qubes 4.0. Other Qrexec services installed by default: From f8787d20e43477603f26872d955664b5d33a69f6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rafa=C5=82=20Wojdy=C5=82a?= Date: Wed, 31 Aug 2016 19:03:09 +0200 Subject: [PATCH 136/708] QWT installation: update log file information --- managing-os/windows-tools-3.md | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/managing-os/windows-tools-3.md b/managing-os/windows-tools-3.md index f94d3a5f..e1fdee05 100644 --- a/managing-os/windows-tools-3.md +++ b/managing-os/windows-tools-3.md @@ -34,12 +34,10 @@ Qubes Windows Tools (QWT for short) contain several components than can be enabl **NOTE**: Xen PV disk drivers are not installed by default. This is because they seem to cause problems (BSOD). We're working with upstream devs to fix this. *However*, the BSOD seems to only occur after the first boot and everything works fine after that. **Enable the drivers at your own risk** of course, but we welcome reports of success/failure in any case (backup your VM first!). With disk PV drivers absent `qvm-block` will not work for the VM, but you can still use standard Qubes inter-VM file copying mechanisms. -Verbose installation --------------------- +Installation logs +----------------- -If the install process fails you can retry it using the command line below to get a detailed installation log (and send that to us): - -`msiexec /i path-to-qubes-tools.msi /lv path-to-log-file.txt` +If the install process fails or something goes wrong during it, include the installation logs in your bug report. They are created in the `%TEMP%` directory, by default `\AppData\Local\Temp`. There are two text files, one small and one big, with names starting with `Qubes_Windows_Tools`. Uninstalling QWT 3.x is **not recommended**. It will most likely make the OS non-bootable because drivers for Xen storage devices will be uninstalled. This will be fixed in the future. From cb9db6d4c44fba7f28fd1560e5ea42de5f6ffd91 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rafa=C5=82=20Wojdy=C5=82a?= Date: Wed, 31 Aug 2016 20:12:53 +0200 Subject: [PATCH 137/708] QWT installation: update uninstallation info --- managing-os/windows-tools-3.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/managing-os/windows-tools-3.md b/managing-os/windows-tools-3.md index e1fdee05..c7d91cb3 100644 --- a/managing-os/windows-tools-3.md +++ b/managing-os/windows-tools-3.md @@ -39,7 +39,8 @@ Installation logs If the install process fails or something goes wrong during it, include the installation logs in your bug report. They are created in the `%TEMP%` directory, by default `\AppData\Local\Temp`. There are two text files, one small and one big, with names starting with `Qubes_Windows_Tools`. -Uninstalling QWT 3.x is **not recommended**. It will most likely make the OS non-bootable because drivers for Xen storage devices will be uninstalled. This will be fixed in the future. +Uninstalling QWT is supported from version 3.2.1. Uninstalling previous versions is **not recommended**. +After uninstalling you need to manually enable the DHCP Client Windows service, or set IP settings yourself to restore network access. Configuration ------------- From 5c1c4f93330351894b6ed680fd121e4c1197be6f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rafa=C5=82=20Wojdy=C5=82a?= Date: Wed, 31 Aug 2016 20:24:21 +0200 Subject: [PATCH 138/708] QWT installation: add note about pvdriver popups --- managing-os/windows-tools-3.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/managing-os/windows-tools-3.md b/managing-os/windows-tools-3.md index c7d91cb3..8d4a5fea 100644 --- a/managing-os/windows-tools-3.md +++ b/managing-os/windows-tools-3.md @@ -34,6 +34,8 @@ Qubes Windows Tools (QWT for short) contain several components than can be enabl **NOTE**: Xen PV disk drivers are not installed by default. This is because they seem to cause problems (BSOD). We're working with upstream devs to fix this. *However*, the BSOD seems to only occur after the first boot and everything works fine after that. **Enable the drivers at your own risk** of course, but we welcome reports of success/failure in any case (backup your VM first!). With disk PV drivers absent `qvm-block` will not work for the VM, but you can still use standard Qubes inter-VM file copying mechanisms. +Xen PV driver components may display a message box asking for reboot during installation -- it's safe to ignore them and defer the reboot. + Installation logs ----------------- From c50dc03c6202b4031ddd199b7caf484a80d57d7a Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Wed, 31 Aug 2016 18:09:37 -0700 Subject: [PATCH 139/708] Update link to Windows Tools 3 page --- managing-os/windows-appvms.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/managing-os/windows-appvms.md b/managing-os/windows-appvms.md index 73364f49..2fd016fb 100644 --- a/managing-os/windows-appvms.md +++ b/managing-os/windows-appvms.md @@ -67,7 +67,7 @@ qvm-start lab-win7 --install-windows-tools Once the Windows VM boots, a CDROM should appear in the 'My Computer' menu (typically as `D:`) with a setup program in its main directory. -After successful installation, the Windows VM must be shut down and started again, possibly a couple of times (see [this page](/doc/WindowsTools/) for detailed configuration options). +After successful installation, the Windows VM must be shut down and started again, possibly a couple of times (see [this page](/doc/windows-tools-3/) for detailed configuration options). Qubes (R2 Beta 3 and later releases) will automatically detect the tools has been installed in the VM and will set appropriate properties for the VM, such as `qrexec_installed`, `guiagent_installed`, and `default_user`. This can be verified (but is not required) using qvm-prefs command: From 45f249f028a90d633b3f641f094711a5e2f2f975 Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Fri, 2 Sep 2016 11:28:17 -0700 Subject: [PATCH 140/708] Update System Requirements page in advance of 4.x * Divide system requirements into 3.x and 4.x sections * Specify new minimum and recommended requirements for 4.x * Add informational links for CPU features * Terminology: correct "AMD-v" to "AMD-V" * Terminology: prefer "AMD-Vi" to "AMD IOMMU" * Add link to Hardware Certification page * Change heading format to support additional level --- hardware/system-requirements.md | 56 +++++++++++++++++++++++---------- 1 file changed, 40 insertions(+), 16 deletions(-) diff --git a/hardware/system-requirements.md b/hardware/system-requirements.md index 911e0014..bc03ccc3 100644 --- a/hardware/system-requirements.md +++ b/hardware/system-requirements.md @@ -8,45 +8,61 @@ redirect_from: - /wiki/SystemRequirements/ --- -System Requirements -=================== +# System Requirements # -Minimum -------- +## Qubes Release 3.x ## + +### Minimum ### * 64-bit Intel or AMD processor (x86\_64 aka x64 aka AMD64) * 4 GB RAM * 32 GB disk space * Legacy boot mode ([UEFI is not supported yet][UEFI]) - -Recommended ------------ +### Recommended ### * Fast SSD (strongly recommended) - * Intel GPU (strongly preferred) + * Intel IGP (strongly preferred) * Nvidia GPUs may require significant [troubleshooting][nvidia]. * ATI GPUs have not been formally tested (but see the [Hardware Compatibility List]). - * Intel VT-x or AMD-v technology (required for running HVM domains, such as + * [Intel VT-x] or [AMD-V] (required for running HVM domains, such as Windows-based AppVMs) - * Intel VT-d or AMD IOMMU technology (required for effective isolation of + * [Intel VT-d] or [AMD-Vi (aka AMD IOMMU)] (required for effective isolation of network VMs) * TPM with proper BIOS support (required for [Anti Evil Maid]) +## Qubes Release 4.x ## -Choosing Hardware ------------------ +### Minimum ### + + * 64-bit Intel or AMD processor (x86\_64 aka x64 aka AMD64) + * [Intel VT-x] with [EPT] or [AMD-V] with [RVI] + * [Intel VT-d] or [AMD-Vi (aka AMD IOMMU)] + * 4 GB RAM + * 32 GB disk space + +### Recommended ### + + * Fast SSD (strongly recommended) + * Intel IGP (strongly preferred) + * Nvidia GPUs may require significant [troubleshooting][nvidia]. + * ATI GPUs have not been formally tested (but see the [Hardware Compatibility + List]). + * TPM with proper BIOS support (required for [Anti Evil Maid]) + * A non-USB keyboard or multiple USB controllers + * Also consider the [hardware certification requirements for Qubes 4.x]. + +## Choosing Hardware ## * Please see the [Hardware Compatibility List] for a compilation of hardware reports generated and submitted by users across various Qubes versions. (For more information about the HCL itself, see [here][hcl-doc]). * For more certain hardware compatibility, you may wish to consider a - [Qubes-certified laptop]. + [Qubes-certified laptop]. (For information about how a computer becomes + Qubes-certified, see [Hardware Certification].) - -Important Notes ---------------- +## Important Notes ## * Qubes **can** be installed on systems which do not meet the recommended requirements. Such systems will still offer significant security @@ -77,6 +93,8 @@ Important Notes [UEFI]: https://github.com/QubesOS/qubes-issues/issues/794 [nvidia]: /doc/install-nvidia-driver/ +[hardware certification requirements for Qubes 4.x]: /news/2016/07/21/new-hw-certification-for-q4/ +[Hardware Certification]: /hardware-certification/ [Hardware Compatibility List]: /hcl/ [hcl-doc]: /doc/hcl/ [hcl-report]: /doc/HCL/#generating-and-submitting-new-reports @@ -85,4 +103,10 @@ Important Notes [live USB]: /doc/live-usb/ [#230]: https://github.com/QubesOS/qubes-issues/issues/230 [vt-d-notebook]: https://groups.google.com/d/msg/qubes-users/Sz0Nuhi4N0o/ZtpJdoc0OY8J +[Intel VT-x]: https://en.wikipedia.org/wiki/X86_virtualization#Intel_virtualization_.28VT-x.29 +[AMD-V]: https://en.wikipedia.org/wiki/X86_virtualization#AMD_virtualization_.28AMD-V.29 +[Intel VT-d]: https://en.wikipedia.org/wiki/X86_virtualization#Intel-VT-d +[AMD-Vi (aka AMD IOMMU)]: https://en.wikipedia.org/wiki/X86_virtualization#I.2FO_MMU_virtualization_.28AMD-Vi_and_Intel_VT-d.29 +[EPT]: https://en.wikipedia.org/wiki/Second_Level_Address_Translation#Extended_Page_Tables +[RVI]: https://en.wikipedia.org/wiki/Second_Level_Address_Translation#Rapid_Virtualization_Indexing From 31476792c2098d3b179571c3ac81ec00cc02cbc0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Marczykowski-G=C3=B3recki?= Date: Sun, 4 Sep 2016 13:20:21 +0200 Subject: [PATCH 141/708] Update QubesDB key names Since Qubes OS 2 and 1 are long unsupported now, update documentation to focus on 3.x. --- debugging/vm-interface.md | 46 +++++++++++++++++++-------------------- 1 file changed, 23 insertions(+), 23 deletions(-) diff --git a/debugging/vm-interface.md b/debugging/vm-interface.md index 098bf5bd..486768b9 100644 --- a/debugging/vm-interface.md +++ b/debugging/vm-interface.md @@ -14,43 +14,43 @@ VM Configuration Interface Qubes VM have some settings set by dom0 based on VM settings. There are multiple configuration channels, which includes: -- XenStore -- QubesDB - replacing most of xenstore (in R3 or later) +- QubesDB +- XenStore (in Qubes 2, data the same as in QubesDB, keys without leading `/`) - Qubes RPC (called at VM startup, or when configuration changed) - GUI protocol -xenstore --------- +QubesDB in Qubes 3.x +-------------------- -Keys exposed by dom0 to VM (only Qubes specific included): +Keys exposed by dom0 to VM: -- `qubes-vm-type` - VM type, the same as `type` field in `qvm-prefs`. One of `AppVM`, `ProxyVM`, `NetVM`, `TemplateVM`, `HVM`, `TemplateHVM` -- `qubes-vm-updatable` - flag whether VM is updatable (whether changes in root.img will survive VM restart). One of `True`, `False` -- `qubes-vm-persistence` - what data do persist between VM restarts: +- `/qubes-vm-type` - VM type, the same as `type` field in `qvm-prefs`. One of `AppVM`, `ProxyVM`, `NetVM`, `TemplateVM`, `HVM`, `TemplateHVM` +- `/qubes-vm-updatable` - flag whether VM is updatable (whether changes in root.img will survive VM restart). One of `True`, `False` +- `/qubes-vm-persistence` - what data do persist between VM restarts: - `full` - all disks - `rw-only` - only `/rw` disk - `none` - none -- `qubes-timezone - name of timezone based on dom0 timezone. For example `Europe/Warsaw` -- `qubes-keyboard` - keyboard layout based on dom0 layout. Its syntax is suitable for `xkbcomp` command (after expanding escape sequences like `\n` or `\t`). This is meant only as some default value, VM can ignore this option and choose its own keyboard layout (this is what keyboard setting from Qubes Manager does). This entry is created as part of gui-daemon initialization (so not available when gui-daemon disabled, or not started yet). -- `qubes-debug-mode` - flag whether VM have debug mode enabled (qvm-prefs setting). One of `1`, `0` -- `qubes-service/SERVICE_NAME` - subtree for VM services controlled from dom0 (using qvm-service command or Qubes Manager). One of `1`, `0`. Note that not every service will be listed here, if entry is missing, it means "use VM default". List of currently supported services is in [qvm-service man page](/wiki/Dom0Tools/QvmService) -- `qubes-netmask` - network mask (only when VM has netvm set); currently hardcoded "255.255.255.0" -- \`qubes-ip - IP address for this VM (only when VM has netvm set) -- `qubes-gateway` - default gateway IP and primary DNS address (only when VM has netvm set); VM should add host route to this address directly via eth0 (or whatever default interface name is) -- `qubes-secondary-dns` - secondary DNS address (only when VM has netvm set) -- `qubes-netvm-gateway` - same as `qubes-gateway` in connected VMs (only when VM serves as network backend - ProxyVM and NetVM); because this is also set as primary DNS in connected VMs, traffic sent to this IP on port 53 should be redirected to DNS server -- `qubes-netvm-netmask` - same as `qubes-netmask` in connected VMs (only when VM serves as network backend - ProxyVM and NetVM) -- `qubes-netvm-network` - network address (only when VM serves as network backend - ProxyVM and NetVM); can be also calculated from qubes-netvm-gateway and qubes-netvm-netmask -- `qubes-netvm-secondary-dns` - same as `qubes-secondary-dns` in connected VMs (only when VM serves as network backend - ProxyVM and NetVM); traffic sent to this IP on port 53 should be redirected to secondary DNS server +- `/qubes-timezone - name of timezone based on dom0 timezone. For example `Europe/Warsaw` +- `/qubes-keyboard` - keyboard layout based on dom0 layout. Its syntax is suitable for `xkbcomp` command (after expanding escape sequences like `\n` or `\t`). This is meant only as some default value, VM can ignore this option and choose its own keyboard layout (this is what keyboard setting from Qubes Manager does). This entry is created as part of gui-daemon initialization (so not available when gui-daemon disabled, or not started yet). +- `/qubes-debug-mode` - flag whether VM have debug mode enabled (qvm-prefs setting). One of `1`, `0` +- `/qubes-service/SERVICE_NAME` - subtree for VM services controlled from dom0 (using qvm-service command or Qubes Manager). One of `1`, `0`. Note that not every service will be listed here, if entry is missing, it means "use VM default". List of currently supported services is in [qvm-service man page](/wiki/Dom0Tools/QvmService) +- `/qubes-netmask` - network mask (only when VM has netvm set); currently hardcoded "255.255.255.0" +- `/qubes-ip - IP address for this VM (only when VM has netvm set) +- `/qubes-gateway` - default gateway IP and primary DNS address (only when VM has netvm set); VM should add host route to this address directly via eth0 (or whatever default interface name is) +- `/qubes-secondary-dns` - secondary DNS address (only when VM has netvm set) +- `/qubes-netvm-gateway` - same as `qubes-gateway` in connected VMs (only when VM serves as network backend - ProxyVM and NetVM); because this is also set as primary DNS in connected VMs, traffic sent to this IP on port 53 should be redirected to DNS server +- `/qubes-netvm-netmask` - same as `qubes-netmask` in connected VMs (only when VM serves as network backend - ProxyVM and NetVM) +- `/qubes-netvm-network` - network address (only when VM serves as network backend - ProxyVM and NetVM); can be also calculated from qubes-netvm-gateway and qubes-netvm-netmask +- `/qubes-netvm-secondary-dns` - same as `qubes-secondary-dns` in connected VMs (only when VM serves as network backend - ProxyVM and NetVM); traffic sent to this IP on port 53 should be redirected to secondary DNS server Keys set by VM for passing info to dom0: -- `memory/meminfo` - used memory (updated by qubes-meminfo-writer), input information for qmemman; Format: 6 lines (EOL encoded as `\n`), each in format "FIELD: VALUE kB"; fields: `MemTotal`, `MemFree`, `Buffers`, `Cached`, `SwapTotal`, `SwapFree`; meaning the same as in `/proc/meminfo` in Linux -- `qubes-block-devices` - list of block devices exposed by this VM, each device (subdirectory) should be named in a way that VM can attach the device based on it. Each should contain those entries: +- `memory/meminfo` (**xenstore**) - used memory (updated by qubes-meminfo-writer), input information for qmemman; Format: 6 lines (EOL encoded as `\n`), each in format "FIELD: VALUE kB"; fields: `MemTotal`, `MemFree`, `Buffers`, `Cached`, `SwapTotal`, `SwapFree`; meaning the same as in `/proc/meminfo` in Linux. +- `/qubes-block-devices` - list of block devices exposed by this VM, each device (subdirectory) should be named in a way that VM can attach the device based on it. Each should contain those entries: - `desc` - device description (ASCII text) - `size` - device size in bytes - `mode` - default connection mode; `r` for read-only, `w` for read-write -- `qubes-usb-devices` - list of USB devices exposed by this VM, each device (subdirectory) should contain: +- `/qubes-usb-devices` - list of USB devices exposed by this VM, each device (subdirectory) should contain: - `desc` - device description (ASCII text) - `usb-ver` - USB version (1, 2 or 3) From 1edfcd26d1bb2877d5eda5673d8b866268b57c93 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Marczykowski-G=C3=B3recki?= Date: Sun, 4 Sep 2016 13:35:50 +0200 Subject: [PATCH 142/708] Describe firewall interface in Qubes 3.x --- debugging/vm-interface.md | 20 ++++++++++++++++++-- 1 file changed, 18 insertions(+), 2 deletions(-) diff --git a/debugging/vm-interface.md b/debugging/vm-interface.md index 486768b9..ee945494 100644 --- a/debugging/vm-interface.md +++ b/debugging/vm-interface.md @@ -22,7 +22,7 @@ Qubes VM have some settings set by dom0 based on VM settings. There are multiple QubesDB in Qubes 3.x -------------------- -Keys exposed by dom0 to VM: +### Keys exposed by dom0 to VM ### - `/qubes-vm-type` - VM type, the same as `type` field in `qvm-prefs`. One of `AppVM`, `ProxyVM`, `NetVM`, `TemplateVM`, `HVM`, `TemplateHVM` - `/qubes-vm-updatable` - flag whether VM is updatable (whether changes in root.img will survive VM restart). One of `True`, `False` @@ -43,7 +43,23 @@ Keys exposed by dom0 to VM: - `/qubes-netvm-network` - network address (only when VM serves as network backend - ProxyVM and NetVM); can be also calculated from qubes-netvm-gateway and qubes-netvm-netmask - `/qubes-netvm-secondary-dns` - same as `qubes-secondary-dns` in connected VMs (only when VM serves as network backend - ProxyVM and NetVM); traffic sent to this IP on port 53 should be redirected to secondary DNS server -Keys set by VM for passing info to dom0: +#### Firewall rules #### + +QubesDB is also used to configure firewall in ProxyVMs. Rules are stored in +separate key for each target VM. Entries: + +- `/qubes-iptables` - control entry - dom0 writing `reload` here signal `qubes-firewall` service to reload rules +- `/qubes-iptables-header` - rules not related to any particular VM, should be applied before domains rules +- `/qubes-iptables-domainrules/NNN` - rules for domain `NNN` (arbitrary number) +in `iptables-save` format. Rules are self-contained - fill `FORWARD` iptables +chain and contains all required matches (source IP address etc), as well as +final default action (`DROP`/`ACCEPT`) + +VM after applying rules may signal some error, writing a message to +`/qubes-iptables-error` key. This does not exclude any other way of +communicating problem - like a popup. + +### Keys set by VM for passing info to dom0 ### - `memory/meminfo` (**xenstore**) - used memory (updated by qubes-meminfo-writer), input information for qmemman; Format: 6 lines (EOL encoded as `\n`), each in format "FIELD: VALUE kB"; fields: `MemTotal`, `MemFree`, `Buffers`, `Cached`, `SwapTotal`, `SwapFree`; meaning the same as in `/proc/meminfo` in Linux. - `/qubes-block-devices` - list of block devices exposed by this VM, each device (subdirectory) should be named in a way that VM can attach the device based on it. Each should contain those entries: From b3cf4663139d45251d7a29f88ffa52eea6e98fec Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Marczykowski-G=C3=B3recki?= Date: Tue, 6 Sep 2016 18:54:17 +0200 Subject: [PATCH 143/708] vm-interface: Add info about qubes-primary-dns entry in R3.2+ --- debugging/vm-interface.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/debugging/vm-interface.md b/debugging/vm-interface.md index ee945494..7cd7337c 100644 --- a/debugging/vm-interface.md +++ b/debugging/vm-interface.md @@ -19,7 +19,7 @@ Qubes VM have some settings set by dom0 based on VM settings. There are multiple - Qubes RPC (called at VM startup, or when configuration changed) - GUI protocol -QubesDB in Qubes 3.x +QubesDB -------------------- ### Keys exposed by dom0 to VM ### @@ -36,11 +36,13 @@ QubesDB in Qubes 3.x - `/qubes-service/SERVICE_NAME` - subtree for VM services controlled from dom0 (using qvm-service command or Qubes Manager). One of `1`, `0`. Note that not every service will be listed here, if entry is missing, it means "use VM default". List of currently supported services is in [qvm-service man page](/wiki/Dom0Tools/QvmService) - `/qubes-netmask` - network mask (only when VM has netvm set); currently hardcoded "255.255.255.0" - `/qubes-ip - IP address for this VM (only when VM has netvm set) -- `/qubes-gateway` - default gateway IP and primary DNS address (only when VM has netvm set); VM should add host route to this address directly via eth0 (or whatever default interface name is) +- `/qubes-gateway` - default gateway IP (only when VM has netvm set); VM should add host route to this address directly via eth0 (or whatever default interface name is) +- `/qubes-primary-dns` - primary DNS address (only when VM has netvm set) (in Qubes 3.2 and later, previously `/qubes-gateway` was used for this purpose) - `/qubes-secondary-dns` - secondary DNS address (only when VM has netvm set) -- `/qubes-netvm-gateway` - same as `qubes-gateway` in connected VMs (only when VM serves as network backend - ProxyVM and NetVM); because this is also set as primary DNS in connected VMs, traffic sent to this IP on port 53 should be redirected to DNS server +- `/qubes-netvm-gateway` - same as `qubes-gateway` in connected VMs (only when VM serves as network backend - ProxyVM and NetVM) - `/qubes-netvm-netmask` - same as `qubes-netmask` in connected VMs (only when VM serves as network backend - ProxyVM and NetVM) - `/qubes-netvm-network` - network address (only when VM serves as network backend - ProxyVM and NetVM); can be also calculated from qubes-netvm-gateway and qubes-netvm-netmask +- `/qubes-netvm-primary-dns` - same as `qubes-primary-dns` in connected VMs (only when VM serves as network backend - ProxyVM and NetVM); traffic sent to this IP on port 53 should be redirected to primary DNS server (in Qubes 3.2 and later, previously `/qubes-netvm-gateway` was used for this purpose) - `/qubes-netvm-secondary-dns` - same as `qubes-secondary-dns` in connected VMs (only when VM serves as network backend - ProxyVM and NetVM); traffic sent to this IP on port 53 should be redirected to secondary DNS server #### Firewall rules #### From a17d9bf4b15b2b2863bec874579761e2594ba4fb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Marczykowski-G=C3=B3recki?= Date: Tue, 6 Sep 2016 18:55:05 +0200 Subject: [PATCH 144/708] vm-interface: new memory/prefmem interface for qmemman --- debugging/vm-interface.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/debugging/vm-interface.md b/debugging/vm-interface.md index 7cd7337c..dc23d9cb 100644 --- a/debugging/vm-interface.md +++ b/debugging/vm-interface.md @@ -63,7 +63,9 @@ communicating problem - like a popup. ### Keys set by VM for passing info to dom0 ### -- `memory/meminfo` (**xenstore**) - used memory (updated by qubes-meminfo-writer), input information for qmemman; Format: 6 lines (EOL encoded as `\n`), each in format "FIELD: VALUE kB"; fields: `MemTotal`, `MemFree`, `Buffers`, `Cached`, `SwapTotal`, `SwapFree`; meaning the same as in `/proc/meminfo` in Linux. +- `memory/meminfo` (**xenstore**) - used memory (updated by qubes-meminfo-writer), input information for qmemman; Format: 6 lines (EOL encoded as `\n`), each in format "FIELD: VALUE kB"; fields: `MemTotal`, `MemFree`, `Buffers`, `Cached`, `SwapTotal`, `SwapFree`; meaning the same as in `/proc/meminfo` in Linux. Deprecated in Qubes 4.0 +- `memory/prefmem` - preferred memory size for this VM, in bytes. Qmemman +daemon in dom0 use this as a hint how to balance memory assignments. This deprecates `memory/meminfo` in Qubes 4.0 - `/qubes-block-devices` - list of block devices exposed by this VM, each device (subdirectory) should be named in a way that VM can attach the device based on it. Each should contain those entries: - `desc` - device description (ASCII text) - `size` - device size in bytes From 66134b80d3d8437b7b0fd9b3b69ebc4e9b314121 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Marczykowski-G=C3=B3recki?= Date: Tue, 6 Sep 2016 18:55:35 +0200 Subject: [PATCH 145/708] vm-interface: firewall interface for R4.0+ QubesOS/qubes-issues#1815 --- debugging/vm-interface.md | 47 ++++++++++++++++++++++++++++++++++++++- 1 file changed, 46 insertions(+), 1 deletion(-) diff --git a/debugging/vm-interface.md b/debugging/vm-interface.md index dc23d9cb..f44132f2 100644 --- a/debugging/vm-interface.md +++ b/debugging/vm-interface.md @@ -45,7 +45,7 @@ QubesDB - `/qubes-netvm-primary-dns` - same as `qubes-primary-dns` in connected VMs (only when VM serves as network backend - ProxyVM and NetVM); traffic sent to this IP on port 53 should be redirected to primary DNS server (in Qubes 3.2 and later, previously `/qubes-netvm-gateway` was used for this purpose) - `/qubes-netvm-secondary-dns` - same as `qubes-secondary-dns` in connected VMs (only when VM serves as network backend - ProxyVM and NetVM); traffic sent to this IP on port 53 should be redirected to secondary DNS server -#### Firewall rules #### +#### Firewall rules in 3.x #### QubesDB is also used to configure firewall in ProxyVMs. Rules are stored in separate key for each target VM. Entries: @@ -61,6 +61,51 @@ VM after applying rules may signal some error, writing a message to `/qubes-iptables-error` key. This does not exclude any other way of communicating problem - like a popup. +#### Firewall rules in 4.x #### + +QubesDB is also used to configure firewall in ProxyVMs. Each rule is stored as +a separate entry, grouped on target VM: + +- `/qubes-firewall/TARGET_IP` - base tree under which rules are placed. All +there rules there should be applied to filter traffic coming from `TARGET_IP`. +Dom0 will do an empty write to this top level entry after finishing rules +update, so VM can setup a watch here to trigger rules reload. +- `/qubes-firewall/TARGET_IP/policy` - default action if no rule matches: +`DROP` or `ACCEPT`. +- `/qubes-firewall/TARGET_IP/NNNN` - rule number `NNNN` - decimal number, + padded with zeros. Se below for rule format. All the rules should be + applied in order of rules implied by those numbers. Note that QubesDB + itself does not impose any ordering (you need to sort the rules after + retrieving them). + +Each rule is a single QubesDB entry, consisting of pairs `key=value` separated +by space. Order of those pairs in a single rule is undefined. QubesDB enforces +a limit on a single entry length - 3072 bytes. +Possible options for a single rule: + + - `action`, values: `accept`, `drop`; this is present it every rule + - `dst4`, value: destination IPv4 address with a mask; for example: `192.168.0.0/24` + - `dst6`, value: destination IPv6 address with a mask; for example: `2000::/3` + - `dstname`, value: DNS hostname of destination host + - `proto`, values: `tcp`, `udp`, `icmp` + - `dstports`, value: destination ports range separated with `-`, valid only + together with `proto=tcp` or `proto=udp`; for example `1-1024`, `80-80` + - `icmp-type`, value: numeric (decimal) icmp message type, for example `8` for + echo request, valid only together with `proto=icmp` + +Rule matches only when all predicates matches. Only one of `dst4`, `dst6`, +`dstname` can be used in a single rule. + +If tool applying firewall encounter any parse error (unknown option, invalid +value etc), it should drop all the traffic coming from that `TARGET_IP`, +regardless of properly parsed rules. + +Example valid rules: + +- `action=accept dst4=8.8.8.8 proto=udp dstports=53-53` +- `action=drop dst6=2a00:1450:4000::/37 proto=tcp` +- `action=drop` + ### Keys set by VM for passing info to dom0 ### - `memory/meminfo` (**xenstore**) - used memory (updated by qubes-meminfo-writer), input information for qmemman; Format: 6 lines (EOL encoded as `\n`), each in format "FIELD: VALUE kB"; fields: `MemTotal`, `MemFree`, `Buffers`, `Cached`, `SwapTotal`, `SwapFree`; meaning the same as in `/proc/meminfo` in Linux. Deprecated in Qubes 4.0 From e99688b4052ef27e836d67bdd7c8cfc3c1067feb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Marczykowski-G=C3=B3recki?= Date: Tue, 6 Sep 2016 18:56:58 +0200 Subject: [PATCH 146/708] Add missing step to R3.0->R3.1 upgrade instruction --- installing/upgrade/upgrade-to-r3.1.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/installing/upgrade/upgrade-to-r3.1.md b/installing/upgrade/upgrade-to-r3.1.md index 46917339..53a4b08f 100644 --- a/installing/upgrade/upgrade-to-r3.1.md +++ b/installing/upgrade/upgrade-to-r3.1.md @@ -90,6 +90,10 @@ complete. should be `3.1.4` or higher. If it's not, repeat the previous step with the `--clean` option. +4. Install new packages: + + sudo qubes-dom0-update qubes-mgmt-salt-admin-tools + 4. Reboot dom0. The system may hang during the reboot. If that happens, do not panic. All From 7a5c830646c3e458f74930fdb004fa7508a93e1e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Marczykowski-G=C3=B3recki?= Date: Tue, 6 Sep 2016 18:58:58 +0200 Subject: [PATCH 147/708] Add missing step to R3.1->R3.2 upgrade instruction --- installing/upgrade/upgrade-to-r3.2.md | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) diff --git a/installing/upgrade/upgrade-to-r3.2.md b/installing/upgrade/upgrade-to-r3.2.md index a9796b6b..1199be65 100644 --- a/installing/upgrade/upgrade-to-r3.2.md +++ b/installing/upgrade/upgrade-to-r3.2.md @@ -128,7 +128,11 @@ repeated in **all** the user's Template and Standalone VMs. sudo dnf upgrade --refresh -4. Shut down the template VM. +4. Add new packages (only needed in default template): + + sudo dnf install qubes-mgmt-salt-vm-connector + +5. Shut down the template VM. ### Upgrade Debian (and Whonix) templates: ### @@ -147,10 +151,14 @@ repeated in **all** the user's Template and Standalone VMs. sudo apt-get update sudo apt-get dist-upgrade -4. Remove unnecessary now file: +4. Add new packages (only needed in default template): + + sudo dnf install qubes-mgmt-salt-vm-connector + +5. Remove unnecessary now file: sudo rm -f /etc/apt/sources.list.d/qubes-r3-upgrade.list -5. Shut down the template VM. +6. Shut down the template VM. From 1201017eb2566cf857b575fc6edd9a4fd357038e Mon Sep 17 00:00:00 2001 From: i7u Date: Wed, 7 Sep 2016 22:31:59 +0100 Subject: [PATCH 148/708] Update managing-appvm-shortcuts.md Fixed inaccurate language about location of /var/lib/qubes/vm-templates, added example of creating shortcut to .desktop file, added section "what if my application has not been automatically included in the list of available apps" to link to a worked example that makes this page more usable/understandable. --- common-tasks/managing-appvm-shortcuts.md | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/common-tasks/managing-appvm-shortcuts.md b/common-tasks/managing-appvm-shortcuts.md index 8f75dd85..8c1f9f9e 100644 --- a/common-tasks/managing-appvm-shortcuts.md +++ b/common-tasks/managing-appvm-shortcuts.md @@ -28,10 +28,16 @@ The above image shows that Windows HVMs are also supported (provided that Qubes Behind the scenes ----------------- -List of installed applications for each AppVM is stored in its template's `/var/lib/qubes/vm-templates/templatename/apps.templates` (or in case of StandaloneVM: `/var/lib/qubes/appvms/vmname/apps.templates`). Each menu entry is a file that follows the [.desktop file format](http://standards.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html) with some wildcards (*%VMNAME%*, *%VMDIR%*). Applications selected to appear in the menu are stored in `/var/lib/qubes/appvms/vmname/apps`. +The list of installed applications for each AppVM is stored in dom0's `/var/lib/qubes/vm-templates/templatename/apps.templates` (or in case of StandaloneVM: `/var/lib/qubes/appvms/vmname/apps.templates`). Each menu entry is a file that follows the [.desktop file format](http://standards.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html) with some wildcards (*%VMNAME%*, *%VMDIR%*). Applications selected to appear in the menu are stored in `/var/lib/qubes/appvms/vmname/apps`. -Actual command lines for the menu shortcuts involve `qvm-run` command which starts a process in another domain. Example: `qvm-run -q --tray -a w7s 'cmd.exe /c "C:\\ProgramData\\Microsoft\\Windows\\Start Menu\\Programs\\Accessories\\Calculator.lnk"'` or `qvm-run -q --tray -a untrusted 'firefox %u'` +Actual command lines for the menu shortcuts involve `qvm-run` command which starts a process in another domain. Examples: `qvm-run -q --tray -a w7s 'cmd.exe /c "C:\\ProgramData\\Microsoft\\Windows\\Start Menu\\Programs\\Accessories\\Calculator.lnk"'` or `qvm-run -q --tray -a untrusted 'firefox %u'` +Note that you can create a shortcut that points to a .desktop file in your AppVM with e.g. `qvm-run -q --tray -a personal -- 'qubes-desktop-run /home/user/application.desktop'` `qvm-sync-appmenus` works by invoking *GetAppMenus* [Qubes service](/doc/qrexec/) in the target domain. This service enumerates installed applications and sends formatted info back to the dom0 script (`/usr/libexec/qubes-appmenus/qubes-receive-appmenus`) which creates .desktop files in the AppVM/TemplateVM directory. For Linux VMs the service script is in `/etc/qubes-rpc/qubes.GetAppMenus`. In Windows it's a PowerShell script located in `c:\Program Files\Invisible Things Lab\Qubes OS Windows Tools\qubes-rpc-services\get-appmenus.ps1` by default. + +What if my application has not been automatically included in the list of available apps? +----------------------------------------------------------------------------------------- + +You can manually create new entries in the "available applications" list of shortcuts. See [Signal] for a worked example of creating a new menu item for a Chrome .desktop shortcut. From 7a637ca94ed4545008e5758e23d253f7225b56cc Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Thu, 8 Sep 2016 00:04:46 -0700 Subject: [PATCH 149/708] Fix Signal page link --- common-tasks/managing-appvm-shortcuts.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/common-tasks/managing-appvm-shortcuts.md b/common-tasks/managing-appvm-shortcuts.md index 8c1f9f9e..df364fe9 100644 --- a/common-tasks/managing-appvm-shortcuts.md +++ b/common-tasks/managing-appvm-shortcuts.md @@ -40,4 +40,4 @@ For Linux VMs the service script is in `/etc/qubes-rpc/qubes.GetAppMenus`. In Wi What if my application has not been automatically included in the list of available apps? ----------------------------------------------------------------------------------------- -You can manually create new entries in the "available applications" list of shortcuts. See [Signal] for a worked example of creating a new menu item for a Chrome .desktop shortcut. +You can manually create new entries in the "available applications" list of shortcuts. See [Signal](/doc/signal/) for a worked example of creating a new menu item for a Chrome .desktop shortcut. From 7c67ef6517b663e1b86dda9428db2714a33da620 Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Fri, 9 Sep 2016 00:38:06 -0700 Subject: [PATCH 150/708] Change R3.0 status to unsupported --- installing/supported-versions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/installing/supported-versions.md b/installing/supported-versions.md index 05f0c906..8e42a32e 100644 --- a/installing/supported-versions.md +++ b/installing/supported-versions.md @@ -26,7 +26,7 @@ past minor releases, are available from our [FTP server]. | ---------------- | ---------- | ---------- | --------------------------- | | Release 1 | 2012-09-03 | 2015-03-26 | Old, unsupported | | Release 2 | 2014-09-26 | 2016-04-01 | Old, unsupported | -| Release 3.0 | 2015-10-01 | 2016-09-09 | Old, supported | +| Release 3.0 | 2015-10-01 | 2016-09-09 | Old, unsupported | | Release 3.1 | 2016-03-09 | TBA | Current, supported | | Release 3.2 | TBA | TBA | In testing | | Release 4.0 | TBA | TBA | In development | From ab1ce56123df1300b8344373c35542339bdef1f3 Mon Sep 17 00:00:00 2001 From: Zrubi Date: Fri, 9 Sep 2016 14:02:06 +0200 Subject: [PATCH 151/708] KDE default login manager added section: how to change the login manager "back" to KDE default. --- customization/kde.md | 17 ++++++++++++++++- 1 file changed, 16 insertions(+), 1 deletion(-) diff --git a/customization/kde.md b/customization/kde.md index c471bb90..c2553f2a 100644 --- a/customization/kde.md +++ b/customization/kde.md @@ -12,11 +12,26 @@ 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. Nonetheless, it is +R3.2, however, [XFCE is the new default desktop environment](https://github.com/QubesOS/qubes-issues/issues/2119). Nonetheless, it is still possible to install KDE by issuing this command in dom0: $ sudo qubes-dom0-update @kde-desktop-qubes +You can also change your default login manager (lightdm) to the new KDE default: sddm + * first you need to edit the `/etc/sddm.conf` to make sure if the custom X parameter is set according to Qubes needs: +~~~ + [XDisplay] + ServerArguments=-nolisten tcp -background none +~~~ + * disable the lightdm service: +~~~ + $ sudo systemctl disable lightdm +~~~ + * enable the sddm service: +~~~ + $ sudo systemctl enable sddm +~~~ + * reboot Window Management ----------------- From 6cf98ddad2ba1f926e24e96d8c6e0ad989f22653 Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Fri, 9 Sep 2016 13:14:02 -0700 Subject: [PATCH 152/708] Add note regarding safety of EOL base OS in dom0 --- installing/supported-versions.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/installing/supported-versions.md b/installing/supported-versions.md index 8e42a32e..9712bb77 100644 --- a/installing/supported-versions.md +++ b/installing/supported-versions.md @@ -45,6 +45,13 @@ The table below shows the OS used for dom0 in each Qubes OS release. | Release 3.2 | Fedora 23 | | Release 4.0 | TBA | +**Note:** Dom0 is isolated from domUs. DomUs can access only a few interfaces, +such as Xen, device backends (in the dom0 kernel and in other VMs, such as the +NetVM), and Qubes tools (gui-daemon, qrexec-daemon, etc.). These components are +[security-critical], and we provide updates for all of them (when necessary), +regardless of the support status of the base distribution. For this reason, we +consider it safe to continue using a given base distribution in dom0 even after +it has reached end-of-life. TemplateVMs ----------- @@ -67,5 +74,6 @@ extensive testing. [Version Scheme]: /doc/version-scheme/ [Downloads]: /downloads/ [FTP server]: https://ftp.qubes-os.org/ +[security-critical]: /doc/security-critical-code/ [TemplateVM]: /doc/templates/ From 6f9f3d1e7616ac528c30199a1edc2a2ce5b1e0e3 Mon Sep 17 00:00:00 2001 From: Zrubi Date: Sat, 10 Sep 2016 09:48:30 +0200 Subject: [PATCH 153/708] correcting some formatting glitches --- customization/kde.md | 27 +++++++++++++++++---------- 1 file changed, 17 insertions(+), 10 deletions(-) diff --git a/customization/kde.md b/customization/kde.md index c2553f2a..486409ce 100644 --- a/customization/kde.md +++ b/customization/kde.md @@ -18,20 +18,27 @@ still possible to install KDE by issuing this command in dom0: $ sudo qubes-dom0-update @kde-desktop-qubes You can also change your default login manager (lightdm) to the new KDE default: sddm - * first you need to edit the `/etc/sddm.conf` to make sure if the custom X parameter is set according to Qubes needs: -~~~ + + * first you need to edit the `/etc/sddm.conf` to make sure if the custom X parameter is set according to Qubes needs: + + ~~~ [XDisplay] ServerArguments=-nolisten tcp -background none -~~~ - * disable the lightdm service: -~~~ + ~~~ + + * disable the lightdm service: + + ~~~ $ sudo systemctl disable lightdm -~~~ - * enable the sddm service: -~~~ + ~~~ + + * enable the sddm service: + + ~~~ $ sudo systemctl enable sddm -~~~ - * reboot + ~~~ + + * reboot Window Management ----------------- From 6603a347feebef05c49503d590893cf53d5d7eaf Mon Sep 17 00:00:00 2001 From: Zrubi Date: Sat, 10 Sep 2016 10:22:35 +0200 Subject: [PATCH 154/708] correcting some formatting glitches --- customization/kde.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/customization/kde.md b/customization/kde.md index 486409ce..ad651512 100644 --- a/customization/kde.md +++ b/customization/kde.md @@ -21,22 +21,22 @@ You can also change your default login manager (lightdm) to the new KDE default: * first you need to edit the `/etc/sddm.conf` to make sure if the custom X parameter is set according to Qubes needs: - ~~~ - [XDisplay] - ServerArguments=-nolisten tcp -background none - ~~~ +~~~ + [XDisplay] + ServerArguments=-nolisten tcp -background none +~~~ * disable the lightdm service: - ~~~ - $ sudo systemctl disable lightdm - ~~~ +~~~ + $ sudo systemctl disable lightdm +~~~ * enable the sddm service: - ~~~ +~~~ $ sudo systemctl enable sddm - ~~~ +~~~ * reboot From 22439b4c7cf9bba7777855e527bceaa5b66d7696 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Marczykowski-G=C3=B3recki?= Date: Thu, 15 Sep 2016 01:20:38 +0200 Subject: [PATCH 155/708] Clarification/update for vm-interface - firewall --- debugging/vm-interface.md | 24 +++++++++++++++--------- 1 file changed, 15 insertions(+), 9 deletions(-) diff --git a/debugging/vm-interface.md b/debugging/vm-interface.md index f44132f2..f9bde9cb 100644 --- a/debugging/vm-interface.md +++ b/debugging/vm-interface.md @@ -66,17 +66,18 @@ communicating problem - like a popup. QubesDB is also used to configure firewall in ProxyVMs. Each rule is stored as a separate entry, grouped on target VM: -- `/qubes-firewall/TARGET_IP` - base tree under which rules are placed. All -there rules there should be applied to filter traffic coming from `TARGET_IP`. +- `/qubes-firewall/SOURCE_IP` - base tree under which rules are placed. All +rules there should be applied to filter traffic coming from `SOURCE_IP`. This +can be either IPv4 or IPv6 address. Dom0 will do an empty write to this top level entry after finishing rules update, so VM can setup a watch here to trigger rules reload. -- `/qubes-firewall/TARGET_IP/policy` - default action if no rule matches: -`DROP` or `ACCEPT`. -- `/qubes-firewall/TARGET_IP/NNNN` - rule number `NNNN` - decimal number, +- `/qubes-firewall/SOURCE_IP/policy` - default action if no rule matches: +`drop` or `accept`. +- `/qubes-firewall/SOURCE_IP/NNNN` - rule number `NNNN` - decimal number, padded with zeros. Se below for rule format. All the rules should be applied in order of rules implied by those numbers. Note that QubesDB itself does not impose any ordering (you need to sort the rules after - retrieving them). + retrieving them). The first rule has number `0000`. Each rule is a single QubesDB entry, consisting of pairs `key=value` separated by space. Order of those pairs in a single rule is undefined. QubesDB enforces @@ -88,22 +89,27 @@ Possible options for a single rule: - `dst6`, value: destination IPv6 address with a mask; for example: `2000::/3` - `dstname`, value: DNS hostname of destination host - `proto`, values: `tcp`, `udp`, `icmp` + - `specialtarget`, value: One of predefined target, currently defined values: + - `dns` - such option should match DNS traffic to default DNS server (but + not any DNS server), on both TCP and UDP - `dstports`, value: destination ports range separated with `-`, valid only together with `proto=tcp` or `proto=udp`; for example `1-1024`, `80-80` - - `icmp-type`, value: numeric (decimal) icmp message type, for example `8` for + - `icmptype`, value: numeric (decimal) icmp message type, for example `8` for echo request, valid only together with `proto=icmp` Rule matches only when all predicates matches. Only one of `dst4`, `dst6`, -`dstname` can be used in a single rule. +`dstname`, `specialtarget` can be used in a single rule. If tool applying firewall encounter any parse error (unknown option, invalid -value etc), it should drop all the traffic coming from that `TARGET_IP`, +value etc), it should drop all the traffic coming from that `SOURCE_IP`, regardless of properly parsed rules. Example valid rules: - `action=accept dst4=8.8.8.8 proto=udp dstports=53-53` - `action=drop dst6=2a00:1450:4000::/37 proto=tcp` +- `specialtarget=dns action=accept` +- `specialtarget=dns action=drop proto=tcp` - drop DNS queries sent using TCP - `action=drop` ### Keys set by VM for passing info to dom0 ### From 027f5c7d74fc72c4718b181eab24266925a74a88 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Marczykowski-G=C3=B3recki?= Date: Thu, 15 Sep 2016 01:21:41 +0200 Subject: [PATCH 156/708] vm-interface: in the end new meminfo-writer use the same key as the old one --- debugging/vm-interface.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/debugging/vm-interface.md b/debugging/vm-interface.md index f9bde9cb..8524737b 100644 --- a/debugging/vm-interface.md +++ b/debugging/vm-interface.md @@ -114,9 +114,9 @@ Example valid rules: ### Keys set by VM for passing info to dom0 ### -- `memory/meminfo` (**xenstore**) - used memory (updated by qubes-meminfo-writer), input information for qmemman; Format: 6 lines (EOL encoded as `\n`), each in format "FIELD: VALUE kB"; fields: `MemTotal`, `MemFree`, `Buffers`, `Cached`, `SwapTotal`, `SwapFree`; meaning the same as in `/proc/meminfo` in Linux. Deprecated in Qubes 4.0 -- `memory/prefmem` - preferred memory size for this VM, in bytes. Qmemman -daemon in dom0 use this as a hint how to balance memory assignments. This deprecates `memory/meminfo` in Qubes 4.0 +- `memory/meminfo` (**xenstore**) - used memory (updated by qubes-meminfo-writer), input information for qmemman; + - Qubes 3.x format: 6 lines (EOL encoded as `\n`), each in format "FIELD: VALUE kB"; fields: `MemTotal`, `MemFree`, `Buffers`, `Cached`, `SwapTotal`, `SwapFree`; meaning the same as in `/proc/meminfo` in Linux. + - Qubes 4.0+ format: used memory size in the VM, in kbytes - `/qubes-block-devices` - list of block devices exposed by this VM, each device (subdirectory) should be named in a way that VM can attach the device based on it. Each should contain those entries: - `desc` - device description (ASCII text) - `size` - device size in bytes From f07119c7168ef89590f19362ff2f5682298a49fd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Marczykowski-G=C3=B3recki?= Date: Thu, 15 Sep 2016 01:22:29 +0200 Subject: [PATCH 157/708] Add link to Debian wiki about Qubes --- managing-os/templates/debian.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/managing-os/templates/debian.md b/managing-os/templates/debian.md index efb61509..9fe0c0f1 100644 --- a/managing-os/templates/debian.md +++ b/managing-os/templates/debian.md @@ -59,3 +59,8 @@ Known issues ------------ If you want to help in improving the template, feel free to [contribute](/wiki/ContributingHowto). + +More information +---------------- + +* [Debian wiki](https://wiki.debian.org/Qubes) From 1448c1e7ab8ba17c7a9b9fdd53fcdefb0f1b329b Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Thu, 15 Sep 2016 01:51:37 -0700 Subject: [PATCH 158/708] Add link to rustybird's Split dm-crypt --- doc.md | 1 + 1 file changed, 1 insertion(+) diff --git a/doc.md b/doc.md index 39c2dd84..c7f7fca4 100644 --- a/doc.md +++ b/doc.md @@ -96,6 +96,7 @@ Security Guides * [Using Multi-factor Authentication with Qubes](/doc/multifactor-authentication/) * [Using GPG more securely in Qubes: Split GPG](/doc/split-gpg/) * [How to Set Up a Split Bitcoin Wallet in Qubes](/doc/split-bitcoin/) + * [[Unofficial] Split dm-crypt](https://github.com/rustybird/qubes-split-dm-crypt) * [Configuring YubiKey for user authentication](/doc/yubi-key/) * [Note regarding password-less root access in VM](/doc/vm-sudo/) From 932dc330f54974aa68f3174f2c0b59d411e78ca2 Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Thu, 15 Sep 2016 02:09:26 -0700 Subject: [PATCH 159/708] Clarify UEFI system requirement for R3.x --- hardware/system-requirements.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/hardware/system-requirements.md b/hardware/system-requirements.md index bc03ccc3..5b1bf3d7 100644 --- a/hardware/system-requirements.md +++ b/hardware/system-requirements.md @@ -17,7 +17,8 @@ redirect_from: * 64-bit Intel or AMD processor (x86\_64 aka x64 aka AMD64) * 4 GB RAM * 32 GB disk space - * Legacy boot mode ([UEFI is not supported yet][UEFI]) + * Legacy boot mode (required for R3.0 and earlier; UEFI is supported beginning + with R3.1) ### Recommended ### @@ -91,7 +92,6 @@ redirect_from: * [Advice on finding a VT-d capable notebook][vt-d-notebook]. -[UEFI]: https://github.com/QubesOS/qubes-issues/issues/794 [nvidia]: /doc/install-nvidia-driver/ [hardware certification requirements for Qubes 4.x]: /news/2016/07/21/new-hw-certification-for-q4/ [Hardware Certification]: /hardware-certification/ From 9e8daab5631f7a93e9205cb9a7d4f2aff5cdf7d6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Marczykowski-G=C3=B3recki?= Date: Thu, 15 Sep 2016 13:37:06 +0200 Subject: [PATCH 160/708] Add bind dirs documentation Fixes QubesOS/qubes-issues#2315 --- configuration/bind-dirs.md | 66 +++++++++++++++++++++++++++++++++++ configuration/config-files.md | 3 ++ 2 files changed, 69 insertions(+) create mode 100644 configuration/bind-dirs.md diff --git a/configuration/bind-dirs.md b/configuration/bind-dirs.md new file mode 100644 index 00000000..62a89fc9 --- /dev/null +++ b/configuration/bind-dirs.md @@ -0,0 +1,66 @@ +--- +layout: doc +title: Bind-dirs - make persisnent changes to arbitrary system file in AppVM +permalink: /doc/bind-dirs/ +redirect_from: +- /en/doc/bind-dirs/ +--- + +# What is bind-dirs.sh? # + +With [bind-dirs.sh](https://github.com/QubesOS/qubes-core-agent-linux/blob/master/vm-systemd/bind-dirs.sh) +you can make arbitrary files or folders persistent in TemplateBasedVMs. + +# What is it useful for? # + +For example, it is useful for Whonix, sys-whonix, where [Tor's data dir /var/lib/tor has been made persistent in the TemplateBased ProxyVM sys-whonix](https://github.com/Whonix/qubes-whonix/blob/8438d13d75822e9ea800b9eb6024063f476636ff/usr/lib/qubes-bind-dirs.d/40_qubes-whonix.conf#L5). So sys-whonix does not require to be a StandaloneVM. And therefore can benefit from the Tor anonymity feature 'persistent Tor entry guards' without the overhead of a StandaloneVM. + +# Minimum Qubes Version # + +bind-dirs.sh works with Qubes R3.2 and above. + +# How to use bind-dirs.sh? # + +1) Create a file `/rw/config/qubes-bind-dirs.d/50_user.conf` with root rights inside a VM. + +2) Append a folder or file to the `binds` variable. In the following example we are using folder `/var/lib/tor`. You can replace that folder with a folder or file of your choice. + +``` +binds+=( '/var/lib/tor' ) +``` + +3) Save. + +4) Reboot the VM. + +5) Done. + +# Other Configuration Folders # + +* `/usr/lib/qubes-bind-dirs.d` (lowest priority, for packages) +* `/etc/qubes-bind-dirs.d` (intermediate priority, for template wide configuration) +* `/rw/config/qubes-bind-dirs.d` (highest priority, for per VM configuration) + +# Limitations # + +* Files that exist in the TempalteVM root image cannot be made deleted in the TemlateBasedVMs root image using bind-dirs.sh. +* Does not work if the file / folder in question does not already exist in the root image. I.e. a file that does not exist in the root image cannot be bind mounted in the TemplateBasedVM. +* Re-running `sudo /usr/lib/qubes/bind-dirs.sh` without previous `sudo /usr/lib/qubes/bind-dirs.sh umount` does not work. +* Running 'sudo /usr/lib/qubes/bind-dirs.sh umount' after boot (before shutdown) is probably not sane and nothing can be done about that. + +# How to remove binds from bind-dirs.sh? # + +`binds` is actually just a bash variable (an array) and the bind-dirs.sh configuration folders are `source`d as bash snippets in lexical order. Therefore if you wanted to remove an existing entry from the `binds` array, you could do that by using a lexically higher configuration file. For example, if you wanted to make `/var/lib/tor` non-persistant in `sys-whonix` without manually editing [`/usr/lib/qubes-bind-dirs.d/40_qubes-whonix.conf`](https://github.com/Whonix/qubes-whonix/blob/master/usr/lib/qubes-bind-dirs.d/40_qubes-whonix.conf), you could use the following. + +`/rw/config/qubes-bind-dirs.d/50_user.conf` + +``` +binds=( "${binds[@]/'/var/lib/tor'}" ) +``` + +(Editing `/usr/lib/qubes-bind-dirs.d/40_qubes-whonix.conf` directly is recommended against, since such changes get lost when that file is changed in the package on upgrades.) + +# Discussion # + +[TemplateBasedVMs: make selected files and folders located in the root image persistent- review bind-dirs.sh](https://groups.google.com/forum/#!searchin/qubes-devel/bind-dirs|sort:relevance/qubes-devel/tcYQ4eV-XX4/J89DRLzOBQAJ) + diff --git a/configuration/config-files.md b/configuration/config-files.md index 43485c5a..388a1cb4 100644 --- a/configuration/config-files.md +++ b/configuration/config-files.md @@ -40,6 +40,9 @@ problematic device drivers. Note that scripts need to be executable (chmod +x) to be used. +Also take a look at [bind-dirs][/doc/bind-dirs] for instruction how to easily +modify arbitrary system file in AppVM and have those changes persistent. + GUI and audio configuration in dom0 =================================== From fcdfccf722c9ec737aecaea602e9207c86dc2704 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Marczykowski-G=C3=B3recki?= Date: Thu, 15 Sep 2016 14:11:56 +0200 Subject: [PATCH 161/708] bind-dirs: adjust title --- configuration/bind-dirs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/configuration/bind-dirs.md b/configuration/bind-dirs.md index 62a89fc9..94341e64 100644 --- a/configuration/bind-dirs.md +++ b/configuration/bind-dirs.md @@ -1,6 +1,6 @@ --- layout: doc -title: Bind-dirs - make persisnent changes to arbitrary system file in AppVM +title: How to make any file in a TemplateBasedVM persistent using bind-dirs permalink: /doc/bind-dirs/ redirect_from: - /en/doc/bind-dirs/ From 437ea386d5b58ffdd21d2d76d654bc9d362bdd11 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Marczykowski-G=C3=B3recki?= Date: Thu, 15 Sep 2016 14:13:21 +0200 Subject: [PATCH 162/708] bind-dirs: move to customization, add to main index --- {configuration => customization}/bind-dirs.md | 0 doc.md | 1 + 2 files changed, 1 insertion(+) rename {configuration => customization}/bind-dirs.md (100%) diff --git a/configuration/bind-dirs.md b/customization/bind-dirs.md similarity index 100% rename from configuration/bind-dirs.md rename to customization/bind-dirs.md diff --git a/doc.md b/doc.md index c7f7fca4..6c691225 100644 --- a/doc.md +++ b/doc.md @@ -152,6 +152,7 @@ Customization Guides * [Installing i3 in dom0](/doc/i3/) * [Language Localization](/doc/language-localization/) * [Dark Theme in Dom0 and DomU](/doc/dark-theme/) + * [How to make any file in a TemplateBasedVM persistent using bind-dirs](/doc/bind-dirs/) Troubleshooting From 93f0211f612776495d18ee8a06a6c698141e5483 Mon Sep 17 00:00:00 2001 From: ttasket Date: Thu, 15 Sep 2016 08:14:54 -0400 Subject: [PATCH 163/708] Update vpn.md * Scripts and text mention openvpn only in the context of examples. * Firewall commands slightly tweaked: Important blocking rules move to top. Removed superfluous check for qvpn OUTPUT rule. * Clarifications, especially mentioning that NM shouldn't be enabled for iptables/scripts option (this was causing DNS to fail for people who tried both NM and scripts). * Tells the user when and what they should test (iptables/scripts). * Change script order to enable testing flow. * Added Usage and Troubleshooting sections. https://github.com/QubesOS/qubes-issues/issues/2317 --- configuration/vpn.md | 168 ++++++++++++++++++++++++------------------- 1 file changed, 95 insertions(+), 73 deletions(-) diff --git a/configuration/vpn.md b/configuration/vpn.md index b718a9c8..117746df 100644 --- a/configuration/vpn.md +++ b/configuration/vpn.md @@ -12,9 +12,9 @@ redirect_from: How To make a VPN Gateway in Qubes ---------------------------------- -Setting up a VPN connection is really not Qubes specific and is documented in your operating system documentation. The relevant documentation for the Qubes default Guest OS (Fedora) is [Establishing a VPN Connection](https://docs.fedoraproject.org/en-US/Fedora/23/html/Networking_Guide/sec-Establishing_a_VPN_Connection.html) +Although setting up a VPN connection is not by itself Qubes specific, there are a number of Qubes-related details that can make using the connection more versatile and secure. This document is a Qubes-specific outline for choosing the type of VM to use, and shows how to prepare a ProxyVM for either NetworkManager or a set of fail-safe VPN scripts. -The Qubes specific part is to choose the right VM for the VPN client: +Please refer to guest OS and VPN service documentation when considering the specific steps and parameters for your connection(s); The relevant documentation for the Qubes default guest OS (Fedora) is [Establishing a VPN Connection.](https://docs.fedoraproject.org/en-US/Fedora/23/html/Networking_Guide/sec-Establishing_a_VPN_Connection.html) ### NetVM @@ -29,22 +29,18 @@ While the NetworkManager service is not started here (for a good reason), you ca ### ProxyVM - -**WARNING:** *You need to use Qubes 3.1-rc2 (or later)! In the previous releases the NetworkManager service was not working in ProxyVMs as expected.* ([#1052](https://github.com/QubesOS/qubes-issues/issues/1052)) - -One of the best thing in Qubes is that you can use a special type of VM called a ProxyVM (or FirewallVM). The special thing is that your AppVMs see this as a NetVM, and your NetVMs see it as an AppVM. Because of this, you can place a ProxyVM between your AppVMs and your NetVM. This is how the default FirewallVM functions. +One of the best things in Qubes is that you can use a special type of VM called a ProxyVM. The special thing is that your AppVMs see this as a NetVM (or uplink), and your NetVMs see it as a downstream AppVM. Because of this, you can place a ProxyVM between your AppVMs and your NetVM. This is how the default sys-firewall VM functions. 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 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 +Set up a ProxyVM as a VPN gateway using NetworkManager +------------------------------------------------------ -#### Using NetworkManager - -1. Create a new VM and check the ProxyVM radio button. +1. Create a new VM: Name it, click the ProxyVM radio button then choose a color and template. ![Create\_New\_VM.png](/attachment/wiki/VPN/Create_New_VM.png) @@ -60,67 +56,40 @@ Using a ProxyVM to set up a VPN client gives you the ability to: 5. Optionally, you can install some [custom icons](https://github.com/Zrubi/qubes-artwork-proxy-vpn) for your VPN -#### Using iptables and openvpn -1. Create a new VM and check the ProxyVM radio button. +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 then choose a color and template. ![Create\_New\_VM.png](/attachment/wiki/VPN/Create_New_VM.png) - If your choice of template VM doesn't already have the `openvpn` package, you'll need to install it in the template first. You may also need to `systemctl disable` any openvpn service that comes with the package if you follow the instructions for autostart below. - -2. Set up OpenVPN. - - Copy your openvpn config files to `/rw/config/openvpn/` folder. The example main config file is `openvpn-client.ovpn`. - - It should have one line that reads `dev tun`. - - If it does not contain a line `redirect-gateway def1` you may wish to add it. This will route all traffic through your vpn's network device after a connection is created. However, many VPN services will push this instruction to your client automatically -- having a line that says `client` or `pull` in your openvpn config instructs your client to use parameters specified by the VPN server. + Note: Do not enable NetworkManager, as it can interfere with the scripts' DNS features. If you used NetworkManager or other method in a previous attempt, do not re-use the old ProxyVM... Create a new one according to this step. - NOTE: If the connection breaks down all traffic will by default be routed through the upstream network device eth0 (we will stop this with iptables in step 3). + If your choice of template VM doesn't already have the VPN client software, you'll need to install the software in the template before proceeding. Disable any auto-starting service that comes with the software package: for example `sudo systemctl disable openvpn.service`. + + You may also wish to install `nano` or other simple text editor for entering the scripts below. - Also add the following to accomodate a DNS script: +2. Set up and initial test of the VPN client. - ~~~ - script-security 2 - up 'qubes-vpn-handler.sh up' - down 'qubes-vpn-handler.sh down' - ~~~ + Make sure the VPN VM and its template VM are not running. + + Run a terminal (CLI) in the VPN VM -- this will start the VM. Then make a new 'vpn' folder with `sudo mkdir /rw/config/vpn` and copy your VPN config files here (the example config filename used here is `openvpn-client.ovpn`). Files accompanying the main config such as *.crt and *.pem should also go here, and should not be referenced in the main config by absolute paths such as '/etc/...'. + + Notes about VPN config options: The VPN scripts here are intended to work with commonly used `tun` interfaces, whereas `tap` mode is untested. Also, the config should route all traffic through your VPN's interface after a connection is created; For openvpn the directive for this is `redirect-gateway def1`. Lastly, the VPN client may not be able to prompt you for credentials when connecting to the server: Creating a file in the 'vpn' folder with your credentials and using a directive such as openvpn's `auth-user-pass ` is recommended. + + __Test your client configuration:__ Run the client from a CLI prompt in the 'vpn' folder, preferably as root. For example: + ``` + sudo openvpn --cd /rw/config/vpn --config openvpn-client.ovpn + ``` + + Watch for status messages that indicate whether the connection is successful and test from another VPN VM terminal window with `ping` and `traceroute`. DNS may be tested at this point by replacing addresses in `/etc/resolv.conf` with ones appropriate for your VPN (although this file will not be used when setup is complete). Diagnose any connection problems using resources such as client documentation and help from your VPN service provider. + + Proceed to the next step when you're sure the basic VPN connection is working. -3. Set up iptables. - - Edit the firewall script with `sudo nano /rw/config/qubes-firewall-user-script` and add: - - ~~~ - #!/bin/bash - # First, block all outgoing traffic - iptables -P OUTPUT DROP - iptables -F OUTPUT - - # 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 openvpn will run as group `qvpn`. - iptables -A OUTPUT -p all -o eth0 -m owner --gid-owner qvpn \ - -m state --state NEW,ESTABLISHED -j ACCEPT - - # Allow internal system connections: - iptables -I OUTPUT -o lo -j ACCEPT - - # 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 - ~~~ - - Now save `/rw/config/qubes-firewall-user-script` and make it executable: - `sudo chmod +x /rw/config/qubes-firewall-user-script` - -4. Create the DNS-handling script. +3. Create the DNS-handling script. Use `sudo nano /rw/config/openvpn/qubes-vpn-handler.sh` to edit and add: ~~~ @@ -131,10 +100,10 @@ Using a ProxyVM to set up a VPN client gives you the ability to: case "$1" in up) - # To override DHCP DNS, assign static DNS addresses with 'setenv vpn_dns' in openvpn config; - # Format is 'X.X.X.X Y.Y.Y.Y [...]' with quotes. + # 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 options from openvpn to set DNS address translation: + # Parses DHCP foreign_option_* vars to automatically set DNS address translation: for optionname in ${!foreign_option_*} ; do option="${!optionname}" unset fops; fops=($option) @@ -164,25 +133,78 @@ Using a ProxyVM to set up a VPN client gives you the ability to: Now save the script and make it executable: `sudo chmod +x /rw/config/openvpn/qubes-vpn-handler.sh` +4. Configure client to use the DNS handling script. Using openvpn as an example, edit the config with `sudo nano /rw/config/vpn/openvpn-client.ovpn` and add these lines: + ~~~ + script-security 2 + up 'qubes-vpn-handler.sh up' + down 'qubes-vpn-handler.sh down' + ~~~ + + **Restart the client and test the connection again** ...this time from an AppVM! + +5. Set up iptables anti-leak rules. + + Edit the firewall script with `sudo nano /rw/config/qubes-firewall-user-script` then clear out the existing lines and add: + + ~~~ + #!/bin/bash + # Block forwarding of connections through upstream network device + # (in case the vpn tunnel breaks): + iptables -I FORWARD -o eth0 -j DROP + iptables -I FORWARD -i eth0 -j DROP + + # Block all outgoing traffic + iptables -P OUTPUT DROP + iptables -F OUTPUT + iptables -I OUTPUT -o lo -j ACCEPT + + # Add the `qvpn` group to system, if it doesn't already exist + if ! grep -q "^qvpn:" /etc/group ; then + groupadd -rf qvpn + sync + fi + sleep 2s + + # Allow traffic from the `qvpn` group to the uplink interface (eth0); + # Our VPN client will run with group `qvpn`. + iptables -I OUTPUT -p all -o eth0 -m owner --gid-owner qvpn -j ACCEPT + ~~~ + + Now save the script and make it executable: + `sudo chmod +x /rw/config/qubes-firewall-user-script` + 5. Set up the VPN's autostart. - Use `sudo nano /rw/config/rc.local` to edit and add: + Use `sudo nano /rw/config/rc.local` to clear out the existing lines and add: ~~~ #!/bin/bash + VPN_CLIENT='openvpn' + VPN_OPTIONS='--cd /rw/config/vpn/ --config openvpn-client.ovpn --daemon' + + su - -c 'notify-send "$(hostname): Starting $VPN_CLIENT..." --icon=network-idle' user groupadd -rf qvpn ; sleep 2s - sg qvpn -c 'openvpn --cd /rw/config/openvpn/ --config openvpn-client.ovpn \ - --daemon --writepid /var/run/openvpn/openvpn-client.pid' + sg qvpn -c "$VPN_CLIENT $VPN_OPTIONS" ~~~ + + Change the `VPN_CLIENT` and `VPN_OPTIONS` variables to match your VPN software. Now save the script and make it executable: `sudo chmod +x /rw/config/rc.local` -6. Restart the new VM! +6. Restart the new VM! The link should then be established automatically with a popup notification to that effect. -7. Configure your AppVMs to use the new VM as a NetVM. +Usage +----- + +Configure your AppVMs to use the VPN VM as a NetVM... ![Settings-NetVM.png](/attachment/wiki/VPN/Settings-NetVM.png) -8. Optionally, you can install some [custom icons](https://github.com/Zrubi/qubes-artwork-proxy-vpn) for your VPN +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. From ddc59df4ae1d29db3931734482152c3405f69484 Mon Sep 17 00:00:00 2001 From: Kewde Date: Thu, 15 Sep 2016 18:07:58 +0000 Subject: [PATCH 164/708] Add nouveau disable instructions --- troubleshooting/nvidia-troubleshooting.md | 67 +++++++++++++++++++++++ 1 file changed, 67 insertions(+) diff --git a/troubleshooting/nvidia-troubleshooting.md b/troubleshooting/nvidia-troubleshooting.md index deb2ea98..8c5cc8fb 100644 --- a/troubleshooting/nvidia-troubleshooting.md +++ b/troubleshooting/nvidia-troubleshooting.md @@ -71,3 +71,70 @@ If you see a terminal window in the top left corner, it means you most likely su 1. Reboot and let the system boot from the normal boot configuration. You should be able to use X under Xen now. + +Disabling Nouveau +--------------------- +If Qubes fails to properly boot after the GRUB Boot menu and displays messages starting with `nouveau` then it means that the nouveau driver failed to launch properly. + +One way to get rid of it is by disabling nouveau. + +Example error +~~~ +nouveau E[ PGRAPH][0000:01:00.0] grctx template channel unload timeout +nouveau E[ PGRAPH][0000:01:00.0] failed to construct context +nouveau E[ PGRAPH][0000:01:00.0] init failed, -16 +~~~ + +0. In the case that you only have an external monitor it is advised to hook it up to the connector directly connected to the motherboard if it is present. + +1. Verify that that GRUB Boot Menu is displaying, you should be presented with two options and a progressbar/timer than goes rather fast. +~~~ +Qubes +Qubes with advanced Xen options +~~~ + +2. Quickly press the "E" key before the time is up. + +3. An editor will open up that will allow you to temporarily change the grub options for the next boot. + +4. Press the down arrow key and move the cursor to the line after the line with the kernel options. The line with the kernel options might look something like, I didn't type everything as it may differ from system to system but it should look something like this: + +~~~ +module /vmlinux-4.1.13-9.pvops.qubes.x86_64 placeholder root=/dev/mapper/qubes_dom0-root ro ... rhgb quiet +~~~ + +Please note: chose the module that starts with `vmlinux`! + +5. Press the left/right arrow keys to position the cursor at the end of kernel options line, after `rhgb quiet` in this case. + +6. Add the following: +~~~ +nouveau.modeset=0 rd.driver.blacklist=nouveau video=vesa:off +~~~ +This will tempororarily disable nouveau until boot. + +7. Press either the F10 key or Ctrl+X to start the boot process. + +Qubes should now boot properly, if that's the case then we should make this change permanent such that the GRUB config knows to not run nouveau. + +To make this change persistent, so your boot will always work properly you'll have to do the following + +1. Open a terminal (do this vb clicking on Q > 'run command' > type 'terminal' and hit enter) + +2. type following commands: +~~~ +cd /etc/default/ +sudo nano grub +~~~ + +3. Edit `GRUB_CMDLINE_LINUX`, add the following to it at the end: +~~~ +nouveau.modeset=0 rd.driver.blacklist=nouveau video=vesa:off +~~~ + +4. ctrl + X and then y to save the file. + +5. The final step is to compile the configuration file to something the bootloader can read. +~~~ +sudo grub2-mkconfig -o /boot/grub2/grub.cfg +~~~ From f1e091e1460a56b0934379e529454ac956a9f456 Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Thu, 15 Sep 2016 13:14:38 -0700 Subject: [PATCH 165/708] Add title and fix heading levels --- customization/bind-dirs.md | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/customization/bind-dirs.md b/customization/bind-dirs.md index 94341e64..7a8a1eb7 100644 --- a/customization/bind-dirs.md +++ b/customization/bind-dirs.md @@ -6,20 +6,22 @@ redirect_from: - /en/doc/bind-dirs/ --- -# What is bind-dirs.sh? # +# How to make any file in a TemplateBasedVM persistent using bind-dirs # + +## What is bind-dirs.sh? ## With [bind-dirs.sh](https://github.com/QubesOS/qubes-core-agent-linux/blob/master/vm-systemd/bind-dirs.sh) you can make arbitrary files or folders persistent in TemplateBasedVMs. -# What is it useful for? # +## What is it useful for? ## For example, it is useful for Whonix, sys-whonix, where [Tor's data dir /var/lib/tor has been made persistent in the TemplateBased ProxyVM sys-whonix](https://github.com/Whonix/qubes-whonix/blob/8438d13d75822e9ea800b9eb6024063f476636ff/usr/lib/qubes-bind-dirs.d/40_qubes-whonix.conf#L5). So sys-whonix does not require to be a StandaloneVM. And therefore can benefit from the Tor anonymity feature 'persistent Tor entry guards' without the overhead of a StandaloneVM. -# Minimum Qubes Version # +## Minimum Qubes Version ## bind-dirs.sh works with Qubes R3.2 and above. -# How to use bind-dirs.sh? # +## How to use bind-dirs.sh? ## 1) Create a file `/rw/config/qubes-bind-dirs.d/50_user.conf` with root rights inside a VM. @@ -35,20 +37,20 @@ binds+=( '/var/lib/tor' ) 5) Done. -# Other Configuration Folders # +## Other Configuration Folders ## * `/usr/lib/qubes-bind-dirs.d` (lowest priority, for packages) * `/etc/qubes-bind-dirs.d` (intermediate priority, for template wide configuration) * `/rw/config/qubes-bind-dirs.d` (highest priority, for per VM configuration) -# Limitations # +## Limitations ## * Files that exist in the TempalteVM root image cannot be made deleted in the TemlateBasedVMs root image using bind-dirs.sh. * Does not work if the file / folder in question does not already exist in the root image. I.e. a file that does not exist in the root image cannot be bind mounted in the TemplateBasedVM. * Re-running `sudo /usr/lib/qubes/bind-dirs.sh` without previous `sudo /usr/lib/qubes/bind-dirs.sh umount` does not work. * Running 'sudo /usr/lib/qubes/bind-dirs.sh umount' after boot (before shutdown) is probably not sane and nothing can be done about that. -# How to remove binds from bind-dirs.sh? # +## How to remove binds from bind-dirs.sh? ## `binds` is actually just a bash variable (an array) and the bind-dirs.sh configuration folders are `source`d as bash snippets in lexical order. Therefore if you wanted to remove an existing entry from the `binds` array, you could do that by using a lexically higher configuration file. For example, if you wanted to make `/var/lib/tor` non-persistant in `sys-whonix` without manually editing [`/usr/lib/qubes-bind-dirs.d/40_qubes-whonix.conf`](https://github.com/Whonix/qubes-whonix/blob/master/usr/lib/qubes-bind-dirs.d/40_qubes-whonix.conf), you could use the following. @@ -60,7 +62,7 @@ binds=( "${binds[@]/'/var/lib/tor'}" ) (Editing `/usr/lib/qubes-bind-dirs.d/40_qubes-whonix.conf` directly is recommended against, since such changes get lost when that file is changed in the package on upgrades.) -# Discussion # +## Discussion ## [TemplateBasedVMs: make selected files and folders located in the root image persistent- review bind-dirs.sh](https://groups.google.com/forum/#!searchin/qubes-devel/bind-dirs|sort:relevance/qubes-devel/tcYQ4eV-XX4/J89DRLzOBQAJ) From ed11064a60370774b3323ce102ae3e377469a0d0 Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Thu, 15 Sep 2016 13:20:30 -0700 Subject: [PATCH 166/708] Fix Markdown formatting --- customization/bind-dirs.md | 18 ++++++++---------- 1 file changed, 8 insertions(+), 10 deletions(-) diff --git a/customization/bind-dirs.md b/customization/bind-dirs.md index 7a8a1eb7..c244e7ad 100644 --- a/customization/bind-dirs.md +++ b/customization/bind-dirs.md @@ -23,19 +23,17 @@ bind-dirs.sh works with Qubes R3.2 and above. ## How to use bind-dirs.sh? ## -1) Create a file `/rw/config/qubes-bind-dirs.d/50_user.conf` with root rights inside a VM. +1. Create a file `/rw/config/qubes-bind-dirs.d/50_user.conf` with root rights inside a VM. -2) Append a folder or file to the `binds` variable. In the following example we are using folder `/var/lib/tor`. You can replace that folder with a folder or file of your choice. +2. Append a folder or file to the `binds` variable. In the following example we are using folder `/var/lib/tor`. You can replace that folder with a folder or file of your choice. -``` -binds+=( '/var/lib/tor' ) -``` + binds+=( '/var/lib/tor' ) -3) Save. +3. Save. -4) Reboot the VM. +4. Reboot the VM. -5) Done. +5. Done. ## Other Configuration Folders ## @@ -56,9 +54,9 @@ binds+=( '/var/lib/tor' ) `/rw/config/qubes-bind-dirs.d/50_user.conf` -``` +~~~ binds=( "${binds[@]/'/var/lib/tor'}" ) -``` +~~~ (Editing `/usr/lib/qubes-bind-dirs.d/40_qubes-whonix.conf` directly is recommended against, since such changes get lost when that file is changed in the package on upgrades.) From 28ec0003414dfc7553e993a0867169ee90214dbe Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Thu, 15 Sep 2016 13:21:04 -0700 Subject: [PATCH 167/708] Fix discussion link --- customization/bind-dirs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/customization/bind-dirs.md b/customization/bind-dirs.md index c244e7ad..c4074994 100644 --- a/customization/bind-dirs.md +++ b/customization/bind-dirs.md @@ -62,5 +62,5 @@ binds=( "${binds[@]/'/var/lib/tor'}" ) ## Discussion ## -[TemplateBasedVMs: make selected files and folders located in the root image persistent- review bind-dirs.sh](https://groups.google.com/forum/#!searchin/qubes-devel/bind-dirs|sort:relevance/qubes-devel/tcYQ4eV-XX4/J89DRLzOBQAJ) +[TemplateBasedVMs: make selected files and folders located in the root image persistent- review bind-dirs.sh](https://groups.google.com/forum/#!topic/qubes-devel/tcYQ4eV-XX4/discussion) From abfdb2939339a263aa59ae53d63632cfa053b7e2 Mon Sep 17 00:00:00 2001 From: ttasket Date: Fri, 16 Sep 2016 07:30:30 -0400 Subject: [PATCH 168/708] Update vpn.md Elaborate note about NM, and fix paths in step 3. --- configuration/vpn.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/configuration/vpn.md b/configuration/vpn.md index 117746df..54d4dfdb 100644 --- a/configuration/vpn.md +++ b/configuration/vpn.md @@ -66,7 +66,7 @@ This method is more involved than the one above, but has anti-leak features that ![Create\_New\_VM.png](/attachment/wiki/VPN/Create_New_VM.png) - Note: Do not enable NetworkManager, as it can interfere with the scripts' DNS features. If you used NetworkManager or other method 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 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`. @@ -90,7 +90,7 @@ This method is more involved than the one above, but has anti-leak features that 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/openvpn/qubes-vpn-handler.sh` to edit and add: + Use `sudo nano /rw/config/vpn/qubes-vpn-handler.sh` to edit and add: ~~~ #!/bin/bash @@ -131,7 +131,7 @@ This method is more involved than the one above, but has anti-leak features that ~~~ Now save the script and make it executable: - `sudo chmod +x /rw/config/openvpn/qubes-vpn-handler.sh` + `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: ~~~ From e00b3e301918fc4a93c2eb70df38726a636ca1ef Mon Sep 17 00:00:00 2001 From: Kewde Date: Fri, 16 Sep 2016 12:14:42 +0000 Subject: [PATCH 169/708] Update nvidia-troubleshooting.md --- troubleshooting/nvidia-troubleshooting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/troubleshooting/nvidia-troubleshooting.md b/troubleshooting/nvidia-troubleshooting.md index 8c5cc8fb..ebe4335c 100644 --- a/troubleshooting/nvidia-troubleshooting.md +++ b/troubleshooting/nvidia-troubleshooting.md @@ -85,7 +85,7 @@ nouveau E[ PGRAPH][0000:01:00.0] failed to construct context nouveau E[ PGRAPH][0000:01:00.0] init failed, -16 ~~~ -0. In the case that you only have an external monitor it is advised to hook it up to the connector directly connected to the motherboard if it is present. +Tip: In the case that you only have an external monitor it is advised to hook it up to the connector directly connected to the motherboard if it is present, this should bypass the graphics card. 1. Verify that that GRUB Boot Menu is displaying, you should be presented with two options and a progressbar/timer than goes rather fast. ~~~ From 8762fba8856efb6e7da47a59077a9042811c1a7b Mon Sep 17 00:00:00 2001 From: Kewde Date: Fri, 16 Sep 2016 19:48:48 +0000 Subject: [PATCH 170/708] Bring more structure to the page Page was optimized to work with one bug only, added a few headers. --- troubleshooting/nvidia-troubleshooting.md | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/troubleshooting/nvidia-troubleshooting.md b/troubleshooting/nvidia-troubleshooting.md index ebe4335c..9451e2ec 100644 --- a/troubleshooting/nvidia-troubleshooting.md +++ b/troubleshooting/nvidia-troubleshooting.md @@ -13,10 +13,17 @@ NVidia Troubleshooting Guide If you have an NVidia graphics card it will probably not work under Xen out of the box. If your system freezes during boot and you don't see the graphical login manager after you installed Xen, then this problem most likely affects you. The following steps should provide a work around so that you should be able to use your NVidia with X under Xen, however without any fancy "desktop effects". +Boot in failsafe +--------------------- + 1. Boot your system using the "failsafe" boot menu, that should have been automatically added to your `grub.conf` when you installed the Dom0 kernel. If the X Window System doesn't start now, this is probably a non-Xen related issue and this guide will probably not help you. + +Configure X with nouveau +--------------------- + Assuming your X Window System works fine now when you booted from the "failsafe" configuration, do the next steps... 1. Do not log into X, but instead switch to a text console (press Ctrl-Alt-F2) @@ -74,9 +81,9 @@ If you see a terminal window in the top left corner, it means you most likely su Disabling Nouveau --------------------- -If Qubes fails to properly boot after the GRUB Boot menu and displays messages starting with `nouveau` then it means that the nouveau driver failed to launch properly. +If Qubes fails to properly boot after the GRUB Boot menu and you get a black screen that displays messages starting with `nouveau` then it means that the nouveau driver failed to launch properly. -One way to get rid of it is by disabling nouveau. +One way to get rid of this for now is to disable nouveau. Example error ~~~ From 1a62109f1817e02d36decbbe21d3100d18bfeb28 Mon Sep 17 00:00:00 2001 From: bkerlin Date: Fri, 16 Sep 2016 17:58:36 -0400 Subject: [PATCH 171/708] Update hvm.md --- managing-os/hvm.md | 42 +++++++++++++++++++++--------------------- 1 file changed, 21 insertions(+), 21 deletions(-) diff --git a/managing-os/hvm.md b/managing-os/hvm.md index 3017ae9c..4c366eda 100644 --- a/managing-os/hvm.md +++ b/managing-os/hvm.md @@ -15,20 +15,20 @@ Creating and using HVM (fully virtualized) domains What are HVM domains? --------------------- -HVM domains (Hardware VM), in contrast to PV domains (Paravirtualized domains), allow to create domains based on any OS, if one only has its installation ISO. E.g. this allows to have Windows-based VMs in Qubes. +HVM domains (Hardware VM), in contrast to PV domains (Paravirtualized domains), allow one to create domains based on any OS for which one has an installation ISO. For example, this allows one to have Windows-based VMs in Qubes. -Interested readers might want to check [this article](http://theinvisiblethings.blogspot.com/2012/03/windows-support-coming-to-qubes.html) to learn why it took so long for Qubes OS to support HVM domains (Qubes 1 only supported Linuxed-based PV domains). +Interested readers might want to check [this article](http://theinvisiblethings.blogspot.com/2012/03/windows-support-coming-to-qubes.html) to learn why it took so long for Qubes OS to support HVM domains (Qubes 1 only supported Linux based PV domains). Creating an HVM domain ---------------------- -First, lets create a new HVM domain (use the --hvm switch to qvm-create, or choose HVM type in the Qubes Manager VM creation dialog box): +First, lets create a new HVM domain. Use the --hvm switch to qvm-create, or choose HVM type in the Qubes Manager VM creation dialog box: ~~~ qvm-create win7 --hvm --label green ~~~ -(Of course, the name of the domain ("win7"), as well as it's label ("green"), are just exemplary). +(The name of the domain ("win7") as well as it's label ("green") are just exemplary of course). If you receive an error like this one, then you must first enable VT-x in your BIOS: @@ -36,58 +36,58 @@ If you receive an error like this one, then you must first enable VT-x in your B libvirt.libvirtError: invalid argument: could not find capabilities for arch=x86_64 ~~~ -Now, we need to install an OS inside this VM, this can done by attaching an installation ISO upon starting the VM (this currently can be done only from command line, but in the future we surely will added an option to do this also from the manager): +Now we need to install an OS inside this VM. This can done by attaching an installation ISO to and starting the VM (this can currently only be done from command line, but in the future we will surely add an option to do this also from the manager): ~~~ qvm-start win7 --cdrom=/usr/local/iso/win7_en.iso ~~~ -The command above assumes the installation ISO was somehow transferred to Dom0, e.g. copied using `dd` command from an installation CDROM. If one wishes to use the actual physical media without copying it first to a file, then one can just pass `/dev/cdrom` as an argument to `--cdrom`: +The above command assumes the installation ISO was transferred to Dom0 (copied using `dd` command from an installation CDROM for example). If one wishes to use the actual physical media without copying it first to a file, then one can just pass `/dev/cdrom` as an argument to `--cdrom`: ~~~ qvm-start win7 --cdrom=/dev/cdrom ~~~ -Now, the VM will start booting from the attached CDROM device, which in the example above just happens to be the Windows 7 installation disk. Depending on the OS that is being installed in the VM, one might be required to start the VM several times (as is the case e.g. with Windows 7 installation), because whenever the installer wants to "reboot the system", it actually shutdowns the VM (and Qubes won't automatically start it), so several invocations of qvm-start command (as shown above) might be needed. +Next the VM will start booting from the attached CDROM device (which in the example above just happens to be a Windows 7 installation disk). Depending on the OS that is being installed in the VM one might be required to start the VM several times (as is the case with Windows 7 installations), because whenever the installer wants to "reboot the system" it actually shutdowns the VM and Qubes won't automatically start it. Several invocations of qvm-start command (as shown above) might be needed. [![r2b1-win7-installing.png](/attachment/wiki/HvmCreate/r2b1-win7-installing.png)](/attachment/wiki/HvmCreate/r2b1-win7-installing.png) Using Installation ISOs located in other VMs -------------------------------------------- -Sometimes one wants to download the installation ISO from the Web and use it for HVM creation. However, for security reasons, networking is disabled for Qubes Dom0, which makes it not possible to download an ISO within Dom0. Also Qubes do not provide any (easy to use) mechanisms for copying files between AppVMs and Dom0, and generally tries to discourage such actions. So, it would be inconvenient to require that the installation ISO for an HVM domain be always located in Dom0. And the good news is that this is indeed not required -- one can use the following syntax when specifying the location of /usr/local/iso/win7\_en.iso the installation ISO: +Sometimes one wants to download the installation ISO from the Web and use it for HVM creation. For security reasons, networking is disabled for Qubes Dom0, which makes it impossible to download an ISO within Dom0. Qubes also does not provide any easy to use mechanisms for copying files between AppVMs and Dom0 and generally tries to discourage such actions. Due to these factors it would be inconvenient to require that the installation ISO for an HVM domain be always located in Dom0. The good news, however, is that this is indeed not required. One can use the following syntax when specifying the location of an installation ISO (such as the Windows 7 installation ISO): ~~~ --cdrom=[appvm]:[/path/to/iso/within/appvm] ~~~ -Assuming e.g. the an installation ISO named `ubuntu-12.10-desktop-i386.iso` has been downloaded in `work-web` AppVM, and located within `/home/user/Downloads` directory within this AppVM, one can immediately create a new HVM and use this ISO as an installation media with the following command (issued in Dom0, of course): +Assuming that an installation ISO named `ubuntu-12.10-desktop-i386.iso` has been downloaded in `work-web` AppVM and is located within the `/home/user/Downloads` directory within this AppVM, one can immediately create a new HVM using this ISO as an installation media with the following command issued in Dom0: ~~~ qvm-create --hvm ubuntu --label red qvm-start ubuntu --cdrom=work-web:/home/user/Downloads/ubuntu-12.10-desktop-i386.iso ~~~ -Of course the AppVM where the ISO is kept must also be running for this to work (this VM is now serving the ISO and acting as a disk backend). +The AppVM where the ISO is kept must be running for this to work as this VM is now serving the ISO and acting as a disk backend. ![r2b1-installing-ubuntu-1.png](/attachment/wiki/HvmCreate/r2b1-installing-ubuntu-1.png) Setting up networking for HVM domains ------------------------------------- -Just like standard (paravirtualized) AppVMs, the HVM domains got fixed IP addresses centrally assigned by Qubes. Normally Qubes agent scripts, running within each AppVM, are responsible for setting up networking within the VM according the configuration created by Qubes. Such centrally managed networking infrastructure allows for [advanced networking configuration](http://theinvisiblethings.blogspot.com/2011/09/playing-with-qubes-networking-for-fun.html). +Just like standard paravirtualized AppVMs, the HVM domains get fixed IP addresses centrally assigned by Qubes. Normally Qubes agent scripts running within each AppVM are responsible for setting up networking within the VM according the configuration created by Qubes. Such centrally managed networking infrastructure allows for [advanced networking configuration](http://theinvisiblethings.blogspot.com/2011/09/playing-with-qubes-networking-for-fun.html). -However, a generic HVM domain, e.g. a standard Windows or Ubuntu installation, has (at least initially) no Qubes agent scripts running inside it, and thus requires manual networking configuration, so that it match the values assigned by Qubes for this domain. +A generic HVM domain such as a standard Windows or Ubuntu installation, however, has no Qubes agent scripts running inside it initially and thus requires manual networking configuration so that it match the values assigned by Qubes for this domain. -Even though we do have a small DHCP server (that runs inside HVM untrusted stub domain) to make the manual network configuration not necessary for many VMs, this won't work for most modern Linux distributions which contain Xen networking PV drivers built in (but not Qubes tools) and which bypass the stub-domain networking (their net frontends connect directly to the net backend in the netvm), and so our DHCP server is not useful. +Even though we do have a small DHCP server that runs inside HVM untrusted stub domain to make the manual network configuration not necessary for many VMs, this won't work for most modern Linux distributions which contain Xen networking PV drivers (but not Qubes tools) built in which bypass the stub-domain networking (their net frontends connect directly to the net backend in the netvm). In this instance our DHCP server is not useful. In order to manually configure networking in a VM, one should first find out the IP/netmask/gateway assigned to the particular VM by Qubes. This can be seen e.g. in the Qubes Manager in the VM's properties: ![r2b1-manager-networking-config.png](/attachment/wiki/HvmCreate/r2b1-manager-networking-config.png) -Alternatively, one can use `qvm-ls -n` command to obtain the same information. +Alternatively, one can use `qvm-ls -n` command to obtain the same information. One should configure the networking within the HVM according to those settings (IP/netmask/gateway). One should set DNS addresses to the same IP as gateway. -Now, one should configure the networking within the HVM according to those settings (IP/netmask/gateway). Only IPv4 networking is currently supported in Qubes. Set DNS address to the same IP as gateway. +Only IPv4 networking is currently supported in Qubes. **Note:** If one plans on installing Qubes Tools for Windows guests (see below) it is 'not' necessary to configure networking manually as described in this section, because the tools will take care of setting the networking automatically for such Windows domains. @@ -99,9 +99,9 @@ Please see our dedicated page on [installing and using Windows-based AppVMs](/do Cloning HVM domains ------------------- -Just like normal AppVMs, the HVM domains can also be cloned, either using a command-line `qvm-clone` command, or via manager's 'Clone VM' option in the right-click menu. +Just like normal AppVMs, the HVM domains can also be cloned either using a command-line `qvm-clone` command or via manager's 'Clone VM' option in the right-click menu. -The cloned VM will get identical root and private image, and essentially will be identical to the original VM, except that it will get a different MAC address for the networking interface: +The cloned VM will get identical root and private image and will essentially be an identical of the original VM except that it will get a different MAC address for the networking interface: ~~~ [joanna@dom0 ~]$ qvm-prefs win7 @@ -157,7 +157,7 @@ drive : None timezone : localtime ~~~ -Note how the MAC addresses differ between those two, otherwise identical VMs. Of course, the IP addresses, assigned by Qubes, will also be different, to allow networking to function properly: +Note how the MAC addresses differ between those two otherwise identical VMs. The IP addresses assigned by Qubes will also be different of course to allow networking to function properly: ~~~ [joanna@dom0 ~]$ qvm-ls -n @@ -167,7 +167,7 @@ Note how the MAC addresses differ between those two, otherwise identical VMs. Of /.../ ~~~ -If, for any reason, one would like to make sure that the two VMs have the same MAC address, one can use qvm-prefs to set a fixed MAC address for the VM: +If for any reason one would like to make sure that the two VMs have the same MAC address, one can use qvm-prefs to set a fixed MAC address for the VM: ~~~ [joanna@dom0 ~]$ qvm-prefs win7-copy -s mac 00:16:3E:5E:6C:05 @@ -196,7 +196,7 @@ drive : None timezone : localtime ~~~ -Please note that as of now Qubes does not support shared templates for HVM domains. This means that HVM domains cloned this way will have two separate copies of the whole filesystems. This has consequences in taking much more disk space compared to standard AppVMs that share the root fs with the Template VM. Another consequence is that it's probably not legal to clone a proprietary OS, such as Windows this way, unless your license specifically allows for that (even though Windows Activation won't complain when one sets identical MAC address for the cloned VMs, it's doubtful practice at best). +Please note that as of now Qubes does not support shared templates for HVM domains. This means that HVM domains cloned this way will have two separate copies of the whole filesystem. This has consequences in taking much more disk space when compared to standard AppVMs that share the root filesystem with the Template VM. Another consequence is that it's probably not legal to clone a proprietary OS (such as Windows) this way unless your license specifically allows for that (even though Windows Activation won't complain when one sets identical MAC address for the cloned VMs, it's doubtful practice at best). In the near future we plan on introducing shared template also for HVM domains, hopefully solving the problems described above. @@ -210,7 +210,7 @@ Assigning PCI devices to HVM domains HVM domains (including Windows VMs) can be [assigned PCI devices](/doc/assigning-devices/) just like normal AppVMs. E.g. one can assign one of the USB controllers to the Windows VM and should be able to use various devices that require Windows software, such as phones, electronic devices that are configured via FTDI, etc. -Once problem, however, at the moment, is that after the whole system gets suspend into S3 sleep, and subsequently resumed, such attached devices stop working and should be restarted within the VM. Under Windows this can be achieved by opening the Device Manager, selecting the actual device, such as a USB controller, and then first 'Disabling', and then 'Enabling' the device again. This is illustrated on the screenshot below: +One problem at the moment however, is that after the whole system gets suspended into S3 sleep and subsequently resumed, some attached devices may stop working and should be restarted within the VM. This can be achieved under a Windows HVM by opening the Device Manager, selecting the actual device (such as a USB controller), 'Disabling' the device, and then 'Enabling' the device again. This is illustrated on the screenshot below: [![r2b1-win7-usb-disable.png](/attachment/wiki/HvmCreate/r2b1-win7-usb-disable.png)](/attachment/wiki/HvmCreate/r2b1-win7-usb-disable.png) From fbbe1394320117f4d6ac7d2c047b4e209d49f915 Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Sat, 17 Sep 2016 02:49:39 -0700 Subject: [PATCH 172/708] Fix code block and image QubesOS/qubes-issues#2317 --- configuration/vpn.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/configuration/vpn.md b/configuration/vpn.md index 54d4dfdb..5a507352 100644 --- a/configuration/vpn.md +++ b/configuration/vpn.md @@ -134,6 +134,7 @@ This method is more involved than the one above, but has anti-leak features that `sudo chmod +x /rw/config/vpn/qubes-vpn-handler.sh` 4. Configure client to use the DNS handling script. Using openvpn as an example, edit the config with `sudo nano /rw/config/vpn/openvpn-client.ovpn` and add these lines: + ~~~ script-security 2 up 'qubes-vpn-handler.sh up' @@ -199,7 +200,7 @@ Usage Configure your AppVMs to use the VPN VM as a NetVM... - ![Settings-NetVM.png](/attachment/wiki/VPN/Settings-NetVM.png) +![Settings-NetVM.png](/attachment/wiki/VPN/Settings-NetVM.png) Troubleshooting --------------- From a4d1c56a1dd16b7343a28fd46af600f721080fe3 Mon Sep 17 00:00:00 2001 From: Kewde Date: Sat, 17 Sep 2016 16:07:55 +0000 Subject: [PATCH 173/708] Update nvidia-troubleshooting.md --- troubleshooting/nvidia-troubleshooting.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/troubleshooting/nvidia-troubleshooting.md b/troubleshooting/nvidia-troubleshooting.md index 9451e2ec..af864941 100644 --- a/troubleshooting/nvidia-troubleshooting.md +++ b/troubleshooting/nvidia-troubleshooting.md @@ -92,7 +92,9 @@ nouveau E[ PGRAPH][0000:01:00.0] failed to construct context nouveau E[ PGRAPH][0000:01:00.0] init failed, -16 ~~~ -Tip: In the case that you only have an external monitor it is advised to hook it up to the connector directly connected to the motherboard if it is present, this should bypass the graphics card. +Tip: In the case that you only have an external monitor it is advised to hook it up to the connector directly connected to the motherboard if it is present, this should bypass the nvidia graphics card. + +If you're seeing this error than that means another graphics card (most likely an integrated one) acted as failsafe. Disabling nouveau has the consequences of disabling nvidia support all together. 1. Verify that that GRUB Boot Menu is displaying, you should be presented with two options and a progressbar/timer than goes rather fast. ~~~ From 3a9cbd7b8a39c22a261c051b8d24bf0818cf91ec Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Sat, 17 Sep 2016 14:00:55 -0700 Subject: [PATCH 174/708] Add QSB 25 --- security/security-bulletins.md | 1 + 1 file changed, 1 insertion(+) diff --git a/security/security-bulletins.md b/security/security-bulletins.md index 119da338..fa4b0769 100644 --- a/security/security-bulletins.md +++ b/security/security-bulletins.md @@ -66,4 +66,5 @@ Qubes Security Bulletins are published through the [Qubes Security Pack](/doc/se ---- - [Qubes Security Bulletin \#24](https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-024-2016.txt) (Critical Xen bug in PV memory virtualization code (XSA 182)) +- [Qubes Security Bulletin \#25](https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-025-2016.txt) (Xen bug in event channel handling code (XSA 188)) From 1a828a1c3825fe34fb86ef33a88b26078437980b Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Sat, 17 Sep 2016 17:19:42 -0700 Subject: [PATCH 175/708] Fix formatting throughout --- troubleshooting/nvidia-troubleshooting.md | 134 ++++++++++++---------- 1 file changed, 71 insertions(+), 63 deletions(-) diff --git a/troubleshooting/nvidia-troubleshooting.md b/troubleshooting/nvidia-troubleshooting.md index af864941..0386dba4 100644 --- a/troubleshooting/nvidia-troubleshooting.md +++ b/troubleshooting/nvidia-troubleshooting.md @@ -16,7 +16,7 @@ If you have an NVidia graphics card it will probably not work under Xen out of t Boot in failsafe --------------------- -1. Boot your system using the "failsafe" boot menu, that should have been automatically added to your `grub.conf` when you installed the Dom0 kernel. +Boot your system using the "failsafe" boot menu, that should have been automatically added to your `grub.conf` when you installed the Dom0 kernel. If the X Window System doesn't start now, this is probably a non-Xen related issue and this guide will probably not help you. @@ -26,57 +26,57 @@ Configure X with nouveau Assuming your X Window System works fine now when you booted from the "failsafe" configuration, do the next steps... -1. Do not log into X, but instead switch to a text console (press Ctrl-Alt-F2) + 1. Do not log into X, but instead switch to a text console (press Ctrl-Alt-F2) -1. Log in as root + 2. Log in as root -1. Switch to runlevel 3 (this should kill your X server): + 3. Switch to runlevel 3 (this should kill your X server): -~~~ -init 3 -~~~ + ~~~ + init 3 + ~~~ -1. Run X-autoconfiguration: + 4. Run X-autoconfiguration: -~~~ -Xorg -configure -~~~ + ~~~ + Xorg -configure + ~~~ -This should generate a file `xorg.conf.new` in the `/root` directory. + This should generate a file `xorg.conf.new` in the `/root` directory. -In most cases you can ignore any warning or error messages displayed by the X server, assuming it generated the xorg.conf.new file. + In most cases you can ignore any warning or error messages displayed by the X server, assuming it generated the xorg.conf.new file. -1. Edit this newly generated `xorg.conf.new` file and introduce the following two modifications: + 5. Edit this newly generated `xorg.conf.new` file and introduce the following two modifications: -- Uncomment the ShadowFB option, so that you should now have something like this: + First, uncomment the ShadowFB option, so that you should now have something like this: ~~~ Option "ShadowFB" # [] ~~~ -- Change the driver name to `nouveau` (you will probably have `nv` written there): + Second, change the driver name to `nouveau` (you will probably have `nv` written there): ~~~ Driver "nouveau" ~~~ -Save the modification, exit the editor. + Save the modification, exit the editor. -1. Move the file to `/etc/X11` and rename it as `xorg.conf`: + 6. Move the file to `/etc/X11` and rename it as `xorg.conf`: -~~~ -mv /root/xorg.conf.new /etc/X11/xorg.conf -~~~ + ~~~ + mv /root/xorg.conf.new /etc/X11/xorg.conf + ~~~ -1. Verify that X will work with those new settings: + 7. Verify that X will work with those new settings: -~~~ -xinit -~~~ + ~~~ + xinit + ~~~ -If you see a terminal window in the top left corner, it means you most likely succeeded, even if your keyboard or mouse do not work now (don't worry about them). + If you see a terminal window in the top left corner, it means you most likely succeeded, even if your keyboard or mouse do not work now (don't worry about them). -1. Reboot and let the system boot from the normal boot configuration. You should be able to use X under Xen now. + 8. Reboot and let the system boot from the normal boot configuration. You should be able to use X under Xen now. Disabling Nouveau @@ -86,6 +86,7 @@ If Qubes fails to properly boot after the GRUB Boot menu and you get a black scr One way to get rid of this for now is to disable nouveau. Example error + ~~~ nouveau E[ PGRAPH][0000:01:00.0] grctx template channel unload timeout nouveau E[ PGRAPH][0000:01:00.0] failed to construct context @@ -96,54 +97,61 @@ Tip: In the case that you only have an external monitor it is advised to hook it If you're seeing this error than that means another graphics card (most likely an integrated one) acted as failsafe. Disabling nouveau has the consequences of disabling nvidia support all together. -1. Verify that that GRUB Boot Menu is displaying, you should be presented with two options and a progressbar/timer than goes rather fast. -~~~ -Qubes -Qubes with advanced Xen options -~~~ + 1. Verify that that GRUB Boot Menu is displaying, you should be presented with two options and a progressbar/timer than goes rather fast. -2. Quickly press the "E" key before the time is up. + ~~~ + Qubes + Qubes with advanced Xen options + ~~~ -3. An editor will open up that will allow you to temporarily change the grub options for the next boot. + 2. Quickly press the "E" key before the time is up. -4. Press the down arrow key and move the cursor to the line after the line with the kernel options. The line with the kernel options might look something like, I didn't type everything as it may differ from system to system but it should look something like this: + 3. An editor will open up that will allow you to temporarily change the grub options for the next boot. -~~~ -module /vmlinux-4.1.13-9.pvops.qubes.x86_64 placeholder root=/dev/mapper/qubes_dom0-root ro ... rhgb quiet -~~~ + 4. Press the down arrow key and move the cursor to the line after the line with the kernel options. The line with the kernel options might look something like, I didn't type everything as it may differ from system to system but it should look something like this: -Please note: chose the module that starts with `vmlinux`! + ~~~ + module /vmlinux-4.1.13-9.pvops.qubes.x86_64 placeholder root=/dev/mapper/qubes_dom0-root ro ... rhgb quiet + ~~~ -5. Press the left/right arrow keys to position the cursor at the end of kernel options line, after `rhgb quiet` in this case. + Please note: chose the module that starts with `vmlinux`! -6. Add the following: -~~~ -nouveau.modeset=0 rd.driver.blacklist=nouveau video=vesa:off -~~~ -This will tempororarily disable nouveau until boot. + 5. Press the left/right arrow keys to position the cursor at the end of kernel options line, after `rhgb quiet` in this case. -7. Press either the F10 key or Ctrl+X to start the boot process. + 6. Add the following: -Qubes should now boot properly, if that's the case then we should make this change permanent such that the GRUB config knows to not run nouveau. + ~~~ + nouveau.modeset=0 rd.driver.blacklist=nouveau video=vesa:off + ~~~ -To make this change persistent, so your boot will always work properly you'll have to do the following + This will tempororarily disable nouveau until boot. -1. Open a terminal (do this vb clicking on Q > 'run command' > type 'terminal' and hit enter) + 7. Press either the F10 key or Ctrl+X to start the boot process. -2. type following commands: -~~~ -cd /etc/default/ -sudo nano grub -~~~ + Qubes should now boot properly, if that's the case then we should make this change permanent such that the GRUB config knows to not run nouveau. -3. Edit `GRUB_CMDLINE_LINUX`, add the following to it at the end: -~~~ -nouveau.modeset=0 rd.driver.blacklist=nouveau video=vesa:off -~~~ +To make this change persistent, so your boot will always work properly you'll have to do the following: -4. ctrl + X and then y to save the file. + 1. Open a terminal (do this vb clicking on Q > 'run command' > type 'terminal' and hit enter) + + 2. type following commands: + + ~~~ + cd /etc/default/ + sudo nano grub + ~~~ + + 3. Edit `GRUB_CMDLINE_LINUX`, add the following to it at the end: + + ~~~ + nouveau.modeset=0 rd.driver.blacklist=nouveau video=vesa:off + ~~~ + + 4. ctrl + X and then y to save the file. + + 5. The final step is to compile the configuration file to something the bootloader can read. + + ~~~ + sudo grub2-mkconfig -o /boot/grub2/grub.cfg + ~~~ -5. The final step is to compile the configuration file to something the bootloader can read. -~~~ -sudo grub2-mkconfig -o /boot/grub2/grub.cfg -~~~ From 6a5ed728f83edcacaf8b0b9cb4b40672c1fc62a3 Mon Sep 17 00:00:00 2001 From: Kewde Date: Sun, 18 Sep 2016 15:19:15 +0000 Subject: [PATCH 176/708] Fixed typos and language errors --- troubleshooting/nvidia-troubleshooting.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/troubleshooting/nvidia-troubleshooting.md b/troubleshooting/nvidia-troubleshooting.md index 0386dba4..6e6dfcd2 100644 --- a/troubleshooting/nvidia-troubleshooting.md +++ b/troubleshooting/nvidia-troubleshooting.md @@ -81,7 +81,7 @@ Assuming your X Window System works fine now when you booted from the "failsafe" Disabling Nouveau --------------------- -If Qubes fails to properly boot after the GRUB Boot menu and you get a black screen that displays messages starting with `nouveau` then it means that the nouveau driver failed to launch properly. +If Qubes fails to properly boot after the GRUB Boot menu and you are stuck on a black screen that displays messages starting with `nouveau` then it means that the nouveau driver failed to launch properly. One way to get rid of this for now is to disable nouveau. @@ -93,7 +93,7 @@ nouveau E[ PGRAPH][0000:01:00.0] failed to construct context nouveau E[ PGRAPH][0000:01:00.0] init failed, -16 ~~~ -Tip: In the case that you only have an external monitor it is advised to hook it up to the connector directly connected to the motherboard if it is present, this should bypass the nvidia graphics card. +Tip: In case that you only have an external monitor it is advised to attach it directly to a connector of the motherboard if it is present, this should make ensure you're using the integrated graphics card instead of the nvidia graphics card. If you're seeing this error than that means another graphics card (most likely an integrated one) acted as failsafe. Disabling nouveau has the consequences of disabling nvidia support all together. @@ -106,13 +106,15 @@ If you're seeing this error than that means another graphics card (most likely a 2. Quickly press the "E" key before the time is up. - 3. An editor will open up that will allow you to temporarily change the grub options for the next boot. + 3. An editor will open up that allows you to temporarily change the grub options for the next boot. - 4. Press the down arrow key and move the cursor to the line after the line with the kernel options. The line with the kernel options might look something like, I didn't type everything as it may differ from system to system but it should look something like this: + 4. Press the down arrow key and move the cursor to the line after the line with the kernel options. The line with the kernel options will look like this: ~~~ module /vmlinux-4.1.13-9.pvops.qubes.x86_64 placeholder root=/dev/mapper/qubes_dom0-root ro ... rhgb quiet ~~~ + + I didn't type everything as it may differ from system to system. Please note: chose the module that starts with `vmlinux`! @@ -132,7 +134,7 @@ If you're seeing this error than that means another graphics card (most likely a To make this change persistent, so your boot will always work properly you'll have to do the following: - 1. Open a terminal (do this vb clicking on Q > 'run command' > type 'terminal' and hit enter) + 1. Open a terminal (do this by clicking on Q > 'run command' > type 'terminal' and hit enter) 2. type following commands: From 3db5623f58525809bead18076e7a990d9e4546f4 Mon Sep 17 00:00:00 2001 From: Kewde Date: Sun, 18 Sep 2016 15:38:57 +0000 Subject: [PATCH 177/708] More language fixes --- troubleshooting/nvidia-troubleshooting.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/troubleshooting/nvidia-troubleshooting.md b/troubleshooting/nvidia-troubleshooting.md index 6e6dfcd2..ffbadb1e 100644 --- a/troubleshooting/nvidia-troubleshooting.md +++ b/troubleshooting/nvidia-troubleshooting.md @@ -93,7 +93,7 @@ nouveau E[ PGRAPH][0000:01:00.0] failed to construct context nouveau E[ PGRAPH][0000:01:00.0] init failed, -16 ~~~ -Tip: In case that you only have an external monitor it is advised to attach it directly to a connector of the motherboard if it is present, this should make ensure you're using the integrated graphics card instead of the nvidia graphics card. +Tip: In case you only have an external monitor it is advised to attach it directly to a connector of the motherboard if it is present, this should ensure that you're using the integrated graphics card instead of the nvidia graphics card. If you're seeing this error than that means another graphics card (most likely an integrated one) acted as failsafe. Disabling nouveau has the consequences of disabling nvidia support all together. @@ -114,7 +114,7 @@ If you're seeing this error than that means another graphics card (most likely a module /vmlinux-4.1.13-9.pvops.qubes.x86_64 placeholder root=/dev/mapper/qubes_dom0-root ro ... rhgb quiet ~~~ - I didn't type everything as it may differ from system to system. + It is not an exact copy as it may differ from system to system. Please note: chose the module that starts with `vmlinux`! @@ -132,7 +132,7 @@ If you're seeing this error than that means another graphics card (most likely a Qubes should now boot properly, if that's the case then we should make this change permanent such that the GRUB config knows to not run nouveau. -To make this change persistent, so your boot will always work properly you'll have to do the following: +You'll have to do the following to make this change persistent, so that it will work properly on every boot : 1. Open a terminal (do this by clicking on Q > 'run command' > type 'terminal' and hit enter) From 6595b07f808147b9573893e244c7cd3616cece52 Mon Sep 17 00:00:00 2001 From: Kewde Date: Sun, 18 Sep 2016 15:41:35 +0000 Subject: [PATCH 178/708] Fix formatting The formatting on the website is terrible off due to inconsistent spacing of ATX-style headers. --- troubleshooting/install-nvidia-driver.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/troubleshooting/install-nvidia-driver.md b/troubleshooting/install-nvidia-driver.md index fd768f11..5dfff7b0 100644 --- a/troubleshooting/install-nvidia-driver.md +++ b/troubleshooting/install-nvidia-driver.md @@ -8,15 +8,15 @@ redirect_from: - /wiki/InstallNvidiaDriver/ --- -#Nvidia proprietary driver installation +# Nvidia proprietary driver installation You can use rpm packages from rpmfusion, or you can build the driver yourself. -##RpmFusion packages +## RpmFusion packages There are rpm packages with all necessary software on rpmfusion. The only package you have to compile is the kernel module (but there is a ready built src.rpm package). -###Download packages +### Download packages You will need any Fedora 18 system to download and build packages. You can use Qubes AppVM for it, but it isn't necessary. To download packages from rpmfusion - add this repository to your yum configuration (instructions are on their website). Then download packages using yumdownloader: @@ -25,7 +25,7 @@ yumdownloader --resolve xorg-x11-drv-nvidia yumdownloader --source nvidia-kmod ~~~ -###Build kernel package +### Build kernel package You will need at least kernel-devel (matching your Qubes dom0 kernel), rpmbuild tool and kmodtool, and then you can use it to build package: @@ -54,7 +54,7 @@ Reboot. -##Manual installation +## Manual installation This process is quite complicated: First - download the source from nvidia.com site. Here "NVIDIA-Linux-x86\_64-260.19.44.run" is used. Copy it to dom0. Every next step is done in dom0. @@ -64,7 +64,7 @@ See [this page](/doc/copy-to-dom0/) for instructions on how to transfer files to -###Userspace components +### Userspace components Install libraries, Xorg driver, configuration utilities. This can by done by nvidia-installer: @@ -72,7 +72,7 @@ Install libraries, Xorg driver, configuration utilities. This can by done by nvi ./NVIDIA-Linux-x86_64-260.19.44.run --ui=none --no-x-check --keep --no-nouveau-check --no-kernel-module ~~~ -###Kernel module +### Kernel module You will need: @@ -96,7 +96,7 @@ mv /lib/modules/2.6.34.1-12.xenlinux.qubes.x86_64/kernel/drivers/video/nvidia.ko Ignore any errors while inserting nvidia.ko (at the end of make phase). -###Disable nouveau: +### Disable nouveau: ~~~ cat /etc/modprobe.d/nouveau-disable.conf @@ -106,7 +106,7 @@ install nouveau /bin/true Add *rdblacklist=nouveau* option to /boot/grub/menu.lst (at the end of line containing *vmlinuz*). -###Configure Xorg +### Configure Xorg After all, you should configure Xorg to use nvidia driver. You can use *nvidia-xconfig* or do it manually: @@ -118,7 +118,7 @@ mv /root/xorg.conf.new /etc/X11/xorg.conf Reboot to verify all this works. -#Troubleshooting lack of video output during installation +# Troubleshooting lack of video output during installation Specifically, the notes below are aimed to help when the GRUB menu shows up fine, the installation environment starts loading, and then the display(s) go into standby mode. This is, typically, related to some sort of an issue with the kernel's KMS/video card modules. From 288f0922754bcba348002670c2443f787ef9f138 Mon Sep 17 00:00:00 2001 From: i7u Date: Sun, 18 Sep 2016 22:11:02 +0100 Subject: [PATCH 179/708] Update signal.md --- privacy/signal.md | 42 +++++++++++++++++++----------------------- 1 file changed, 19 insertions(+), 23 deletions(-) diff --git a/privacy/signal.md b/privacy/signal.md index b8f74c63..f9ed8bc3 100644 --- a/privacy/signal.md +++ b/privacy/signal.md @@ -42,34 +42,30 @@ Creating a Shortcut in KDE -------------------------- Let's make Signal a bit more usable by creating a shortcut in our desktop -panel that launches Signal directly. This assumes that you're using KDE in Dom0 -and that your AppVM is named `Signal`. +panel that launches Signal directly. This assumes that you're using KDE in Dom0, +you use Signal in an AppVM named `Signal`, and this AppVM uses `fedora-23` as its TemplateVM. -1. Create a Chromium shortcut (Q -> Domain: Signal -> Signal: Add more - shortcuts... -> Select "Chromium web browser") -2. Follow [these instructions][shortcut] to create a desktop shortcut. -3. Right-click on Chromium icon in panel and select "Icon Settings". -4. Change the "Command" field of the "Application" tab to: +1. Follow [these instructions][shortcut] to create a desktop shortcut on the Desktop of your Signal AppVM. + Let's assume the shortcut file you get is /home/user/Desktop/chrome-bikioccmkafdpakkkcpdbhpfkkhcmohk-Default.desktop +2. Copy this shortcut file to the AppVM's TemplateVM - in this case, to fedora-23. +3. You'll also want to copy across an icon for your new shortcut - you can find this at + /home/user/.local/share/icons/hicolor/48x48/apps/chrome-bikioccmkafdpakkkcpdbhpfkkhcmohk-Default.png + Copy this icon to the fedora-23 TemplateVM. +4. Open a terminal in your fedora-23 TemplateVM and cd to /home/user/QubesIncoming/Signal/ + You should find your shortcut and icon files just transferred across from the Signal AppVM. + Move these files to the following locations: + [user@fedora-23 Signal]$ sudo mv chrome-bikioccmkafdpakkkcpdbhpfkkhcmohk-Default.desktop /usr/share/applications/ + [user@fedora-23 Signal]$ sudo mv chrome-bikioccmkafdpakkkcpdbhpfkkhcmohk-Default.png /usr/share/icons/hicolor/48x48/ +5. From a Dom0 terminal, instruct Qubes to synchronize the application menus of this TemplateVM: + [user@dom0 ~]$ qvm-sync-appmenus fedora-23 +6. With your mouse select the `Q` menu -> `Domain: Signal` -> `Signal: Add more shortcuts` + Select `Signal Private Messenger` from the left `Available` column, move it to the right `Selected` column by clicking the `>` button and then `OK` to apply the changes and close the window. +7. Then follow the `Q` menu once more, right-click on the new `Signal: Signal Private Messenger` menu item and select `Add to Panel`. - qvm-run -a --tray Signal '/usr/lib64/chromium-browser/chromium-browser.sh --profile-directory=Default --app-id=' - - **Note:** Another method (more "correct" but less straightforward) is to [use - the way Qubes handles shortcuts internally to create a `.desktop` - file][shortcut-desktop]. -5. (Optional) Copy the Signal app icon file from the Signal AppVM to dom0. - (**Warning**: copying untrusted files to dom0 is dangerous! Do this only if - you understand and accept the risks!) - - [user@dom0]$ qvm-run --pass-io Signal 'cat /home/user/.local/share/icons/hicolor/48x48/apps/chrome--Default.png' > /home/users/signal-icon.png -6. (Optional) Change your new shortcut's icon from Chrome to Signal by pointing - it to `/home/users/signal-icon.png`. +You can now launch the Signal messenger inside its own dedicated AppVM with a single click from KDE's panel. ----- -These instructions were contributed by Qubes community member Alex (IX4 Svs) in -a [message] to the `qubes-users` [mailing list]. Thanks, Alex! - - [Signal]: https://whispersystems.org/ [signal-wikipedia]: https://en.wikipedia.org/wiki/Signal_(software) [shortcut]: http://support.whispersystems.org/hc/en-us/articles/216839277-Where-is-Signal-Desktop-on-my-computer- From 893ec2bb6aa9f3e291f3cb2ee1fe97d814e806a2 Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Sun, 18 Sep 2016 16:36:26 -0700 Subject: [PATCH 180/708] Add Nvidia troubleshooting guide to index --- doc.md | 1 + 1 file changed, 1 insertion(+) diff --git a/doc.md b/doc.md index 6c691225..3cd4247b 100644 --- a/doc.md +++ b/doc.md @@ -161,6 +161,7 @@ Troubleshooting * [Home directory is out of disk space error](/doc/out-of-memory/) * [Installing on system with new AMD GPU (missing firmware problem)](https://groups.google.com/group/qubes-devel/browse_thread/thread/e27a57b0eda62f76) * [How to install an Nvidia driver in dom0](/doc/install-nvidia-driver/) + * [Nvidia troubleshooting guide](/doc/nvidia-troubleshooting/) * [Solving problems with Macbook Air 2012](https://groups.google.com/group/qubes-devel/browse_thread/thread/b8b0d819d2a4fc39/d50a72449107ab21#8a9268c09d105e69) * [Getting Sony Vaio Z laptop to work with Qubes](/doc/sony-vaio-tinkering/) * [Getting Lenovo 450 to work with Qubes](/doc/lenovo450-tinkering/) From dae8dfda68813ef7f0106e1d0c08d34f995f90f0 Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Sun, 18 Sep 2016 16:52:54 -0700 Subject: [PATCH 181/708] Fix code blocks --- troubleshooting/install-nvidia-driver.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/troubleshooting/install-nvidia-driver.md b/troubleshooting/install-nvidia-driver.md index 5dfff7b0..4fb762fd 100644 --- a/troubleshooting/install-nvidia-driver.md +++ b/troubleshooting/install-nvidia-driver.md @@ -40,15 +40,15 @@ Then you need to disable nouveau (normally it is done by install scripts from nv Edit /etc/default/grub: - ~~~ - GRUB_CMDLINE_LINUX="quiet rhgb nouveau.modeset=0 rd.driver.blacklist=nouveau video=vesa:off" - ~~~ +~~~ +GRUB_CMDLINE_LINUX="quiet rhgb nouveau.modeset=0 rd.driver.blacklist=nouveau video=vesa:off" +~~~ Regenerate grub configuration: - ~~~ - grub2-mkconfig -o /boot/grub2/grub.cfg - ~~~ +~~~ +grub2-mkconfig -o /boot/grub2/grub.cfg +~~~ Reboot. From d3f1a137189a68de75bcb988c99f7518aeab1da1 Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Wed, 21 Sep 2016 10:56:55 -0700 Subject: [PATCH 182/708] Add QSB 26 --- security/security-bulletins.md | 1 + 1 file changed, 1 insertion(+) diff --git a/security/security-bulletins.md b/security/security-bulletins.md index fa4b0769..149c19a2 100644 --- a/security/security-bulletins.md +++ b/security/security-bulletins.md @@ -67,4 +67,5 @@ Qubes Security Bulletins are published through the [Qubes Security Pack](/doc/se - [Qubes Security Bulletin \#24](https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-024-2016.txt) (Critical Xen bug in PV memory virtualization code (XSA 182)) - [Qubes Security Bulletin \#25](https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-025-2016.txt) (Xen bug in event channel handling code (XSA 188)) +- [Qubes Security Bulletin \#26](https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-026-2016.txt) (Colored window border handling bug in Qubes GUI daemon) From 51d6be47e07ecca8d20853f882725cafce8611c3 Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Wed, 21 Sep 2016 18:09:09 -0700 Subject: [PATCH 183/708] Add entry for "TemplateBasedHVM" --- reference/glossary.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/reference/glossary.md b/reference/glossary.md index 53dc5bad..eec374d2 100644 --- a/reference/glossary.md +++ b/reference/glossary.md @@ -82,7 +82,8 @@ applications, but not for running them. TemplateBasedVM --------------- -Any [VM](#vm) which depends on a TemplateVM for its root filesystem. +Any [VM](#vm) which depends on a [TemplateVM](#templatevm) for its root +filesystem. Standalone(VM) -------------- @@ -164,6 +165,11 @@ Any [HVM](#hvm) which functions as a [TemplateVM](#templatevm) by supplying its root filesystem to other VMs. In Qubes, TemplateHVMs are referred to as **HVM templates**. +TemplateBasedHVM +---------------- +Any [HVM](#hvm) that depends on a [TemplateVM](#templatevm) for its root +filesystem. + PVH --- [PV](#pv) on [HVM](#hvm). To boost performance, fully virtualized HVM guests can From 7c2c6a79f33957a277fe6261faeaf101e92ff2cd Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Wed, 21 Sep 2016 18:09:43 -0700 Subject: [PATCH 184/708] Correct "PVH" to "PVHVM" According to the Xen project, "PVHVM" and "PVH" are distinct terms, and the definition here is for "PVHVM." See: https://wiki.xen.org/wiki/Xen_Project_Software_Overview#PVHVM --- reference/glossary.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/reference/glossary.md b/reference/glossary.md index eec374d2..e7f4dfd8 100644 --- a/reference/glossary.md +++ b/reference/glossary.md @@ -170,8 +170,8 @@ TemplateBasedHVM Any [HVM](#hvm) that depends on a [TemplateVM](#templatevm) for its root filesystem. -PVH ---- +PVHVM +----- [PV](#pv) on [HVM](#hvm). To boost performance, fully virtualized HVM guests can use special paravirtual device drivers (PVHVM or PV-on-HVM drivers). These drivers are optimized PV drivers for HVM environments and bypass the emulation From a5dc677c2ffeff303ab8fdc7ba792beffcf65b82 Mon Sep 17 00:00:00 2001 From: 0xNULL Date: Thu, 22 Sep 2016 09:02:12 +0000 Subject: [PATCH 185/708] Fix typo Make changes from 6. Create a AppVMs based on the `ptf` template to `blackarch` template --- managing-os/pentesting/blackarch.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/managing-os/pentesting/blackarch.md b/managing-os/pentesting/blackarch.md index 80d76bf6..9e6f6c64 100644 --- a/managing-os/pentesting/blackarch.md +++ b/managing-os/pentesting/blackarch.md @@ -84,7 +84,7 @@ Create ArchLinux Based BlackArch Template pacman -Ss burpsuite sudo pacman -S burpsuite -6. Create a AppVMs based on the `ptf` template +6. Create a AppVMs based on the `blackarch` template - (Optional) Attach necessary devices From efa0d8aef94e8b71386aa28addd15197f04ccc5a Mon Sep 17 00:00:00 2001 From: Joe Thielen Date: Sat, 24 Sep 2016 12:38:18 -0400 Subject: [PATCH 186/708] Add fix for Linux HVM kernel error on bootup: BUG: soft lockup - CPU#0 stuck for 23s! [systemd-udevd:244] --- managing-os/linux-hvm-tips.md | 35 +++++++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) diff --git a/managing-os/linux-hvm-tips.md b/managing-os/linux-hvm-tips.md index 53e56348..f07400d2 100644 --- a/managing-os/linux-hvm-tips.md +++ b/managing-os/linux-hvm-tips.md @@ -11,6 +11,41 @@ redirect_from: Tips for Linux in HVM domain ============================ +Fixing bootup kernel error `BUG: soft lockup - CPU#0 stuck for 23s! [systemd-udevd:244]` +---------------------------------------------------------------------------------------- +*Tested with Qubes R3.2-RC3* +Issue may be related to "bochs_drm" video driver. + +To fix: + +1. Edit the file /etc/default/grub +2. Find the line which starts: + + ~~~ + GRUB_CMDLINE_LINUX= + ~~~ + +3. Remove this text from that line: + + ~~~ + rhgb + ~~~ + +4. Add this text to that line: + + ~~~ + modprobe.blacklist=bochs_drm + ~~~ + +5. Run this command: + + ~~~ + grub2-mkconfig --output=/boot/grub2/grub.cfg + ~~~ + +The HVM should no longer display the error if it's related to the "bochs_drm" kernel driver. + + Screen resolution ----------------- From f32bf85689605f1c27f0fe9e7fa3f0682d671788 Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Sat, 24 Sep 2016 13:12:37 -0700 Subject: [PATCH 187/708] Fix table of contents (QubesOS/qubes-issues#1941) --- configuration/vpn.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/configuration/vpn.md b/configuration/vpn.md index 5a507352..72fa2eda 100644 --- a/configuration/vpn.md +++ b/configuration/vpn.md @@ -10,7 +10,7 @@ redirect_from: --- How To make a VPN Gateway in Qubes ----------------------------------- +================================== Although setting up a VPN connection is not by itself Qubes specific, there are a number of Qubes-related details that can make using the connection more versatile and secure. This document is a Qubes-specific outline for choosing the type of VM to use, and shows how to prepare a ProxyVM for either NetworkManager or a set of fail-safe VPN scripts. From e02030119ef5a34ee1bf306ec38d39bc7ecfa822 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Marczykowski-G=C3=B3recki?= Date: Sun, 25 Sep 2016 01:25:34 +0200 Subject: [PATCH 188/708] Fix internal links --- basics_user/user-faq.md | 6 +++--- building/development-workflow.md | 2 +- common-tasks/backup-restore.md | 2 +- common-tasks/copying-files.md | 2 +- hardware/system-requirements.md | 2 +- installing/live-usb.md | 2 +- installing/upgrade/upgrade-to-r2.md | 2 +- managing-os/templates.md | 2 +- managing-os/templates/archlinux.md | 2 +- managing-os/templates/fedora-minimal.md | 2 +- releases/3.1/release-notes.md | 2 +- releases/3.1/schedule.md | 2 +- releases/3.2/schedule.md | 2 +- security/anti-evil-maid.md | 2 +- security/security-guidelines.md | 4 ++-- security/split-gpg.md | 4 ++-- 16 files changed, 20 insertions(+), 20 deletions(-) diff --git a/basics_user/user-faq.md b/basics_user/user-faq.md index 0ed37bcf..457b24d9 100644 --- a/basics_user/user-faq.md +++ b/basics_user/user-faq.md @@ -30,7 +30,7 @@ Qubes Users' FAQ * [Is Qubes a multi-user system?](#is-qubes-a-multi-user-system) * [Why passwordless sudo?](#why-passwordless-sudo) * [How should I report documentation issues?](#how-should-i-report-documentation-issues) - * [Will Qubes seek to get certified on the GNU Free System Distribution Guidelines (GNU FSDG)?](#will-qubes-seek-gnu-fsdg) + * [Will Qubes seek to get certified on the GNU Free System Distribution Guidelines (GNU FSDG)?](#will-qubes-seek-to-get-certified-under-the-gnu-free-system-distribution-guidelines-gnu-fsdg) [Installation & Hardware Compatibility](#installation--hardware-compatibility) ------------------------------------------------------------------------------ @@ -51,8 +51,8 @@ Qubes Users' FAQ * [My dom0 and/or TemplateVM update stalls when attempting to update via …](#my-dom0-andor-templatevm-update-stalls-when-attempting-to-update-via-the-gui-tool-what-should-i-do) * [How do I run a Windows HVM in non-seamless mode (i.e., as a single window)?](#how-do-i-run-a-windows-hvm-in-non-seamless-mode-ie-as-a-single-window) * [I created a usbVM and assigned usb controllers to it. Now the usbVM wont boot.](#i-created-a-usbvm-and-assigned-usb-controllers-to-it-now-the-usbvm-wont-boot) - * [I assigned a PCI device to a qube, then unassigned it/shut down the …](#i-assigned-a-pci-device-to-a-qube-then-unassigned-itshut-down-the-qube`-why-isnt-the-device-available-in-dom0) - * [How do I install Flash in a Debian qube?](#how-do-i-install-flash-in-a Debian-qube) + * [I assigned a PCI device to a qube, then unassigned it/shut down the …](#i-assigned-a-pci-device-to-a-qube-then-unassigned-itshut-down-the-qube-why-isnt-the-device-available-in-dom0) + * [How do I install Flash in a Debian qube?](#how-do-i-install-flash-in-a-debian-qube) ----------------- diff --git a/building/development-workflow.md b/building/development-workflow.md index f9e8cea9..c413b217 100644 --- a/building/development-workflow.md +++ b/building/development-workflow.md @@ -541,6 +541,6 @@ Usage: add this line to `/etc/apt/sources.list` on test machine (adjust host and deb http://local-test.lan/linux-deb/r3.1 jessie-unstable main ~~~ -[port-forwarding]: /doc/qubes-firewall/#tocAnchor-1-1-5 +[port-forwarding]: /doc/qubes-firewall/#port-forwarding-to-a-vm-from-the-outside-world [linux-yum]: https://github.com/QubesOS/qubes-linux-yum [linux-deb]: https://github.com/QubesOS/qubes-linux-deb diff --git a/common-tasks/backup-restore.md b/common-tasks/backup-restore.md index fa48ffec..78e320fa 100644 --- a/common-tasks/backup-restore.md +++ b/common-tasks/backup-restore.md @@ -87,7 +87,7 @@ For emergency restore of backup created on Qubes R2 or newer take a look [here]( Migrating Between Two Physical Machines --------------------------------------- -In order to migrate your Qubes system from one physical machine to another, simply follow the backup procedure on the old machine, [install Qubes](/doc/downloads/) on the new machine, and follow the restoration procedure on the new machine. All of your settings and data will be preserved! +In order to migrate your Qubes system from one physical machine to another, simply follow the backup procedure on the old machine, [install Qubes](/downloads/) on the new machine, and follow the restoration procedure on the new machine. All of your settings and data will be preserved! Notes diff --git a/common-tasks/copying-files.md b/common-tasks/copying-files.md index 2fcb9980..6b9eb277 100644 --- a/common-tasks/copying-files.md +++ b/common-tasks/copying-files.md @@ -43,4 +43,4 @@ However, one should keep in mind that performing a data transfer from *less trus See also [this article](http://theinvisiblethings.blogspot.com/2011/03/partitioning-my-digital-life-into.html) for more information on this topic, and some ideas of how we might solve this problem in some future version of Qubes. -You may also want to read how to [revoke "Yes to All" authorization](/doc/Qrexec/#revoking-yes-to-all-authorization) +You may also want to read how to [revoke "Yes to All" authorization](/doc/qrexec3/#revoking-yes-to-all-authorization) diff --git a/hardware/system-requirements.md b/hardware/system-requirements.md index 5b1bf3d7..4bbde4e3 100644 --- a/hardware/system-requirements.md +++ b/hardware/system-requirements.md @@ -97,7 +97,7 @@ redirect_from: [Hardware Certification]: /hardware-certification/ [Hardware Compatibility List]: /hcl/ [hcl-doc]: /doc/hcl/ -[hcl-report]: /doc/HCL/#generating-and-submitting-new-reports +[hcl-report]: /doc/hcl/#generating-and-submitting-new-reports [Anti Evil Maid]: /doc/anti-evil-maid/ [Qubes-certified laptop]: /doc/certified-laptops/ [live USB]: /doc/live-usb/ diff --git a/installing/live-usb.md b/installing/live-usb.md index c3b25227..b3912180 100644 --- a/installing/live-usb.md +++ b/installing/live-usb.md @@ -100,7 +100,7 @@ Downloading and burning ----------------------- 1. Download the ISO (and its signature for verification) from the - [downloads page](/downloads/#qubes-live-usb-alpha/). + [downloads page](/downloads/#qubes-live-usb-alpha). 2. "Burn" (copy) the ISO onto a USB drive (replace `/dev/sdX` with your USB drive device): diff --git a/installing/upgrade/upgrade-to-r2.md b/installing/upgrade/upgrade-to-r2.md index 613dbfc7..a572d1eb 100644 --- a/installing/upgrade/upgrade-to-r2.md +++ b/installing/upgrade/upgrade-to-r2.md @@ -19,7 +19,7 @@ Current Qubes R2 Beta 3 (R2B3) systems can be upgraded in-place to the latest R2 Upgrade Template and Standalone VM(s) ------------------------------------- -- Qubes R2 comes with new template based on Fedora 20. You can upgrade existing template according to procedure described [here](/doc/FedoraTemplateUpgrade/). +- Qubes R2 comes with new template based on Fedora 20. You can upgrade existing template according to procedure described [here](/doc/fedora-template-upgrade-20/). - **It also possible to download a new Fedora 20-based template from our repositories**. To do this please first upgrade the Dom0 distro as described in the section below. diff --git a/managing-os/templates.md b/managing-os/templates.md index 39c09d60..9d7de876 100644 --- a/managing-os/templates.md +++ b/managing-os/templates.md @@ -17,7 +17,7 @@ TemplateBasedVMs is installed. The default template is based on Fedora, but there are additional templates based on other Linux distributions. There are also templates available with or without certain software preinstalled. The concept of TemplateVMs is initially described -[here](/doc/getting-started/#appvms-domains-and-templatevms). The technical +[here](/getting-started/#appvms-qubes-and-templatevms). The technical details of this implementation are described in the developer documentation [here](/doc/template-implementation/). diff --git a/managing-os/templates/archlinux.md b/managing-os/templates/archlinux.md index 636ce1aa..a0cde5fe 100644 --- a/managing-os/templates/archlinux.md +++ b/managing-os/templates/archlinux.md @@ -694,6 +694,6 @@ Note: For info on Reflector and its configs: [Reflector](https://wiki.archlinux. * [How can I contribute to the Qubes Project?](/doc/contributing/) -* [Guidelines for Documentation Contributors](doc/doc-guidelines/) +* [Guidelines for Documentation Contributors](/doc/doc-guidelines/)
diff --git a/managing-os/templates/fedora-minimal.md b/managing-os/templates/fedora-minimal.md index 7aea2fbd..4370313e 100644 --- a/managing-os/templates/fedora-minimal.md +++ b/managing-os/templates/fedora-minimal.md @@ -75,7 +75,7 @@ This template is now ready to use for a standard firewall VM. The needed packages depend on the VPN technology. The `dnf search "NetworkManager VPN plugin"` command may help you to choose the right one. You should also install the corresponding GNOME related packages as well. -[More details about setting up a VPN Gateway](/wiki/VPN#ProxyVM) +[More details about setting up a VPN Gateway](/doc/vpn/#proxyvm) #### TOR diff --git a/releases/3.1/release-notes.md b/releases/3.1/release-notes.md index c4506032..657f06f3 100644 --- a/releases/3.1/release-notes.md +++ b/releases/3.1/release-notes.md @@ -71,6 +71,6 @@ using](/doc/releases/3.0/release-notes/#upgrading) first, then follow the instructions above. This will be time consuming process. [salt-doc]: /doc/salt/ -[pvgrub-doc]: /doc/managing-vm-kernel/#tocAnchor-1-3 +[pvgrub-doc]: /doc/managing-vm-kernel/#using-kernel-installed-in-the-vm [input-proxy]: https://github.com/QubesOS/qubes-app-linux-input-proxy/blob/master/README.md [github-release-notes]: https://github.com/QubesOS/qubes-issues/issues?q=is%3Aissue+sort%3Aupdated-desc+milestone%3A%22Release+3.1%22+label%3Arelease-notes+is%3Aclosed diff --git a/releases/3.1/schedule.md b/releases/3.1/schedule.md index 296ca3e0..e4caa612 100644 --- a/releases/3.1/schedule.md +++ b/releases/3.1/schedule.md @@ -9,7 +9,7 @@ redirect_from: Qubes R3.1 Release Schedule =========================== -This schedule is based on [Version Scheme](/doc/version-scheme/#tocAnchor-1-1-3). +This schedule is based on [Version Scheme](/doc/version-scheme/#release-schedule). - | Date | Stage | | -----------:| --------------------------------------- | | 8 Dec 2015 | 3.1-rc1 release | diff --git a/releases/3.2/schedule.md b/releases/3.2/schedule.md index c7c93d0e..05dc5599 100644 --- a/releases/3.2/schedule.md +++ b/releases/3.2/schedule.md @@ -11,14 +11,6 @@ Qubes R3.2 Release Schedule This schedule is based on [Version Scheme](/doc/version-scheme/#release-schedule). - - | Date | Stage | | -----------:| --------------------------------------- | | 18 Jun 2016 | 3.2-rc1 release | From be5e0df56cdaff6010da611d0861a4dcfc2f66c2 Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Sat, 15 Oct 2016 17:20:05 -0700 Subject: [PATCH 223/708] Remove page-specific style block for article table --- installing/supported-versions.md | 8 -------- 1 file changed, 8 deletions(-) diff --git a/installing/supported-versions.md b/installing/supported-versions.md index 96ebc39d..ed6b2a02 100644 --- a/installing/supported-versions.md +++ b/installing/supported-versions.md @@ -4,14 +4,6 @@ title: Supported Versions permalink: /doc/supported-versions/ --- - - Supported Versions ================== From 88122ca7fabff3aaffbe92fe0590fd0fef191bee Mon Sep 17 00:00:00 2001 From: unman Date: Sun, 16 Oct 2016 01:28:26 +0100 Subject: [PATCH 224/708] Note that cron uses bind-dirs setup --- reference/dom0-tools/qvm-service.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reference/dom0-tools/qvm-service.md b/reference/dom0-tools/qvm-service.md index 3cd2cffe..e077265b 100644 --- a/reference/dom0-tools/qvm-service.md +++ b/reference/dom0-tools/qvm-service.md @@ -88,7 +88,7 @@ Enable CUPS service. The user can disable cups in VM which do not need printing crond Default: disabled -Enable CRON service. To have cron jobs persist across reboots, put /var/spool/cron in /rw/config/qubes-bind-dirs/50_user.conf. (See [Instructions](/doc/bind-dirs/) ) +Enable CRON service. To have cron jobs persist across reboots, /var/spool/cron is bind-mounted from /rw/bind-dirs. To override this see [Bind-Dir Instructions](/doc/bind-dirs/) ) network-manager Default: enabled in NetVM From 7a79975415038a9a792d4fd75b156e9135d65be4 Mon Sep 17 00:00:00 2001 From: unman Date: Sun, 16 Oct 2016 01:10:26 +0000 Subject: [PATCH 225/708] Update managing-vm-kernel.md Add reference to missing module --- configuration/managing-vm-kernel.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/configuration/managing-vm-kernel.md b/configuration/managing-vm-kernel.md index a80384a6..6748228f 100644 --- a/configuration/managing-vm-kernel.md +++ b/configuration/managing-vm-kernel.md @@ -320,7 +320,9 @@ grub2-probe: error: cannot find a GRUB drive for /dev/mapper/dmroot. Check your ~~~ Then shutdown the VM. From now you can set `pvgrub2` as VM kernel and it will -start kernel configured within VM. +start kernel configured within VM. + +When starting the VM you can safely ignore any warnings about a missing module 'dummy-hcd' ### Troubleshooting From 05e81abf273348abbf85b11498826fe3c0639477 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Marczykowski-G=C3=B3recki?= Date: Sun, 16 Oct 2016 23:22:13 +0200 Subject: [PATCH 226/708] Testing repository no longer needed for R3.2 upgrade --- installing/upgrade/upgrade-to-r3.2.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/installing/upgrade/upgrade-to-r3.2.md b/installing/upgrade/upgrade-to-r3.2.md index 6a2d0920..6d898e79 100644 --- a/installing/upgrade/upgrade-to-r3.2.md +++ b/installing/upgrade/upgrade-to-r3.2.md @@ -26,7 +26,7 @@ Upgrading dom0 3. Install `qubes-release` package carrying R3.2 repository information. - sudo qubes-dom0-update --enablerepo=qubes*testing --releasever=3.2 qubes-release + sudo qubes-dom0-update --releasever=3.2 qubes-release If you made any manual changes to repository definitions, new definitions will be installed as `/etc/yum.repos.d/qubes-dom0.repo.rpmnew` (you'll see @@ -120,7 +120,7 @@ repeated in **all** the user's Template and Standalone VMs. 2. Install the `qubes-upgrade-vm` package: - sudo dnf install --enablerepo=qubes*testing --refresh qubes-upgrade-vm + sudo dnf install --refresh qubes-upgrade-vm 3. Proceed with a normal upgrade in the template: From e06cafc33f1c57a3b5e63fdbc94ff4c45a1b2bf2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Marczykowski-G=C3=B3recki?= Date: Mon, 17 Oct 2016 23:24:50 +0200 Subject: [PATCH 227/708] Fix formatting --- installing/upgrade/upgrade-to-r3.0.md | 1 + 1 file changed, 1 insertion(+) diff --git a/installing/upgrade/upgrade-to-r3.0.md b/installing/upgrade/upgrade-to-r3.0.md index fa922053..35c6c8fd 100644 --- a/installing/upgrade/upgrade-to-r3.0.md +++ b/installing/upgrade/upgrade-to-r3.0.md @@ -103,6 +103,7 @@ Upgrading template on already upgraded dom0 When for some reason you did not upgraded all the templates and standalone VMs before upgrading dom0, you can still do this, but it will be somehow more complicated. This can be a case when you restore backup done on Qubes R2. When you start R2 template/standalone VM on R3.0, there will be some limitations: + 1. qrexec will not connect (you will see an error message during VM startup) 2. GUI will not connect - you will not see any VM window 3. VM will not be configured - especially it will not have network access From 749ce71d5603ac635177d2e0dc193669f3677297 Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Wed, 19 Oct 2016 16:13:51 -0700 Subject: [PATCH 228/708] Redirect old System Doc to new Developer Docs section --- basics_dev/system-doc.md | 44 ++-------------------------------------- 1 file changed, 2 insertions(+), 42 deletions(-) diff --git a/basics_dev/system-doc.md b/basics_dev/system-doc.md index 5f4cb4a3..110e7fb7 100644 --- a/basics_dev/system-doc.md +++ b/basics_dev/system-doc.md @@ -6,47 +6,7 @@ redirect_from: - /en/doc/system-doc/ - /doc/SystemDoc/ - /wiki/SystemDoc/ +redirect_to: +- /doc/#developer-documentation --- -System Documentation for Developers -=================================== - -Fundamentals ------------- - * [Qubes OS Architecture Overview](/doc/architecture/) - * [Qubes OS Architecture Spec v0.3 [PDF]](/attachment/wiki/QubesArchitecture/arch-spec-0.3.pdf) - (The original 2009 document that started this all...) - * [Security-critical elements of Qubes OS](/doc/security-critical-code/) - * [Qrexec: command execution in VMs](/doc/qrexec3/) - * [Qubes GUI virtualization protocol](/doc/gui/) - * [Networking in Qubes](/doc/networking/) - * [Implementation of template sharing and updating](/doc/template-implementation/) - -Services --------- - * [Inter-domain file copying](/doc/qfilecopy/) (deprecates [`qfileexchgd`](/doc/qfileexchgd/)) - * [Dynamic memory management in Qubes](/doc/qmemman/) - * [Implementation of DisposableVMs](/doc/dvm-impl/) - * [Article about disposable VMs](http://theinvisiblethings.blogspot.com/2010/06/disposable-vms.html) - * [Dom0 secure update mechanism](/doc/dom0-secure-updates/) - * VM secure update mechanism (forthcoming) - -Debugging ---------- - * [Profiling python code](/doc/profiling/) - * [Test environment in separate machine for automatic tests](/doc/test-bench/) - * [Automated tests](/doc/automated-tests/) - * [VM-dom0 internal configuration interface](/doc/vm-interface/) - * [Debugging Windows VMs](/doc/windows-debugging/) - -Building --------- - * [Building Qubes](/doc/qubes-builder/) (["API" Details](/doc/qubes-builder-details/)) - * [Development Workflow](/doc/development-workflow/) - * [KDE Dom0 packages for Qubes](/doc/kde-dom0/) - * [Building Qubes OS 3.0 ISO](/doc/qubes-r3-building/) - * [Building USB passthrough support (experimental)](/doc/pvusb/) - * [Building a TemplateVM based on a new OS (ArchLinux example)](/doc/building-non-fedora-template/) - * [Building the Archlinux Template](/doc/building-archlinux-template/) - - From 31a9ccd9ee95d6f42f674dda75623ecb91340cc2 Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Wed, 19 Oct 2016 16:26:57 -0700 Subject: [PATCH 229/708] Update CONTRIBUTING.md Direct potential contributors to read the Documentation Guidelines on the Qubes OS website. This prevents us from having to update the guidelines in more than one location. --- CONTRIBUTING.md | 58 ++++--------------------------------------------- 1 file changed, 4 insertions(+), 54 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e5ab919a..948aacde 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,58 +2,8 @@ Contributing to `qubes-doc` =========================== Thank you for your interest in contributing to `qubes-doc`, the Qubes OS -Project's dedicated documentation repository! Please take a moment to -familiarize yourself with the terms defined in the [glossary], and try to use -these terms consistently and accurately throughout your writing and editing. - -Please report all documentation issues in [qubes-issues]. - - -Markdown Conventions --------------------- - -All the documentation is written in Markdown for maximum accessibility. When -making contributions, please try to observe the following style conventions: - - * Use spaces instead of tabs. - * Hard wrap Markdown lines at 80 characters. - * If appropriate, make numerals in numbered lists match between Markdown - source and HTML output. - * Rationale: In the event that a user is required to read the Markdown source - directly, this will make it easier to follow, e.g., numbered steps in a set - of instructions. - * Use hanging indentations - where appropriate. - * Use underline headings (`=====` and `-----`) if possible. If this is not - possible, use Atx-style headings on both the left and right sides - (`### H3 ###`). - * Use `[reference-style][ref]` links. - -`[ref]: https://daringfireball.net/projects/markdown/syntax#link` - -([This][md] is a great source for learning about Markdown.) - - -Git Conventions ---------------- - -Please attempt to follow these conventions when writing your Git commit -messages: - - * Separate the subject line from the body with a blank line. - * Limit the subject line to approximately 50 characters. - * Capitalize the subject line. - * Do not end the subject line with a period. - * Use the imperative mood in the subject line. - * Wrap the body at 72 characters. - * Use the body to explain *what* and *why* rather than *how*. - -For details, examples, and the rationale behind each of these conventions, -please see [this blog post][git-commit], which is the source of this list. - - -[glossary]: https://www.qubes-os.org/doc/glossary/ -[qubes-issues]: https://github.com/QubesOS/qubes-issues/issues -[md]: https://daringfireball.net/projects/markdown/ -[git-commit]: http://chris.beams.io/posts/git-commit/ +Project's dedicated documentation repository! Please take a moment to read our +[Documentation Guidelines] before you begin writing. These guidelines are +important to maintaining high quality documentation, and following them will +increase the likelihood that your contribution will be accepted. From 7be7715fb5bf79362039b308b88dbeb165628b69 Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Wed, 19 Oct 2016 16:30:49 -0700 Subject: [PATCH 230/708] Update and organize Doc index --- doc.md | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/doc.md b/doc.md index 3cd4247b..6e70c2d3 100644 --- a/doc.md +++ b/doc.md @@ -16,9 +16,12 @@ User Documentation The Basics ---------- - * [A Tour of Qubes OS](/tour/) + * [What is Qubes OS?](/intro/) + * [Video Tours](/video-tours/) + * [Screenshots](/screenshots/) * [Getting Started](/getting-started/) * [User FAQ](/doc/user-faq/) + * [Mailing Lists](/mailing-lists/) Choosing Your Hardware @@ -191,17 +194,17 @@ Developer Documentation The Basics ---------- - * [Developers' FAQ](/doc/devel-faq/) - * [Feature Development Tracker](/qubes-issues/) + * [Developer FAQ](/doc/devel-faq/) * [Reporting Security Issues](/security/) * [Reporting Bugs](/doc/reporting-bugs/) * [Source Code](/doc/source-code/) - * [How to Contribute to the Qubes OS Project](/doc/contributing/) + * [Feature Development Tracker](/qubes-issues/) + * [How to Contribute](/doc/contributing/) * [Coding Guidelines](/doc/coding-style/) * [Documentation Guidelines](/doc/doc-guidelines/) * [Code Signing](/doc/code-signing/) - * [Books for Developers](/doc/devel-books/) * [Qubes OS License](/doc/license/) + * [Books for Developers](/doc/devel-books/) * [Style Guide](/doc/style-guide/) * [Usability & UX](/doc/usability-ux/) From 63afba639fa1ad65d8e10536b242206b8cc87737 Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Wed, 19 Oct 2016 16:36:30 -0700 Subject: [PATCH 231/708] Merge Help into Docs QubesOS/qubes-issues#1833 QubesOS/qubes-issues#1841 --- doc.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/doc.md b/doc.md index 6e70c2d3..a109c01b 100644 --- a/doc.md +++ b/doc.md @@ -8,6 +8,10 @@ redirect_from: - /wiki/UserDoc/ - /doc/QubesDocs/ - /wiki/QubesDocs/ +- /help/ +- /en/help/ +- /en/community/ +- /community/ --- User Documentation From 2d93078274c81aaadb2b36b8d69df13475001f52 Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Wed, 19 Oct 2016 16:44:53 -0700 Subject: [PATCH 232/708] Add Hardware Certification page to Doc index --- doc.md | 1 + 1 file changed, 1 insertion(+) diff --git a/doc.md b/doc.md index a109c01b..836f98bb 100644 --- a/doc.md +++ b/doc.md @@ -34,6 +34,7 @@ Choosing Your Hardware * [System Requirements](/doc/system-requirements/) * [Hardware Compatibility List (HCL)](/hcl/) * [Qubes-Certified Laptops](/doc/certified-laptops/) + * [Hardware Certification](/hardware-certification/) Installing & Upgrading Qubes From a478ed0984290c175225c64fdd6041c2ebaad351 Mon Sep 17 00:00:00 2001 From: Jean-Philippe Ouellet Date: Thu, 20 Oct 2016 02:37:45 -0400 Subject: [PATCH 233/708] Remove outdated no-PVUSB claim There is an entire section below on how to do single-device passthrough since R3.2. --- common-tasks/usb.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/common-tasks/usb.md b/common-tasks/usb.md index 90698eb8..10a20ff9 100644 --- a/common-tasks/usb.md +++ b/common-tasks/usb.md @@ -152,9 +152,7 @@ USB stack is put to work to parse the data presented by the USB device in order to determine if it is a USB mass storage device, to read its configuration, etc. This happens even if the drive is then assigned and mounted in another qube. -To avoid this risk, it is possible to prepare and utilize a USB qube. However, -Xen does not yet provide working PVUSB functionality, so only USB mass storage -devices can be passed to individual qubes. +To avoid this risk, it is possible to prepare and utilize a USB qube. For this reason, you may wish to avoid using a USB qube if you do not have a USB controller free of input devices and programmable devices, although Qubes R3.1 From 2b65809ad344770e185a9d45f7d89ff871c754a1 Mon Sep 17 00:00:00 2001 From: Michael Carbone Date: Thu, 20 Oct 2016 19:28:12 +0200 Subject: [PATCH 234/708] removed gendered language --- 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 03bf6b51..719b1c35 100644 --- a/security/split-gpg.md +++ b/security/split-gpg.md @@ -258,9 +258,9 @@ In this example, the following keys are stored in the following locations leave the `vault` VM, so it is extremely unlikely ever to be obtained by an adversary (see below). Second, an adversary who *does* manage to obtain the master secret key either possesses the passphrase to unlock the key - (if one is used), or he does not. If he does, then he can simply use + (if one is used), or they do not. If they do, then they can simply use the passphrase in order to legally extend the expiration date of the key - (or remove it entirely). If he does not, then he cannot use the key at + (or remove it entirely). If they do not, then they cannot use the key at all. In either case, an expiration date provides no additional benefit. By the same token, however, having a passphrase on the key is of little From 37b9e3c3613bdb1250e08753e3e87ace1c2cbbc0 Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Thu, 20 Oct 2016 16:15:31 -0700 Subject: [PATCH 235/708] Rewrite to avoid pronouns entirely --- security/split-gpg.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/security/split-gpg.md b/security/split-gpg.md index 719b1c35..53e8555d 100644 --- a/security/split-gpg.md +++ b/security/split-gpg.md @@ -258,10 +258,11 @@ In this example, the following keys are stored in the following locations leave the `vault` VM, so it is extremely unlikely ever to be obtained by an adversary (see below). Second, an adversary who *does* manage to obtain the master secret key either possesses the passphrase to unlock the key - (if one is used), or they do not. If they do, then they can simply use - the passphrase in order to legally extend the expiration date of the key - (or remove it entirely). If they do not, then they cannot use the key at - all. In either case, an expiration date provides no additional benefit. + (if one is used) or does not. An adversary who *does* possess the passphrase + can simply use it to legally extend the expiration date of the key + (or remove it entirely). An adversary who does *not* possess the passphrase + cannot use the key at all. In either case, an expiration date provides no + additional benefit. By the same token, however, having a passphrase on the key is of little value. An adversary who is capable of stealing the key from your `vault` From fc61183f2d2085021a9132ff84caa1a455388583 Mon Sep 17 00:00:00 2001 From: nescravana Date: Sat, 22 Oct 2016 16:04:10 +0100 Subject: [PATCH 236/708] Create macbookair2011(4,2).md --- troubleshooting/macbookair2011(4,2).md | 96 ++++++++++++++++++++++++++ 1 file changed, 96 insertions(+) create mode 100644 troubleshooting/macbookair2011(4,2).md diff --git a/troubleshooting/macbookair2011(4,2).md b/troubleshooting/macbookair2011(4,2).md new file mode 100644 index 00000000..394544e4 --- /dev/null +++ b/troubleshooting/macbookair2011(4,2).md @@ -0,0 +1,96 @@ + +After browsing through multiple posts, I finally was able to install Qubes on a MacBook Air 13” mid 2011 (MacBookAir 4,2). I’m just sharing this, so ppl don’t need to read through multiple forums to understand how to do it. + +This model is features with: +• Dual Intel i7-2677M 1.80 Ghz CPU (2 dual cores) +• Intel HD Graphics 3000 +• 4Gb RAM +• 256Gb SDD +• Broadcom BCM43224 802.11 a/b/g/n wifi and Bluetooth adapter +• Intel DSL2310 Thunderbolt controller +• It has 1 DVI/Thunderbolt display port, 2 USB2.0 ports, a Magsafe power adapter, a standard 3.5mm audio jack and SD reader. + +First try to install Qubes using the UEFI boot failed, and not wanting to waste too much time, I quickly opted for the legacy BIOS install. + +1. Boot from MacOSX (or Internet Recovery Image with CMD+R during bootup). +Run Terminal application as root [1]: +~~~ +# diskutil list +(find your usb device) +# bless –device /dev/diskX –legacy –setBoot –nextonly # bless the disk not the partition +# reboot +~~~ + +Insert Qubes 3.2 USB flash: +ISOLINUX boot screen should come up. +Install Qubes normaly + + +If you try to boot Qubes now, it will freeze while “setting up networking”. You need to put the Broadcom wireless device into PCI passtrough [2,3]. Or, as an alternative remove it from your mac (https://www.ifixit.com/Guide/MacBook+Air+13-Inch+Mid+2011+AirPort-Bluetooth+Card+Replacement/6360) and Qubes will boot up smoothly. +If you choose to remove the card jump to step 3. + +2. Boot from MacOSX, again. +~~~ +Run Terminal application as root: +# diskutil list +(find your usb device) +# bless –device /dev/diskX –legacy –setBoot –nextonly # bless the disk not the partition +# reboot +~~~ + +Insert Qubes 3.2 USB flash: +ISOLINUX boot screen should come up. +Select Troubleshooting and Boot the Rescue image; insert disk password when prompted; select continue and after mounting the HD filesystem, launching a shell, chroot as instructed. + +Then: +a) Find your Bluetooth card: +~~~ +# lspci +.. +02:00.0 Network controller: Broadcom Corporation BCM43224 802.11a/b/g/n (rev 01) +… +# qvm-pci -a sys-net 02:00.0 # this assigns the device to sys-net VM +~~~ + +then create Create /etc/systemd/system/qubes-pre-netvm.service +with: +~~~ +[Unit] +Description=Netvm fix for Broadcom +Before=qubes-netvm.service + +[Service] +ExecStart=/bin/sh -c 'echo 02:00.0 > /sys/bus/pci/drivers/pciback/permissive' +Type=oneshot +RemainAfterExit=yes + +[Install] +WantedBy=multi-user.target +~~~ +And that’s it. + + +3. After reboot, boot MacOSX, again. +Run Terminal application as root: +~~~ +# diskutil list +(find the HD device where you installed Qubes) +# bless –device /dev/diskX –legacy –setBoot # bless the disk not the partition +# reboot +~~~ + +Results: +• System booted and running smoothly. +• Youtube video: OK (including full screen after configuration) +• Trackpad: OK +• Audio control: OK +• Brightness control: OK +• Keyboard light control:OK +• SD card access: OK (tested at dom0) +• Lid-close suspend: OK +• Wifi: +10%-20% ICMP packet loss when comparing with OSX (have similar rates with tails Linux, more tests are required) + +References: +[1] https://github.com/QubesOS/qubes-issues/issues/794 +[2] https://github.com/QubesOS/qubes-issues/issues/1261 +[3] https://www.qubes-os.org/doc/assigning-devices/ From fca9e714257ec54fa63d72c41a7953ef2115831c Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Sun, 23 Oct 2016 00:30:59 -0700 Subject: [PATCH 237/708] Duplicate reporting links under both "Basics" sections QubesOS/qubes-issues#1833 --- doc.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/doc.md b/doc.md index 836f98bb..c3a829b4 100644 --- a/doc.md +++ b/doc.md @@ -26,6 +26,8 @@ The Basics * [Getting Started](/getting-started/) * [User FAQ](/doc/user-faq/) * [Mailing Lists](/mailing-lists/) + * [Report a Security Issue](/security/) + * [Report a Bug](/doc/reporting-bugs/) Choosing Your Hardware @@ -200,8 +202,8 @@ The Basics ---------- * [Developer FAQ](/doc/devel-faq/) - * [Reporting Security Issues](/security/) - * [Reporting Bugs](/doc/reporting-bugs/) + * [Report a Security Issue](/security/) + * [Report a Bug](/doc/reporting-bugs/) * [Source Code](/doc/source-code/) * [Feature Development Tracker](/qubes-issues/) * [How to Contribute](/doc/contributing/) From de7e8867871b50a8a5e9ea9808ddf61638864d98 Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Sun, 23 Oct 2016 00:56:22 -0700 Subject: [PATCH 238/708] Update bug reporting page * Distinguish security issues from bugs and add link to information on reporting security issues * Add link to Mailing Lists page in place of direct link to Google Groups web interface * Add common redirects --- basics_dev/reporting-bugs.md | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/basics_dev/reporting-bugs.md b/basics_dev/reporting-bugs.md index 98f8c0b1..6a00214b 100644 --- a/basics_dev/reporting-bugs.md +++ b/basics_dev/reporting-bugs.md @@ -6,12 +6,19 @@ redirect_from: - /en/doc/reporting-bugs/ - /doc/BugReportingGuide/ - /wiki/BugReportingGuide/ +- /reporting-bugs/ +- /bug/ +- /bugs/ +- /bug-report/ +- /bug-reports/ --- Bug Reporting Guide =================== -One of the most important contribution task is reporting the bugs you have found. +One of the most important contribution tasks is reporting the bugs you have +found. Please note that there is a separate process for [reporting security +issues](/security/). Asking a Question ----------------- @@ -21,9 +28,8 @@ docs](https://www.qubes-os.org/doc/), Google, GitHub, and StackOverflow. If your question is something that has been answered many times before, the project maintainers might be tired of repeating themselves. -Whenever possible, ask your question on the Qubes mailing list which is -located [here](https://groups.google.com/forum/#!forum/qubes-users). This -allows anyone to answer and makes the answer available for the next person +Whenever possible, ask your question on the [mailing lists](/mailing-lists/). +This allows anyone to answer and makes the answer available for the next person with the same question. Submitting a Bug Report (or "Issue") From bc2ce98850d4156aa600500e71cbe25c53c54898 Mon Sep 17 00:00:00 2001 From: nescravana Date: Sun, 23 Oct 2016 12:17:56 +0100 Subject: [PATCH 239/708] Update macbookair2011(4,2).md --- troubleshooting/macbookair2011(4,2).md | 44 ++++++++++++-------------- 1 file changed, 21 insertions(+), 23 deletions(-) diff --git a/troubleshooting/macbookair2011(4,2).md b/troubleshooting/macbookair2011(4,2).md index 394544e4..d2a77a08 100644 --- a/troubleshooting/macbookair2011(4,2).md +++ b/troubleshooting/macbookair2011(4,2).md @@ -2,17 +2,17 @@ After browsing through multiple posts, I finally was able to install Qubes on a MacBook Air 13” mid 2011 (MacBookAir 4,2). I’m just sharing this, so ppl don’t need to read through multiple forums to understand how to do it. This model is features with: -• Dual Intel i7-2677M 1.80 Ghz CPU (2 dual cores) -• Intel HD Graphics 3000 -• 4Gb RAM -• 256Gb SDD -• Broadcom BCM43224 802.11 a/b/g/n wifi and Bluetooth adapter -• Intel DSL2310 Thunderbolt controller -• It has 1 DVI/Thunderbolt display port, 2 USB2.0 ports, a Magsafe power adapter, a standard 3.5mm audio jack and SD reader. +* Dual Intel i7-2677M 1.80 Ghz CPU (2 dual cores); +* Intel HD Graphics 3000; +* 4Gb RAM; +* 256Gb SDD; +* Broadcom BCM43224 802.11 a/b/g/n wifi and Bluetooth adapter; +* Intel DSL2310 Thunderbolt controller; +* It has 1 DVI/Thunderbolt display port, 2 USB2.0 ports, a Magsafe power adapter, a standard 3.5mm audio jack and SD reader. First try to install Qubes using the UEFI boot failed, and not wanting to waste too much time, I quickly opted for the legacy BIOS install. -1. Boot from MacOSX (or Internet Recovery Image with CMD+R during bootup). +###1. Boot from MacOSX (or Internet Recovery Image with CMD+R during bootup). Run Terminal application as root [1]: ~~~ # diskutil list @@ -29,7 +29,7 @@ Install Qubes normaly If you try to boot Qubes now, it will freeze while “setting up networking”. You need to put the Broadcom wireless device into PCI passtrough [2,3]. Or, as an alternative remove it from your mac (https://www.ifixit.com/Guide/MacBook+Air+13-Inch+Mid+2011+AirPort-Bluetooth+Card+Replacement/6360) and Qubes will boot up smoothly. If you choose to remove the card jump to step 3. -2. Boot from MacOSX, again. +###2. Boot from MacOSX, again. ~~~ Run Terminal application as root: # diskutil list @@ -70,7 +70,7 @@ WantedBy=multi-user.target And that’s it. -3. After reboot, boot MacOSX, again. +###3. After reboot, boot MacOSX, again. Run Terminal application as root: ~~~ # diskutil list @@ -80,17 +80,15 @@ Run Terminal application as root: ~~~ Results: -• System booted and running smoothly. -• Youtube video: OK (including full screen after configuration) -• Trackpad: OK -• Audio control: OK -• Brightness control: OK -• Keyboard light control:OK -• SD card access: OK (tested at dom0) -• Lid-close suspend: OK -• Wifi: +10%-20% ICMP packet loss when comparing with OSX (have similar rates with tails Linux, more tests are required) +* System booted and running smoothly. +* Youtube video: OK (including full screen after configuration) +* Trackpad: OK +* Audio control: OK +* Brightness control: OK +* Keyboard light control:OK +* SD card access: OK (tested at dom0) +* Lid-close suspend: OK +* Wifi: +10%-20% ICMP packet loss when comparing with OSX (have similar rates with tails Linux, more tests are required) -References: -[1] https://github.com/QubesOS/qubes-issues/issues/794 -[2] https://github.com/QubesOS/qubes-issues/issues/1261 -[3] https://www.qubes-os.org/doc/assigning-devices/ +References: [1] https://github.com/QubesOS/qubes-issues/issues/794 ; [2] https://github.com/QubesOS/qubes-issues/issues/1261 ; +[3] https://www.qubes-os.org/doc/assigning-devices/ ; From 27cad57f0794597156e3ca1933bbea51ca58bea7 Mon Sep 17 00:00:00 2001 From: nescravana Date: Sun, 23 Oct 2016 12:35:10 +0100 Subject: [PATCH 240/708] Update macbookair2011(4,2).md added the systemctl update --- troubleshooting/macbookair2011(4,2).md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/troubleshooting/macbookair2011(4,2).md b/troubleshooting/macbookair2011(4,2).md index d2a77a08..21a1ce76 100644 --- a/troubleshooting/macbookair2011(4,2).md +++ b/troubleshooting/macbookair2011(4,2).md @@ -67,6 +67,10 @@ RemainAfterExit=yes [Install] WantedBy=multi-user.target ~~~ +Run: +~~~ +systemctl enable qubes-pre-netvm.service +~~~ And that’s it. From 06b9f02fc61e349e985ff795f39bae01ca1511f9 Mon Sep 17 00:00:00 2001 From: Michael Carbone Date: Mon, 24 Oct 2016 06:07:23 +0200 Subject: [PATCH 241/708] delete out-of-date doc this doc is way out of date, clearly before Qubes had kde dom0 packages: https://www.qubes-os.org/doc/kde/ refers explicitly to Fedora 12 (!) and talks about how it doesn't yet have colored title bars... --- building/kde-dom0.md | 57 -------------------------------------------- 1 file changed, 57 deletions(-) delete mode 100644 building/kde-dom0.md diff --git a/building/kde-dom0.md b/building/kde-dom0.md deleted file mode 100644 index 5e0a9bbc..00000000 --- a/building/kde-dom0.md +++ /dev/null @@ -1,57 +0,0 @@ ---- -layout: doc -title: KDE dom0 -permalink: /doc/kde-dom0/ -redirect_from: -- /en/doc/kde-dom0/ -- /doc/KdeDom0/ -- /wiki/KdeDom0/ ---- - -Qubes-customized KDE packages for Dom0 -====================================== - -The Qubes kde-dom0 project (see [Source Code](/doc/source-code/)) contains the source code needed for building the customized KDE packages for use in Qubes Dom0 (the user desktop). The packages are based on Fedora 12 KDE packages, but are heavily slimmed down (Qubes doesn't need lots of KDE functionality in Dom0, such as most of the KDE apps). In the near future those KDE packages will also get some Qubes specific extensions, such as coloured titlebars/frames nicely integrated into the KDE Window Manager. And, of course, custom themes, e.g. for KDM :) - -Getting the sources -------------------- - -~~~ -git clone git://qubes-os.org/mainstream/kde-dom0.git kde-dom0 -~~~ - -Building the packages ---------------------- - -It's best to use Fedora 12 or 13 as a development system. - -First, you should download and verify the original KDE sources (not part of the kde-dom0 repository): - -~~~ -make get-sources verify-sources -~~~ - -Now, check if you have all the required build dependencies: - -~~~ -make prep -~~~ - -Install any required packages that `make` might have complained about. Then you're ready to build the rpms (you might want to adjust the release of each rpm package by editing the `rel` variable at the beginning of each `.spec` file): - -~~~ -make rpms -~~~ - -**Note:** The `kdebase-*` packages build process requires corresponding `kdelibs-devel` package to be installed first. If your build system is based on Fedora 12/13, and if the `kdelibs-devel` package exist in Fedora repo that is based the same KDE software version (e.g. 4.4.3) as the KDE packages you're building (see the `version` file), than you should be able to use the Fedora package: - -~~~ -yum install kdelibs-devel-{version} -~~~ - -If not, then you should build your `kdelibs-devel` first (`cd kdelibs-devel && make rpms`), then install it on your build system, and then you can build all the rest (`make rpms`). - -Installing KDE packages from Qubes repository ---------------------------------------------- - -TODO From 4ff8c3614e570c5d07a048925e6aced1de396ce7 Mon Sep 17 00:00:00 2001 From: Michael Carbone Date: Mon, 24 Oct 2016 06:13:13 +0200 Subject: [PATCH 242/708] changed link to release notes changed link to R3.2 release notes rather than github issue. --- customization/kde.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/customization/kde.md b/customization/kde.md index ad651512..cee094a6 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://github.com/QubesOS/qubes-issues/issues/2119). Nonetheless, it is +R3.2, however, [XFCE is the new default desktop environment](https://www.qubes-os.org/doc/releases/3.2/release-notes/). Nonetheless, it is still possible to install KDE by issuing this command in dom0: $ sudo qubes-dom0-update @kde-desktop-qubes From a08adb1a0c28f20e2adb2aa2176d7e9b6eafe7d6 Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Sun, 23 Oct 2016 23:59:54 -0700 Subject: [PATCH 243/708] Prepare MacBook page for incorporation into docs * Rename file * Fix formatting * Clean up grammatical/stylistic issues * Fix links and references --- troubleshooting/macbook.md | 134 +++++++++++++++++++++++++ troubleshooting/macbookair2011(4,2).md | 98 ------------------ 2 files changed, 134 insertions(+), 98 deletions(-) create mode 100644 troubleshooting/macbook.md delete mode 100644 troubleshooting/macbookair2011(4,2).md diff --git a/troubleshooting/macbook.md b/troubleshooting/macbook.md new file mode 100644 index 00000000..4d90404d --- /dev/null +++ b/troubleshooting/macbook.md @@ -0,0 +1,134 @@ +--- +layout: doc +title: Apple MacBook Troubleshooting +permalink: /doc/macbook/ +--- + +Apple MacBook Troubleshooting +============================= + +MacBook Air 13" mid 2011 (MacBookAir 4,2) +----------------------------------------- + +In this section, I explain how to install Qubes on a MacBook Air 13" mid 2011 +(MacBookAir 4,2). + +This model has the following features: + +* Dual Intel i7-2677M 1.80 Ghz CPU (2 dual cores) +* Intel HD Graphics 3000 +* 4Gb RAM +* 256Gb SDD +* Broadcom BCM43224 802.11 a/b/g/n wifi and Bluetooth adapter +* Intel DSL2310 Thunderbolt controller +* It has 1 DVI/Thunderbolt display port, 2 USB2.0 ports, a Magsafe power + adapter, a standard 3.5mm audio jack and SD reader. + +I first tried to install Qubes using the UEFI boot, but it failed. Not wanting +to waste too much time, I quickly opted for the legacy BIOS install. + +### 1. Boot from Mac OS X (or Internet Recovery Image with `CMD`+`R` during bootup) + +Run in a terminal [[1]]: + +~~~ +# diskutil list +(find your usb device) +# bless –device /dev/diskX –legacy –setBoot –nextonly # bless the disk not the partition +# reboot +~~~ + +Insert your Qubes 3.2 USB flash drive. The ISOLINUX boot screen should come up. +Install Qubes normally. + +If you try to boot Qubes now, it will freeze while "setting up networking." You +need to put the Broadcom wireless device into PCI passtrough [[2],[3]]. Or, as +an alternative [remove it from your Mac][bluetooth-replacement] and Qubes will +boot up smoothly. If you choose to remove the card, jump to step 3. + +### 2. Boot from Mac OS X again + +Run in a terminal: + +~~~ +# diskutil list +(find your usb device) +# bless –device /dev/diskX –legacy –setBoot –nextonly # bless the disk not the partition +# reboot +~~~ + +Insert your Qubes 3.2 USB flash drive. The ISOLINUX boot screen should come up. +Select Troubleshooting and Boot the Rescue image. Enter your disk password when +prompted. Select continue and after mounting the HD filesystem and launching a +shell, `chroot` as instructed. + +Then find your Bluetooth card: + +~~~ +# lspci +.. +02:00.0 Network controller: Broadcom Corporation BCM43224 802.11a/b/g/n (rev 01) +… +# qvm-pci -a sys-net 02:00.0 # this assigns the device to sys-net VM +~~~ + +Then create `/etc/systemd/system/qubes-pre-netvm.service` with: + +~~~ +[Unit] +Description=Netvm fix for Broadcom +Before=qubes-netvm.service + +[Service] +ExecStart=/bin/sh -c 'echo 02:00.0 > /sys/bus/pci/drivers/pciback/permissive' +Type=oneshot +RemainAfterExit=yes + +[Install] +WantedBy=multi-user.target +~~~ + +Run: + +~~~ +systemctl enable qubes-pre-netvm.service +~~~ + +And that's it. + +### 3. After reboot, boot Mac OS X again + +Run in a terminal: + +~~~ +# diskutil list +(find the HD device where you installed Qubes) +# bless –device /dev/diskX –legacy –setBoot # bless the disk not the partition +# reboot +~~~ + +Results: + +* System booted and running smoothly +* Youtube video: OK (including full screen after configuration) +* Trackpad: OK +* Audio control: OK +* Brightness control: OK +* Keyboard light control:OK +* SD card access: OK (tested at dom0) +* Lid-close suspend: OK +* Wifi: +10%-20% ICMP packet loss when comparing with OSX (have similar rates + with tails Linux, more tests are required) + +### References + +1. +2. +3. + + +[1]: https://github.com/QubesOS/qubes-issues/issues/794 +[2]: https://github.com/QubesOS/qubes-issues/issues/1261 +[3]: https://www.qubes-os.org/doc/assigning-devices/ +[bluetooth-replacement]: https://www.ifixit.com/Guide/MacBook+Air+13-Inch+Mid+2011+AirPort-Bluetooth+Card+Replacement/6360 + diff --git a/troubleshooting/macbookair2011(4,2).md b/troubleshooting/macbookair2011(4,2).md deleted file mode 100644 index 21a1ce76..00000000 --- a/troubleshooting/macbookair2011(4,2).md +++ /dev/null @@ -1,98 +0,0 @@ - -After browsing through multiple posts, I finally was able to install Qubes on a MacBook Air 13” mid 2011 (MacBookAir 4,2). I’m just sharing this, so ppl don’t need to read through multiple forums to understand how to do it. - -This model is features with: -* Dual Intel i7-2677M 1.80 Ghz CPU (2 dual cores); -* Intel HD Graphics 3000; -* 4Gb RAM; -* 256Gb SDD; -* Broadcom BCM43224 802.11 a/b/g/n wifi and Bluetooth adapter; -* Intel DSL2310 Thunderbolt controller; -* It has 1 DVI/Thunderbolt display port, 2 USB2.0 ports, a Magsafe power adapter, a standard 3.5mm audio jack and SD reader. - -First try to install Qubes using the UEFI boot failed, and not wanting to waste too much time, I quickly opted for the legacy BIOS install. - -###1. Boot from MacOSX (or Internet Recovery Image with CMD+R during bootup). -Run Terminal application as root [1]: -~~~ -# diskutil list -(find your usb device) -# bless –device /dev/diskX –legacy –setBoot –nextonly # bless the disk not the partition -# reboot -~~~ - -Insert Qubes 3.2 USB flash: -ISOLINUX boot screen should come up. -Install Qubes normaly - - -If you try to boot Qubes now, it will freeze while “setting up networking”. You need to put the Broadcom wireless device into PCI passtrough [2,3]. Or, as an alternative remove it from your mac (https://www.ifixit.com/Guide/MacBook+Air+13-Inch+Mid+2011+AirPort-Bluetooth+Card+Replacement/6360) and Qubes will boot up smoothly. -If you choose to remove the card jump to step 3. - -###2. Boot from MacOSX, again. -~~~ -Run Terminal application as root: -# diskutil list -(find your usb device) -# bless –device /dev/diskX –legacy –setBoot –nextonly # bless the disk not the partition -# reboot -~~~ - -Insert Qubes 3.2 USB flash: -ISOLINUX boot screen should come up. -Select Troubleshooting and Boot the Rescue image; insert disk password when prompted; select continue and after mounting the HD filesystem, launching a shell, chroot as instructed. - -Then: -a) Find your Bluetooth card: -~~~ -# lspci -.. -02:00.0 Network controller: Broadcom Corporation BCM43224 802.11a/b/g/n (rev 01) -… -# qvm-pci -a sys-net 02:00.0 # this assigns the device to sys-net VM -~~~ - -then create Create /etc/systemd/system/qubes-pre-netvm.service -with: -~~~ -[Unit] -Description=Netvm fix for Broadcom -Before=qubes-netvm.service - -[Service] -ExecStart=/bin/sh -c 'echo 02:00.0 > /sys/bus/pci/drivers/pciback/permissive' -Type=oneshot -RemainAfterExit=yes - -[Install] -WantedBy=multi-user.target -~~~ -Run: -~~~ -systemctl enable qubes-pre-netvm.service -~~~ -And that’s it. - - -###3. After reboot, boot MacOSX, again. -Run Terminal application as root: -~~~ -# diskutil list -(find the HD device where you installed Qubes) -# bless –device /dev/diskX –legacy –setBoot # bless the disk not the partition -# reboot -~~~ - -Results: -* System booted and running smoothly. -* Youtube video: OK (including full screen after configuration) -* Trackpad: OK -* Audio control: OK -* Brightness control: OK -* Keyboard light control:OK -* SD card access: OK (tested at dom0) -* Lid-close suspend: OK -* Wifi: +10%-20% ICMP packet loss when comparing with OSX (have similar rates with tails Linux, more tests are required) - -References: [1] https://github.com/QubesOS/qubes-issues/issues/794 ; [2] https://github.com/QubesOS/qubes-issues/issues/1261 ; -[3] https://www.qubes-os.org/doc/assigning-devices/ ; From 49851d55755e7f33cc803474c58877bc86389d47 Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Mon, 24 Oct 2016 00:05:49 -0700 Subject: [PATCH 244/708] Incorporate existing MacBook troubleshooting entry --- .../{macbook.md => macbook-troubleshooting.md} | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) rename troubleshooting/{macbook.md => macbook-troubleshooting.md} (92%) diff --git a/troubleshooting/macbook.md b/troubleshooting/macbook-troubleshooting.md similarity index 92% rename from troubleshooting/macbook.md rename to troubleshooting/macbook-troubleshooting.md index 4d90404d..7103d795 100644 --- a/troubleshooting/macbook.md +++ b/troubleshooting/macbook-troubleshooting.md @@ -1,7 +1,7 @@ --- layout: doc title: Apple MacBook Troubleshooting -permalink: /doc/macbook/ +permalink: /doc/macbook-troubleshooting/ --- Apple MacBook Troubleshooting @@ -127,8 +127,15 @@ Results: 3. +MacBook Air 2012 (MacBookAir 5,1) +--------------------------------- + +Please see [this thread o the qubes-devel mailing list][macbook-air-2012-5-1]. + + [1]: https://github.com/QubesOS/qubes-issues/issues/794 [2]: https://github.com/QubesOS/qubes-issues/issues/1261 [3]: https://www.qubes-os.org/doc/assigning-devices/ [bluetooth-replacement]: https://www.ifixit.com/Guide/MacBook+Air+13-Inch+Mid+2011+AirPort-Bluetooth+Card+Replacement/6360 +[macbook-air-2012-5-1]: https://groups.google.com/d/topic/qubes-devel/uLDYGdKk_Dk/discussion From 69c35c7c7ece4f798a744f8955072da236401b1f Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Mon, 24 Oct 2016 00:07:01 -0700 Subject: [PATCH 245/708] Replace existing MacBook entry with new page --- doc.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc.md b/doc.md index c3a829b4..c305264f 100644 --- a/doc.md +++ b/doc.md @@ -172,7 +172,7 @@ Troubleshooting * [Installing on system with new AMD GPU (missing firmware problem)](https://groups.google.com/group/qubes-devel/browse_thread/thread/e27a57b0eda62f76) * [How to install an Nvidia driver in dom0](/doc/install-nvidia-driver/) * [Nvidia troubleshooting guide](/doc/nvidia-troubleshooting/) - * [Solving problems with Macbook Air 2012](https://groups.google.com/group/qubes-devel/browse_thread/thread/b8b0d819d2a4fc39/d50a72449107ab21#8a9268c09d105e69) + * [Apple MacBook Troubleshooting](/doc/macbook-troubleshooting/) * [Getting Sony Vaio Z laptop to work with Qubes](/doc/sony-vaio-tinkering/) * [Getting Lenovo 450 to work with Qubes](/doc/lenovo450-tinkering/) * [Getting Lenovo Thinkpad X201 to work with Qubes](/doc/thinkpad_x201/) From 39d1f8f26091f9d590d4db5124399e1abb9fb7ad Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Mon, 24 Oct 2016 00:12:48 -0700 Subject: [PATCH 246/708] Combine ThinkPad troubleshooting pages into a single page --- doc.md | 3 +- troubleshooting/thinkpad-troubleshooting.md | 33 ++++++++++++++++----- 2 files changed, 27 insertions(+), 9 deletions(-) diff --git a/doc.md b/doc.md index c305264f..76cd7546 100644 --- a/doc.md +++ b/doc.md @@ -172,10 +172,9 @@ Troubleshooting * [Installing on system with new AMD GPU (missing firmware problem)](https://groups.google.com/group/qubes-devel/browse_thread/thread/e27a57b0eda62f76) * [How to install an Nvidia driver in dom0](/doc/install-nvidia-driver/) * [Nvidia troubleshooting guide](/doc/nvidia-troubleshooting/) + * [Lenovo ThinkPad Troubleshooting](/doc/thinkpad-troubleshooting/) * [Apple MacBook Troubleshooting](/doc/macbook-troubleshooting/) * [Getting Sony Vaio Z laptop to work with Qubes](/doc/sony-vaio-tinkering/) - * [Getting Lenovo 450 to work with Qubes](/doc/lenovo450-tinkering/) - * [Getting Lenovo Thinkpad X201 to work with Qubes](/doc/thinkpad_x201/) * [Troubleshooting UEFI related problems](/doc/uefi-troubleshooting/) diff --git a/troubleshooting/thinkpad-troubleshooting.md b/troubleshooting/thinkpad-troubleshooting.md index 6ea6ec4b..4e5ed82b 100644 --- a/troubleshooting/thinkpad-troubleshooting.md +++ b/troubleshooting/thinkpad-troubleshooting.md @@ -1,15 +1,27 @@ --- layout: doc -title: ThinkPad Troubleshooting +title: Lenovo ThinkPad Troubleshooting permalink: /doc/thinkpad-troubleshooting/ redirect_from: - /doc/thinkpad_x201/ - /en/doc/thinkpad_x201/ - /doc/Thinkpad_X201/ - /wiki/Thinkpad_X201/ +- /doc/lenovo450-tinkering/ +- /en/doc/lenovo450-tinkering/ +- /doc/Lenovo450Tinkering/ +- /wiki/Lenovo450Tinkering/ --- -# ThinkPad Troubleshooting # +# Lenovo ThinkPad Troubleshooting # + +## ThinkPads with Intel HD 3000 graphics ## + +Several ThinkPad models have Intel HD 3000 graphics, including the T420s and the +T520. Some users with these laptops have experienced random reboots, which were +solved by adding `i915.enable_rc6=0` as a kernel parameter to +`GRUB_CMDLINE_LINUX` in the file `/etc/default/grub` in dom0. + ## Instructions for getting your Lenovo Thinkpad X201 & X200 laptop working with Qubes/Linux ## @@ -39,10 +51,17 @@ Then reboot, enter BIOS and re-enable VT-d. 2. Add the script to the startup-items of your desktop environment. -## ThinkPads with Intel HD 3000 graphics ## -Several ThinkPad models have Intel HD 3000 graphics, including the T420s and the -T520. Some users with these laptops have experienced random reboots, which were -solved by adding `i915.enable_rc6=0` as a kernel parameter to -`GRUB_CMDLINE_LINUX` in the file `/etc/default/grub` in dom0. +## Instructions for getting your Lenovo 450 laptop working with Qubes/Linux ## + +Lenovo 450 uses UEFI, so some settings are needed to get Qubes (or Fedora) to boot, otherwise Qubes install USB stick will reboot right after boot selector screen and not continue install. + +### Setting UEFI options to get Qubes install to boot ### + +1. Enable Legacy USB mode +2. Disable all Secure Boot and UEFI options, but leave this enabled: Config / USB / USB UEFI BIOS SUPPORT +3. Save settings and reboot +5. Install Qubes + +... and now enjoy :) These settings may be needed also in other UEFI computers. From 2753f8aa4b7b69e60d3a6a7d185bdf6b62da4b0d Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Mon, 24 Oct 2016 00:13:44 -0700 Subject: [PATCH 247/708] Remove deprecated page --- troubleshooting/lenovo450-tinkering.md | 24 ------------------------ 1 file changed, 24 deletions(-) delete mode 100644 troubleshooting/lenovo450-tinkering.md diff --git a/troubleshooting/lenovo450-tinkering.md b/troubleshooting/lenovo450-tinkering.md deleted file mode 100644 index 3a441c34..00000000 --- a/troubleshooting/lenovo450-tinkering.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -layout: doc -title: Lenovo450 Tinkering -permalink: /doc/lenovo450-tinkering/ -redirect_from: -- /en/doc/lenovo450-tinkering/ -- /doc/Lenovo450Tinkering/ -- /wiki/Lenovo450Tinkering/ ---- - -Instructions for getting your Lenovo 450 laptop working with Qubes/Linux -========================================================================= - -Lenovo 450 uses UEFI, so some settings are needed to get Qubes (or Fedora) to boot, otherwise Qubes install USB stick will reboot right after boot selector screen and not continue install. - -Setting UEFI options to get Qubes install to boot -------------------------------------------------- - -1. Enable Legacy USB mode -2. Disable all Secure Boot and UEFI options, but leave this enabled: Config / USB / USB UEFI BIOS SUPPORT -3. Save settings and reboot -5. Install Qubes - -... and now enjoy :) These settings may be needed also in other UEFI computers. From 3f5c670d6def8cb2bde29da67d6997a4a62c8664 Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Mon, 24 Oct 2016 01:40:07 -0700 Subject: [PATCH 248/708] Remove deprecated portion on KDE --- basics_dev/devel-faq.md | 13 ------------- 1 file changed, 13 deletions(-) diff --git a/basics_dev/devel-faq.md b/basics_dev/devel-faq.md index 76be513b..0f9cb4f2 100644 --- a/basics_dev/devel-faq.md +++ b/basics_dev/devel-faq.md @@ -18,19 +18,6 @@ Since 2013 [Xen has not supported 32-bit x86 architecture](http://wiki.xenprojec In addition, often it is more difficult to exploit a bug on the x64 Linux than it is on x86 Linux (e.g. ASLR is sometimes harder to get around). While we designed Qubes with the emphasis on limiting any potential attack vectors in the first place, still we realize that some of the code running in Dom0, e.g. our GUI daemon or xen-store daemon, even though it is very simple code, might contain some bugs. Plus currently we haven't implemented a separate storage domain, so also the disk backends are in Dom0 and are "reachable" from the VMs, which adds up to the potential attack surface. So, having faced a choice between 32-bit and 64-bit OS for Dom0, it was almost a no-brainer, as the 64-bit option provides some (little perhaps, but still) more protection against some classes of attacks, and at the same time does not have any disadvantages (except that it requires a 64-bit processor, but all systems on which it makes sense to run Qubes, e.g. that have at least 3-4GB memory, they do have 64-bit CPUs anyway). -Q: Why do you use KDE in Dom0? What is the roadmap for Gnome support? ---------------------------------------------------------------------- - -There are a few things that are KDE-specific, but generally it should not be a big problem to also add Gnome support to Qubes (in Dom0 of course). Those KDE-specific things are: - -- Qubes requires KDM (KDE Login Manager), rather than GDM, for the very simple reason that GDM doesn't obey standards and start `/usr/bin/Xorg` instead of `/usr/bin/X`. This is important for Qubes, because we need to load a special "X wrapper" (to make it possible to use Linux usermode shared memory to access Xen shared memory pages in our App Viewers -- see the sources [here](https://github.com/QubesOS/qubes-gui-daemon/tree/master/shmoverride)). So, Qubes makes the `/usr/bin/X` to be a symlink to the Qubes X Wrapper, which, in turn, executes the `/usr/bin/Xorg`. This works well with KDM (and would probably also work with other X login managers), but not with GDM. If somebody succeeded in makeing GDM to execute `/usr/bin/X` instead of `/usr/bin/Xorg`, we would love to hear about it! - -- We maintain a special [repository](/doc/kde-dom0/) for building packages specifically for Qubes Dom0. - -- We've patched the KDE's Window Manager (specifically [one of the decoration plugins](https://github.com/QubesOS/qubes-desktop-linux-kde/tree/master/plastik-for-qubes)) to draw window decorations in the color of the specific AppVM's label. - -If you're interested in porting GNOME for Qubes Dom0 use, let us know -- we will most likely welcome patches in this area. - Q: What is the recommended build environment? --------------------------------------------- From f879771e241d40747f919b61640cf4e52cb993c3 Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Mon, 24 Oct 2016 01:40:40 -0700 Subject: [PATCH 249/708] Remove index entry for kde-dom0 page --- doc.md | 1 - 1 file changed, 1 deletion(-) diff --git a/doc.md b/doc.md index 76cd7546..0f17df30 100644 --- a/doc.md +++ b/doc.md @@ -246,7 +246,6 @@ Building -------- * [Building Qubes](/doc/qubes-builder/) (["API" Details](/doc/qubes-builder-details/)) * [Development Workflow](/doc/development-workflow/) - * [KDE Dom0 packages for Qubes](/doc/kde-dom0/) * [Building Qubes OS 3.0 ISO](/doc/qubes-r3-building/) * [Building USB passthrough support (experimental)](/doc/pvusb/) * [Building Qubes Templates](https://github.com/QubesOS/qubes-template-configs) From c4b8166ffe2b9534a1d26ed984d3c8364154e394 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Marczykowski-G=C3=B3recki?= Date: Tue, 25 Oct 2016 21:49:17 +0200 Subject: [PATCH 250/708] backup format v4: add backup_id field Protect against feeding the user with the same VM but from older/newer backup. --- common-tasks/backup-emergency-restore-v4.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/common-tasks/backup-emergency-restore-v4.md b/common-tasks/backup-emergency-restore-v4.md index a2f5efc0..3b94a75a 100644 --- a/common-tasks/backup-emergency-restore-v4.md +++ b/common-tasks/backup-emergency-restore-v4.md @@ -64,12 +64,14 @@ Recovery - format version 3](/doc/backup-emergency-restore-v3/) encrypted=True compressed=True compression-filter=gzip + backup_id=20161020T123455-1234 6. Verify the integrity and decrypt the `private.img` file which houses your data. + [user@restore ~]$ backup_id=20161020T123455-1234 # see backup-header above [user@restore ~]$ for f_enc in vm1/private.img.???.enc; do \ f_dec=${f_enc%.enc}; \ - echo "$f_dec!$backup_pass" | scrypt -P dec $f_enc $f_dec || break; \ + echo "$backup_id!$f_dec!$backup_pass" | scrypt -P dec $f_enc $f_dec || break; \ done **Note:** If the above fail, most likely your backup is corrupted, or been tampered with. From 66650144bf1c71901dec3494db5d2d05e0410ba6 Mon Sep 17 00:00:00 2001 From: Thom Wiggers Date: Tue, 25 Oct 2016 22:59:28 +0200 Subject: [PATCH 251/708] Format instructions I also added Xfce to the description since it's quite similar how you would add it to xfce. --- privacy/signal.md | 26 +++++++++++++++----------- 1 file changed, 15 insertions(+), 11 deletions(-) diff --git a/privacy/signal.md b/privacy/signal.md index f9ed8bc3..74598ec4 100644 --- a/privacy/signal.md +++ b/privacy/signal.md @@ -38,26 +38,30 @@ If you're a Signal user on Android, you can now have Signal inside Qubes. this app with your phone. 6. Signal should now work in your AppVM. -Creating a Shortcut in KDE --------------------------- +Creating a Shortcut in the applications menu +-------------------------------------------- Let's make Signal a bit more usable by creating a shortcut in our desktop -panel that launches Signal directly. This assumes that you're using KDE in Dom0, +panel that launches Signal directly. This assumes that you're using KDE or Xfce in Dom0, you use Signal in an AppVM named `Signal`, and this AppVM uses `fedora-23` as its TemplateVM. 1. Follow [these instructions][shortcut] to create a desktop shortcut on the Desktop of your Signal AppVM. - Let's assume the shortcut file you get is /home/user/Desktop/chrome-bikioccmkafdpakkkcpdbhpfkkhcmohk-Default.desktop -2. Copy this shortcut file to the AppVM's TemplateVM - in this case, to fedora-23. + Let's assume the shortcut file you get is `/home/user/Desktop/chrome-bikioccmkafdpakkkcpdbhpfkkhcmohk-Default.desktop` +2. Copy this shortcut file to the AppVM's TemplateVM - in this case, to `fedora-23`. 3. You'll also want to copy across an icon for your new shortcut - you can find this at - /home/user/.local/share/icons/hicolor/48x48/apps/chrome-bikioccmkafdpakkkcpdbhpfkkhcmohk-Default.png - Copy this icon to the fedora-23 TemplateVM. -4. Open a terminal in your fedora-23 TemplateVM and cd to /home/user/QubesIncoming/Signal/ + `/home/user/.local/share/icons/hicolor/48x48/apps/chrome-bikioccmkafdpakkkcpdbhpfkkhcmohk-Default.png` + Copy this icon to the `fedora-23` TemplateVM. +4. Open a terminal in your `fedora-23` TemplateVM and `cd` to `/home/user/QubesIncoming/Signal/`. You should find your shortcut and icon files just transferred across from the Signal AppVM. Move these files to the following locations: - [user@fedora-23 Signal]$ sudo mv chrome-bikioccmkafdpakkkcpdbhpfkkhcmohk-Default.desktop /usr/share/applications/ - [user@fedora-23 Signal]$ sudo mv chrome-bikioccmkafdpakkkcpdbhpfkkhcmohk-Default.png /usr/share/icons/hicolor/48x48/ + + [user@fedora-23 Signal]$ sudo mv chrome-bikioccmkafdpakkkcpdbhpfkkhcmohk-Default.desktop /usr/share/applications/ + [user@fedora-23 Signal]$ sudo mv chrome-bikioccmkafdpakkkcpdbhpfkkhcmohk-Default.png /usr/share/icons/hicolor/48x48/ + 5. From a Dom0 terminal, instruct Qubes to synchronize the application menus of this TemplateVM: - [user@dom0 ~]$ qvm-sync-appmenus fedora-23 + + [user@dom0 ~]$ qvm-sync-appmenus fedora-23 + 6. With your mouse select the `Q` menu -> `Domain: Signal` -> `Signal: Add more shortcuts` Select `Signal Private Messenger` from the left `Available` column, move it to the right `Selected` column by clicking the `>` button and then `OK` to apply the changes and close the window. 7. Then follow the `Q` menu once more, right-click on the new `Signal: Signal Private Messenger` menu item and select `Add to Panel`. From 65fc5bc0c58887333dd08137e5915fb9354e7237 Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Tue, 1 Nov 2016 04:50:29 -0700 Subject: [PATCH 252/708] Clarify wording regarding manual reinstallation option https://github.com/QubesOS/qubes-doc/pull/201#issuecomment-257524128 --- managing-os/reinstall-template.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/managing-os/reinstall-template.md b/managing-os/reinstall-template.md index 0c69a072..6be0ca38 100644 --- a/managing-os/reinstall-template.md +++ b/managing-os/reinstall-template.md @@ -29,9 +29,9 @@ restarted. Manual Reinstallation Method ---------------------------- -If you're using Qubes 3.0 or older, or if you wish to do a clean reinstallation -of a template in order to upgrade to a different version, you should use the -manual method. +If you're using Qubes 3.0 or older, you should use the manual reinstallation +method. You can also use this method on later Qubes versions if, for any reason, +you want to reinstall a template manually. In what follows, the term "target TemplateVM" refers to whichever TemplateVM you want to reinstall. If you want to reinstall more than one TemplateVM, repeat From 87f5804bed3be3374e928dabf91413c97290b707 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Marczykowski-G=C3=B3recki?= Date: Wed, 2 Nov 2016 00:58:01 +0100 Subject: [PATCH 253/708] Add Fedora 23->24 upgrade instruction --- doc.md | 1 + managing-os/fedora-template-upgrade-23.md | 170 ++++++++++++++++++++++ 2 files changed, 171 insertions(+) create mode 100644 managing-os/fedora-template-upgrade-23.md diff --git a/doc.md b/doc.md index 0f17df30..4c358762 100644 --- a/doc.md +++ b/doc.md @@ -87,6 +87,7 @@ Managing Operating Systems within Qubes * [Advanced options and troubleshooting of Qubes Tools for Windows (R3)](/doc/windows-tools-3/) * [Advanced options and troubleshooting of Qubes Tools for Windows (R2)](/doc/windows-tools-2/) * [Uninstalling Qubes Tools for Windows 2.x](/doc/uninstalling-windows-tools-2/) + * [Upgrading the Fedora 23 Template](/doc/fedora-template-upgrade-23/) * [Upgrading the Fedora 21 Template](/doc/fedora-template-upgrade-21/) * [Upgrading the Fedora 20 Template](/doc/fedora-template-upgrade-20/) * [Upgrading the Fedora 18 Template](/doc/fedora-template-upgrade-18/) diff --git a/managing-os/fedora-template-upgrade-23.md b/managing-os/fedora-template-upgrade-23.md new file mode 100644 index 00000000..cf74037d --- /dev/null +++ b/managing-os/fedora-template-upgrade-23.md @@ -0,0 +1,170 @@ +--- +layout: doc +title: Upgrading the Fedora 23 Template +permalink: /doc/fedora-template-upgrade-23/ +redirect_from: +- /en/doc/fedora-template-upgrade-23/ +- /doc/FedoraTemplateUpgrade23/ +- /wiki/FedoraTemplateUpgrade23/ +--- + +Upgrading the Fedora 23 Template +================================ + +Summary: Upgrading the Standard Fedora 23 Template to Fedora 24 +--------------------------------------------------------------- + + [user@dom0 ~]$ qvm-clone fedora-23 fedora-24 + [user@dom0 ~]$ truncate -s 5GB /var/tmp/template-upgrade-cache.img + [user@dom0 ~]$ qvm-run -a fedora-24 gnome-terminal + [user@dom0 ~]$ qvm-block -A fedora-24 dom0:/var/tmp/template-upgrade-cache.img + [user@fedora-24 ~]$ sudo mkfs.ext4 /dev/xvdi + [user@fedora-24 ~]$ sudo mount /dev/xvdi /mnt/removable + [user@fedora-24 ~]$ sudo dnf clean all + [user@fedora-24 ~]$ sudo dnf --releasever=24 --setopt=cachedir=/mnt/removable distro-sync + + (Shut down TemplateVM by any normal means.) + + [user@dom0 ~]$ rm /var/tmp/template-upgrade-cache.img + [user@dom0 ~]$ qvm-trim-template fedora-24 + + (Done.) + +Detailed: Upgrading the Standard Fedora 23 Template to Fedora 24 +---------------------------------------------------------------- + +These instructions will show you how to upgrade the standard Fedora 23 +TemplateVM to Fedora 24. The same general procedure may be used to upgrade any +template based on the standard Fedora 23 template. + + 1. Ensure the existing template is not running. + + [user@dom0 ~]$ qvm-shutdown fedora-23 + + 2. Clone the existing template and start a terminal in the new template. + + [user@dom0 ~]$ qvm-clone fedora-23 fedora-24 + [user@dom0 ~]$ qvm-run -a fedora-24 gnome-terminal + + 2. Attempt the upgrade process in the new template. + + [user@fedora-24 ~]$ sudo dnf clean all + [user@fedora-24 ~]$ sudo dnf --releasever=24 distro-sync + + 3. Shutdown the new TemplateVM via dom0 command line or Qubes VM Manager; + + [user@dom0 ~]$ qvm-shutdown fedora-24 + + If you encounter no errors, proceed to step 7. + + 4. If `dnf` reports that you do not have enough free disk space to proceed with + the upgrade process, create an empty file in dom0 to use as a cache and + attach it to the template as a virtual disk. + + [user@dom0 ~]$ truncate -s 5GB /var/tmp/template-upgrade-cache.img + [user@dom0 ~]$ qvm-block -A fedora-24 dom0:/var/tmp/template-upgrade-cache.img + + Then reattempt the upgrade process, but this time using the virtual disk as + a cache. + + [user@fedora-24 ~]$ sudo mkfs.ext4 /dev/xvdi + [user@fedora-24 ~]$ sudo mount /dev/xvdi /mnt/removable + [user@fedora-24 ~]$ sudo dnf clean all + [user@fedora-24 ~]$ sudo dnf --releasever=24 --setopt=cachedir=/mnt/removable distro-sync + + (Poweroff via Qubes VM Manager. May need to be killed.) + + 5. `dnf` may complain: + + At least X MB more space needed on the / filesystem. + + In this case, one option is to [resize the TemplateVM's disk + image](/doc/ResizeDiskImage/) before reattempting the upgrade process. + (See **Additional Information** below for other options.) + + 6. After the upgrade process is finished, remove the cache file, if you + created one. + + [user@dom0 ~]$ rm /var/tmp/template-upgrade-cache.img + + 7. Trim the new template (see **Compacting the Upgraded Template** for details + and other options). + + [user@dom0 ~]$ qvm-trim-template fedora-24 + + 8. (Optional) Remove the old default template. + + [user@dom0 ~]$ sudo dnf remove qubes-template-fedora-23 + + +Summary: Upgrading the Minimal Fedora 23 Template to Fedora 24 +-------------------------------------------------------------- + + [user@dom0 ~]$ qvm-clone fedora-23-minimal fedora-24-minimal + [user@dom0 ~]$ qvm-run -a fedora-24-minimal xterm + [user@fedora-24-minimal ~]$ su - + [root@fedora-24-minimal ~]# dnf clean all + [user@fedora-24-minimal ~]# dnf --releasever=24 distro-sync + + (Shut down TemplateVM by any normal means.) + + [user@dom0 ~]$ qvm-trim-template fedora-24-minimal + +(If you encounter insufficient space issues, you may need to use the methods +described for the standard template above.) + + +Differences Between the Standard and Minimal Upgrade Procedures +--------------------------------------------------------------- + +The procedure for upgrading the minimal template (or any template based on the +minimal template) is the same as the procedure for the standard template above, +**with the following exceptions**: + + 1. `gnome-terminal` is not installed by default. Unless you've installed it + (or another terminal emulator), use `xterm`. (Of course, you can also use + `xterm` for the standard template, if you prefer.) + 2. `sudo` is not installed by default. Unless you've installed it, use `su` as + demonstrated above. (Of course, you can also use `su` for the standard + template, if you prefer.) + + +Compacting the Upgraded Template +================================ + +Neither `fstrim` nor the `discard` mount option works on the TemplateVM's root +filesystem, so when a file is removed in the template, space is not freed in +dom0. This means that the template will use about twice as much space as is +really necessary after upgrading. + +You can use the `qvm-trim-template` tool: + + [user@dom0 ~]$ qvm-trim-template fedora-24 + + +Additional Information +====================== + +As mentioned above, you may encounter the following `dnf` error: + + At least X MB more space needed on the / filesystem. + +In this case, you have several options: + + 1. [Increase the TemplateVM's disk image size](/doc/resize-disk-image/). + This is the solution mentioned in the main instructions above. + 2. Delete files in order to free up space. One way to do this is by + uninstalling packages. You may then reinstalling them again after you + finish the upgrade process, if desired). However, you may end up having to + increase the disk image size anyway (see previous option). + 3. Increase the `root.img` size with `qvm-grow-root`. + 4. Do the upgrade in parts, e.g., by using package groups. (First upgrade + `@core` packages, then the rest.) + 5. Do not perform an in-place upgrade. Instead, simply download and install a + new template package, then redo all desired template modifications. + +With regard to the last option, here are some useful messages from the mailing +list which also apply to TemplateVM management and migration in general: + + * [Marek](https://groups.google.com/d/msg/qubes-users/mCXkxlACILQ/dS1jbLRP9n8J) + * [Jason M](https://groups.google.com/d/msg/qubes-users/mCXkxlACILQ/5PxDfI-RKAsJ) From 915a1347c843649a971af35f74e27c85b970badc Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Wed, 2 Nov 2016 21:34:27 -0700 Subject: [PATCH 254/708] Remove deprecated section on UEFI boot --- configuration/multiboot.md | 12 ------------ 1 file changed, 12 deletions(-) diff --git a/configuration/multiboot.md b/configuration/multiboot.md index 01a77d18..e3660dcd 100644 --- a/configuration/multiboot.md +++ b/configuration/multiboot.md @@ -40,18 +40,6 @@ If you are really paranoid clone your disc. Make sure you have install discs to hand for the existing operating system. -Qubes 3.0 does not support UEFI boot. If you are already using it the first step -is to change boot mode. - -Most PCs using UEFI firmware and bootloader can be configured to disable -UEFI entirely and instead revert to legacy MBR boot mode. - -Two separate steps are often required to achieve this: - -* Enabling legacy boot mode -* Disabling Secure Boot - - Qubes by default does not include other systems in the generated grub menu, because handling of other systems has been disabled. This means that you will have to manually add grub entries for any other OS. From 534c345d81298736fd2b8aad8d73380aad73d1c6 Mon Sep 17 00:00:00 2001 From: Lauri Ojansivu Date: Fri, 4 Nov 2016 14:00:13 +0200 Subject: [PATCH 255/708] Add: Converting VirtualBox VM to HVM --- managing-os/hvm.md | 69 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 69 insertions(+) diff --git a/managing-os/hvm.md b/managing-os/hvm.md index 21fce99d..5775f479 100644 --- a/managing-os/hvm.md +++ b/managing-os/hvm.md @@ -72,6 +72,75 @@ The AppVM where the ISO is kept must be running for this to work as this VM is n ![r2b1-installing-ubuntu-1.png](/attachment/wiki/HvmCreate/r2b1-installing-ubuntu-1.png) +Converting VirtualBox VM to HVM +------------------------------- + +Microsoft provides [free 90 day evaluation VirtualBox VMs for browser testing](https://developer.microsoft.com/en-us/microsoft-edge/tools/vms/). + +About 60 GB of disk space is required for conversion, use external harddrive if needed. Final root.img size is 40 GB. + +In Debian AppVM, install qemu-utils and unzip: + +~~~ +sudo apt install qemu-utils unzip +~~~ + +Unzip VirtualBox zip file: + +~~~ +unzip *.zip +~~~ + +Extract OVA tar archive: + +~~~ +tar -xvf *.ova +~~~ + +Convert vmdk to raw: + +~~~ +qemu-img convert -O raw *.vmdk win10.raw +~~~ + +Create new HVM in Dom0, with amount of RAM in MB you wish: + +~~~ +qvm-create --hvm win10 --label red --mem=4096 +~~~ + +Copy file to Dom0: + +~~~ +qvm-run --pass-io untrusted 'cat "/media/user/externalhd/win10.raw"' > /var/lib/qubes/appvms/win10/root.img +~~~ + +Start win10 VM: + +~~~ +qvm-start win10 +~~~ + +**Optional ways to get more information** + +Filetype of OVA file: + +~~~ +file *.ova +~~~ + +List files of OVA tar archive: + +~~~ +tar -tf *.ova +~~~ + +List filetypes supported by qemu-img: + +~~~ +qemu-img -h | tail -n1 +~~~ + Setting up networking for HVM domains ------------------------------------- From a1867f36c5dbe0bed79bc89cc27334e041768dd5 Mon Sep 17 00:00:00 2001 From: m8r-5dbmvp Date: Sun, 6 Nov 2016 09:55:57 +0000 Subject: [PATCH 256/708] Included qubes-input-proxy-sender to the packages Expanded the description of a standard NetVM with qubes-input-proxy-sender, so that a 3.2 standard installation with NetVM=UsbVM does not leave USB broken when replacing the NetVM template with the fedora-minimal one. --- managing-os/templates/fedora-minimal.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/managing-os/templates/fedora-minimal.md b/managing-os/templates/fedora-minimal.md index 4370313e..cc62aecf 100644 --- a/managing-os/templates/fedora-minimal.md +++ b/managing-os/templates/fedora-minimal.md @@ -49,10 +49,10 @@ To access the journald log, use the `journalctl` command. ### as a NetVM -If you want to use this template to for standard NetVMs you should install some more packeges: +If you want to use this template to for standard NetVMs with USB forwarding capabilities you should install some more packeges: ~~~ -[user@F21-Minimal ~]$ sudo dnf install NetworkManager NetworkManager-wifi network-manager-applet wireless-tools dbus-x11 dejavu-sans-fonts tinyproxy +[user@F21-Minimal ~]$ sudo dnf install NetworkManager NetworkManager-wifi network-manager-applet wireless-tools dbus-x11 dejavu-sans-fonts tinyproxy qubes-input-proxy-sender ~~~ And maybe some more optional but useful packages as well: From 321e2da1cb95631a91115d90507f8289e1ca7c68 Mon Sep 17 00:00:00 2001 From: unman Date: Tue, 8 Nov 2016 18:15:36 +0000 Subject: [PATCH 257/708] Update qubes-firewall.md-include limit on iptables QubesOS/qubes-issues#1570 refers --- security/qubes-firewall.md | 85 +++++++++++++++++++++----------------- 1 file changed, 47 insertions(+), 38 deletions(-) diff --git a/security/qubes-firewall.md b/security/qubes-firewall.md index 6d5feca5..79827b37 100644 --- a/security/qubes-firewall.md +++ b/security/qubes-firewall.md @@ -14,8 +14,8 @@ Understanding Qubes networking and firewall Understanding firewalling in Qubes ---------------------------------- -Every VM in Qubes is connected to the network via a FirewallVM, which is used to -enforce network-level policies. By default there is one default Firewall VM, but +Every qube in Qubes is connected to the network via a FirewallVM, which is used to +enforce network-level policies. By default there is one default FirewallVM, but the user is free to create more, if needed. For more information, see the following: @@ -26,7 +26,7 @@ For more information, see the following: How to edit rules ----------------- -In order to edit rules for a given domain, select this domain in the Qubes +In order to edit rules for a given qube, select it in the Qubes Manager and press the "firewall" button: ![r2b1-manager-firewall.png](/attachment/wiki/QubesFirewall/r2b1-manager-firewall.png) @@ -41,69 +41,78 @@ firewall rules by hand. The firewall rules for each VM are saved in an XML file in that VM's directory in dom0: /var/lib/qubes/appvms//firewall.xml + +Please note that there is a 3kb limit to the size of the iptables script. +This equates to somewhere between 35 and 39 rules. +If this limit is exceeded then the qube will not start. + +It is possible to work around this limit by enforcing the rules on the qube itself +by putting appropriate rules in /rw/config. See [below](#where_to_put_firewall_rules). +In complex cases it might be appropriate to load a ruleset using iptables-restore +called from /rw/config/rc.local Reconnecting VMs after a NetVM reboot ---------------------------------------- -Normally Qubes doesn't let the user to stop a NetVM if there are other VMs +Normally Qubes doesn't let the user stop a NetVM if there are other qubes running which use it as their own NetVM. But in case the NetVM stops for whatever reason (e.g. it crashes, or the user forces its shutdown via qvm-kill via terminal in Dom0), then there is an easy way to restore the connection to -the netvm by issuing: +the NetVM by issuing: ` qvm-prefs -s netvm ` -Normally VMs do not connect directly to the actual NetVM which has networking -devices, but rather to the default FirewallVM first, and in most cases it would -be the NetVM that would crash, e.g. in response to S3 sleep/restore or other -issues with WiFi drivers. In that case it is necessary to just issue the above -command once, for the FirewallVM (this assumes default VM-naming used by the +Normally qubes do not connect directly to the actual NetVM which has networking +devices, but rather to the default sys-firewall first, and in most cases it would +be the NetVM that will crash, e.g. in response to S3 sleep/restore or other +issues with WiFi drivers. In that case it is only necessary to issue the above +command once, for the sys-firewall (this assumes default VM-naming used by the default Qubes installation): -` qvm-prefs firewallvm -s netvm netvm ` +` qvm-prefs sys-firewall -s netvm netvm ` -Enabling networking between two VMs +Enabling networking between two qubes -------------------------------------- -Normally any networking traffic between VMs is prohibited for security reasons. -However, in special situations, one might want to selectively allow specific VMs -to be able to establish networking connectivity between each other. For example, -this might come useful in some development work, when one wants to test +Normally any networking traffic between qubes is prohibited for security reasons. +However, in special situations, one might want to selectively allow specific qubes +to establish networking connectivity between each other. For example, +this might be useful in some development work, when one wants to test networking code, or to allow file exchange between HVM domains (which do not have Qubes tools installed) via SMB/scp/NFS protocols. -In order to allow networking between VM A and B follow those steps: +In order to allow networking between qubes A and B follow these steps: * Make sure both A and B are connected to the same firewall vm (by default all VMs use the same firewall VM). -* Note the Qubes IP addresses assigned to both VMs. This can be done using the - `qvm-ls -n` command, or via the Qubes Manager preferences pane for each VM. -* Start both VMs, and also open a terminal in the firewall VM +* Note the Qubes IP addresses assigned to both qubes. This can be done using the + `qvm-ls -n` command, or via the Qubes Manager preferences pane for each qube. +* Start both qubes, and also open a terminal in the firewall VM * In the firewall VM's terminal enter the following iptables rule: ~~~ sudo iptables -I FORWARD 2 -s -d -j ACCEPT ~~~ -* In VM B's terminal enter the following iptables rule: +* In qube B's terminal enter the following iptables rule: ~~~ sudo iptables -I INPUT -s -j ACCEPT ~~~ -* Now you should be able to reach the VM B from A -- test it using e.g. ping - issued from VM A. Note however, that this doesn't allow you to reach A from +* Now you should be able to reach B from A -- test it using e.g. ping + issued from A. Note however, that this doesn't allow you to reach A from B -- for this you would need two more rules, with A and B swapped. * If everything works as expected, then the above iptables rules should be - written into firewall VM's `qubes-firewall-user-script` script which is run + written into firewallVM's `qubes-firewall-user-script` script which is run on every firewall update, and A and B's `rc.local` script which is run when - the vm is launched. The `qubes-firewall-user-script` is necessary because Qubes - orders every firewall VM to update all the rules whenever new VM is started in - the system. If we didn't enter our rules into this "hook" script, then shortly + the qube is launched. The `qubes-firewall-user-script` is necessary because Qubes + orders every firewallVM to update all the rules whenever a new connected qube is + started. If we didn't enter our rules into this "hook" script, then shortly our custom rules would disappear and inter-VM networking would stop working. Here's an example how to update the script (note that, by default, there is no - script file present, so we likely will be creating it, unless we had some other - custom rules defines earlier in this firewallvm): + script file present, so we will probably be creating it, unless we had some other + custom rules defined earlier in this firewallVM): ~~~ [user@sys-firewall ~]$ sudo bash @@ -119,12 +128,12 @@ sudo iptables -I INPUT -s -j ACCEPT [root@B user]# chmod +x /rw/config/rc.local ~~~ -Port forwarding to a VM from the outside world +Port forwarding to a qube from the outside world -------------------------------------------------- -In order to allow a service present in a VM to be exposed to the outside world -in the default setup (where the VM has the Firewall VM as network VM, which in -turn has the Net VM as network VM) +In order to allow a service present in a qube to be exposed to the outside world +in the default setup (where the qube has sys-firewall as network VM, which in +turn has sys-net as network VM) the following needs to be done: * In the sys-net VM: @@ -133,8 +142,8 @@ the following needs to be done: * In the sys-firewall VM: * Route packets from the sys-net VM to the VM * Allow packets through the sys-firewall VM firewall - * In the VM: - * Allow packets in the VM firewall to reach the service + * In the qube: + * Allow packets in the qube firewall to reach the service As an example we can take the use case of a web server listening on port 443 that we want to expose on our physical interface eth0, but only to our local @@ -240,7 +249,7 @@ interface Eth0 (i.e. 10.137.2.x) ` ifconfig | grep -i cast ` Back into the sys-firewall VM's Terminal, code a natting firewall rule to route -traffic on its outside interface for the service to the VM +traffic on its outside interface for the service to the qube ` iptables -t nat -A PREROUTING -i eth0 -p tcp --dport 443 -d 10.137.1.x -j DNAT --to-destination 10.137.2.y ` @@ -305,7 +314,7 @@ Finally make this file executable (so it runs at every Firewall VM update) sudo chmod +x /rw/config/qubes-firewall-user-script ~~~ -**3. Allow packets into the VM to reach the service** +**3. Allow packets into the qube to reach the service** Here no routing is required, only filtering. Proceed in the same way as above but store the filtering rule in the '/rw/config/rc.local' script. @@ -338,7 +347,7 @@ Where to put firewall rules --------------------------- Implicit in the above example [scripts](/doc/config-files/), but worth -calling attention to: for all VMs *except* ProxyVMs, iptables commands +calling attention to: for all qubes *except* ProxyVMs, iptables commands should be added to the `/rw/config/rc.local` script. For ProxyVMs (`sys-firewall` inclusive), iptables commands should be added to `/rw/config/qubes-firewall-user-script`. This is because a ProxyVM is From 28aee1d10fc9a560d301f4c41d538498ca30b484 Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Wed, 9 Nov 2016 14:54:09 -0800 Subject: [PATCH 258/708] Fix link and clean up text --- security/qubes-firewall.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/security/qubes-firewall.md b/security/qubes-firewall.md index 79827b37..64c848e0 100644 --- a/security/qubes-firewall.md +++ b/security/qubes-firewall.md @@ -42,14 +42,14 @@ in that VM's directory in dom0: /var/lib/qubes/appvms//firewall.xml -Please note that there is a 3kb limit to the size of the iptables script. +Please note that there is a 3 kB limit to the size of the `iptables` script. This equates to somewhere between 35 and 39 rules. -If this limit is exceeded then the qube will not start. +If this limit is exceeded, the qube will not start. It is possible to work around this limit by enforcing the rules on the qube itself -by putting appropriate rules in /rw/config. See [below](#where_to_put_firewall_rules). -In complex cases it might be appropriate to load a ruleset using iptables-restore -called from /rw/config/rc.local +by putting appropriate rules in `/rw/config`. See [below](#where-to-put-firewall-rules). +In complex cases, it might be appropriate to load a ruleset using `iptables-restore` +called from `/rw/config/rc.local`. Reconnecting VMs after a NetVM reboot ---------------------------------------- From 84a1dd34f7c1c0f6b7aa3f7493db82ee87739d8e Mon Sep 17 00:00:00 2001 From: sprig-florist Date: Thu, 10 Nov 2016 20:40:21 +0000 Subject: [PATCH 259/708] Updated the qubes-input-proxy-sender package into another section. Moved the qubes-input-proxy-sender recommendation into a new section for the USBVMs, to cleanly separate it from the NetVM --- managing-os/templates/fedora-minimal.md | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/managing-os/templates/fedora-minimal.md b/managing-os/templates/fedora-minimal.md index cc62aecf..162e81e4 100644 --- a/managing-os/templates/fedora-minimal.md +++ b/managing-os/templates/fedora-minimal.md @@ -49,10 +49,10 @@ To access the journald log, use the `journalctl` command. ### as a NetVM -If you want to use this template to for standard NetVMs with USB forwarding capabilities you should install some more packeges: +If you want to use this template for standard NetVMs you should install some more packages: ~~~ -[user@F21-Minimal ~]$ sudo dnf install NetworkManager NetworkManager-wifi network-manager-applet wireless-tools dbus-x11 dejavu-sans-fonts tinyproxy qubes-input-proxy-sender +[user@F21-Minimal ~]$ sudo dnf install NetworkManager NetworkManager-wifi network-manager-applet wireless-tools dbus-x11 dejavu-sans-fonts tinyproxy ~~~ And maybe some more optional but useful packages as well: @@ -63,6 +63,14 @@ And maybe some more optional but useful packages as well: If your network device needs some firmware then you should also install the corresponding packages as well. The `lspci` and `dnf search firmware` command will help to choose the right one :) +### as a USBVM + +If you want this template to allow USB input forwarding, you will need to install one extra package. + +~~~ +[user@F21-Minimal ~]$ sudo dnf install qubes-input-proxy-sender +~~~ + ### as a ProxyVM If you want to use this template as a ProxyVM you may want to install even more packages From e6f34ca5d663e65f25cf021a04568c2e65c6607b Mon Sep 17 00:00:00 2001 From: unman Date: Fri, 11 Nov 2016 03:02:08 +0000 Subject: [PATCH 260/708] Update ubuntu.md --- managing-os/templates/ubuntu.md | 15 ++++++--------- 1 file changed, 6 insertions(+), 9 deletions(-) diff --git a/managing-os/templates/ubuntu.md b/managing-os/templates/ubuntu.md index 3a100cc5..e72640a7 100644 --- a/managing-os/templates/ubuntu.md +++ b/managing-os/templates/ubuntu.md @@ -12,10 +12,10 @@ redirect_from: Ubuntu template(s) ================== -If you like to use Ubuntu Linux distribution in your AppVMs, you can build and -install one of available Ubuntu templates. Those template currently are not +If you would like to use Ubuntu Linux distribution in your AppVMs, you can build and +install one of the available Ubuntu templates. These templates are currently not available in ready to use binary packages, because Canonical does not allow -to redistribute a modified Ubuntu. The redistribution is not allowed by their +redistribution of a modified Ubuntu. The redistribution is not allowed by their [Intellectual property rights policy](http://www.ubuntu.com/legal/terms-and-policies/intellectual-property-policy). @@ -30,15 +30,12 @@ To quickly prepare the builder configuration, you can use `setup` script available in the repository - it will interactively ask you which templates you want to build. +Ubuntu 14.4 LTS (Trusty) can be built with little effort. + Known issues ------------ -Building an Ubuntu 14.4 LTS template can be difficult ([see](https://groups.google.com/forum/#!topic/qubes-users/w0uZNr8nno8)). -A workaround is creating an ubuntu HVM A and use X over ssh from a second vm B ([see](https://groups.google.com/forum/#!topic/qubes-users/-wkG7E55PUI)). -To do this you have to enable networking between A and B, or set B as netvm of A. -If B supports copy and paste or seamless mode so does (indirectly) A. (you will be missing some features. e.g.: send file to vm A) -Doing this reduces the security of A to the security of B! -This is no problem, if B's only purpose is providing X over ssh only for vm A. + If you want to help in improving the template, feel free to [contribute](/wiki/ContributingHowto). From 6359f87ecdd878e6688896b1bf5388b2e42503a0 Mon Sep 17 00:00:00 2001 From: Jean-Philippe Ouellet Date: Fri, 11 Nov 2016 04:23:23 -0500 Subject: [PATCH 261/708] Fix issue link --- services/qrexec3.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/services/qrexec3.md b/services/qrexec3.md index d1aa3edb..cdc91150 100644 --- a/services/qrexec3.md +++ b/services/qrexec3.md @@ -187,9 +187,10 @@ _after_ considering the action. Sometimes just service name isn't enough to make reasonable qrexec policy. One example of such situation is [qrexec-based USB -passthrough](https://github.com/qubesos/qubes-issues/531) - using just service -name it isn't possible to express policy "allow access to device X and deny to -others". It isn't also feasible to create separate service for every device... +passthrough](https://github.com/qubesos/qubes-issues/issues/531) - using just +service name it isn't possible to express policy "allow access to device X and +deny to others". It isn't also feasible to create separate service for every +device... For this reason, starting with Qubes 3.2, it is possible to specify service argument, which will be subject to policy. Besides above example of USB From 852212e5d922562b6c5dd04929f75f88d257025d Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Fri, 11 Nov 2016 14:27:48 -0800 Subject: [PATCH 262/708] Remove Known Issues section and update Contributing link --- managing-os/templates/ubuntu.md | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/managing-os/templates/ubuntu.md b/managing-os/templates/ubuntu.md index e72640a7..af4dc282 100644 --- a/managing-os/templates/ubuntu.md +++ b/managing-os/templates/ubuntu.md @@ -32,10 +32,7 @@ want to build. Ubuntu 14.4 LTS (Trusty) can be built with little effort. -Known issues ------------- - - +---------- If you want to help in improving the template, feel free to -[contribute](/wiki/ContributingHowto). +[contribute](/doc/contributing/). From ee87a5e6d8b77720657bae2aa59c017a904c23b3 Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Fri, 11 Nov 2016 16:39:56 -0800 Subject: [PATCH 263/708] Update section link --- building/development-workflow.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/building/development-workflow.md b/building/development-workflow.md index c413b217..b1599dd6 100644 --- a/building/development-workflow.md +++ b/building/development-workflow.md @@ -541,6 +541,6 @@ Usage: add this line to `/etc/apt/sources.list` on test machine (adjust host and deb http://local-test.lan/linux-deb/r3.1 jessie-unstable main ~~~ -[port-forwarding]: /doc/qubes-firewall/#port-forwarding-to-a-vm-from-the-outside-world +[port-forwarding]: /doc/qubes-firewall/#port-forwarding-to-a-qube-from-the-outside-world [linux-yum]: https://github.com/QubesOS/qubes-linux-yum [linux-deb]: https://github.com/QubesOS/qubes-linux-deb From 8843982f76900e148e8fca09a6b96aff17cf4da0 Mon Sep 17 00:00:00 2001 From: sprig-florist Date: Sat, 12 Nov 2016 18:29:45 +0000 Subject: [PATCH 264/708] Re-working the template introduction First changes to re-work the introduction of the fedora-minimal template --- managing-os/templates/fedora-minimal.md | 37 +++++++++++-------------- 1 file changed, 16 insertions(+), 21 deletions(-) diff --git a/managing-os/templates/fedora-minimal.md b/managing-os/templates/fedora-minimal.md index 162e81e4..f9bbf978 100644 --- a/managing-os/templates/fedora-minimal.md +++ b/managing-os/templates/fedora-minimal.md @@ -12,35 +12,38 @@ redirect_from: Fedora - minimal ================ -The template weighs only about 300MB and has most of the stuff cut off, except for minimal X and xterm. It is really just a barebone and not even usable in this form - but you can customize it to meet your needs. You can find some usage examples in the section below. +The template only weighs about 300 MB and has only the most vital packages installed, including a minimal X and xterm installation. It is not thought to be usable in its original form. +The minimal template, however, can be easily extended to fit your requirements. The sections below contain the instructions on duplicating the template and provide some examples for commonly desired use cases. - - -Install +Installation ------- -It can be installed via the following command: +The Fedora minimal template can be installed with the following command: ~~~ [user@dom0 ~]$ sudo qubes-dom0-update qubes-template-fedora-23-minimal ~~~ -The download may take a while. +The download and installation process may take some time. -Usage +Cloning the template ----- -It is a good idea to clone the original template, and make any changes in the new clone instead: +It is higly recommended to clone the original template, and make any changes in the clone instead of the original template. The following command clones the template. Replace "your-new-clone" with your desired name. ~~~ -[user@dom0 ~]$ qvm-clone fedora-23-minimal +[user@dom0 ~]$ qvm-clone fedora-23-minimal your-new-clone ~~~ -The sudo package is not installed by default, so let's install it: +First steps +----- + +You must start the template machine in order to customize it. +A recommended first step is to install the `sudo` package, which is not installed by default in the minimal template: ~~~ -[user@F23-Minimal ~]$ su - -[user@F23-Minimal ~]$ dnf install sudo +[user@your-new-clone ~]$ su - +[user@your-new-clone ~]$ dnf install sudo ~~~ The rsyslog logging service is not installed by default. All logging is now being handled by the systemd journal. Users requiring the rsyslog service should install it manually. @@ -49,7 +52,7 @@ To access the journald log, use the `journalctl` command. ### as a NetVM -If you want to use this template for standard NetVMs you should install some more packages: +If you want to use this template to for standard NetVMs you should install some more packeges: ~~~ [user@F21-Minimal ~]$ sudo dnf install NetworkManager NetworkManager-wifi network-manager-applet wireless-tools dbus-x11 dejavu-sans-fonts tinyproxy @@ -63,14 +66,6 @@ And maybe some more optional but useful packages as well: If your network device needs some firmware then you should also install the corresponding packages as well. The `lspci` and `dnf search firmware` command will help to choose the right one :) -### as a USBVM - -If you want this template to allow USB input forwarding, you will need to install one extra package. - -~~~ -[user@F21-Minimal ~]$ sudo dnf install qubes-input-proxy-sender -~~~ - ### as a ProxyVM If you want to use this template as a ProxyVM you may want to install even more packages From e91680b6a942de73fb1f7706772bdfbf8a4c6cf7 Mon Sep 17 00:00:00 2001 From: sprig-florist Date: Sat, 12 Nov 2016 19:38:02 +0000 Subject: [PATCH 265/708] Formatted use cases as a table Formatted the document in a more structured table listing the known use cases. - Separated the network utilities from the standard util packages - Removed the ProxyVM section completely, as it didn't add much information - Moved the logging information to an ending section, where more topics can be listed. --- managing-os/templates/fedora-minimal.md | 71 +++++++++++-------------- 1 file changed, 32 insertions(+), 39 deletions(-) diff --git a/managing-os/templates/fedora-minimal.md b/managing-os/templates/fedora-minimal.md index f9bbf978..49efab45 100644 --- a/managing-os/templates/fedora-minimal.md +++ b/managing-os/templates/fedora-minimal.md @@ -26,7 +26,7 @@ The Fedora minimal template can be installed with the following command: The download and installation process may take some time. -Cloning the template +Duplication and first steps ----- It is higly recommended to clone the original template, and make any changes in the clone instead of the original template. The following command clones the template. Replace "your-new-clone" with your desired name. @@ -35,10 +35,7 @@ It is higly recommended to clone the original template, and make any changes in [user@dom0 ~]$ qvm-clone fedora-23-minimal your-new-clone ~~~ -First steps ------ - -You must start the template machine in order to customize it. +You must start the template in order to customize it. A recommended first step is to install the `sudo` package, which is not installed by default in the minimal template: ~~~ @@ -46,40 +43,36 @@ A recommended first step is to install the `sudo` package, which is not installe [user@your-new-clone ~]$ dnf install sudo ~~~ -The rsyslog logging service is not installed by default. All logging is now being handled by the systemd journal. Users requiring the rsyslog service should install it manually. +Customization +----- + +Customizing the template for specific use cases normally only requires installing additional packages. +The following table provides an overview of which packages are needed for which purpose. + +As expected, the required packages are to be installed in the running template with the following command. Replace "packages" with the list of packages to be installed, separated by space. + +~~~ +[user@your-new-clone ~]$ sudo dnf install packages +~~~ + +Use case | Description | Required steps +--- | --- | --- +**Standard utilities** | If you need the commonly used utilities | Install the following packages: `pciutils` `vim-minimal` `less` `psmisc` `gnome-keyring` +**Firewall VM** | You can use the minimal template as a firewall VM, such as the basis template for `sys-firewall` | No extra packages are needed for the template to work as a firewall. +**Network VM** | You can use this template as the basis for a NetVM such as `sys-net` | Install the following packages: `NetworkManager` `NetworkManager-wifi` `network-manager-applet` `wireless-tools` `dbus-x11 dejavu-sans-fonts` `tinyproxy`. +**Network VM (extra firmware)** | If your network devices need extra packages for the template to work as a network VM | Use the `lspci` command to identify the devices, then run `dnf search firmware` (replace "firmware" with the appropriate device identifier) to find the needed packages and then install them. +**Network utilities** | If you need utilities for debugging and analyzing network connections | Install the following packages: `tcpdump` `telnet` `nmap` `nmap-ncat` +**USB VM** | If you want USB input forwarding to use this template as the basis for a USBVM such as `sys-usb` | Install `qubes-input-proxy-sender` +**VPN VM** | You can use this template as basis for a VPN machine | Use the `dnf search "NetworkManager VPN plugin"` command to look up the VPN packages you need, based on the VPN technology you'll be using, and install them. Some GNOME related packages may be needed as well. After creation of a machine based on this template, follow the [VPN howto](/doc/vpn/#set-up-a-proxyvm-as-a-vpn-gateway-using-networkmanager) to configure it. +**TOR** | If you want to provide torified networking to other clients | As described in [the TorVM page](/doc/torvm/), the recommendation is to use [the standard Whonix image](/doc/whonix/) for this use case. + +Common questions +----- + +#### Logging + +The rsyslog logging service is not installed by default, as all logging is instead being handled by the systemd journal. +Users requiring the rsyslog service should install it manually. To access the journald log, use the `journalctl` command. -### as a NetVM - -If you want to use this template to for standard NetVMs you should install some more packeges: - -~~~ -[user@F21-Minimal ~]$ sudo dnf install NetworkManager NetworkManager-wifi network-manager-applet wireless-tools dbus-x11 dejavu-sans-fonts tinyproxy -~~~ - -And maybe some more optional but useful packages as well: - -~~~ -[user@F21-Minimal ~]$ sudo dnf install pciutils vim-minimal less tcpdump telnet psmisc nmap nmap-ncat gnome-keyring -~~~ - -If your network device needs some firmware then you should also install the corresponding packages as well. The `lspci` and `dnf search firmware` command will help to choose the right one :) - -### as a ProxyVM - -If you want to use this template as a ProxyVM you may want to install even more packages - -#### Firewall - -This template is now ready to use for a standard firewall VM. - -#### VPN - -The needed packages depend on the VPN technology. The `dnf search "NetworkManager VPN plugin"` command may help you to choose the right one. You should also install the corresponding GNOME related packages as well. - -[More details about setting up a VPN Gateway](/doc/vpn/#proxyvm) - -#### TOR - -[UserDoc/TorVM](/wiki/UserDoc/TorVM) From 070b782b73ef7829660f36b6ce92cb323cd6a2d1 Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Sat, 12 Nov 2016 12:29:09 -0800 Subject: [PATCH 266/708] Clean up text and formatting; add links --- managing-os/templates/fedora-minimal.md | 37 ++++++++++++------------- 1 file changed, 17 insertions(+), 20 deletions(-) diff --git a/managing-os/templates/fedora-minimal.md b/managing-os/templates/fedora-minimal.md index 49efab45..6b58adeb 100644 --- a/managing-os/templates/fedora-minimal.md +++ b/managing-os/templates/fedora-minimal.md @@ -12,11 +12,11 @@ redirect_from: Fedora - minimal ================ -The template only weighs about 300 MB and has only the most vital packages installed, including a minimal X and xterm installation. It is not thought to be usable in its original form. +The template only weighs about 300 MB and has only the most vital packages installed, including a minimal X and xterm installation. The minimal template, however, can be easily extended to fit your requirements. The sections below contain the instructions on duplicating the template and provide some examples for commonly desired use cases. Installation -------- +------------ The Fedora minimal template can be installed with the following command: @@ -24,12 +24,12 @@ The Fedora minimal template can be installed with the following command: [user@dom0 ~]$ sudo qubes-dom0-update qubes-template-fedora-23-minimal ~~~ -The download and installation process may take some time. +The download may take a while depending on your connection speed. Duplication and first steps ------ +--------------------------- -It is higly recommended to clone the original template, and make any changes in the clone instead of the original template. The following command clones the template. Replace "your-new-clone" with your desired name. +It is higly recommended to clone the original template, and make any changes in the clone instead of the original template. The following command clones the template. Replace `your-new-clone` with your desired name. ~~~ [user@dom0 ~]$ qvm-clone fedora-23-minimal your-new-clone @@ -44,12 +44,12 @@ A recommended first step is to install the `sudo` package, which is not installe ~~~ Customization ------ +------------- Customizing the template for specific use cases normally only requires installing additional packages. The following table provides an overview of which packages are needed for which purpose. -As expected, the required packages are to be installed in the running template with the following command. Replace "packages" with the list of packages to be installed, separated by space. +As expected, the required packages are to be installed in the running template with the following command. Replace "packages` with a space-delimited list of packages to be installed. ~~~ [user@your-new-clone ~]$ sudo dnf install packages @@ -58,21 +58,18 @@ As expected, the required packages are to be installed in the running template w Use case | Description | Required steps --- | --- | --- **Standard utilities** | If you need the commonly used utilities | Install the following packages: `pciutils` `vim-minimal` `less` `psmisc` `gnome-keyring` -**Firewall VM** | You can use the minimal template as a firewall VM, such as the basis template for `sys-firewall` | No extra packages are needed for the template to work as a firewall. -**Network VM** | You can use this template as the basis for a NetVM such as `sys-net` | Install the following packages: `NetworkManager` `NetworkManager-wifi` `network-manager-applet` `wireless-tools` `dbus-x11 dejavu-sans-fonts` `tinyproxy`. -**Network VM (extra firmware)** | If your network devices need extra packages for the template to work as a network VM | Use the `lspci` command to identify the devices, then run `dnf search firmware` (replace "firmware" with the appropriate device identifier) to find the needed packages and then install them. +**FirewallVM** | You can use the minimal template as a [FirewallVM](/doc/qubes-firewall/), such as the basis template for `sys-firewall` | No extra packages are needed for the template to work as a firewall. +**NetVM** | You can use this template as the basis for a NetVM such as `sys-net` | Install the following packages: `NetworkManager` `NetworkManager-wifi` `network-manager-applet` `wireless-tools` `dbus-x11 dejavu-sans-fonts` `tinyproxy`. +**NetVM (extra firmware)** | If your network devices need extra packages for the template to work as a network VM | Use the `lspci` command to identify the devices, then run `dnf search firmware` (replace `firmware` with the appropriate device identifier) to find the needed packages and then install them. **Network utilities** | If you need utilities for debugging and analyzing network connections | Install the following packages: `tcpdump` `telnet` `nmap` `nmap-ncat` -**USB VM** | If you want USB input forwarding to use this template as the basis for a USBVM such as `sys-usb` | Install `qubes-input-proxy-sender` -**VPN VM** | You can use this template as basis for a VPN machine | Use the `dnf search "NetworkManager VPN plugin"` command to look up the VPN packages you need, based on the VPN technology you'll be using, and install them. Some GNOME related packages may be needed as well. After creation of a machine based on this template, follow the [VPN howto](/doc/vpn/#set-up-a-proxyvm-as-a-vpn-gateway-using-networkmanager) to configure it. -**TOR** | If you want to provide torified networking to other clients | As described in [the TorVM page](/doc/torvm/), the recommendation is to use [the standard Whonix image](/doc/whonix/) for this use case. +**USB** | If you want USB input forwarding to use this template as the basis for a [USB](/doc/usb/) qube such as `sys-usb` | Install `qubes-input-proxy-sender` +**VPN** | You can use this template as basis for a [VPN](/doc/vpn/) qube | Use the `dnf search "NetworkManager VPN plugin"` command to look up the VPN packages you need, based on the VPN technology you'll be using, and install them. Some GNOME related packages may be needed as well. After creation of a machine based on this template, follow the [VPN howto](/doc/vpn/#set-up-a-proxyvm-as-a-vpn-gateway-using-networkmanager) to configure it. -Common questions ------ +Logging +------- -#### Logging +The `rsyslog` logging service is not installed by default, as all logging is instead being handled by the `systemd` journal. +Users requiring the `rsyslog` service should install it manually. -The rsyslog logging service is not installed by default, as all logging is instead being handled by the systemd journal. -Users requiring the rsyslog service should install it manually. - -To access the journald log, use the `journalctl` command. +To access the `journald` log, use the `journalctl` command. From 2d07f7831c9be109f3dbc42165b3e38038f9bee8 Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Sat, 12 Nov 2016 12:39:24 -0800 Subject: [PATCH 267/708] Change "/doc/qubes-firewall/" to "/doc/firewall/" --- building/development-workflow.md | 2 +- common-tasks/software-update-vm.md | 4 ++-- doc.md | 2 +- managing-os/templates/fedora-minimal.md | 2 +- security/data-leaks.md | 2 +- security/{qubes-firewall.md => firewall.md} | 7 ++++--- 6 files changed, 10 insertions(+), 9 deletions(-) rename security/{qubes-firewall.md => firewall.md} (99%) diff --git a/building/development-workflow.md b/building/development-workflow.md index b1599dd6..4ddce81f 100644 --- a/building/development-workflow.md +++ b/building/development-workflow.md @@ -541,6 +541,6 @@ Usage: add this line to `/etc/apt/sources.list` on test machine (adjust host and deb http://local-test.lan/linux-deb/r3.1 jessie-unstable main ~~~ -[port-forwarding]: /doc/qubes-firewall/#port-forwarding-to-a-qube-from-the-outside-world +[port-forwarding]: /doc/firewall/#port-forwarding-to-a-qube-from-the-outside-world [linux-yum]: https://github.com/QubesOS/qubes-linux-yum [linux-deb]: https://github.com/QubesOS/qubes-linux-deb diff --git a/common-tasks/software-update-vm.md b/common-tasks/software-update-vm.md index 44f125fa..c4402eeb 100644 --- a/common-tasks/software-update-vm.md +++ b/common-tasks/software-update-vm.md @@ -99,7 +99,7 @@ As the template VM is used for creating filesystems for other AppVMs, where you There are several ways to deal with this problem: -- Only install packages from trusted sources -- e.g. from the pre-configured Fedora repositories. All those packages are signed by Fedora, and as we expect that at least the package's installation scripts are not malicious. This is enforced by default (at the [firewall VM level](/doc/qubes-firewall/)), by not allowing any networking connectivity in the default template VM, except for access to the Fedora repos. +- Only install packages from trusted sources -- e.g. from the pre-configured Fedora repositories. All those packages are signed by Fedora, and as we expect that at least the package's installation scripts are not malicious. This is enforced by default (at the [firewall VM level](/doc/firewall/)), by not allowing any networking connectivity in the default template VM, except for access to the Fedora repos. - Use *standalone VMs* (see below) for installation of untrusted software packages. @@ -109,7 +109,7 @@ Some popular questions: - So, why should we actually trust Fedora repos -- it also contains large amount of 3rd party software that might buggy, right? -As long as template's compromise is considered, it doesn't really matter whether /usr/bin/firefox is buggy and can be exploited, or not. What matters is whether its *installation* scripts (such as %post in the rpm.spec) are benign or not. Template VM should be used only for installation of packages, and nothing more, so it should never get a chance to actually run the /usr/bin/firefox and got infected from it, in case it was compromised. Also, some of your more trusted AppVMs, would have networking restrictions enforced by the [firewall VM](/doc/qubes-firewall/), and again they should not fear this proverbial /usr/bin/firefox being potentially buggy and easy to compromise. +As long as template's compromise is considered, it doesn't really matter whether /usr/bin/firefox is buggy and can be exploited, or not. What matters is whether its *installation* scripts (such as %post in the rpm.spec) are benign or not. Template VM should be used only for installation of packages, and nothing more, so it should never get a chance to actually run the /usr/bin/firefox and got infected from it, in case it was compromised. Also, some of your more trusted AppVMs, would have networking restrictions enforced by the [firewall VM](/doc/firewall/), and again they should not fear this proverbial /usr/bin/firefox being potentially buggy and easy to compromise. - But why trusting Fedora? diff --git a/doc.md b/doc.md index 4c358762..61690762 100644 --- a/doc.md +++ b/doc.md @@ -101,7 +101,7 @@ Security Guides * [Qubes OS Project Security Information](/security/) * [Security Guidelines](/doc/security-guidelines/) - * [Understanding Qubes Firewall](/doc/qubes-firewall/) + * [Understanding Qubes Firewall](/doc/firewall/) * [Understanding and Preventing Data Leaks](/doc/data-leaks/) * [Installing Anti Evil Maid](/doc/anti-evil-maid/) * [Using Multi-factor Authentication with Qubes](/doc/multifactor-authentication/) diff --git a/managing-os/templates/fedora-minimal.md b/managing-os/templates/fedora-minimal.md index 6b58adeb..e220e5ab 100644 --- a/managing-os/templates/fedora-minimal.md +++ b/managing-os/templates/fedora-minimal.md @@ -58,7 +58,7 @@ As expected, the required packages are to be installed in the running template w Use case | Description | Required steps --- | --- | --- **Standard utilities** | If you need the commonly used utilities | Install the following packages: `pciutils` `vim-minimal` `less` `psmisc` `gnome-keyring` -**FirewallVM** | You can use the minimal template as a [FirewallVM](/doc/qubes-firewall/), such as the basis template for `sys-firewall` | No extra packages are needed for the template to work as a firewall. +**FirewallVM** | You can use the minimal template as a [FirewallVM](/doc/firewall/), such as the basis template for `sys-firewall` | No extra packages are needed for the template to work as a firewall. **NetVM** | You can use this template as the basis for a NetVM such as `sys-net` | Install the following packages: `NetworkManager` `NetworkManager-wifi` `network-manager-applet` `wireless-tools` `dbus-x11 dejavu-sans-fonts` `tinyproxy`. **NetVM (extra firmware)** | If your network devices need extra packages for the template to work as a network VM | Use the `lspci` command to identify the devices, then run `dnf search firmware` (replace `firmware` with the appropriate device identifier) to find the needed packages and then install them. **Network utilities** | If you need utilities for debugging and analyzing network connections | Install the following packages: `tcpdump` `telnet` `nmap` `nmap-ncat` diff --git a/security/data-leaks.md b/security/data-leaks.md index efd9513b..3fafeab5 100644 --- a/security/data-leaks.md +++ b/security/data-leaks.md @@ -14,7 +14,7 @@ Understanding and Preventing Data Leaks The Role of the Firewall ------------------------ -**[Firewalling in Qubes](/doc/qubes-firewall/) is not intended to be a leak-prevention mechanism.** +**[Firewalling in Qubes](/doc/firewall/) is not intended to be a leak-prevention mechanism.** There are several reasons for this, which will be explained below. However, the main reason is that Qubes cannot prevent an attacker who has compromised one AppVM (with restrictive firewall rules) from leaking data via cooperative covert channels through a different AppVM (with sufficiently nonrestrictive firewall rules, if any) which the attacker has also compromised. diff --git a/security/qubes-firewall.md b/security/firewall.md similarity index 99% rename from security/qubes-firewall.md rename to security/firewall.md index 64c848e0..23c925cc 100644 --- a/security/qubes-firewall.md +++ b/security/firewall.md @@ -1,9 +1,10 @@ --- layout: doc -title: Qubes Firewall -permalink: /doc/qubes-firewall/ +title: The Qubes Firewall +permalink: /doc/firewall/ redirect_from: -- /en/doc/qubes-firewall/ +- /doc/firewall/ +- /en/doc/firewall/ - /doc/QubesFirewall/ - /wiki/QubesFirewall/ --- From d77c58b6c78b1fd4c593b25b2ab1fb83dba3e9d9 Mon Sep 17 00:00:00 2001 From: Michael Carbone Date: Sun, 13 Nov 2016 16:12:58 -0500 Subject: [PATCH 268/708] make more inviting, improve language I modified it to get it closer to [best practices for contributing pages](https://github.com/nayafia/contributing-template/blob/master/CONTRIBUTING-template.md) --- basics_dev/contributing.md | 32 ++++++++++++++++++-------------- 1 file changed, 18 insertions(+), 14 deletions(-) diff --git a/basics_dev/contributing.md b/basics_dev/contributing.md index e3cf2d38..3664aff4 100644 --- a/basics_dev/contributing.md +++ b/basics_dev/contributing.md @@ -11,24 +11,28 @@ redirect_from: How can I contribute to the Qubes Project? ========================================== -Ok, so you think Qubes Project is cool and you would like to contribute? You are very welcome! +Thank you for your interest in contributing to the Qubes OS project! -First you should decide what you are interested in (and good in). The Qubes project would welcome contributions in various areas: +Following these guidelines helps communicate you respect the time of the developers managing and developing this open source project. In return, they will reciprocate that respect in addressing your issue, assessing changes, and helping you finalize your pull requests. -- Testing and [bug reporting](/doc/reporting-bugs/) -- Code audit (e.g. gui-daemon) -- New features -- Artwork (plymouth themes, KDM themes, installer themes, wallpapers, etc) -- [Documentation](/doc/doc-guidelines) +There are many ways to contribute to the Qubes OS project: -Perhaps the best starting point is to have a look at the [issues](https://github.com/QubesOS/qubes-issues/issues) to see what are the most urgent tasks to do. +- writing turorials or recording video demos +- testing and [bug reporting](/doc/reporting-bugs/) +- auditing code +- requesting or implementing new features +- creating artwork (plymouth themes, KDM themes, installer themes, wallpapers, etc) +- writing [documentation](/doc/doc-guidelines) -Before you engage in some longer activity, e.g. implementing a new feature, it's always good to contact us first (preferably via the [qubes-devel](/doc/mailing-lists/) list), to avoid a situation when two or more independent people would work on the same feature at the same time, doubling each other's work. When you contact us and devote to a particular task, we will create a ticket for this task with info who is working on this feature and what is the expected date of some early code to be posted. +The best starting point is to have a look at the [issues](https://github.com/QubesOS/qubes-issues/issues) to see what are the most urgent tasks to do. You can filter issues depending on your interest and experience, such as: -When you are ready to start some work, read how to [access Qubes sources and send patches](/doc/source-code/). +- [help wanted](https://github.com/QubesOS/qubes-issues/issues?page=3&q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22&utf8=%E2%9C%93) +- [UX and usability](https://github.com/QubesOS/qubes-issues/issues?q=is%3Aissue+is%3Aopen+label%3AUX) +- [Windows tools](https://github.com/QubesOS/qubes-issues/issues?q=is%3Aissue+is%3Aopen+label%3A%22C%3A+windows+tools%22) +- [Documentation](https://github.com/QubesOS/qubes-issues/issues?q=is%3Aissue+is%3Aopen+label%3A%22C%3A+doc%22) +- [privacy](https://github.com/QubesOS/qubes-issues/issues?utf8=%E2%9C%93&q=is%3Aissue%20is%3Aopen%20label%3A%22privacy%22%20) +- [Debian](https://github.com/QubesOS/qubes-issues/issues?q=is%3Aissue+is%3Aopen+label%3A%22C%3A+Debian%22) -You can also contribute in other areas than coding and testing, e.g. by providing mirrors for Qubes rpm repositories, providing feedback about what features you would like to have in Qubes, or perhaps even preparing some cool You Tube videos that would demonstrate some Qubes' features. You are always encouraged to discuss your ideas on qubes-devel. +Before you engage in an activity that will take you a significant amount of time, e.g. implementing a new feature, it's always good to contact us first, preferably via the [qubes-devel](/doc/mailing-lists/) list. When you contact us and devote to a particular task, we will create a ticket for this task with info who is working on this feature and what is the expected date of some early code to be posted. -You should be aware, however, that we will not blindly accept all the contributions! We will accept only the quality ones. Open source doesn't mean lack of quality control! If we reject your patch, please do not get discouraged, try fixing it so that it adheres to the required standards. We will only reject contributions in the good faith, to make Qubes a better OS. - -Thanks, [The Qubes Project team](/team). +If you are interested in contributing code, please read how to [access Qubes sources and send patches](/doc/source-code/). From 435599eed0f44c9cc73d9578e4fdc665c85790a9 Mon Sep 17 00:00:00 2001 From: Michael Carbone Date: Mon, 14 Nov 2016 12:47:11 -0500 Subject: [PATCH 269/708] fix typo --- 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 d84b8057..4356b2c2 100644 --- a/privacy/anonymizing-your-mac-address.md +++ b/privacy/anonymizing-your-mac-address.md @@ -21,7 +21,7 @@ NM 1.4.2 is currently available from the Debian 9 (testing) repository, and has In the Debian 9 template you intend to use as a NetVM, check that Network Manager version is now at least 1.4.2: ~~~ -$ sudo Network-Manager -V +$ sudo NetworkManager -V 1.4.2 ~~~ From 732ba9334c4876366a698f446e7e909f3cad8b5d Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Tue, 15 Nov 2016 00:31:43 -0800 Subject: [PATCH 270/708] Add FAQ entry on respecting distros' culture See discussion on QubesOS/qubes-issues#1014. --- basics_dev/devel-faq.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/basics_dev/devel-faq.md b/basics_dev/devel-faq.md index 0f9cb4f2..eef08f25 100644 --- a/basics_dev/devel-faq.md +++ b/basics_dev/devel-faq.md @@ -32,3 +32,10 @@ Q: How do I submit a patch? --------------------------- See [Qubes Source Code Repositories](/doc/source-code/). + +Q: What is Qubes' attitude toward changing guest distros? +--------------------------------------------------------- + +We try to respect each distro's culture, where possibe. See the discussion on +issue [#1014](https://github.com/QubesOS/qubes-issues/issues/1014) for an +example. From ccbb26f5ccd974c07c25ff9a075011a1513b6320 Mon Sep 17 00:00:00 2001 From: unman Date: Tue, 15 Nov 2016 20:55:29 +0000 Subject: [PATCH 271/708] Correct typo in vm-sudo.md --- security/vm-sudo.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/security/vm-sudo.md b/security/vm-sudo.md index 7449654f..45d048e3 100644 --- a/security/vm-sudo.md +++ b/security/vm-sudo.md @@ -105,7 +105,7 @@ this for extra security.** 1. Adding Dom0 "VMAuth" service: [root@dom0 /]# echo -n "/usr/bin/echo 1" >/etc/qubes-rpc/qubes.VMAuth - [root@dom0 /]# echo -n "$anyvm dom0 ask" >/etc/qubes-rpc/policy/qubes.VMAuth + [root@dom0 /]# echo -n "\$anyvm dom0 ask" >/etc/qubes-rpc/policy/qubes.VMAuth (Note: any VMs you would like still to have password-less root access (e.g. TemplateVMs) can be specified in the second file with "\ dom0 allow") From 82809af961ae36edba5388237bc8aaf73a3f2a1c Mon Sep 17 00:00:00 2001 From: Rusty Bird Date: Wed, 16 Nov 2016 17:30:25 +0000 Subject: [PATCH 272/708] [device-scan] -> [device] It only worked because 'wifi.scan-rand-mac-address=yes' is already the default anyway. --- 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 4356b2c2..8b7baea2 100644 --- a/privacy/anonymizing-your-mac-address.md +++ b/privacy/anonymizing-your-mac-address.md @@ -28,7 +28,7 @@ $ sudo NetworkManager -V Add the settings in `/etc/NetworkManager/NetworkManager.conf`. The following example enables Wifi MAC address randomization both while scanning (not connected) and while connected. ~~~ -[device-scan] +[device] wifi.scan-rand-mac-address=yes [connection] From 91d3abac156fa50e973c2896254ae4d8ef669587 Mon Sep 17 00:00:00 2001 From: Rusty Bird Date: Wed, 16 Nov 2016 18:23:30 +0000 Subject: [PATCH 273/708] Also randomize MAC address per Ethernet connection profile --- privacy/anonymizing-your-mac-address.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/privacy/anonymizing-your-mac-address.md b/privacy/anonymizing-your-mac-address.md index 8b7baea2..0b056cb3 100644 --- a/privacy/anonymizing-your-mac-address.md +++ b/privacy/anonymizing-your-mac-address.md @@ -25,7 +25,7 @@ $ sudo NetworkManager -V 1.4.2 ~~~ -Add the settings in `/etc/NetworkManager/NetworkManager.conf`. The following example enables Wifi MAC address randomization both while scanning (not connected) and while connected. +Add the settings in `/etc/NetworkManager/NetworkManager.conf`. The following example enables Wifi MAC address randomization while scanning (not connected), and uses a randomly generated but persistent MAC address for each individual Wifi and Ethernet connection profile. ~~~ [device] @@ -33,6 +33,7 @@ wifi.scan-rand-mac-address=yes [connection] wifi.cloned-mac-address=stable +ethernet.cloned-mac-address=stable ~~~ To see the available configuration options, refer to the man page: `man nm-settings` From 3466bbe86aedf0ff9d9eab51fe0f51b840b8cbec Mon Sep 17 00:00:00 2001 From: Rusty Bird Date: Wed, 16 Nov 2016 18:23:30 +0000 Subject: [PATCH 274/708] Save in conf.d/ instead of modifying NetworkManager.conf --- 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 0b056cb3..5385583b 100644 --- a/privacy/anonymizing-your-mac-address.md +++ b/privacy/anonymizing-your-mac-address.md @@ -25,7 +25,7 @@ $ sudo NetworkManager -V 1.4.2 ~~~ -Add the settings in `/etc/NetworkManager/NetworkManager.conf`. The following example enables Wifi MAC address randomization while scanning (not connected), and uses a randomly generated but persistent MAC address for each individual Wifi and Ethernet connection profile. +Write the settings to a new file in the `/etc/NetworkManager/conf.d/` directory, such as `mac.conf`. The following example enables Wifi MAC address randomization while scanning (not connected), and uses a randomly generated but persistent MAC address for each individual Wifi and Ethernet connection profile. ~~~ [device] From 699d546a99b586f8b69b851bfaece7f7e9556790 Mon Sep 17 00:00:00 2001 From: tezeb Date: Fri, 18 Nov 2016 11:45:18 +0100 Subject: [PATCH 275/708] Update archlinux template building instructions --- managing-os/templates/archlinux.md | 46 ++++++++++++++---------------- 1 file changed, 22 insertions(+), 24 deletions(-) diff --git a/managing-os/templates/archlinux.md b/managing-os/templates/archlinux.md index a0cde5fe..5afb2afb 100644 --- a/managing-os/templates/archlinux.md +++ b/managing-os/templates/archlinux.md @@ -23,7 +23,7 @@ Main maintainer of this template is [Olivier Médoc](mailto:o_medoc@yahoo.fr). ## Instructions ##
-**These are the instructions for Qubes 3.1. They will take you step by step through the entire process start to finish** +**These are the instructions for Qubes 3.2. They will take you step by step through the entire process start to finish** *Note: Currently there are no binary packages and it must be compiled from source using the instructions below.* @@ -107,10 +107,10 @@ Main maintainer of this template is [Olivier Médoc](mailto:o_medoc@yahoo.fr).

-* You will now have the Qubes Builder System environment installed in the directory below: - * **/home/user/qubes-builder** -
+* You will now have the Qubes Builder System environment installed in the directory below: + + * **/home/user/qubes-builder/**

@@ -120,11 +120,11 @@ Main maintainer of this template is [Olivier Médoc](mailto:o_medoc@yahoo.fr). *In the future this should not be needed once a change is made to the 'setup' script.* - * Edit the '**qubes-os-r3.1.conf**' which is found in **/home/user/qubes-builder/example-configs** Use the text editor of your choice. + * Edit the '**qubes-os-r3.2.conf**' which is found in **/home/user/qubes-builder/example-configs** Use the text editor of your choice. * **$ cd /home/user/qubes-builder/example-config/** - * **$ nano -W qubes-os-r3.1.conf** or **$ gedit qubes-os-r3.1.conf** or etc…. + * **$ nano -W qubes-os-r3.2.conf** or **$ gedit qubes-os-r3.2.conf** or etc….

![arch-template-06](/attachment/wiki/ArchlinuxTemplate/arch-template-06.png) @@ -172,7 +172,7 @@ Main maintainer of this template is [Olivier Médoc](mailto:o_medoc@yahoo.fr). * This screen will give you the choice of which Qubes Release to build the template for. - * Select '**Qubes Release 3.1**' + * Select '**Qubes Release 3.2**' * Select '**OK**' Press '**Enter**'

@@ -185,6 +185,9 @@ Main maintainer of this template is [Olivier Médoc](mailto:o_medoc@yahoo.fr). * Select 'QubesOS/qubes- Stable - Default Repo' * Select '**OK**' Press '**Enter**'
+
+![arch-template-12](/attachment/wiki/ArchlinuxTemplate/arch-template-12.png) +

* Screen "**Build Template Only?**" @@ -192,7 +195,7 @@ Main maintainer of this template is [Olivier Médoc](mailto:o_medoc@yahoo.fr). * Select '**Yes**' Press '**Enter**'

-![arch-template-12](/attachment/wiki/ArchlinuxTemplate/arch-template-12.png) +![arch-template-12](/attachment/wiki/ArchlinuxTemplate/arch-template-12a.png)

@@ -200,9 +203,9 @@ Main maintainer of this template is [Olivier Médoc](mailto:o_medoc@yahoo.fr). * Deselect '**Fedora**' - * Deselect '**mgnt_salt**' + * Deselect '**mgmt_salt**' - * Select '**archlinux**' + * Select '**builder-archlinux**' * Select '**OK**' Press **Enter**
@@ -213,10 +216,18 @@ Main maintainer of this template is [Olivier Médoc](mailto:o_medoc@yahoo.fr). * Screen '**Get sources**' wants to download additional packages needed for the choosen plugin/s. - * Select '**No**' Press '**Enter**' + * Select '**Yes**' Press '**Enter**'

![arch-template-14](/attachment/wiki/ArchlinuxTemplate/arch-template-14.png) +
+
+ + * Then wait for download to finish and press '**OK**' +
+
+![arch-template-14](/attachment/wiki/ArchlinuxTemplate/arch-template-15.png) +

* Screen '**Template Distribution Selection**' allows you to choose the actual template/s you wish to build. @@ -237,19 +248,6 @@ Main maintainer of this template is [Olivier Médoc](mailto:o_medoc@yahoo.fr).
![arch-template-17](/attachment/wiki/ArchlinuxTemplate/arch-template-17.png)
-
- * Archlinux builder is not(yet?) in official Qubes release branch, so it has to be downloaded from different repository. - - * Open file builder.conf with your favourite text editor and find section **"O V E R R I D E B R A N C H"** (single space -between letters) and add: - - * **GIT_URL_builder_archlinux = $(GIT_BASEURL)/marmarek/qubes-builder-archlinux.git** - -
-
-![arch-template-17](/attachment/wiki/ArchlinuxTemplate/arch-template-17a.png) -
-

##### **7: Install all the dependencies:** ##### From 46d5778b1902e9037b8ddcbded0c715f9af21367 Mon Sep 17 00:00:00 2001 From: Wojtek Porczyk Date: Fri, 18 Nov 2016 22:40:16 +0100 Subject: [PATCH 276/708] Preliminary management API Currently not linked anywhere, on purpose --- services/mgmt1.md | 90 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 90 insertions(+) create mode 100644 services/mgmt1.md diff --git a/services/mgmt1.md b/services/mgmt1.md new file mode 100644 index 00000000..1a1e5eb5 --- /dev/null +++ b/services/mgmt1.md @@ -0,0 +1,90 @@ +--- +layout: doc +title: Management API +permalink: /doc/mgmt1/ +--- + +# Management API + +*(This page is the current draft of the proposal. It is not implemented yet.)* + +The API should be implemented as a set of qrexec calls. This is to make it easy +to set the policy using current mechanism. + +## The calls + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
calldestargumentinsidereturnnote
mgmt1.vm.List "dom0" - - "<name> class=<class> state=<state>\n"
mgmt1.vm.Create template or "dom0" class "name=<name> label=<label>" -
mgmt1.vm.CreateInPool template or "dom0" class "name=<name> label=<label> pool=<pool>" -
mgmt1.vm.CreateTemplate "dom0" name root.img -
mgmt1.vm.property.List vm - - "<property>\n"
mgmt1.vm.property.Get vm property - "default={yes|no} <value>"
mgmt1.vm.property.Help vm property - help.rst
mgmt1.vm.property.Reset vm property - -
mgmt1.vm.property.Set vm property value -
mgmt1.vm.feature.List vm - - "<feature>\n"
mgmt1.vm.feature.Get vm feature - value
mgmt1.vm.feature.CheckWithTemplate vm feature - value
mgmt1.vm.feature.Remove vm feature - -
mgmt1.vm.feature.Set vm feature value -
mgmt1.vm.tag.List vm tag - "<tag>\n"
mgmt1.vm.tag.Get vm tag - "0" or "1" retcode?
mgmt1.vm.tag.Remove vm tag - -
mgmt1.vm.tag.Set vm tag - -
mgmt1.vm.firewall.Get vm position - "<rule id> <rule>\n"
mgmt1.vm.firewall.InsertRule vm position rule rule id
mgmt1.vm.firewall.RemoveRule vm rule id - -
mgmt1.vm.firewall.Flush vm - - -
mgmt1.vm.device.<class>.Attach vm device - -
mgmt1.vm.device.<class>.Detach vm device - -
mgmt1.vm.device.<class>.List vm - - "<device>\n"
mgmt1.vm.device.<class>.Available vm - - "<device>\n"
mgmt1.vm.microphone.Attach vm - - -
mgmt1.vm.microphone.Detach vm - - -
mgmt1.pool.List "dom0" - - "<pool>\n"
mgmt1.pool.Info "dom0" pool - "<property>=<value>\n"
mgmt1.pool.Add "dom0" pool "<property>=<value>\n" -
mgmt1.pool.Remove "dom0" pool - -
mgmt1.pool.volume.List "dom0" pool - volume id
mgmt1.pool.volume.Info "dom0" pool:vid - "<property>=<value>\n"
mgmt1.pool.volume.ListSnapshots "dom0" pool:vid - "<snapshot>\n"
mgmt1.pool.volume.Snapshot "dom0" pool:vid - snapshot
mgmt1.pool.volume.Revert "dom0" pool:vid snapshot -
mgmt1.pool.volume.Extend "dom0" pool:vid - "<size_in_bytes>"
mgmt1.vm.volume.List vm -/pool? - ?
mgmt1.vm.volume.Info vm volume - ?
mgmt1.vm.volume.ListSnapshots vm volume - snapshot duplicate of mgmt1.pool.volume., but with other call params
mgmt1.vm.volume.Snapshot vm volume - snapshot id.
mgmt1.vm.volume.Revert vm volume snapshot - id.
mgmt1.vm.volume.Extend vm volume - "<size_in_bytes>" id.
mgmt1.vm.volume.Attach vm volume - -
mgmt1.vm.volume.Detach vm volume - -
mgmt1.vm.Start vm - - -
mgmt1.vm.Shutdown vm - - -
mgmt1.vm.Pause vm - - -
mgmt1.vm.Unpause vm - - -
mgmt1.vm.Kill vm - - -
mgmt1.backup.Execute "dom0" config id - - config in /etc/qubes/backup/<id>.conf
mgmt1.backup.Info "dom0" ? content? ?
mgmt1.backup.Restore "dom0" ? content ?
+ + +## Tags + +- created-by-<vm> +- managed-by-<vm> +- backup-<id> + +## TODO + +- something to configure/update policy From bb99c1a6f1190fb304e85c94785d10d76072b2f3 Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Sat, 19 Nov 2016 00:55:05 -0800 Subject: [PATCH 277/708] Convert table to Markdow and remove custom styling QubesOS/qubes-issues#853 --- services/mgmt1.md | 120 ++++++++++++++++++++++------------------------ 1 file changed, 56 insertions(+), 64 deletions(-) diff --git a/services/mgmt1.md b/services/mgmt1.md index 1a1e5eb5..a2bb6f28 100644 --- a/services/mgmt1.md +++ b/services/mgmt1.md @@ -13,70 +13,62 @@ to set the policy using current mechanism. ## The calls - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
calldestargumentinsidereturnnote
mgmt1.vm.List "dom0" - - "<name> class=<class> state=<state>\n"
mgmt1.vm.Create template or "dom0" class "name=<name> label=<label>" -
mgmt1.vm.CreateInPool template or "dom0" class "name=<name> label=<label> pool=<pool>" -
mgmt1.vm.CreateTemplate "dom0" name root.img -
mgmt1.vm.property.List vm - - "<property>\n"
mgmt1.vm.property.Get vm property - "default={yes|no} <value>"
mgmt1.vm.property.Help vm property - help.rst
mgmt1.vm.property.Reset vm property - -
mgmt1.vm.property.Set vm property value -
mgmt1.vm.feature.List vm - - "<feature>\n"
mgmt1.vm.feature.Get vm feature - value
mgmt1.vm.feature.CheckWithTemplate vm feature - value
mgmt1.vm.feature.Remove vm feature - -
mgmt1.vm.feature.Set vm feature value -
mgmt1.vm.tag.List vm tag - "<tag>\n"
mgmt1.vm.tag.Get vm tag - "0" or "1" retcode?
mgmt1.vm.tag.Remove vm tag - -
mgmt1.vm.tag.Set vm tag - -
mgmt1.vm.firewall.Get vm position - "<rule id> <rule>\n"
mgmt1.vm.firewall.InsertRule vm position rule rule id
mgmt1.vm.firewall.RemoveRule vm rule id - -
mgmt1.vm.firewall.Flush vm - - -
mgmt1.vm.device.<class>.Attach vm device - -
mgmt1.vm.device.<class>.Detach vm device - -
mgmt1.vm.device.<class>.List vm - - "<device>\n"
mgmt1.vm.device.<class>.Available vm - - "<device>\n"
mgmt1.vm.microphone.Attach vm - - -
mgmt1.vm.microphone.Detach vm - - -
mgmt1.pool.List "dom0" - - "<pool>\n"
mgmt1.pool.Info "dom0" pool - "<property>=<value>\n"
mgmt1.pool.Add "dom0" pool "<property>=<value>\n" -
mgmt1.pool.Remove "dom0" pool - -
mgmt1.pool.volume.List "dom0" pool - volume id
mgmt1.pool.volume.Info "dom0" pool:vid - "<property>=<value>\n"
mgmt1.pool.volume.ListSnapshots "dom0" pool:vid - "<snapshot>\n"
mgmt1.pool.volume.Snapshot "dom0" pool:vid - snapshot
mgmt1.pool.volume.Revert "dom0" pool:vid snapshot -
mgmt1.pool.volume.Extend "dom0" pool:vid - "<size_in_bytes>"
mgmt1.vm.volume.List vm -/pool? - ?
mgmt1.vm.volume.Info vm volume - ?
mgmt1.vm.volume.ListSnapshots vm volume - snapshot duplicate of mgmt1.pool.volume., but with other call params
mgmt1.vm.volume.Snapshot vm volume - snapshot id.
mgmt1.vm.volume.Revert vm volume snapshot - id.
mgmt1.vm.volume.Extend vm volume - "<size_in_bytes>" id.
mgmt1.vm.volume.Attach vm volume - -
mgmt1.vm.volume.Detach vm volume - -
mgmt1.vm.Start vm - - -
mgmt1.vm.Shutdown vm - - -
mgmt1.vm.Pause vm - - -
mgmt1.vm.Unpause vm - - -
mgmt1.vm.Kill vm - - -
mgmt1.backup.Execute "dom0" config id - - config in /etc/qubes/backup/<id>.conf
mgmt1.backup.Info "dom0" ? content? ?
mgmt1.backup.Restore "dom0" ? content ?
+| call | dest | argument | inside | return | note | +| --------------------------------------- | ---------------------- | ------------- | ----------------------------------------- | -------------------------------------------------------- | ---- | +| mgmt1.vm.List | "dom0" | - | - | "<name> class=<class> state=<state>\n" | | +| mgmt1.vm.Create | template or "dom0" | class | "name=<name> label=<label>" | - | | +| mgmt1.vm.CreateInPool | template or "dom0" | class | "name=<name> label=<label> pool=<pool>" | - | | +| mgmt1.vm.CreateTemplate | "dom0" | name | root.img | - | | +| mgmt1.vm.property.List | vm | - | - | "<property>\n" | | +| mgmt1.vm.property.Get | vm | property | - | "default={yes|no} <value>" | | +| mgmt1.vm.property.Help | vm | property | - | help.rst | | +| mgmt1.vm.property.Reset | vm | property | - | - | | +| mgmt1.vm.property.Set | vm | property | value | - | | +| mgmt1.vm.feature.List | vm | - | - | "<feature>\n" | | +| mgmt1.vm.feature.Get | vm | feature | - | value | | +| mgmt1.vm.feature.CheckWithTemplate | vm | feature | - | value | | +| mgmt1.vm.feature.Remove | vm | feature | - | - | | +| mgmt1.vm.feature.Set | vm | feature | value | - | | +| mgmt1.vm.tag.List | vm | tag | - | "<tag>\n" | | +| mgmt1.vm.tag.Get | vm | tag | - | "0" or "1" |retcode? | +| mgmt1.vm.tag.Remove | vm | tag | - | - | | +| mgmt1.vm.tag.Set | vm | tag | - | - | | +| mgmt1.vm.firewall.Get | vm | position | - | "<rule id> <rule>\n" | | +| mgmt1.vm.firewall.InsertRule | vm | position | rule | rule id | | +| mgmt1.vm.firewall.RemoveRule | vm | rule id | - | - | | +| mgmt1.vm.firewall.Flush | vm | - | - | - | | +| mgmt1.vm.device.<class>.Attach | vm | device | - | - | | +| mgmt1.vm.device.<class>.Detach | vm | device | - | - | | +| mgmt1.vm.device.<class>.List | vm | - | - | "<device>\n" | | +| mgmt1.vm.device.<class>.Available | vm | - | - | "<device>\n" | | +| mgmt1.vm.microphone.Attach | vm | - | - | - | | +| mgmt1.vm.microphone.Detach | vm | - | - | - | | +| mgmt1.pool.List | "dom0" | - | - | "<pool>\n" | | +| mgmt1.pool.Info | "dom0" | pool | - | "<property>=<value>\n" | | +| mgmt1.pool.Add | "dom0" | pool | "<property>=<value>\n" | - | | +| mgmt1.pool.Remove | "dom0" | pool | - | - | | +| mgmt1.pool.volume.List | "dom0" | pool | - | volume id | | +| mgmt1.pool.volume.Info | "dom0" | pool:vid | - | "<property>=<value>\n" | | +| mgmt1.pool.volume.ListSnapshots | "dom0" | pool:vid | - | "<snapshot>\n" | | +| mgmt1.pool.volume.Snapshot | "dom0" | pool:vid | - | snapshot | | +| mgmt1.pool.volume.Revert | "dom0" | pool:vid | snapshot | - | | +| mgmt1.pool.volume.Extend | "dom0" | pool:vid | - | "<size_in_bytes>" | | +| mgmt1.vm.volume.List | vm | -/pool? | - | ? | | +| mgmt1.vm.volume.Info | vm | volume | - | ? | | +| mgmt1.vm.volume.ListSnapshots | vm | volume | - | snapshot |duplicate of mgmt1.pool.volume., but with other call params | +| mgmt1.vm.volume.Snapshot | vm | volume | - | snapshot |id. | +| mgmt1.vm.volume.Revert | vm | volume | snapshot | - |id. | +| mgmt1.vm.volume.Extend | vm | volume | - | "<size_in_bytes>" |id. | +| mgmt1.vm.volume.Attach | vm | volume | - | - | | +| mgmt1.vm.volume.Detach | vm | volume | - | - | | +| mgmt1.vm.Start | vm | - | - | - | | +| mgmt1.vm.Shutdown | vm | - | - | - | | +| mgmt1.vm.Pause | vm | - | - | - | | +| mgmt1.vm.Unpause | vm | - | - | - | | +| mgmt1.vm.Kill | vm | - | - | - | | +| mgmt1.backup.Execute | "dom0" | config id | - | - |config in /etc/qubes/backup/<id>.conf | +| mgmt1.backup.Info | "dom0" | ? | content? | ? | | +| mgmt1.backup.Restore | "dom0" | ? | content | ? | | ## Tags From 06b2edcbbff200e1567466d260b3ef2855bc1a92 Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Sat, 19 Nov 2016 01:13:12 -0800 Subject: [PATCH 278/708] Remove extra table cells; substitute HTML entity for vbar QubesOS/qubes-issues#853 --- services/mgmt1.md | 96 +++++++++++++++++++++++------------------------ 1 file changed, 48 insertions(+), 48 deletions(-) diff --git a/services/mgmt1.md b/services/mgmt1.md index a2bb6f28..0a640c9d 100644 --- a/services/mgmt1.md +++ b/services/mgmt1.md @@ -15,60 +15,60 @@ to set the policy using current mechanism. | call | dest | argument | inside | return | note | | --------------------------------------- | ---------------------- | ------------- | ----------------------------------------- | -------------------------------------------------------- | ---- | -| mgmt1.vm.List | "dom0" | - | - | "<name> class=<class> state=<state>\n" | | -| mgmt1.vm.Create | template or "dom0" | class | "name=<name> label=<label>" | - | | -| mgmt1.vm.CreateInPool | template or "dom0" | class | "name=<name> label=<label> pool=<pool>" | - | | -| mgmt1.vm.CreateTemplate | "dom0" | name | root.img | - | | -| mgmt1.vm.property.List | vm | - | - | "<property>\n" | | -| mgmt1.vm.property.Get | vm | property | - | "default={yes|no} <value>" | | -| mgmt1.vm.property.Help | vm | property | - | help.rst | | -| mgmt1.vm.property.Reset | vm | property | - | - | | -| mgmt1.vm.property.Set | vm | property | value | - | | -| mgmt1.vm.feature.List | vm | - | - | "<feature>\n" | | -| mgmt1.vm.feature.Get | vm | feature | - | value | | -| mgmt1.vm.feature.CheckWithTemplate | vm | feature | - | value | | -| mgmt1.vm.feature.Remove | vm | feature | - | - | | -| mgmt1.vm.feature.Set | vm | feature | value | - | | -| mgmt1.vm.tag.List | vm | tag | - | "<tag>\n" | | +| mgmt1.vm.List | "dom0" | - | - | "<name> class=<class> state=<state>\n" | +| mgmt1.vm.Create | template or "dom0" | class | "name=<name> label=<label>" | - | +| mgmt1.vm.CreateInPool | template or "dom0" | class | "name=<name> label=<label> pool=<pool>" | - | +| mgmt1.vm.CreateTemplate | "dom0" | name | root.img | - | +| mgmt1.vm.property.List | vm | - | - | "<property>\n" | +| mgmt1.vm.property.Get | vm | property | - | "default={yes|no} <value>" | +| mgmt1.vm.property.Help | vm | property | - | help.rst | +| mgmt1.vm.property.Reset | vm | property | - | - | +| mgmt1.vm.property.Set | vm | property | value | - | +| mgmt1.vm.feature.List | vm | - | - | "<feature>\n" | +| mgmt1.vm.feature.Get | vm | feature | - | value | +| mgmt1.vm.feature.CheckWithTemplate | vm | feature | - | value | +| mgmt1.vm.feature.Remove | vm | feature | - | - | +| mgmt1.vm.feature.Set | vm | feature | value | - | +| mgmt1.vm.tag.List | vm | tag | - | "<tag>\n" | | mgmt1.vm.tag.Get | vm | tag | - | "0" or "1" |retcode? | -| mgmt1.vm.tag.Remove | vm | tag | - | - | | -| mgmt1.vm.tag.Set | vm | tag | - | - | | -| mgmt1.vm.firewall.Get | vm | position | - | "<rule id> <rule>\n" | | -| mgmt1.vm.firewall.InsertRule | vm | position | rule | rule id | | -| mgmt1.vm.firewall.RemoveRule | vm | rule id | - | - | | -| mgmt1.vm.firewall.Flush | vm | - | - | - | | -| mgmt1.vm.device.<class>.Attach | vm | device | - | - | | -| mgmt1.vm.device.<class>.Detach | vm | device | - | - | | -| mgmt1.vm.device.<class>.List | vm | - | - | "<device>\n" | | -| mgmt1.vm.device.<class>.Available | vm | - | - | "<device>\n" | | -| mgmt1.vm.microphone.Attach | vm | - | - | - | | -| mgmt1.vm.microphone.Detach | vm | - | - | - | | -| mgmt1.pool.List | "dom0" | - | - | "<pool>\n" | | -| mgmt1.pool.Info | "dom0" | pool | - | "<property>=<value>\n" | | -| mgmt1.pool.Add | "dom0" | pool | "<property>=<value>\n" | - | | -| mgmt1.pool.Remove | "dom0" | pool | - | - | | -| mgmt1.pool.volume.List | "dom0" | pool | - | volume id | | -| mgmt1.pool.volume.Info | "dom0" | pool:vid | - | "<property>=<value>\n" | | -| mgmt1.pool.volume.ListSnapshots | "dom0" | pool:vid | - | "<snapshot>\n" | | -| mgmt1.pool.volume.Snapshot | "dom0" | pool:vid | - | snapshot | | -| mgmt1.pool.volume.Revert | "dom0" | pool:vid | snapshot | - | | -| mgmt1.pool.volume.Extend | "dom0" | pool:vid | - | "<size_in_bytes>" | | -| mgmt1.vm.volume.List | vm | -/pool? | - | ? | | -| mgmt1.vm.volume.Info | vm | volume | - | ? | | +| mgmt1.vm.tag.Remove | vm | tag | - | - | +| mgmt1.vm.tag.Set | vm | tag | - | - | +| mgmt1.vm.firewall.Get | vm | position | - | "<rule id> <rule>\n" | +| mgmt1.vm.firewall.InsertRule | vm | position | rule | rule id | +| mgmt1.vm.firewall.RemoveRule | vm | rule id | - | - | +| mgmt1.vm.firewall.Flush | vm | - | - | - | +| mgmt1.vm.device.<class>.Attach | vm | device | - | - | +| mgmt1.vm.device.<class>.Detach | vm | device | - | - | +| mgmt1.vm.device.<class>.List | vm | - | - | "<device>\n" | +| mgmt1.vm.device.<class>.Available | vm | - | - | "<device>\n" | +| mgmt1.vm.microphone.Attach | vm | - | - | - | +| mgmt1.vm.microphone.Detach | vm | - | - | - | +| mgmt1.pool.List | "dom0" | - | - | "<pool>\n" | +| mgmt1.pool.Info | "dom0" | pool | - | "<property>=<value>\n" | +| mgmt1.pool.Add | "dom0" | pool | "<property>=<value>\n" | - | +| mgmt1.pool.Remove | "dom0" | pool | - | - | +| mgmt1.pool.volume.List | "dom0" | pool | - | volume id | +| mgmt1.pool.volume.Info | "dom0" | pool:vid | - | "<property>=<value>\n" | +| mgmt1.pool.volume.ListSnapshots | "dom0" | pool:vid | - | "<snapshot>\n" | +| mgmt1.pool.volume.Snapshot | "dom0" | pool:vid | - | snapshot | +| mgmt1.pool.volume.Revert | "dom0" | pool:vid | snapshot | - | +| mgmt1.pool.volume.Extend | "dom0" | pool:vid | - | "<size_in_bytes>" | +| mgmt1.vm.volume.List | vm | -/pool? | - | ? | +| mgmt1.vm.volume.Info | vm | volume | - | ? | | mgmt1.vm.volume.ListSnapshots | vm | volume | - | snapshot |duplicate of mgmt1.pool.volume., but with other call params | | mgmt1.vm.volume.Snapshot | vm | volume | - | snapshot |id. | | mgmt1.vm.volume.Revert | vm | volume | snapshot | - |id. | | mgmt1.vm.volume.Extend | vm | volume | - | "<size_in_bytes>" |id. | -| mgmt1.vm.volume.Attach | vm | volume | - | - | | -| mgmt1.vm.volume.Detach | vm | volume | - | - | | -| mgmt1.vm.Start | vm | - | - | - | | -| mgmt1.vm.Shutdown | vm | - | - | - | | -| mgmt1.vm.Pause | vm | - | - | - | | -| mgmt1.vm.Unpause | vm | - | - | - | | -| mgmt1.vm.Kill | vm | - | - | - | | +| mgmt1.vm.volume.Attach | vm | volume | - | - | +| mgmt1.vm.volume.Detach | vm | volume | - | - | +| mgmt1.vm.Start | vm | - | - | - | +| mgmt1.vm.Shutdown | vm | - | - | - | +| mgmt1.vm.Pause | vm | - | - | - | +| mgmt1.vm.Unpause | vm | - | - | - | +| mgmt1.vm.Kill | vm | - | - | - | | mgmt1.backup.Execute | "dom0" | config id | - | - |config in /etc/qubes/backup/<id>.conf | -| mgmt1.backup.Info | "dom0" | ? | content? | ? | | -| mgmt1.backup.Restore | "dom0" | ? | content | ? | | +| mgmt1.backup.Info | "dom0" | ? | content? | ? | +| mgmt1.backup.Restore | "dom0" | ? | content | ? | ## Tags From 889a830d05de10d9e0c89b7182f4a44e32456b5c Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Sat, 19 Nov 2016 01:34:24 -0800 Subject: [PATCH 279/708] Clean up table source * Use backticks to wrap literal text * Replace HTML entities with ASCII characters * Make column spacing uniform QubesOS/qubes-issues#853 --- services/mgmt1.md | 118 +++++++++++++++++++++++----------------------- 1 file changed, 59 insertions(+), 59 deletions(-) diff --git a/services/mgmt1.md b/services/mgmt1.md index 0a640c9d..efba6b05 100644 --- a/services/mgmt1.md +++ b/services/mgmt1.md @@ -13,69 +13,69 @@ to set the policy using current mechanism. ## The calls -| call | dest | argument | inside | return | note | -| --------------------------------------- | ---------------------- | ------------- | ----------------------------------------- | -------------------------------------------------------- | ---- | -| mgmt1.vm.List | "dom0" | - | - | "<name> class=<class> state=<state>\n" | -| mgmt1.vm.Create | template or "dom0" | class | "name=<name> label=<label>" | - | -| mgmt1.vm.CreateInPool | template or "dom0" | class | "name=<name> label=<label> pool=<pool>" | - | -| mgmt1.vm.CreateTemplate | "dom0" | name | root.img | - | -| mgmt1.vm.property.List | vm | - | - | "<property>\n" | -| mgmt1.vm.property.Get | vm | property | - | "default={yes|no} <value>" | -| mgmt1.vm.property.Help | vm | property | - | help.rst | -| mgmt1.vm.property.Reset | vm | property | - | - | -| mgmt1.vm.property.Set | vm | property | value | - | -| mgmt1.vm.feature.List | vm | - | - | "<feature>\n" | -| mgmt1.vm.feature.Get | vm | feature | - | value | -| mgmt1.vm.feature.CheckWithTemplate | vm | feature | - | value | -| mgmt1.vm.feature.Remove | vm | feature | - | - | -| mgmt1.vm.feature.Set | vm | feature | value | - | -| mgmt1.vm.tag.List | vm | tag | - | "<tag>\n" | -| mgmt1.vm.tag.Get | vm | tag | - | "0" or "1" |retcode? | -| mgmt1.vm.tag.Remove | vm | tag | - | - | -| mgmt1.vm.tag.Set | vm | tag | - | - | -| mgmt1.vm.firewall.Get | vm | position | - | "<rule id> <rule>\n" | -| mgmt1.vm.firewall.InsertRule | vm | position | rule | rule id | -| mgmt1.vm.firewall.RemoveRule | vm | rule id | - | - | -| mgmt1.vm.firewall.Flush | vm | - | - | - | -| mgmt1.vm.device.<class>.Attach | vm | device | - | - | -| mgmt1.vm.device.<class>.Detach | vm | device | - | - | -| mgmt1.vm.device.<class>.List | vm | - | - | "<device>\n" | -| mgmt1.vm.device.<class>.Available | vm | - | - | "<device>\n" | -| mgmt1.vm.microphone.Attach | vm | - | - | - | -| mgmt1.vm.microphone.Detach | vm | - | - | - | -| mgmt1.pool.List | "dom0" | - | - | "<pool>\n" | -| mgmt1.pool.Info | "dom0" | pool | - | "<property>=<value>\n" | -| mgmt1.pool.Add | "dom0" | pool | "<property>=<value>\n" | - | -| mgmt1.pool.Remove | "dom0" | pool | - | - | -| mgmt1.pool.volume.List | "dom0" | pool | - | volume id | -| mgmt1.pool.volume.Info | "dom0" | pool:vid | - | "<property>=<value>\n" | -| mgmt1.pool.volume.ListSnapshots | "dom0" | pool:vid | - | "<snapshot>\n" | -| mgmt1.pool.volume.Snapshot | "dom0" | pool:vid | - | snapshot | -| mgmt1.pool.volume.Revert | "dom0" | pool:vid | snapshot | - | -| mgmt1.pool.volume.Extend | "dom0" | pool:vid | - | "<size_in_bytes>" | -| mgmt1.vm.volume.List | vm | -/pool? | - | ? | -| mgmt1.vm.volume.Info | vm | volume | - | ? | -| mgmt1.vm.volume.ListSnapshots | vm | volume | - | snapshot |duplicate of mgmt1.pool.volume., but with other call params | -| mgmt1.vm.volume.Snapshot | vm | volume | - | snapshot |id. | -| mgmt1.vm.volume.Revert | vm | volume | snapshot | - |id. | -| mgmt1.vm.volume.Extend | vm | volume | - | "<size_in_bytes>" |id. | -| mgmt1.vm.volume.Attach | vm | volume | - | - | -| mgmt1.vm.volume.Detach | vm | volume | - | - | -| mgmt1.vm.Start | vm | - | - | - | -| mgmt1.vm.Shutdown | vm | - | - | - | -| mgmt1.vm.Pause | vm | - | - | - | -| mgmt1.vm.Unpause | vm | - | - | - | -| mgmt1.vm.Kill | vm | - | - | - | -| mgmt1.backup.Execute | "dom0" | config id | - | - |config in /etc/qubes/backup/<id>.conf | -| mgmt1.backup.Info | "dom0" | ? | content? | ? | -| mgmt1.backup.Restore | "dom0" | ? | content | ? | +| call | dest | argument | inside | return | note | +| --------------------------------------- | ---------------------- | ------------- | ----------------------------------------- | ---------------------------------------- | ---- | +| `mgmt1.vm.List` | `dom0` | - | - | ` class= state=\n` | +| `mgmt1.vm.Create` | template or `dom0` | class | `name= label=