diff --git a/docs/building/building-archlinux-template.md b/docs/building/building-archlinux-template.md index f5c89c7..deee4c7 100644 --- a/docs/building/building-archlinux-template.md +++ b/docs/building/building-archlinux-template.md @@ -1,654 +1 @@ -# Building the 'archlinux-minimal' Qubes template - -## Read first -This is a community guide, not an official guide. So please, first read the below official guides: -- [Qubes-builder](https://www.qubes-os.org/doc/qubes-builder/) -- [Qubes-builder-details](https://www.qubes-os.org/doc/qubes-builder-details/) -- [Qubes-builder doc directory](https://github.com/marmarek/qubes-builder/tree/master/doc) -- [Qubes templates config](https://github.com/QubesOS/qubes-template-configs/blob/master/README.md) - -Only if the above guides don't work for you, then try this one. - -Arch Linux is a [rolling](https://en.wikipedia.org/wiki/Rolling_release) -distribution, making it fragile. In fact, with always the latest versions, the -ArchLinux packages meet first the new problems. So it's better to first try to -build templates or packages for Fedora or Debian. - -Also read: -- the *Debugging the build process* below section -- the [ArchLinux known issues](https://github.com/QubesOS/qubes-issues/labels/C%3A%20Arch%20Linux) with Qubes-OS - -These instructions are known to work for QubesOS 4.1. - -## Steps - -### 1. Create a qubes-builder AppVM - -Create an AppVM, based on the last Fedora TemplateVM, named for example -*qubes-builder* or *build-archlinux* (see below). - -![arch-template-01](/attachment/wiki/ArchlinuxTemplate/arch-template-01.png) - -> **The StandaloneVM type cannot build the Arch Linux (minimal or not) template -> currently, as its Makefiles and Scripts only fully accomodate for the AppVM -> type's set of filesystem permissions!** - -In the qubes settings set at least 15GB of space in the Qube's private storage -and create the AppVM by clicking OK. - -![arch-template-02](/attachment/wiki/ArchlinuxTemplate/arch-template-02.png) - -Then run the following commands in dom0 to set the VCPUs and memory for the -AppVM: - -```console -qvm-prefs build-archlinux2 vcpus $(nproc) -qvm-prefs build-archlinux2 memory 4000 -qvm-prefs build-archlinux2 maxmem 4000 -``` - -> **`nproc` specified the number of CPU logical cores it detected, meaning -> memory usage will increase for compilations that utilize the additional -> logical cores. For building the 'archlinux-minimal' template, 4000MB should be -> plenty.** - -### 2. Downloading and verifying the integrity of the "Qubes Automated Build System" - -> **Open a terminal in the qubes-builder AppVM that you just created. All -following commands are supposed to typed there, unless stated otherwise.** - -Set terminal size to 30 lines and 100 columns; ensures text from **qubes-builder**'s setup script isn't cut-off. - -```console -resize -s 30 100 -``` - -Install initial dependencies without user confirmation. - -```console -sudo dnf install -y git make -``` - -Import and verify the Qubes master key (have a look -[here](https://www.qubes-os.org/security/verifying-signatures/) to understand -the purpose of the verification). - -```console -gpg2 --import /usr/share/qubes/qubes-master-key.asc -gpg2 --edit-key 0x427F11FD0FAA4B080123F01CDDFA1A3E36879494 -``` - -In the interactive gnupg shell that opens following the last command, you type -in `fpr` and hit enter to show the fingerprint. Afterwards you type `trust` and -`5` to set the trust level to 'ultimately'. Afterwards you need to confirm your -selection with 'y' and save and exit via `quit`. It should look something like -this: - -```console -gpg> fpr -pub rsa4096/DDFA1A3E36879494 2010-04-01 Qubes Master Signing Key - Primary key fingerprint: 427F 11FD 0FAA 4B08 0123 F01C DDFA 1A3E 3687 9494 - -gpg> trust -pub rsa4096/DDFA1A3E36879494 - created: 2010-04-01 expires: never usage: SC - trust: unknown validity: unknown -[ unknown] (1). Qubes Master Signing Key - -Please decide how far you trust this user to correctly verify other users' keys -(by looking at passports, checking fingerprints from different sources, etc.) - - 1 = I don't know or won't say - 2 = I do NOT trust - 3 = I trust marginally - 4 = I trust fully - 5 = I trust ultimately - m = back to the main menu - -Your decision? 5 -Do you really want to set this key to ultimate trust? (y/N) y - -pub rsa4096/DDFA1A3E36879494 - created: 2010-04-01 expires: never usage: SC - trust: ultimate validity: unknown -[ unknown] (1). Qubes Master Signing Key -Please note that the shown key validity is not necessarily correct -unless you restart the program. - -gpg> quit -``` - -Download then import the Qubes developers' keys: - -```console -curl -O https://keys.qubes-os.org/keys/qubes-developers-keys.asc -gpg2 --import qubes-developers-keys.asc -``` - -Download the latest stable `qubes-builder` repository: - -```console -git clone https://github.com/QubesOS/qubes-builder.git $HOME/qubes-builder/ -``` - -Verify the integrity of the `qubes-builder` repository: - -```console -cd $HOME/qubes-builder/ -git tag -v $(git describe) -``` - -The output should contain something like this - -```console -gpg: Good signature from "Marek Marczykowski-Górecki (Qubes OS signing key) " [full] -``` - -The verifcation succeeded if you see a good signature as seen above. - -Now install the remaining dependencies: - -```console -make install-deps -``` - -### 3. Configure the `builder.conf` file - -> **The manual way is copying an example config like -> `$HOME/qubes-builder/example-configs/qubes-os-r4.0.conf` to -> `$HOME/qubes-builder/builder.conf`, then editing that copied file.** - -
Setup script method (easier to begin with) - -Run the `setup` script located in `$HOME/qubes-builder/`: - -```console -./setup -``` - -Install the missing dependencies, by pressing **y**. - -![arch-template-04](/attachment/wiki/ArchlinuxTemplate/arch-template-04.png) - -Import the 'Qubes-Master-Signing-key.asc' by selecting **Yes**. The setup script -downloads and confirms this key to that of the key on Qubes OS website. - -![arch-template-05](/attachment/wiki/ArchlinuxTemplate/arch-template-05.png) - -Confirm again with **Yes**. - -![arch-template-06](/attachment/wiki/ArchlinuxTemplate/arch-template-06.png) - -Choose which Qubes release to build templates for, e.g. **4.1** (use space key to select) and -hit enter to accept selection. - -![arch-template-07](/attachment/wiki/ArchlinuxTemplate/arch-template-07.png) - -Choose source repos to use to build packages. Select **QubesOS/qubes-** to get the -default stable repo. - -![arch-template-08](/attachment/wiki/ArchlinuxTemplate/arch-template-08.png) - -Select **Yes** for fast git cloning. - -> **'No' is for reusing the same building environment on a StandaloneVM (not an -> AppVM, as we have used here); a "shallow clone" (depth equal one) is [a bad -> choice for reusable -> environments](https://github.blog/2020-12-21-get-up-to-speed-with-partial-clone-and-shallow-clone/).** - -![arch-template-09](/attachment/wiki/ArchlinuxTemplate/arch-template-09.png) - -Do **not select** any pre-built package repository to build the template -yourself. - -![arch-template-10](/attachment/wiki/ArchlinuxTemplate/arch-template-10.png) - -Select **Yes** to only build the template. - -![arch-template-11](/attachment/wiki/ArchlinuxTemplate/arch-template-11.png) - -Template distribution selection offers choices of distributions to build. -Deselect everything (navigating to entry and hitting space) and select -**archlinux-minimal** and confirm by hitting enter. - -> **Using 'archlinux' may introduce more failed compiles based on additional -> Qubes components you may not even need. You can install them later manually -> instead.** - -![arch-template-12](/attachment/wiki/ArchlinuxTemplate/arch-template-12.png) - -The builder plugins selection offers choices of builder plugins to compile. -Deselect everything (navigating to entry and hitting space) and select -**builder-archlinux** and confirm by hitting enter. - -![arch-template-13](/attachment/wiki/ArchlinuxTemplate/arch-template-13.png) - -Select **Yes** to fetch additional source files needed for the chosen builder -plugins. - -![arch-template-14](/attachment/wiki/ArchlinuxTemplate/arch-template-14.png) - -Press Enter/Return while **OK** is selected to exit. - -![arch-template-15](/attachment/wiki/ArchlinuxTemplate/arch-template-15.png) - -Go directly to [step 4 below](#4-make-all-the-required-qubes-components) to -proceed with the build process. - -
- -
Manually creating `builder.conf` (for experienced users) - -```console -ls -l $HOME/qubes-builder/example-configs -``` -```sh -#!/bin/sh -VER=r4.0 -if [ -f example-configs/qubes-os-$VER.conf ]; then - cp example-configs/qubes-os-$VER.conf "${PWD}"/builder.conf - sed -i 's/DISTS_VM ?=.*/DISTS_VM ?= archlinux+minimal/' "${PWD}"/builder.conf - sed -i 's/#COMPONENTS += builder-archlinux/COMPONENTS += builder-archlinux/g' "${PWD}"/builder.conf - sed -i 's/#BUILDER_PLUGINS += builder-archlinux/BUILDER_PLUGINS += builder-archlinux/g' "${PWD}"/builder.conf - else - # Can execute this script outside of `$HOME/qubes-builder` and it still works as intended. - cp example-configs/qubes-os-$VER.conf "${0%/*}"/builder.conf - sed -i 's/DISTS_VM ?=.*/DISTS_VM ?= archlinux+minimal/' "${0%/*}"/builder.conf - sed -i 's/#COMPONENTS += builder-archlinux/COMPONENTS += builder-archlinux/g' "${0%/*}"/builder.conf - sed -i 's/#BUILDER_PLUGINS += builder-archlinux/BUILDER_PLUGINS += builder-archlinux/g' "${0%/*}"/builder.conf -fi -``` - -
- -### 4. Make all the required Qubes components - -At first the following components need to be build: - -```console -make remount -make install-deps -make get-sources -``` - -> **These commands above should get executed every time you restart the -> qubes-builder AppVM, because these change are lost after a reboot of the VM!** - -Now build all Qubes components (this can take a long time) via - -```console -make qubes-vm -``` - -
Debugging: commands to 'make' every Qubes component manually - -If `make qubes-vm` fails, you can try to pinpoint the problem by building the -components one by one manually. - -```console -make vmm-xen-vm -make core-vchan-xen-vm -make core-qubesdb-vm -make core-qrexec-vm -make linux-utils-vm -make core-agent-linux-vm -make gui-common-vm -make gui-agent-linux-vm -make app-linux-split-gpg-vm -make app-linux-usb-proxy-vm -make meta-packages-vm -``` - -
- -### 5. Build the actual Arch Linux template - -```console -make template -``` - -### 6. Transfer the template into Dom0 - -You need to ensure the rpm template is in the `noarch` directory: - -```console -ls $HOME/qubes-builder/qubes-src/linux-template-builder/rpm/noarch -qubes-template-archlinux-*.*.*-*.noarch.rpm -``` - -Transfer the qubes-template-archlinux rpm into Dom0 - -> **File transfering to Dom0 is considered unsafe. You accept full -> responsibility if Dom0 is compromised due to this file transfer.** - -Follow the -[copying-to-dom0](https://www.qubes-os.org/doc/how-to-copy-from-dom0/#copying-to-dom0) -official guide. Afterwards, read [how to install software in -dom0](https://www.qubes-os.org/doc/how-to-install-software-in-dom0/) and install -the rpm with `sudo dnf install `. - -If the build process went smoothly, the 'archlinux-minimal' template will be listed in Qubes Manager. - -___ -## Debugging the build process - -Arch Linux is a [rolling](https://en.wikipedia.org/wiki/Rolling_release) distro, making it a fragile template for Qubes. -It's important to understand how to debug Qubes templates, fix, then do a pull request. - -See below explanations and examples which (we hope) will help you to solve the common problems, and do a pull request with your solution. - -[neowutran's semi-automated 'archlinux-minimal' Qubes template builder script](https://github.com/Qubes-Community/Contents/blob/master/code/OS-administration/build-archlinux.sh). \ -The most important part about this script is where to add custom code that is not in the Qubes OS repositories. - - - -You can put your custom code by replacing the `qubes-src/` directories. -For example: -```console -$ rm -Rf "$directory/qubes-src/gui-agent-linux/" -$ cp -R ~/qubes-gui-agent-linux "$directory/qubes-src/gui-agent-linux" -``` - -### UseCase : Xorg - -Launch the build: -```console -$ ./build_arch.sh -``` -It crashed with the following output: -``` -Makefile:202: target 'builder-archlinux.get-sources' given more than once in the same rule -Makefile:204: target 'builder-archlinux.get-sources-extra' given more than once in the same rule -Makefile:225: target 'builder-archlinux-vm' given more than once in the same rule -Makefile:237: target 'builder-archlinux-dom0' given more than once in the same rule -Makefile:585: target 'builder-archlinux.grep' given more than once in the same rule --> Building template archlinux (logfile: build-logs/template-archlinux.log)... -make: *** [Makefile:319: template-local-archlinux+minimal] Error 1 -``` -Let's check `build-logs/template-archlinux.log`: -``` ---> Finishing installation of qubes packages... -resolving dependencies... -warning: cannot resolve "xorg-server<1.20.7", a dependency of "qubes-vm-gui" -:: The following package cannot be upgraded due to unresolvable dependencies: - qubes-vm-gui - -:: Do you want to skip the above package for this upgrade? [y/N] error: failed to prepare transaction (could not satisfy dependencies) - -:: unable to satisfy dependency 'xorg-server<1.20.7' required by qubes-vm-gui -make[1]: *** [Makefile:64: rootimg-build] Error 1 -``` -The xorg-server package was probably updated to a version greater than 1.20.7. -Let's search what is the current version of xorg-server... Currently, it is **1.20.7-1**. -Neither a fix nor a minor version change is likely to break things. -So let's find the dependency for "**xorg-server<1.20.7**" and change it to "**xorg-server<1.21**". - -> **rg stands for [ripgrep](https://github.com/BurntSushi/ripgrep), an alternative to GNU grep.** - -```console -$ rg -iuu "xorg-server<1.20.7" ./qubes-builder/qubes-src/ 2> /dev/null -./qubes-builder/qubes-src/gui-agent-linux/archlinux/PKGBUILD -55: 'xorg-server>=1.20.4' 'xorg-server<1.20.7' -``` -So the **/archlinux/PKGBUILD** file of the repository "qubes-gui-agent-linux" requires modification. \ -Git clone "qubes-gui-agent-linux", git checkout to the correct branch (example: `release4.0` instead of master), and then attempt a modification on the **/archlinux/PKGBUILD** file. \ -In your building script, right before the "make qubes-vm", remove the existing "gui-agent-linux" folder and replace it with your own. -Example, add this to the script: -```sh -rm -Rf "~/qubes-builder/qubes-src/gui-agent-linux/" -cp -R ~/qubes-gui-agent-linux "~/qubes-builder/qubes-src/gui-agent-linux" -``` -Then try building the template. -If the template built successfully and works as expected, do a pull request on GitHub to share your fix(es). - -### UseCase: Missing pulsecore error when building the gui-agent-linux - -```console -$ make -module-vchan-sink.c:64:10: fatal error: pulsecore/core-error.h: No such file or directory - 64 | #include - | ^```````````````~~~ -``` -This error is caused by Arch Linux having a newer version of PulseAudio than the PulseAudio headers imported by the Qubes team. -It can be fixed by downloading the new version of the headers, and rebuilding. -This solution prevents any breaking API changes from going silently unnoticed. - -> **Replace 14.2 with your version (with additional suffixes such as -PATCH removed)** - -```console -$ git clone https://github.com/pulseaudio/pulseaudio.git $HOME/git/pulseaudio -$ cd $HOME/git/pulseaudio -$ git checkout v14.2 -$ cd $HOME/qubes-builder/qubes-src/gui-agent-linux/pulse/ -$ cp -r $HOME/git/pulseaudio/src/pulsecore/pulsecore-14.2/ #symlink didn't work -``` -Or simply use the old headers and hope nothing breaks unexpectedly later: -```console -$ cd $HOME/qubes-builder/qubes-src/gui-agent-linux/pulse/ -$ ln -sr pulsecore-14.1 pulsecore-14.2 -``` - -### Known issues - -### xenstore-read: xs_open: permission denied -If the following error appears: -
Click here to show error message - -``` -+ umask 022 -+ cd /home/user/qubes-builder/qubes-src/linux-template-builder -+ rm -rf /home/user/qubes-builder/qubes-src/linux-template-builder/rpmbuild/BUILDROOT/qubes-template-archlinux-4.0.6-202111300407.noarch -+ RPM_EC=0 -++ jobs -p -+ exit 0 -xenstore-read: xs_open: Permission denied -``` - -
- -During the template building process an error ocurred, corrupting the group id of the /dev/xen/* files. -To fix this you'll need to assign the correct permissions, so you'll have to enter the following while `make template` is running: -```console -sudo chgrp qubes /dev/xen/* -``` - - - - -## Debugging the Qubes-ArchLinux runtime -If you are able to launch a terminal and execute command, utilize your Arch-fu to fix the issue. \ -If unable to launch a terminal, shutdown the qube, create a new DisposableVM, [mount an Arch Linux ISO in a DisposableVM](https://www.qubes-os.org/doc/mount-lvm-image/), chroot to it, and then use your Arch-fu. \ -Example of this kind of debugging [that happened on Reddit](https://old.reddit.com/r/Qubes/comments/eg50ne/built_arch_linux_template_and_installed_but_app/). - -### Question -Hello. -I just built an 'archlinux' template and moved it to Dom0, then installed the template. -Afterwards I tried to open a terminal in the 'archlinux' TemplateVM, but it shows nothing. \ -Can you please check this logs and please tell me what is wrong. Thanks. - -I searched the word "Failed" and found few: -``` -[0m] Failed to start..... Initialize and mount /rw and /home.... see 'systemctl status qubes-mount-dirs.service' for details -[0m] Failed unmounting.... /usr/lib/modules.... -... msg='unit=qubes-mount-dirs comm="systemd" exe="/usr/lib/systemd/systemd" hostname=" addr=? terminal=? res=failed' -tsc: Fast TSC calibration failed -failed to mount moving /dev to /sysroot/dev: Invalid argument -failed to mount moving /proc to /sysroot/dev: Invalid argument -failed to mount moving /sys to /sysroot/dev: Invalid argument -failed to mount moving /run to /sysroot/dev: Invalid argument -when I tried to run terminal, in log says -audit: type=1131 audit(some number): pid=1 uid=0 auid=some number ses=some number msg='unit=systemd=tmpfiles-clean cmm="systemd" exe="/usr/lib/systemd" hostname=? addr=? terminal? res=success' -``` -I tried to rebuild the 'archlinux' template and got the same issue. \ -How can I debug this Qube? - -### Answer -The issue came from a systemd unit named "qubes-mount-dirs". We want to know more about that. \ -We can't execute command into the qube, so let's shut it down. -Then, we mount the 'archlinux' root disk into a DisposableVM ( -[mount_lvm_image.sh](https://github.com/Qubes-Community/Contents/blob/master/code/OS-administration/mount_lvm_image.sh) -& [mount-lvm-image](https://www.qubes-os.org/doc/mount-lvm-image/) ) -```console -$ ./mount_lvm_image.sh /dev/qubes_dom0/vm-archlinux-minimal-root fedora-dvm -``` -In the newly created DisposableVM, mount that (disk) image and {ch}ange {root}. -```console -# mount /dev/xvdi3 /mnt -# chroot /mnt -``` -Then check its systemd-journald entries: -``` -[root@disp9786 /]# journalctl -u qubes-mount-dirs --- Logs begin at Fri 2019-12-27 09:26:15 CET, end at Fri 2019-12-27 09:27:58 CET. -- -Dec 27 09:26:16 archlinux systemd[1]: Starting Initialize and mount /rw and /home... -Dec 27 09:26:16 archlinux mount-dirs.sh[420]: /usr/lib/qubes/init/setup-rwdev.sh: line 16: cmp: command not found -Dec 27 09:26:16 archlinux mount-dirs.sh[414]: Private device management: checking /dev/xvdb -Dec 27 09:26:16 archlinux mount-dirs.sh[414]: Private device management: fsck.ext4 /dev/xvdb failed: -Dec 27 09:26:16 archlinux mount-dirs.sh[414]: fsck.ext4: Bad magic number in super-block while trying to open /dev/xvdb -Dec 27 09:26:16 archlinux mount-dirs.sh[414]: /dev/xvdb: -Dec 27 09:26:16 archlinux mount-dirs.sh[414]: The superblock could not be read or does not describe a valid ext2/ext3/ext4 -Dec 27 09:26:16 archlinux mount-dirs.sh[414]: filesystem. If the device is valid and it really contains an ext2/ext3/ext4 -Dec 27 09:26:16 archlinux mount-dirs.sh[414]: filesystem (and not swap or ufs or something else), then the superblock -Dec 27 09:26:16 archlinux mount-dirs.sh[414]: is corrupt, and you might try running e2fsck with an alternate superblock: -Dec 27 09:26:16 archlinux mount-dirs.sh[414]: e2fsck -b 8193 -Dec 27 09:26:16 archlinux mount-dirs.sh[414]: or -Dec 27 09:26:16 archlinux mount-dirs.sh[414]: e2fsck -b 32768 -Dec 27 09:26:16 archlinux mount-dirs.sh[430]: mount: /rw: wrong fs type, bad option, bad superblock on /dev/xvdb, missing codepage or helper program, or other error. -Dec 27 09:26:16 archlinux systemd[1]: qubes-mount-dirs.service: Main process exited, code=exited, status=32/n/a -Dec 27 09:26:16 archlinux systemd[1]: qubes-mount-dirs.service: Failed with result 'exit-code'. -Dec 27 09:26:16 archlinux systemd[1]: Failed to start Initialize and mount /rw and /home. --- Reboot -- -Dec 27 09:26:54 archlinux mount-dirs.sh[423]: /usr/lib/qubes/init/setup-rwdev.sh: line 16: cmp: command not found -Dec 27 09:26:54 archlinux mount-dirs.sh[416]: Private device management: checking /dev/xvdb -Dec 27 09:26:54 archlinux systemd[1]: Starting Initialize and mount /rw and /home... -Dec 27 09:26:54 archlinux mount-dirs.sh[416]: Private device management: fsck.ext4 /dev/xvdb failed: -Dec 27 09:26:54 archlinux mount-dirs.sh[416]: fsck.ext4: Bad magic number in super-block while trying to open /dev/xvdb -Dec 27 09:26:54 archlinux mount-dirs.sh[416]: /dev/xvdb: -Dec 27 09:26:54 archlinux mount-dirs.sh[416]: The superblock could not be read or does not describe a valid ext2/ext3/ext4 -Dec 27 09:26:54 archlinux mount-dirs.sh[416]: filesystem. If the device is valid and it really contains an ext2/ext3/ext4 -Dec 27 09:26:54 archlinux mount-dirs.sh[416]: filesystem (and not swap or ufs or something else), then the superblock -Dec 27 09:26:54 archlinux mount-dirs.sh[416]: is corrupt, and you might try running e2fsck with an alternate superblock: -Dec 27 09:26:54 archlinux mount-dirs.sh[416]: e2fsck -b 8193 -Dec 27 09:26:54 archlinux mount-dirs.sh[416]: or -Dec 27 09:26:54 archlinux mount-dirs.sh[416]: e2fsck -b 32768 -Dec 27 09:26:54 archlinux mount-dirs.sh[432]: mount: /rw: wrong fs type, bad option, bad superblock on /dev/xvdb, missing codepage or helper program, or other error. -Dec 27 09:26:54 archlinux systemd[1]: qubes-mount-dirs.service: Main process exited, code=exited, status=32/n/a -Dec 27 09:26:54 archlinux systemd[1]: qubes-mount-dirs.service: Failed with result 'exit-code'. -Dec 27 09:26:54 archlinux systemd[1]: Failed to start Initialize and mount /rw and /home. -``` -The most important line was: -```console -/usr/lib/qubes/init/setup-rwdev.sh: line 16: cmp: command not found -``` -Let's edit `setup-rwdev.sh`: -```sh -#!/bin/sh -set -e -dev=/dev/xvdb -max_size=1073741824 # check at most 1 GiB -if [ -e "$dev" ] ; then - # The private /dev/xvdb device is present. - # Check if private.img (xvdb) is empty/all zeros - private_size=$(( $(blockdev --getsz "$dev") * 512)) - if [ $private_size -gt $max_size ]; then - private_size=$max_size - fi - if cmp --bytes $private_size "$dev" /dev/zero >/dev/null && { blkid -p "$dev" >/dev/null; [ $? -eq 2 ]; }; then - # The device is empty; create a ext4 filesystem - echo "Virgin boot of the VM: creating private.img filesystem on $dev" >&2 - if ! content=$(mkfs.ext4 -m 0 -q "$dev" 2>&1) ; then - echo "Virgin boot of the VM: creation of private.img on $dev failed:" >&2 - echo "$content" >&2 - echo "Virgin boot of the VM: aborting" >&2 - exit 1 - fi - fi -fi -``` -`cmp` definitely needs to be working. So the binary `cmp` is missing, let's find it: -```console -# pacman -Fy cmp -``` -It's located in ***`core/diffutils`***, and for some (currently) unknown reason is not installed. -Let's modify the 'archlinux' template builder to add this package. Modify the files `qubes-builder/qubes-src/builder-archlinux/script/packages` to add the ***`diffutils`***, and rebuild the template. -Why this package was not installed in the first place? I am unsure. It could be that it was a dependency of the package ***`xf86dgaproto`*** that was removed few days ago, but I don't have the PKGBUILD of this package since it was deleted, so can't confirm. It can be something else too. -I rebuild the template with those modification, and it is working as expected. -I will send a pull request. Does someone have a better idea on "Why ***`diffutils`*** was not installed in the first place?" ? -[The commit](https://github.com/neowutran/qubes-builder-archlinux/commit/09a435fcc6bdcb19144d198ea20f7a27826c1d80) - -___ -## Creating an ArchLinux repository -Once the template have been build, you could use the generated archlinux packages to create your own archlinux repository for QubesOS packages. -You need to: -* Sign the packages with your GPG key -* Host the packages on your HTTP server - -I will assume that you already have a working HTTP server. \ -So you need to sign the packages and transmit everything to the qubes that will upload them to your HTTP server. -The script `update-remote-repo.sh` of the "qubes-builder-archlinux" repository can do that. -Below, an example of code that sign the packages + template rpm file, and transmit everything to another qube. -```sh -$directory/qubes-src/builder-archlinux/update-remote-repo.sh -rpmfile=$(ls -1 $directory/qubes-src/linux-template-builder/rpm/noarch/*.rpm | head -n 1) -qubes-gpg-client-wrapper --detach-sign $rpmfile > $rpmfile.sig -qvm-copy $rpmfile -qvm-copy $rpmfile.sig -qvm-copy $directory/qubes-packages-mirror-repo/vm-archlinux/pkgs/ -``` -Upload everything to your HTTP server, and you are good. -You can now modify the file `/etc/pacman.d/99-qubes-repository-4.0.conf` in your archlinux template to use your repository. -Example of content for this file (**replace the server URL with your own**): -```console -[qubes] -Server = https://neowutran.ovh/qubes/vm-archlinux/pkgs -``` -### About the package `qubes-vm-keyring` -The goal of this package was to add a **`pacman`** source for the Qubes OS packages, and to set its maintainer GPG key as trusted. -**There are binary packages available (unofficially):** -* https://neowutran.ovh/qubes/vm-archlinux/pkgs (go up a directory for an Arch Linux template built for Qubes OS 4.0.3 only) - -If the Qubes OS developers start providing binary packages themselves, the GPG key and fingerprint of the new maintainer(s) might be added in the files below: -* https://github.com/QubesOS/qubes-core-agent-linux/blob/master/archlinux/PKGBUILD-keyring-keys -* https://github.com/QubesOS/qubes-core-agent-linux/blob/master/archlinux/archlinux/PKGBUILD-keyring-trusted - -___ -### StandaloneVM stuff -Having a StandaloneVM for building Qube distro templates would be safer than an AppVM, and wouldn't require reinstalling all dependencies after each VM reboot. \ -But if this wasn't chosen over AppVM by default, there must be downsides to a StandaloneVM I'm unable to think of from a lack of knowledge with Qubes' inner workings. - -### Was in 3. -#### Open a terminal in Dom0 -```console -# sed -e 's/nodev/dev/g' -e 's/nosuid/suid/g' -i /etc/fstab -``` -```console -# qvm-shutdown --wait build-archlinux2;qvm-start build-archlinux2 -``` - -### Was in 5. -Finding if anything in `qubes-builder/` is currently mounted. -```console -$ findmnt -``` -`$`Edit: `$HOME/cleanup.sh` -```sh -#!/bin/sh -sudo umount --lazy --recursive "$HOME/qubes-builder/chroot-vm-archlinux/*/" -sudo umount --lazy --recursive "$HOME/qubes-builder/cache/archlinux/bootstrap/*/" -sudo umount --lazy --recursive "$HOME/qubes-builder/qubes-src/linux-template-builder/*/" -sudo rm -Rf "$HOME/qubes-builder/chroot-vm-archlinux/" -sudo rm -Rf "$HOME/qubes-builder/cache/" -``` -> **Since --lazy is used, rebooting the VM afterwards will prevent strange problems.** - -___ +This content has moved to [Qubes Forum: Community Guides](https://forum.qubes-os.org/c/guides/14). [Learn more.](https://forum.qubes-os.org/t/announcement-qubes-community-project-has-been-migrated-to-the-forum/20367/) diff --git a/docs/building/building-non-fedora-template.md b/docs/building/building-non-fedora-template.md index 6f0b792..deee4c7 100644 --- a/docs/building/building-non-fedora-template.md +++ b/docs/building/building-non-fedora-template.md @@ -1,159 +1 @@ - -Building a TemplateVM for a new OS -============================================================== - -If you don't like using one of the existing templates because of specific administration, package management or other building needs, you can build a TemplateVM for your distribution of choice. - -This article shows how to go about building a template for a different OS. - -You should make sure you understand the details of the BuilderPlugins API - they are explained [here][API]. - -Qubes builder scripts -===================== - -One way to start is by creating Qubes builder scripts for your new OS. -Note that this will probably make your testing process harder than trying to build the package directly in an HVM on which you have already installed the new OS. - -chroot initialization ---------------------- - -You need to customize some scripts that will be used to build all the Qubes tools. -Create a new directory to hold the files for the new os. -You can start from the Fedora scripts in `builder-rpm/template-scripts`, and see how they have been changed for Debian and Archlinux. -The scripts you need are in : - -~~~ -builder-archlinux/scripts -builder-debian/template-debian -builder-rpm/template-scripts -~~~ - -### 00\_prepare.sh - -The goal of the first script `00_prepare.sh` is to download and verify the signature of the installation CD and tools, or the native tools for building an OS. -You can use the `$CACHEDIR` directory variable to store files that could be reused (such as downloaded scripts or iso files). - -### 01\_install\_core.sh - -The goal of this script is to install a base environment of your target OS inside the `$INSTALLDIR` directory variable. -Generally you need to bootstrap/install your package manager inside the `$INSTALLDIR` directory and install the base packages. - -### Testing the installation process - -Edit the file `builder.conf` to change the variable `$DISTS_VM` to your OS name (`DISTS_VM=your_os_name`). -Then try to create (make) the template to check that at least these first two scripts are working correctly: - -~~~ -make linux-template-builder -~~~ - -Qubes builder Makefiles ------------------------ - -Now you need to create Makefiles specific to your OS. -You will find the required scripts to adapt in the `builder-*` folders: - -~~~ -prepare-chroot-yourOSname -Makefile.yourOSname -~~~ - -### prepare-chroot-yourOSname - -The goal of this file is to prepare a development environment of your target OS inside a chroot. -You will reuse the `00_prepare.sh` and `01_install_core.sh` scripts. -Additionally, the following things have to be done in this Makefile: - -- the `$1` variable will contain the installation directory (`$INSTALLDIR` should contain the same value as `$1` when you run `00_prepare.sh` or `01_install_core.sh`) -- after your base system is installed, you should install development tools and libraries (gcc, make, ...) -- create a user called 'user' inside your chroot, and give them enough rights to run the command sudo without any password -- register all the repositories that will be necessary and synchronize the package database -- register a custom repository that will be used to store Qubes packages - -### Makefile.yourOSname - -This file will be used to define the action required when installing a custom package. -The most important one are: - -- `dist-prepare-chroot`: that's where you will call `prepare-chroot-yourOSname` if the chroot has not been initialized. -- `dist-package`: that's where you will chroot the development environment and run the command used to build a package. -- `dist-build-dep`: that's where you will create the custom repository for your target OS based on already compiled packages. - -These additional targets need to exist once you have created your first packages: - -- `dist-copy-out`: that's where you will retrieve the package you just built and put it with all the other packages you prepared. -- `update-repo`: that's where you will retrieve the package that has been built and add it to the custom repository. - -### Testing the development chroot - -You will be able to test these scripts when making the first Qubes packages. -Don't forget that the first things that run when running `make somecomponent-vm` will be these two scripts, and that you will need to debug it at this point. - -Qubes packages --------------- - -* [vmm-xen](https://github.com/QubesOS/qubes-vmm-xen) -* [core-vchan-xen](https://github.com/QubesOS/qubes-core-vchan-xen) -* [linux-utils](https://github.com/QubesOS/qubes-linux-utils) -* [core-agent-linux](https://github.com/QubesOS/qubes-core-agent-linux) -* [gui-common](https://github.com/QubesOS/qubes-gui-common) -* [gui-agent-linux](https://github.com/QubesOS/qubes-gui-agent-linux) - -Additional Installation scripts -------------------------------- - -Again you need to create new scripts based on the existing scripts in these folders: - - -~~~ -builder-archlinux/scripts -builder-debian/template-debian -builder-rpm/template-scripts -~~~ - -### 02\_install\_groups.sh - -The goal of this script is to install all the packages that you want to use in your template (eg: firefox, thunderbird, a file manager, Xorg...). - -### 04\_install\_qubes.sh - -The goal of this script is to install in your template all the packages you built previously. -Also you need to edit the fstab file of your template to mount Qubes virtual hard drives. - -### 09\_cleanup.sh - -This script is used to finalize and to remove unnecessary things from your template, such as cached packages, unused development packages ... - -Starting with an HVM -==================== - -If no Qubes packages are available for your selected OS you could start by installing your OS in an HVM. -Your goals will be: - -- to identify how to install the OS using command lines -- to create required Qubes packages -- to identify potential issues, making sure all Qubes agents and scripts work correctly. - -As soon as you manage to get `qrexec` and `qubes-gui-agent` working, you will be ready to start preparing a template VM. - -### Xen libraries - -Several Xen libraries are required for Qubes to work correctly. -In fact, you need to make `xenstore` commands working before anything else. -For this, Qubes git can be used as several patches have been selected by Qubes developers that could impact the activity inside a VM. -Start by retrieving a recent git and identify how you can build a package from it: `git clone https://github.com/QubesOS/qubes-vmm-xen.git`. - -Find the .spec file in the git repository (this is the file used to build rpm packages), and try to adapt it to your OS in order to build a package similar to the target 'vmm-xen'. -For example, a PKGBUILD has been created for -[ArchLinux](https://www.qubes-os.org/doc/building-archlinux-template/) which can be found in the vmm-xen repository. - -Don't be afraid of the complexity of the PKGBUILD: most of the code is almost a copy/paste of required sources and patches found in the .spec file provided in the git repository. - -Note once the package has been successfully compiled and installed, you need to setup XEN filesystem. -Add the following line to your fstab (you can create this line in your package install script): -`xen /proc/xen xenfs defaults 0 0`. - -Now install the package you built and mount `/proc/xen`. -Verify that xenstore-read works by running: `xenstore-read name`. That should give you the current qube name. - -[API]: https://github.com/QubesOS/qubes-builder/blob/master/doc/BuilderPluginAPI.md +This content has moved to [Qubes Forum: Community Guides](https://forum.qubes-os.org/c/guides/14). [Learn more.](https://forum.qubes-os.org/t/announcement-qubes-community-project-has-been-migrated-to-the-forum/20367/) diff --git a/docs/building/building-whonix-template.md b/docs/building/building-whonix-template.md index d34ae57..deee4c7 100644 --- a/docs/building/building-whonix-template.md +++ b/docs/building/building-whonix-template.md @@ -1,87 +1 @@ - -## Building Whonix Templates - -The Whonix templates are easily downloaded and installed by following the [procedure here](https://www.whonix.org/wiki/Qubes/Install). -However, they are integrated into `qubes-builder` so they are straight-forward to build yourself if you prefer. - -Many other Qubes templates can also be built by following this procedure. -Simply choose the appropriate builder(s) and template(s) you wish to build in the `./setup` procedure below. -Always include the `mgmt-salt` builder. - -First, set up the [Build Environment](https://www.qubes-os.org/doc/qubes-iso-building/#build-environment) (follow the build environment section only). - -Next, configure the builder: - -~~~ -cd ~/qubes-builder -./setup -# Select Yes to add Qubes Master Signing Key -# Select Yes to add Qubes OS Signing Key -# Select 4.0 for version -# Stable -# Select Current (if you want the option to use pre-built packages) -# Yes (we want to build only templates) -# Select fc29 and stretch (for the currently shipping templates) -# Select builder-rpm, builder-debian, template-whonix, mgmt-salt -# Yes (to download) -~~~ - -Once it completes downloading, re-run `setup` to add the Whonix templates: - -~~~ -./setup -# Choose the same options as above, except at templates select: -# whonix-gateway-14, whonix-workstation-14 -# If prompted, choose Yes to add adrelanos's third party key -~~~ -Continue the build process with: - -~~~ -make install-deps -make get-sources -~~~ - -You will often need to edit/update `qubes-src/template-whonix/builder.conf` at this stage to specify the currently shipping Tor Browser version. -Open it in your favorite editor, then look for "Extra Whonix Build Options" and add/edit the `WHONIX_TBB_VERSION` variable to specify the current version. -For example: - -``` -################################################################################ -# Extra Whonix Build Options -################################################################################ - -# Whonix repository. -WHONIX_APT_REPOSITORY_OPTS ?= stable -#WHONIX_APT_REPOSITORY_OPTS = off - -# Use turbo mode to build template -BUILDER_TURBO_MODE ?= 1 - -# Enable Tor by default (0: disable; 1: enable) -WHONIX_ENABLE_TOR ?= 0 - -WHONIX_TBB_VERSION ?= 7.5.2 -``` - -You can add/edit the `WHONIX_TBB_VERSION` variable in `~/qubes-builder/builder.conf` instead of this file if preferred. - -Finally, use: - -~~~ -make qubes-vm -make template -~~~ - -Once the build is complete, the install packages for your newly built templates will be located in `~/qubes-builder/qubes-src/linux-template-builder/rpm/noarch`. -Copy them from there to dom0 and install: - -~~~ -qvm-run --pass-io 'cat ~/qubes-builder/qubes-src/linux-template-builder/rpm/noarch/qubes-template-whonix-gw-4.0.0-201802250036.noarch.rpm' > ~/qubes-template-whonix-gw-4.0.0-201802250036.noarch.rpm -qvm-run --pass-io 'cat ~/qubes-builder/qubes-src/linux-template-builder/rpm/noarch/qubes-template-whonix-ws-4.0.0-201802250145.noarch.rpm' > ~/qubes-template-whonix-ws-4.0.0-201802250145.noarch.rpm -sudo dnf install qubes-template-whonix-gw-4.0.0-201802250036.noarch.rpm -sudo dnf install qubes-template-whonix-ws-4.0.0-201802250145.noarch.rpm -~~~ - -And you are done! - - +This content has moved to [Qubes Forum: Community Guides](https://forum.qubes-os.org/c/guides/14). [Learn more.](https://forum.qubes-os.org/t/announcement-qubes-community-project-has-been-migrated-to-the-forum/20367/) diff --git a/docs/common-tasks/copying-files-to-dom0.md b/docs/common-tasks/copying-files-to-dom0.md index 8dc819b..deee4c7 100644 --- a/docs/common-tasks/copying-files-to-dom0.md +++ b/docs/common-tasks/copying-files-to-dom0.md @@ -1,45 +1 @@ -Copying files to dom0 -===================== - -**!! Note: copying untrusted content (or trusted content from an untrusted VM) compromises the whole Qubes OS security model !!** - - -Technically, the output of a file in a VM (generated by a `qvm-run --pass-io ...` command) is redirected into a file in dom0: - -~~~ -qvm-run --pass-io vm-name "cat /path/to/file/in/vm" > "/path/to/file/in/dom0" -~~~ - -or with a pipe into `dd`, with the `conv=sparse` option to recreate a sparse file in dom0: - -~~~ -qvm-run --pass-io vm-name "cat /path/to/file/in/vm" | dd conv=sparse of=/path/to/file/in/dom0 -~~~ - -Note that in this case the **whole** file is read by `cat` so the operation will take some time to complete for large files. Alternatively, one could pipe the output of `tar -Scf - large_file` into `tar` in dom0, but this is not recommended since an attacker could use potential vulnerabilities in `tar` to compromise dom0. - -Script to automate copying: - -~~~ -#!/bin/bash -# qvm-copy-to-dom0 -# Copy a file from an AppVM to dom0 -# qvm-copy-to-dom0 appVM srcPath [ dst ] - -AppVM=$1 # mandatory -Source=$2 # mandatory -Destination=$3 # optional (will use ~/QubesIncoming/AppVM/ folder if null) - -if [ -z "$Destination" ]; then - Destination="$HOME/QubesIncoming/$AppVM/$(basename "$Source")" - mkdir -p "$HOME/QubesIncoming/$AppVM" -fi - -if [ -e "$Destination" ]; then - echo "'$Destination' exists; aborting" >&2 - exit 1 -fi - -qvm-run --pass-io $AppVM "cat $Source" > "$Destination" -~~~ - +This content has moved to [Qubes Forum: Community Guides](https://forum.qubes-os.org/c/guides/14). [Learn more.](https://forum.qubes-os.org/t/announcement-qubes-community-project-has-been-migrated-to-the-forum/20367/) diff --git a/docs/common-tasks/opening-urls-in-vms.md b/docs/common-tasks/opening-urls-in-vms.md index 07e3eff..deee4c7 100644 --- a/docs/common-tasks/opening-urls-in-vms.md +++ b/docs/common-tasks/opening-urls-in-vms.md @@ -1,187 +1 @@ -*Note: there is an ongoing [pull request](https://github.com/QubesOS/qubes-doc/pull/1314) to add most of the content of this document to the official Qubes OS documentation.* - - - -This page is about opening URLs and files from one qube in a different qube. The most straightforward way to do this is simply to [copy and paste URLs](/doc/how-to-copy-and-paste-text/) or [copy and move files](/doc/how-to-copy-and-move-files/) from the source qube to the target qube, then manually open them in the target qube. However, some users might wish to use [RPC policies](/doc/rpc-policy/) in order to regiment their workflows and safeguard themselves from making mistakes. - -Naming conventions: - -- `` is the qube in which the URL or file originates. -- `` is the qube in which we wish to open the URL or file. - -## Configuring RPC policies - -The `qvm-open-in-vm` and `qvm-open-in-dvm` scripts are invoked in a qube to open files and URLs in another qube. Those scripts make use of the `qubes.OpenInVM` and `qubes.OpenURL` [RPC services](/doc/qrexec/#qubes-rpc-services). Qubes [RPC policies](/doc/rpc-policy/) control which RPC services are allowed between qubes. - -Policy files are in `/etc/qubes/policy.d/`. - -### Using the `ask` action - -This action displays a confirmation prompt in dom0 with a drop-down list of allowed target qubes each time the associated RPC service is called. This setup makes it possible to always control whether and in which qube a URL or file opened. - -The selected qube will automatically start if it wasn't running. - -**Note:** When using `ask`, the target qube given as an argument to `qvm-open-in-vm` is ignored if no `allow` rule matches the current RPC service and source/target qubes. - -### Using the `allow` action - -This action allows a specified RPC service to be invoked between source and target qubes without displaying a confirmation prompt in dom0. - -When an `allow` action is defined for a target other than `@dispvm`, the target qube is the one given as an argument to `qvm-open-in-vm` in ``. The corresponding RPC policies must be configured accordingly. - -**Warning:** Since there is no user confirmation with `allow`, applications in `` could leak data through URLs or file names. - -### Using disposables and the `@dispvm` keyword in policies - -It is possible to further restrict a target disposable qube by specifying the template on which it is based with the `@dispvm:` syntax ([learn more](/doc/how-to-use-disposables/#opening-a-link-in-a-disposable-based-on-a-non-default-disposable-template-from-a-qube)). - -**Note:** The keyword `@dispvm` designates any disposable based on the calling qube's default disposable template. It does *not* designate any disposable whatsoever. For example, if you were to run `qvm-open-in-vm @dispvm: https://www.qubes-os.org` in `` while `` is *not* ``'s default disposable template, it wouldn't work if your policy line merely had `@dispvm` as the target. You would have to use `@dispvm:` as the target instead. - -## Sample RPC user policy - -_See the main document, [RPC policies](/doc/rpc-policy/), for more information._ - -The following is a partial example of the kinds of `qubes.OpenInVM` and `qubes.OpenURL` rules that you could write in `/etc/qubes/policy.d/30-user.policy`: - -~~~ -# Deny opening files or URLs from or in 'vault' -qubes.OpenInVM * @anyvm vault deny -qubes.OpenURL * @anyvm vault deny -qubes.OpenInVM * vault @anyvm deny -qubes.OpenURL * vault @anyvm deny - -# Allow 'work' to open URLs in disposable qubes without prompting the user -qubes.OpenURL * work @dispvm allow - -# Allow 'work' to open files in 'untrusted' without prompting the user -qubes.OpenInVM * work @dispvm allow target=untrusted - -# Allow any qube to open files and URLs in disposables based on the -# disposable templates 'foo' and 'bar' -qubes.OpenInVM * @anyvm @dispvm:foo allow -qubes.OpenURL * @anyvm @dispvm:bar allow - -# Prompt the user before opening any file or URL in any other qube, but prefill -# the target with 'personal' for files and 'untrusted' for URLs -qubes.OpenInVM * @anyvm @anyvm ask default_target=personal -qubes.OpenURL * @anyvm @anyvm ask default_target=untrusted -~~~ - -## Configuring application handlers - -It is possible to (re)define a default application handler so that it is automatically called by *any* application in `` to open files or URLs provided that the applications adhere to the [freedesktop](https://en.wikipedia.org/wiki/Freedesktop.org) standard (which is almost always the case nowadays). - -For application-specific configurations or applications that don't adhere to the freedesktop standard, please refer to the unofficial, external [community documentation](https://github.com/Qubes-Community/Contents/blob/master/docs/common-tasks/opening-urls-in-vms.md). - -Defining a new handler simply requires creating a [.desktop](https://specifications.freedesktop.org/desktop-entry-spec/latest/) file and registering it. The following example shows how to open http/https URLs (along with common "web" [media types](https://en.wikipedia.org/wiki/Media_type)) with `qvm-open-in-vm`: - -- Create `$HOME/.local/share/applications/mybrowser.desktop` with the following content: - - ~~~ - [Desktop Entry] - Encoding=UTF-8 - Name=MyBrowser - Exec=qvm-open-in-vm %u - Terminal=false - X-MultipleArgs=false - Type=Application - Categories=Network;WebBrowser; - MimeType=x-scheme-handler/unknown;x-scheme-handler/about;text/html;text/xml;application/xhtml+xml;application/xml;application/vnd.mozilla.xul+xml;application/rss+xml;application/rdf+xml;image/gif;image/jpeg;image/png;x-scheme-handler/http;x-scheme-handler/https; - ~~~ - -- Register the `.desktop` file with `xdg-settings set default-web-browser mybrowser.desktop`. - -The same can be done with any other media type (see `man xdg-mime` and `xdg-settings`). - -### Notes - -- Some applications may not use the new XDG application handler (e.g., if you had previously configured default applications), in which case you'd have to manually configure the application to use the XDG handler. - -- `qvm-open-in-vm target-qube %u` can be replaced by a user wrapper with custom logic for selecting different target qubes depending on the URL/file type, level of trust, etc. The RPC policies should be configured accordingly. - -- Advanced users may wish to consider basing app qubes on [minimal templates](/doc/templates/minimal/). That way, unless a default handler is set, it is unlikely that any other program will be present that can open the URL or file. - - - -## Configuring specific applications - -Most applications provide a way to select a given program to use for opening specific URL/file (MIME) types. We can use that feature to select the `/usr/bin/qvm-open-in-{vm,dvm}` scripts instead of the default programs. - -The subsections below show how to configure popular applications in case the "default handler" approach above doesn't work / isn't sufficient. - -### Firefox, Chrome/Chromium - -Those browsers have an option to define programs associated to a file (MIME) type. It is pretty straightforward to configure and is outside the scope of this document. - -An alternative is to use Raffaele Florio's [qubes-url-redirector](https://github.com/raffaeleflorio/qubes-url-redirector) add-on, which provides a lot of flexibility when opening links without the hassle of having to write custom shell wrappers to `qvm-open-in-vm`. For instance links can be opened with a context menu and the add-on's default behavior can be configured, even with whitelist regexes. - -Notes: - -- the qubes-url-redirector add-on will likely be included officialy in Qubes (see [this](https://github.com/QubesOS/qubes-issues/issues/3152) issue). -- the add-on can actually be used with applications other than firefox/chrome/chromium, the only requirement is that URLs open in a browser in ``. It works like so: - - the application in `` opens an URL in the default browser in `` (eg. firefox) - - firefox starts on ``, the add-on processes the URL and according to its configuration "sends" the URL to `` with `qubes.OpenURL` - - the URL opens in the ``'s browser - -### Thunderbird - -**Opening attachments**: "actions" must be defined, see section "Download Actions" settings" in [this document](http://kb.mozillazine.org/Actions_for_attachment_file_types). - -**Opening URLs**: changing the way http and https URLs are opened requires tweaking configuration options; see [this](http://kb.mozillazine.org/Changing_the_web_browser_invoked_by_Thunderbird) and [this](http://kb.mozillazine.org/Network.protocol-handler.expose-all) document for more information. Those changes can be made in Thunderbird's built-in config editor, or by adding the following lines to `$HOME/.thunderbird/user.js`: - -``` -user_pref("network.protocol-handler.warn-external.http", true); -user_pref("network.protocol-handler.warn-external.https", true); -user_pref("network.protocol-handler.expose-all", true); -``` - -Thunderbird will then ask which program to use the next time a link is opened. If `` is a standard (random) dispVM, choose `/usr/bin/qvm-open-in-dvm`. Otherwise you'll have to create a wrapper to `qvm-open-in-vm` since arguments cannot be passed to programs selected in Thunderbird's dialog gui. For instance, put the following text in `$HOME/bin/thunderbird-open-url`, make it executable, and select that program when asked which program to use: - -``` -#!/bin/sh -qvm-open-in-vm "$@" -``` - -### Vi - -Opening URLs: put the following in `$HOME/.vimrc`: - -``` -let g:netrw_browsex_viewer = 'qvm-open-in-vm ' -``` - -Typing `gx` when the cursor is over an URL will then open it in `` (or will trigger a dialog if `ask` policy is configured, ignoring the `` argument). - - -# Considerations on dispVMs - -## Re-using dispVMs - -In the section above we've seen how using the 'ask' RPC policy allowed us to start a (disp)VM once and use it for opening subsequent URLs (or files) to avoid having to wait insane amounts of time for dispVMs to start. However this comes at the price of a loss in compartmentalization. It is thus up to the user to carefully pick destination VMs and to manage the lifecycle of dispVMs, killing it/them when necessary when a clean state is required. - -## Managing changes - -When opening and modifying a document in a dispVM the content is sent back to `` when the dispVM's process (eg. LibreOffice) closes. The dispVM's private volume is then wiped and any change that was made to the VM are discarded - eg. automatically updated add-ons, blacklists, tweaked browser preferences, ... ; The following ideas show how to cope with those "deliberate" changes: - -- inter-VM copy/paste is probably the easiest way to synchronize small amounts of data in text form from the dispVM to `` (or to another dedicated VM like the oft-used 'vault' VM). Eg.: - - passwords: copy/paste from/to KeepassX (or one of its forks). - - bookmarks: copy/paste from/to - - a plain text file - - or an html bookmark file (most browsers can export/import such file) - - or a dedicated bookmark manager like [buku](https://github.com/jarun/Buku) (command line manager, available in Fedora 28 repo - `dnf install buku`). -- other content/changes will have to be copied, usually to the dispVM templateVM. Care must be taken not to replicate compromised files: working with a freshly started dispVM and performing only the required update actions before synchronizing files with the templateVM is a good idea. - -## Using "named" dispVMs - -If for some reason a user needs to have use a dispVM with a given name - which is for instance handy when using `allow` RPC policies - he/she can do like so (replace `fedora-28-dvm` with the dvm template you want to use): - -``` -qvm-create -C DispVM -t fedora-28-dvm -l red -``` - -This VM works like a regular VM, with the difference that its private disk is wiped after it's powered off. However it doesn't "auto power off" like random dispVMs so it's up to the user to power off (and optionally restart) the VM when he/she deems necessary. - - ------------------------------------------------------------------------- - -`Credits:` @raffaeleflorio, [Micah Lee](https://micahflee.com/2016/06/qubes-tip-opening-links-in-your-preferred-appvm/) +This content has moved to [Qubes Forum: Community Guides](https://forum.qubes-os.org/c/guides/14). [Learn more.](https://forum.qubes-os.org/t/announcement-qubes-community-project-has-been-migrated-to-the-forum/20367/) diff --git a/docs/common-tasks/setup-trezor-cryptocurrency-hardware-wallet.md b/docs/common-tasks/setup-trezor-cryptocurrency-hardware-wallet.md index 37a8f93..deee4c7 100644 --- a/docs/common-tasks/setup-trezor-cryptocurrency-hardware-wallet.md +++ b/docs/common-tasks/setup-trezor-cryptocurrency-hardware-wallet.md @@ -1,29 +1 @@ -## Setting up a Trezor cryptocurrency hardware wallet in Qubes - -using a Fedora-based sys-usb VM and a Whonix WS-based application VM: -- navigate to the [Trezor instructions](https://wiki.trezor.io/Qubes_OS) page and read them. They are more frequently updated than this document. -- in dom0: - `sudo vim /etc/qubes-rpc/policy/trezord-service` -add this line: - `$anyvm $anyvm allow,user=trezord,target=sys-usb` -replace `sys-usb` with `disp-sys-usb` if you are using a disposable sys-usb - -- in the sys-usb VM, or for disp-sys-usb, the VM on which it is based - (in both cases, assumed to use a fedora-3x template): - `sudo mkdir /usr/local/etc/qubes-rpc` - `sudo vim /usr/local/etc/qubes-rpc/trezord-service` - and add this line to trezord-service: - `socat - TCP:localhost:21325` -- in the whonix-based application VM: - `pip3 install --user trezor` - `sudo vim /rw/config/rc.local` - add this line (note the "&" at the end): - `socat TCP-LISTEN:21325,fork EXEC:"qrexec-client-vm sys-usb trezord-service" &` -- in the fedora-3x template: - `sudo dnf install trezor-common` -- download the bridge RPM from - https://wallet.trezor.io/#/bridge - and remember to verify it! -- copy to fedora-3x -- in fedora-3x - `sudo rpm -i /path/to/trezor.rpm` +This content has moved to [Qubes Forum: Community Guides](https://forum.qubes-os.org/c/guides/14). [Learn more.](https://forum.qubes-os.org/t/announcement-qubes-community-project-has-been-migrated-to-the-forum/20367/) diff --git a/docs/common-tasks/uqus-doc.md b/docs/common-tasks/uqus-doc.md index 499459c..deee4c7 100644 --- a/docs/common-tasks/uqus-doc.md +++ b/docs/common-tasks/uqus-doc.md @@ -1,137 +1 @@ - - -### 1) Introduction -UQUS (Universal Qubes Update Script) is a script made to make it easy to update TemplateVM's and StandaloneVM's in Qubes 4.0, however -it may also be useful for Qubes 3.2. (Currently need 3.2. testers). - - **NOTE!!** Newst version of UQUS is currently not yet uploaded, but it will be uploaded soon. For example current version of UQUS has no - autonomouse detection, nor any logging capability. Some extra work is needed before its ready. Stay tuned for an update. - **This doc is written for the upcoming UQUS version.** - -
- -### 2) Feature: Autonomouse dectection of TemplateVM's and StandaloneVM's. -UQUS will automatically find your TemplateVM's and StandaloneVM's containing the primary template OS name. -For example, any TemplateVM or standaloneVM containing the word "fedora", "debian", or "whonix", will -update separately in order to make up for their differences in the update process. - - It is possible to autonomously update all TemplateVM and StandaloneVM's irregardless of their VM names with a different script (and in part what UQUS's autonomous detection is based on), however please see the limitations section below as for why UQUS has this minor limiation. It is deemed a minor limitation because templates normally always include their OS name in the VM-name anyway, however steps are taken to allow user different choices to overcome this issue, should you have given your TemplateVM or StandaloneVM a unique name. - -
- -### 3) Feature: LogVM - Logging all update/upgrade/autoremove transactions. -UQUS supports a low-system-resource "one-way" centralized offline LogVM, which is strictly used for logging and nothing else. -The benifit is that you can keep all your logs gathered at a single location, which neither needs much RAM -to run, nor much disk space to preserve a long history of logs. - - Security: The LogVM is an offline based AppVM, with strict inter-VM Qubes-RPC (Policy) restrictions. This means - that neither the LogVM, nor the StandaloneVM's or TemplateVM's, have direct internet access at any time, nor does - the LogVM ever import anything else but logs, so that the risk of malware being imported to the LogVM is low. Furthermore - transactions are restricted in one-direction, so templateVM's can never be accessed despite of moving logs to a centralized LogVM. - The biggest limitation to this security model for LogVM's, is if the user puts a wrong Qubes-RPC (Policy). Changing Qubes-RPC may - one day become autnomous in UQUS, however it depends greatly if the script will remain located in dom0, or be moved to a less trusted VM. - Accessing dom0 from a less trusted domain is not desured, however options for future UQUS updates are still being considered here. - -
- - -### 4) Feature: Autonomous error detection. -Having all update/upgrade/autoremove logs centralized in the LogVM, allows for a single procress to monitor for errors. This is potentially still -some months into the future, however it is a major goal, and is therefore included. -- Error detection will primarily be simple and based on searching for words like "danger, dangerours, critical, critically, fail, failed, unable, and similar words that indicate errors, and autonomously present it in an easy to read manner. - - Currently this can only be done manually in the LogVM, however the log history is preserved and future log detection processes can later be run on older historic logs. - - Autonomous error-detection "could" potentially mean less risk by running -y autoaccept on updates and upgrades, however only "less risky". - - Autonomous support for autoremove will on-purpose remain unsupported. - - Autonomous error-detection may be more complicated than estimated, however stay tuned for now. - -
- -### 5) Feature: Central log-window output for awareness of how UQUS is progressing. -The central output window has multiple of different benifits, as following: -- Shows live which TemplateVM and StandaloneVM is being updated. -- Shows which commands are in current-time being executed. -- Shows how far the UQUS update script has progressed. -- Written so it is made easy to read and keep track of the log-window progressive content. -- Output from the central log-window is also moved to the LogVM. - - This happens when UQUS finishes, or if any different script-command fails mid-way. -- Central window includes basic UQUS information, including how to stop the script (i.e. running `kill -9 pid) and also includes the scripts current PID number so you don't need to go looking for it yourself. - - In the future keybinds may be included to pause or stop UQUS, which can be modified to different keys in the script. - -
- -### 6) Feature: UQUS seeks and provides high flexibility to settings and prefferences. -A persistent goal is to make UQUS allow easy and effortless user modifications - as far possible. UQUS may be further updated in the -future in order to get as close to this goal as possible. Setting modications include: -- Script is written so that it is easier to perform modifications, both simple and more advanced ones. -- Script is written so that it is easier to change or add more autonomouse filters, i.e. to include different search parameters. -- Script is written to allow manaual update/upgrade/autoremove, in case the VM-name is not matching the search-parameters. -- Script is written to allow easy change of colors/fonts and change messages. -- Toggle, on/off - Qubes current-testing repositories (for dom0/fedora/debian based systems respectively). -- Toggle, on/off - Autonomous -y accept of updates/upgrades (discouraged, but included). - - Autoaccept of autoremove is on purpose not supported. -- Toggle, on/off - shutdown of LogVM upon script completion. -- Toggle, on/off - shutdown of sys-whonix upon script completion. -- Toggle, on/off - question-message providing options, whether to shutdown, restart, just shutodwn all VM's only, or do nothing, upon script completion. - -
- -### 7) Feature: Steps taken to make it easy to run UQUS, and in different ways. - It makes no difference if you keybind the script, turn it into a clickable icon or menu item, or run it directly in -your terminal, UQUS will always behave the same way. -- This means, for example, you will always get the central output window, because -UQUS itself runs in the background, while the background script allocates a low-resource output window for information. -- You may optionally choose to disable the central log-window, however, it is useful to keep it enabled to stay informed. -- The easy access to enable/disable the central log-window, allowing the script to run the same way, whether by desktop shortcut, menu option, -keybinded, executed manually in terminal, or even time based activation, provides the user with freedom to make own preferrences. - -
- -### 8) Feature: Quick and easy to stop the script gracefully. -The script is increasingly being made to support this goal, so that you retain maximum control of your update/upgrade process. -More work may be done in the future to enhance this capability further, for example to "pick up" where you left off, rather than -having to start the update/upgrade procress all over again from the beginning. - -
- -### 9) Limitation: Some minor UQUS VM-naming limitations to be aware of. -There is a different more simple script existing which part of UQUS's autonomous parts is also inspired by, which can run all -templates despite of their given VM-names. The reason UQUS is inspired by this scripts full autonomous detection capability but UQUS remain minorly limited in its autonomous detection capaibity, in comparison, is because of additional commands being -executed, and also to allow the user to make changes in the script settings and freedom to personal prefferences. - -**9.1. names like these will work autonomously:** -- Fedora-28 -- stuff-fedora-28-apps -- stufffedora28apps -- Works similar for Debian/Whonix/CentOS). - -**9.2. names like these won't work autonomously:** -- fed-28 -- stuff-fed-28-apps -- stufffed28apps -- Any name without fedora (or Debian/Whonix/CentOS) in it. - -If you do however happen to have specific TemplateVM's or StandaloneVM's which do not contain the name of the OS its -based on in the TemplateVM or standaloneVM's name, then you may either; -- Change the TemplateVM or standaloneVM name to containthe OS name it is based on. -- Manually create additional rules in the script (hardest of the three options, but not very difficult to do either). - -
- -### 10) Requirements and prerequisities. -- You must run UQUS in dom0, it will otherwise "currently" not work. - - Thoughts are being put in to make it work in a VM, this feature "might" be introduced one day. - - Speculation on whether to make Qubes-RPC changes automatically in the script, or instead alternatively make UQUS run in a VM (and change the Qubes-RPC's manually). - - This is being considered as "trade-offs". -- For first-time users of scripts, you must first allow the script to be executeable. - - You may do this in dom0 with `chmod +x /path/to/script/uqus.bash` -- Ensure you have enough RAM to start your TemplateVM's, StandaloneVM's and optionally your LogVM. - - Note: UQUS will **always** only start one TemplateVM/StandaloneVM at any one point in time, in a series of sequence. - - But remember if you use the LogVM feature, it'll take up low-resources to run (i.e. some 300-400 RAM), but this VM - will only need to be run during the brief period UQUS is running, and can be optionally disabled as well. - - -
- -### 11) More features are being pursued. -The above features should be ready soon. However some un-mentioned features are still being considered, and I lack time to start -working on them. Once the above features have been updated in UQUS, there might be some months before new features or fine-tuning updates emerge. - -
- +This content has moved to [Qubes Forum: Community Guides](https://forum.qubes-os.org/c/guides/14). [Learn more.](https://forum.qubes-os.org/t/announcement-qubes-community-project-has-been-migrated-to-the-forum/20367/) diff --git a/docs/configuration/bluetooth.md b/docs/configuration/bluetooth.md index 48956f0..deee4c7 100644 --- a/docs/configuration/bluetooth.md +++ b/docs/configuration/bluetooth.md @@ -1,33 +1 @@ -# Graphical Bluetooth configuration - -Install the package `blueman` in the template of your `sys-usb` qube. - -``` -sudo dnf install -y blueman -``` - -Then restart the qube. From now on you should have a tray icon and be ready to connect to bluetooth devices graphically, like so: - -![](https://forum.qubes-os.org/uploads/db3820/original/2X/e/e7eb9d14ec38c6a9e3784b319866ba2b105b1621.png) - -In the picture above I had a sys-net combined to use USB devices too. The procedure stays the same. - -Note: if you're using a separate sys-usb, and need to attach your bluetooth module to a AudioVM or MediaVM, 'blueman-manager' won't run without a recognized adapter from 'blueman-applet'. Once you attach, you can run 'blueman-manager' and with a script like the below in your AppVM's `rc.local` auto-connect to your preffered device: - -``` -address="XX:XX:XX:XX:XX:XX" - -while (sleep 1) -do -connected=`sudo hidd --show` > /dev/null -if [[ ! $connected =~ .*${address}.* ]] ; then -sudo hidd --connect ${address} > /dev/null 2>&1 -fi -done - -``` -The loop should be the last thing in rc.local or appended with `&`. This is a simple solution. (Something more robust would require extra work with `udev` perhaps.) - -## AudioVM - -For the most secure scenario, one should be running an AudioVM rather than rely on having PulseAudio in dom0. The creation of such a VM is beyond the scope of this guide. +This content has moved to [Qubes Forum: Community Guides](https://forum.qubes-os.org/c/guides/14). [Learn more.](https://forum.qubes-os.org/t/announcement-qubes-community-project-has-been-migrated-to-the-forum/20367/) diff --git a/docs/configuration/change-time-zone.md b/docs/configuration/change-time-zone.md index 9ebdc5d..deee4c7 100644 --- a/docs/configuration/change-time-zone.md +++ b/docs/configuration/change-time-zone.md @@ -1,31 +1 @@ - -# Changing your Time Zone # - -## Qubes 4.0 ## - -### Command line ### - -If you use the i3 window manager or would prefer to change the system's time -zone in terminal you can issue the `timedatectl` command with the option -`set-timezone`. - -For example, to set the system's time zone to Berlin, Germany type in a dom0 -terminal: - - $ sudo timedatectl set-timezone 'Europe/Berlin' - -You can list the available time zones with the option `list-timezones` and show -the current settings of the system clock and time zone with option `status`. - -Example output status of `timedatectl` on a system with time zone set to -Europe/Berlin: - - [user@dom0 ~]$ timedatectl status - Local time: Sun 2018-10-14 06:20:00 CEST - Universal time: Sun 2018-10-14 04:20:00 UTC - RTC time: Sun 2018-10-14 04:20:00 - Time zone: Europe/Berlin (CEST, +0200) - Network time on: no - NTP synchronized: no - RTC in local TZ: no - +This content has moved to [Qubes Forum: Community Guides](https://forum.qubes-os.org/c/guides/14). [Learn more.](https://forum.qubes-os.org/t/announcement-qubes-community-project-has-been-migrated-to-the-forum/20367/) diff --git a/docs/configuration/disk-trim.md b/docs/configuration/disk-trim.md index 5b85a07..deee4c7 100644 --- a/docs/configuration/disk-trim.md +++ b/docs/configuration/disk-trim.md @@ -1,104 +1 @@ - -Disk Trim -========= - -Disk trimming is the procedure by which the operating system informs the underlying storage device of which storage blocks are no longer in use. -It does this by issuing an `ATA_TRIM` command for the block. This is also known as a `discard`. -In this way, the storage device can perform garbage collection of the unused blocks and internally prepare them for reuse. SSDs in general benefit from this, while HDDs do not. - -In a Linux system running on bare metal, this is relatively straight-forward. -When instructed by the operating system, discards are issued by the file-system driver directly to the storage driver and then to the SSD. - -In Qubes, this gets more complex due to virtualization, LUKS, and LVM (and thin pools on R4.0 and up). -If you run `fstrim --all` inside a TemplateVM, in a worst case the `discard` can follow a path like: - - OS -> File-system Driver -> Virtual Storage Driver -> Backend Storage Driver -> LVM Storage Driver -> LUKS Driver -> Physical Storage Driver -> Physical Storage Device - -If discards are not supported at any one of those layers, it will not make it to the underlying physical device. - -There are some security implications to permitting TRIM (read for example [this article](https://asalor.blogspot.com/2011/08/trim-dm-crypt-problems.html)), but in most cases not exploitable. -Conversely, TRIM can improve security against local forensics when using SSDs, because with TRIM enabled deleting data (usually) results in the actual data being erased quickly, rather than remaining in unallocated space indefinitely. -However deletion is not guaranteed, and can fail to happen without warning for a variety of reasons. - - -Configuration ----------- - -In all versions of Qubes, you may want to set up a periodic job in `dom0` to trim the disk. -This can be done with either systemd (weekly only) or cron (daily or weekly). -You should also add this service or cron job to **each VM** you want the trim function to work in. - - * **Systemd** - - From a terminal as a regular user: - - ``` - systemctl enable fstrim.timer - systemctl start fstrim.timer - ``` - - * **Cron** - - This can be done from a terminal as root, by creating a `trim` file in `/etc/cron.daily` (or `/etc/cron.weekly`). - Add the following contents: - - ``` - #!/bin/bash - /sbin/fstrim --all - ``` - And mark it as executable with `chmod 755 /etc/cron.daily/trim`. - -**Note** Although discards can be issued on every delete inside `dom0` by adding the `discard` mount option to `/etc/fstab`, this option can hurt performance so the above procedure is recommended instead. -However, inside App and Template qubes, the `discard` mount option is on by default to notify the LVM thin pool driver that the space is no longer needed and can be zeroed and re-used. - -If you are using Qubes with LVM, you may also want to set `issue_discards = 1` in `/etc/lvm/lvm.conf`. -Setting this option will permit LVM to issue discards to the SSD when logical volumes are shrunk or deleted. -In R4.x, LVM Logical volumes are frequently deleted (every time a disposable VM is shut down, for example) so you may want to set `issue_discards = 1` if using an SSD, but see the article linked in the first section of this page. -However, this is relatively rare in R3.x. - - -LUKS (R4.0) ----------- - -If you have enabled LUKS in dom0, discards will not get passed down to the storage device in R4.0. Note that this procedure is no longer needed in R4.1, as discards are enabled by default. - -To enable TRIM support in dom0 with LUKS you need to: - -1. Get your LUKS device UUID: - - ~~~ - ls /dev/mapper/luks-* - ~~~ - -2. Add entry to `/etc/crypttab` (replace luks-\ with the device name and the \ with UUID alone): - - ~~~ - luks- UUID= none discard - ~~~ - -3. Add `rd.luks.options=discard` to kernel cmdline (follow either GRUB2 or EFI, not both): - * GRUB2: `/etc/default/grub`, `GRUB_CMDLINE_LINUX` line and - Rebuild grub config (`grub2-mkconfig -o /boot/grub2/grub.cfg`), then - Rebuild initrd (`dracut -f`) - * EFI: `/boot/efi/EFI/qubes/xen.cfg`, `kernel=` line(s), then - Rebuild initrd (`dracut -f /boot/efi/EFI/qubes/initramfs-$(uname -r).img $(uname -r)`) - -4. Reboot the system. - -5. To verify if discards are enabled you may use `dmsetup table` (confirm the line for your device mentions "discards") or just run `fstrim -av` (you should see a `/` followed by the number of bytes trimmed). - - -Swap Space ----------- - -By default TRIM is not enabled for swap in both R4.0 and R4.1. -To enable it add the `discard` flag to the options for the swap entry in `/etc/fstab`. -This may or may not actually improve performance. -If you only want the security against local forensics benefit of TRIM, you can use the `discard=once` option instead to only perform the TRIM operation once during at boot. - -To verify that TRIM is enabled, check `dmesg` for what flags were enabled when the swap space was activated. -You should see something like the following: - - Adding 32391164k swap on /dev/mapper/qubes_dom0-swap. Priority:-2 extents:1 across:32391164k SSDscFS - -The `s` indicates that the entire swap device will be trimmed at boot, and `c` indicates that individual pages are trimmed after they are no longer being used. +This content has moved to [Qubes Forum: Community Guides](https://forum.qubes-os.org/c/guides/14). [Learn more.](https://forum.qubes-os.org/t/announcement-qubes-community-project-has-been-migrated-to-the-forum/20367/) diff --git a/docs/configuration/external-audio.md b/docs/configuration/external-audio.md index 6ee7197..deee4c7 100644 --- a/docs/configuration/external-audio.md +++ b/docs/configuration/external-audio.md @@ -1,46 +1 @@ - -Using External Audio Devices -============================ - -Why you want to use external audio devices ------------------------------------------- - -Qubes audio virtualization protocol does not implement latency reporting for security reasons, keeping the protocol as simple as possible. -Also, in a compromise between low latency and low CPU usage, latency may be around 200 ms. -So applications demanding higher audio quality (even Skype) need a better environment. -But Qubes flexibility fully allows that using external audio devices. -These are mostly USB audio cards, but firewire devices also might be used. - -Implementing external audio devices ------------------------------------ - -First you need to identify an user VM dedicated to audio and [assign a device](https://www.qubes-os.org/doc/AssigningDevices) to it. -In the most common case the assigned device is the USB controller to which your USB audio card will be connected. - -### Fedora VMs - -In a terminal of the template from which you user VM depends, install pavucontrol with: - -~~~ -sudo dnf install pavucontrol -~~~ - -Close the template and start or restart your user VM, insert your external audio device, open a terminal and prepare pulseaudio to use it with: - -~~~ -sudo chmod a+rw /dev/snd/* -pactl load-module module-udev-detect -~~~ - -Start the audio application that is going to use the external audio device. - -Launch pavucontrol, for example using "run command in VM" of Qubes Manager and select your external audio card in pavucontrol. -You need to do that only the first time you use a new external audio device, then pulse audio will remember your selection. - -If you detach your external audio device, then want to insert it again (or want to change it with another one), you need to repeat the previous commands in terminal adding another line at the beginning: - -~~~ -pactl unload-module module-udev-detect -sudo chmod a+rw /dev/snd/* -pactl load-module module-udev-detect -~~~ +This content has moved to [Qubes Forum: Community Guides](https://forum.qubes-os.org/c/guides/14). [Learn more.](https://forum.qubes-os.org/t/announcement-qubes-community-project-has-been-migrated-to-the-forum/20367/) diff --git a/docs/configuration/fetchmail.md b/docs/configuration/fetchmail.md index 7be4e26..deee4c7 100644 --- a/docs/configuration/fetchmail.md +++ b/docs/configuration/fetchmail.md @@ -1,98 +1 @@ - -Fetchmail -========= - -Fetchmail is standalone MRA (Mail Retrieval Agent) aka "IMAP/POP3 client". Its sole purpose is to fetch your messages and store it locally or feed to local MTA (Message Transfer Agent). It cannot "read" messages — for that, use a MUA like Thunderbird or [Mutt](https://www.qubes-os.org/doc/mutt/). - -Installation ------------- - -`dnf install fetchmail` - -Configuration -------------- - -Assuming you have more than one account (safe assumption these days), you need to spawn multiple fetchmail instances, one for each IMAP/POP3 server (though one instance can watch over several accounts on one server). The easiest way is to create template systemd unit and start it several times. Fedora does not supply any, so we have to write one anyway. - -**NOTE:** this assumes you use [Postfix](https://www.qubes-os.org/doc/postfix/) or Exim4 as your local MTA. - -In TemplateVM create `/etc/systemd/system/fetchmail@.service`: - -~~~ -[Unit] -Description=Mail Retrieval Agent -After=network.target -Requires=postfix.service - -[Service] -User=user -ExecStart=/bin/fetchmail -f /usr/local/etc/fetchmail/%I.rc -d 60 -i /usr/local/etc/fetchmail/.%I.fetchids --pidfile /usr/local/etc/fetchmail/.%I.pid -RestartSec=1 -~~~ - -Alternatively, in Debian with Exim4: - -~~~ -[Unit] -Description=Mail Retrieval Agent -After=network.target -Requires=exim4.service - -[Service] -User=user -ExecStart=/usr/bin/fetchmail -f /usr/local/etc/fetchmail/%I.rc -d 60 -i /usr/local/etc/fetchmail/.%I.fetchids --pidfile /usr/local/etc/fetchmail/.%I.pid -RestartSec=1 -~~~ - -Then shutdown TemplateVM, start AppVM and create directory `/usr/local/etc/fetchmail`. In it, create one `.rc` file for each instance of fetchmail, ie. `personal1.rc` and `personal2.rc`. Sample configuration file: - -~~~ -set syslog -set no bouncemail -#set daemon 600 - -poll mailserver1.com proto imap - no dns - uidl - tracepolls -user woju pass supersecret - ssl - sslproto "TLS1" - sslcertfile "/etc/pki/ca-trust/extracted/openssl/ca-bundle.trust.crt" - sslcertck - mda "/usr/sbin/sendmail -i -f %F -- user" - fetchall - idle - -# vim: ft=fetchmail -~~~ - -Then `chown -R user:user /usr/local/etc/fetchmail` and `chmod 600 /usr/local/etc/fetchmail/*.rc`. **This is important**, fetchmail will refuse to run with wrong permissions on its rc-file. - -Next, add this to `/rw/config/rc.local`: - -~~~ -#!/bin/sh - -for rc in /usr/local/etc/fetchmail/*.rc; do - instance=${rc%.*} - instance=${instance##*/} - systemctl --no-block start fetchmail@${instance} -done -~~~ - -Make sure the folder '/rw/config/qubes-bind-dirs.d' exists. - -~~~ -sudo mkdir -p /rw/config/qubes-bind-dirs.d -~~~ - -Create the file '/rw/config/qubes-bind-dirs.d/50_user.conf' with root rights. - -Now edit it to append the '/var/spool/mail/' directory to the binds variable. - -~~~ -binds+=( '/var/spool/mail' ) -~~~ - -Now reboot your AppVM and you are done. +This content has moved to [Qubes Forum: Community Guides](https://forum.qubes-os.org/c/guides/14). [Learn more.](https://forum.qubes-os.org/t/announcement-qubes-community-project-has-been-migrated-to-the-forum/20367/) diff --git a/docs/configuration/http-proxy.md b/docs/configuration/http-proxy.md index b8b90ae..deee4c7 100644 --- a/docs/configuration/http-proxy.md +++ b/docs/configuration/http-proxy.md @@ -1,156 +1 @@ -How to run an HTTP filtering proxy -================================================= - -Introduction ------------- - -By default, Qubes uses a special firewall VM that sits between the networking VM and each AppVM. -This VM controls the traffic for AppVMs and can be used to restrict what AppVMs can send or receive. -The traffic rules can be setup using the filtering rules GUI in Qubes VM manager. -The manager translates user-defined setup into iptables rules for the firewall VM's kernel. - -The primary goal of the filtering rule setup in the firewall VM is to allow for the user to protect either from his own mistakes (like accessing an arbitrary website from a browser running in a banking VM) or from the mistakes of websites (like a banking website that loads JS code from a social network operator when the user logs into the bank). - -As the rules in the firewall are IP-based, it has drawbacks. -First, the rules cannot be used if one has to use an HTTP proxy to connect to websites (a common setup on corporate networks). -Second, Qubes resolves DNS names from the firewall rules when the AppVM loads. -This prevents websites that use DNS-based load balancers from working unless the user reloads the firewall rules (which re-resolve the DNS names) whenever the balancer transfers her session to another IP. -Third, the initial setup of the rules is complicated as the firewall drops the connection silently. -As a workaround, one can use a browser's network console to see what is blocked, but this is time-consuming and one can easily miss some important cases like including sites for OCSP SSL certificate verification in the firewall white-list. - -These drawbacks can be mitigated if one replaces iptable-based rules with a filtering HTTP proxy. -The following describes how to setup a tinyproxy-based proxy in either the firewall VM or a custom proxy VM to achieve such filtering. - -**Note** This content only describes setup of an HTTP proxy. -This will handle web browsing using HTTP and HTTPS, but this type of proxy does not support other protocols such as IMAP used in Thunderbird. -For that, you need a fully featured SOCKS proxy such as Squid which is beyond the scope of this article. - -Warning -------- - -Running an HTTP proxy in your firewall VM increases the attack surface against that VM from a compromised AppVM. -Tinyproxy has relatively simple code and a reasonable track record to allow to certain level of trust, but one cannot exclude bugs especially in the case of hostile proxy clients as this is a less tested scenario. -It is not advisable to use the proxy in a shared firewall VM against untrusted AppVMs to black-list some unwanted connections such as advertisement sites. - -A less problematic setup is to white-list possible connections for several trusted and semi-trusted AppVMs within one firewall VM. -Still, for maximum safety, one should consider running a separate ProxyVM for each important AppVM. - -In Qubes R4.0, one no longer creates ProxyVMs as such. However, the same is accomplished by choosing the `provides network` checkbox when creating an AppVM that will be used as a proxy. - -As a counterpoint to this warning, it is important to note that an HTTP proxy decreases the attack surface of AppVMs. -For example, with a proxy the AppVM does not need to make direct DNS connections, so a bug in the kernel or in the browser in that area would not affect the AppVM. -Also, browsers typically avoid many of the latest and greatest HTTP features when connecting through proxies, minimizing exposure of new and unproven networking code. - - -Setup ------ - -1. After reading through the Warning section above, determine if you want to proceed with the following steps in either your default `sys-firewall` VM or in a newly created proxy VM. - If you decide to create a separate proxy VM, - * In R4.0, create a new AppVM with the `provides network` checkbox set. - * In R3.2, create a new ProxyVM. - - Then, proceed with the following. - -2. Copy this [archive] (**Note:** not reviewed, use at own risk!) with the proxy control script, default tinyproxy config, and a sample filtering file into the proxy VM and unpack it in the `/rw/config` folder there as root: - - cd /rw/config - sudo tar xzf .../proxy.tar.xz - -3. If necessary, adjust `/rw/config/tinyproxy/config` according to the man page for `tinyproxy.conf`. - The included config file refuses the connection unless the host is white-listed in the filtering file, so this can be altered if one prefers to black-list connections. - One may also specify upstream proxies here. - The file is a template file and the control script will replace `{name}` constructs in the file with actual parameters. - In general, lines with `{}` should be preserved as is. - -4. For each AppVM that one wants to run through the proxy, create a corresponding filtering file in the `/rw/config/tinyproxy` directory. - With the default config, the filtering file should contain regular expressions to match white-listed hosts with one regular expression per line. - See the man page for tinyproxy.conf for details. - The file should be named: - - name.ip-address-of-app-vm - - The name before the dot is arbitrary. - For convenience, one can use an AppVM name here, but this is not required. - - It is important to get the ip address part right, as this is what the control script uses to determine to which AppVM it will apply the proxy rules. - If you have created a separate proxy VM, change the `NetVM` of each AppVM that will be using it to the proxy VM. - That can be done in Qubes VM manager in the VM settings dialog under the Basic tab. - Next, see the Networking settings on the same tab to check the IP address of an AppVM. - - The attached archive includes a `social.10.137.2.13` file with rules for an AppVM allowing connections to Google, Facebook, Linkedin, Livejournal, Youtube, and few other other sites. - One can use it as an example after changing the IP address accordingly. - - When editing the rules, remember to include a `$` at the end of the host name, and to prefix each dot in the host name with a backslash (like `\.`). - This way, the pattern matches the whole host and not just a prefix, and the dot is not interpreted as an instruction to match an arbitrary character according to regular expression syntax. - -5. Check that the `proxyctl.py` script can properly recognize the rule files. - For that, run: - - sudo /rw/config/tinyproxy/proxyctl.py show - - For each rule file it should print the name, ip address, and network interface of the running AppVMs. - It will also display the id of the tinyproxy process that proxies that AppVM. - Each pid will be `--` because we have no running proxies yet. - -6. Now, start the AppVM for which you created a rule file, and then run: - - sudo /rw/config/tinyproxy/proxyctl.py update - - The update command starts proxy processes and adjusts the iptable rules to allow for proxy traffic for each running AppVM from the filtering files list. - For each stopped AppVM, the proxy is killed. - - Check that proxy is started and the `pid` field of the show command is a number: - - sudo /rw/config/tinyproxy/proxyctl.py show - -7. Run the browser in the active AppVM and configure it to use the proxy on port 8100 of the proxy VM interface's IP address. - In Qubes VM manager, the IP address is displayed in the Gateway field in the Settings dialog for the AppVM. - - In Firefox, go to the Preferences dialog, select Advanced->Network, and click Settings for the Connection section. - In the Connection Settings dialog, select Manual proxy configuration. For the HTTP Proxy field use the IP address of the AppVM's gateway. - Enter 8100 as the port, and select the checkbox "Use this proxy server for all protocols". - - Go to a test web site. - The browser should either load it (if it was white-listed in the filtering file), or show a page generated by tinyproxy that the page was filtered out. - - In the proxy VM, see the `/run/tinyproxy//log` file. - For each filtered out website it contains an entry, and one can adjust the filtering file to include the corresponding host. - After changing the file, run either: - - sudo /rw/config/tinyproxy/proxyctl.py restart - - to restart the proxy with an updated rules file only for the given VM, or - - sudo /rw/config/tinyproxy/proxyctl.py kill-all-and-restart - - to restart all proxy processes. - -8. To make sure that the proxy is started automatically when the AppVM starts, change `/rw/config/qubes-firewall-user-script` to include the following line: - - /rw/config/tinyproxy/proxyctl.py update - - If the file does not exist, create it so it looks like this: - - #!/bin/sh - /rw/config/tinyproxy/proxyctl.py update - - Make sure that the script is owned by root and executable: - - sudo chown root:root /rw/config/qubes-firewall-user-script - sudo chmod 755 /rw/config/qubes-firewall-user-script - -9. In Qubes VM manager, adjust the Firewall rules for each AppVM using a proxy. - In a typical case, when only the HTTP proxy should be permitted for outside connections: - * In R4.0, select "Limit outgoing Internet connections to..." and make sure the address list is empty. - * In R3.2, select "Deny network access except...", make sure the address list is empty, and then unselect the "Allow ICMP," "DNS", and "Update proxy" checkboxes. - - There is no need to add any special entries for the proxy in the GUI as `proxyctl.py` adds rules for the proxy traffic itself. - --------------------------------------------------------------------------------- - -This guide was initially written by Igor Bukanov in a [message] to the `qubes-devel` [mailing list]. - -[archive]: https://groups.google.com/group/qubes-devel/attach/39c95d63fccca12b/proxy.tar.gz?part=0.1 -[message]: https://groups.google.com/d/msg/qubes-devel/UlK8P27UtD4/K6HM_GNdyTkJ -[mailing list]: https://www.qubes-os.org/mailing-lists/ +This content has moved to [Qubes Forum: Community Guides](https://forum.qubes-os.org/c/guides/14). [Learn more.](https://forum.qubes-os.org/t/announcement-qubes-community-project-has-been-migrated-to-the-forum/20367/) diff --git a/docs/configuration/install-nvidia-driver.md b/docs/configuration/install-nvidia-driver.md index 7e14462..deee4c7 100644 --- a/docs/configuration/install-nvidia-driver.md +++ b/docs/configuration/install-nvidia-driver.md @@ -1,112 +1 @@ - -# Nvidia proprietary driver installation - -You can use rpm packages from rpmfusion, or you can build the driver yourself. - -## Word of Caution - -Proprietary (NVIDIA/AMD) drivers are known to be sometimes highly problematic, or completely unsupported. -Radeon driver support is prebaked in the Qubes kernel (v4.4.14-11) but only versions 4000-9000 give or take. -Support for newer cards is limited until AMDGPU support in the 4.5+ kernel, which isn't released yet for Qubes. - -Built in Intel graphics, Radeon graphics (between that 4000-9000 range), and perhaps some prebaked NVIDIA card support that I don't know about. Those are your best bet for great Qubes support. - -If you do happen to get proprietary drivers working on your Qubes system (via installing them), please take the time to go to the -[Hardware Compatibility List (HCL)](https://www.qubes-os.org/doc/hcl/#generating-and-submitting-new-reports ) -Add your computer, graphics card, and installation steps you did to get everything working. - -Before continuing, you may wish to try the `kernel-latest` package from the `current` repository. This kernel may better support your card and if so, you would not have to rely on proprietary drivers. This can be installed from dom0 with: -~~~ -sudo qubes-dom0-update kernel-latest -~~~ - -## 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 - -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: - -~~~ -yumdownloader --resolve xorg-x11-drv-nvidia -yumdownloader --source nvidia-kmod -~~~ - -### 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 the package: - -~~~ -yum install kernel-devel rpm-build kmodtool -rpmbuild --nodeps -D "kernels `uname -r`" --rebuild nvidia-kmod-260.19.36-1.fc13.3.src.rpm -~~~ - -In the above command, replace `uname -r` with kernel version from your Qubes dom0. If everything went right, you have now complete packages with nvidia drivers for the Qubes system. Transfer them to dom0 (e.g. using a USB stick) and install (using standard "yum install /path/to/file"). - -Then you need to disable nouveau (normally it is done by install scripts from nvidia package, but unfortunately it isn't compatible with Qubes...): - -Edit /etc/default/grub: - -~~~ -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 -~~~ - -Reboot. - - - -## Manual installation - -This process is quite complicated: First - download the source from nvidia.com site. Here "NVIDIA-Linux-x86\_64-525.116.04" is used. Copy it to dom0. Every next step is done in dom0. - -See [this page](https://www.qubes-os.org/doc/copy-to-dom0/) for instructions on how to transfer files to Dom0 (where there is normally no networking). - -**WARNING**: Nvidia doesn't sign their files. To make it worse, you are forced to download them over a plaintext connection. This means there are virtually dozens of possibilities for somebody to modify this file and provide you with a malicious/backdoored file. You should realize that installing untrusted files into your Dom0 is a bad idea. Perhaps it might be a better idea to just get a new laptop with integrated Intel GPU? You have been warned. - -### Userspace components - -Install libraries, Xorg driver, configuration utilities. This can by done by nvidia-installer: - -~~~ -./NVIDIA-Linux-x86_64-525.116.04.run --ui=none --no-x-check --keep --extract -~~~ - -### Kernel module - -You will need: - -- nvidia kernel module sources (left from previous step) -- kernel-devel package installed -- gcc, make, etc - -This installation must be done manually, because nvidia-installer refuses to install it on Xen kernel. - -To build the kernel module, enter *NVIDIA-Linux-x86\_64-525.116.04/kernel* directory and execute: - -~~~ -make IGNORE_XEN_PRESENCE=1 CC="gcc -DNV_VMAP_4_PRESENT -DNV_SIGNAL_STRUCT_RLIM" -mv nvidia.ko /lib/modules/$(uname -r)/kernel/drivers/video/ -depmod -a -~~~ - -### Disable nouveau - -Add `rd.driver.blacklist=nouveau` option in `/etc/default/grub` (at the end of line `GRUB_CMDLINE_LINUX`). - -Install the new grub config with `grub2-mkconfig -o /boot/efi/EFI/qubes/grub.cfg`. - -### Reboot - -Reboot to verify all this works. You can ensure the module is loaded by running `lsmod | grep nvidia` which should display a single output line, and `lsmod | grep nouveau` should have no output. - -## Troubleshooting lack of video output during installation - -The GRUB menu may show 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. See the [Nvidia Troubleshooting](https://www.qubes-os.org/doc/nvidia-troubleshooting/#lack-of-video-output-during-nvidia-driver-installation) guide for troubleshooting steps. - +This content has moved to [Qubes Forum: Community Guides](https://forum.qubes-os.org/c/guides/14). [Learn more.](https://forum.qubes-os.org/t/announcement-qubes-community-project-has-been-migrated-to-the-forum/20367/) diff --git a/docs/configuration/multiboot.md b/docs/configuration/multiboot.md index 8de687f..deee4c7 100644 --- a/docs/configuration/multiboot.md +++ b/docs/configuration/multiboot.md @@ -1,209 +1 @@ - -Multibooting Qubes -======================================== - -Introduction ---------------------- - -You should think carefully before dual booting Qubes on your box. -Read the [guidelines](https://www.qubes-os.org/doc/security-guidelines) carefully. - -One problem is that when you dual or multiboot, even if you are using -encryption on your Qubes installation, /boot is still unprotected and -could be maliciously modified by the other OS, possibly leading to Qubes -itself being maliciously modified. - -The other problem is firmware security - for example the other system -could infect the BIOS firmware, which might enable compromise or spying on -the Qubes system. - -You can use [Anti Evil Maid](https://www.qubes-os.org/doc/anti-evil-maid/), which would inform -you if /boot had been modified, but it cannot prevent or fix the problem. - -If you have considered these issues, tried out the live system and want to -install Qubes alongside your existing OS, these notes should help. - -They assume that you are installing Qubes on a PC where you already have -another OS installed. - -The first thing to do is STOP. -Before you do anything else back up all your data. -If possible do a full system backup. -Back up the MBR. -Back up /boot. -If you are really paranoid clone your disc. - -Make sure you have install discs on hand for the existing operating system. - -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. - -The general approach is: - -* Enable legacy boot mode -* Ensure current OS boots in legacy mode -* Install Qubes -* Manually add boot stanzas to /etc/grub.d/40_custom -* Update grub - - - -Windows ----------------------- - -If you change boot mode to legacy boot almost certainly the Windows -installation will not boot. -You will either have to format the disk and reinitialise it, and then reinstall -Windows in legacy boot mode, or use a utility like Easy Recovery Essentials -which will change the existing installation to be bootable in both -UEFI/GPT and BIOS/MBR mode in-place, without losing any data. - -At this stage you can install Qubes. - -As noted above the default configuration will not add an entry for Windows to -the grub menu, so you will need to add one. - -1. Boot into Qubes - -2. Identify the Windows system partition that has /bootmgr: - - In blkid output, the system partition is the one with LABEL='SYSTEM - RESERVED' or LABEL='SYSTEM' and is only about 100 to 200 MB in size - -3. Add this stanza to /etc/grub.d/40_custom: - -~~~ -menuentry "Windows" { - insmod part_msdos - insmod ntldr - insmod ntfs - ntldr (hd1,X)/bootmgr -} -~~~ - -(Change `X` to reflect the relevant system partition.) - -Then update the grub config: - -~~~ -sudo grub2-mkconfig -o /boot/grub2/grub.cfg -~~~ - -There is no need to reinstall grub itself. - -If the above stanza does not work, you may try this one (at your own risk!) -instead: - -~~~ -menuentry "Windows" { - insmod part_msdos - insmod ntfs - set root='(hd0,msdosX)' - chainloader +1 -} -~~~ - -(Change `X` to reflect the relevant system partition.) - - -Linux ----------------------- - -If you have had to change to legacy boot mode then you may have to reinstall grub in -the existing OS. (Make sure that you use grub rather than a grub-efi version). - -Micah Lee -[suggests](https://micahflee.com/2014/04/dual-booting-qubes-and-ubuntu-with-encrypted-disks/) -installing grub to a partition, and then installing Qubes with grub -installed in MBR. - -If you take this approach then you need to add to /etc/grub.d/40_custom in Qubes -dom0: - -~~~ -menuentry "Other Linux" { -set root=(hd1,X) -chainloader +1 -} -(Change X to reflect the relevant partition where grub is installed.) -~~~ - -Then update the grub config: - -~~~ -sudo grub2-mkconfig -o /boot/grub2/grub.cfg -~~~ - -There is no need to reinstall grub itself. - - -Existing /boot partition, grub installed in MBR ----------------------- - -Most distros will have already installed grub to the MBR. - -It is possible to use the *same* /boot for both OS. -To do this, do **NOT** choose the automatic configuration option when installing -Qubes. -Select 'custom' layout, and assign the existing /boot partition as /boot. -Deselect the 'Format' option. -Then continue with the installation. -This will install the qubes boot files in /boot *alongside* the existing files, -but overwrite the grub.cfg file in /boot/grub2. - -If the other distro uses legacy grub you can simply copy the relevant sections -from /boot/grub/grub.cfg into /etc/grub.d/40_custom. - -If the other distro uses grub2 then copy the relevant sections -from the backup you made into /etc/grub.d/40_custom. - -Then update the grub config: - -~~~ -sudo grub2-mkconfig -o /boot/grub2/grub.cfg -~~~ - - - -Troubleshooting ----------------------- - -If you install Qubes without making any backups beforehand, don't worry. -If you didn't overwrite the original partitions, then it is usually -possible to recover your old systems relatively easily, as described above. - -If you decided to use a shared /boot and *don't* have backups of your previous -grub config, it is quite easy to fix this. -This example may help. - -* Boot into Qubes -* Back up (at a minimum) /boot/grub2 -* Identify the partition containing the other OS -* Then mount the other OS and chroot in to it: - -~~~ -sudo mount /dev/sdX /mnt -sudo mount --bind /dev/sdY /mnt/boot -sudo mount --bind /dev /mnt/dev -sudo mount --bind /dev/pts /mnt/dev/pts -sudo mount --bind /proc /mnt/proc -sudo mount --bind /sys /mnt/sys - -sudo chroot /mnt -~~~ - -* Update the grub config: - -~~~ -sudo grub2-mkconfig -o /boot/grub2/grub.cfg.new -~~~ - -* Exit out the chroot, and reverse the mounts -* Copy the relevant sections from /boot/grub2/grub.cfg.new in to -/etc/grub.d/40_custom -* Update the grub config: - -~~~ -sudo grub2-mkconfig -o /boot/grub2/grub.cfg -~~~ +This content has moved to [Qubes Forum: Community Guides](https://forum.qubes-os.org/c/guides/14). [Learn more.](https://forum.qubes-os.org/t/announcement-qubes-community-project-has-been-migrated-to-the-forum/20367/) diff --git a/docs/configuration/multimedia.md b/docs/configuration/multimedia.md index 5be2511..deee4c7 100644 --- a/docs/configuration/multimedia.md +++ b/docs/configuration/multimedia.md @@ -1,231 +1 @@ - -How to Make a Multimedia TemplateVM -=================================== - -Note: This Howto has been written and was tested under Qubes 4rc4 - -You can consolidate most of your media streaming tasks into one "multimedia" App-VM. This howto explains how to create a multimedia template which can be used to play multimedia content. -This includes: - -- Spotify -- Amazon Prime -- Netflix -- DVDs - -Installation ------------- - -Start by cloning the default debian template in dom0. -Hint: -t-multimedia is just the template VM where we will install all packages. -In the last step we will create an AppVM from this template. - -`qvm-clone debian-10 t-multimedia` - -Launch a Terminal in the new template VM: - -`qvm-run --auto t-multimedia gnome-terminal` - -Important: -Enter all the following commands in the terminal of the template VM. -Become the root user to run all following command without the need to use sudo in the multimedia template VM. - -`sudo -i` - -This howto assumes that you have xclip available in the AppVM where you download the Repository Signing keys. -xclip will be used to paste the content of the clipboard to a file. -You can install xclip via: - -`apt-get install xclip` on Debian -`dnf install xclip` on Fedora - -You can of course install xclip just into the AppVM where you download the signing keys to have it available for this howto and it will be deleted if you reboot the AppVM. To have xclip available also after a reboot you need to install it in the Template VM on which your Internet AppVM is based (make sure to reboot the AppVM after you've installed any package in its template) - -Installation of Spotify ------------------------ - -Import GPG-Key for spotify -As the template VM can't connect to internet you need to get the public key file from another AppVM and copy it to the template VM. The easiest way is to use the Qubes Clipboard to copy the keys from the AppVM where you get the key to the Template VM. - -In an AppVM which has Internet access: -- Open -- Copy content of page to the Clipboard (Ctrl+A and Ctrl+C) -- open a Terminal in this AppVM and copy the content of the clipboard to a file - `xclip -o > spotify.pubkey` - -Copy the public signing key over to the multimedia template VM -- copy the file via `qvm-copy-to-vm t-multimedia spotify.pubkey` -- or create a new file on the Template VM and copy the content of the clipboard (the public key) - Copy content of page to the Qubes Clipboard (Ctrl+C and then Shift+Ctrl+C) - Switch to the gnome terminal in the Multimedia Template VM - `nano spotify.pubkey` - Paste the content from the Qubes Clipboard into nano (Shift+Ctrl+V and then Paste) - Save the file (Ctrl+O Ctrl+X) - -Check the signature of the signing key (in the multimedia Template VM). -Hint: depending on your installed version of GnuPG the command to show a public might slightly be different. -See [this StackExchange question](https://unix.stackexchange.com/questions/391344/gnupg-command-to-show-key-info-from-file) for more information. -If this command doesn't show a fingerprint choose one of the other commands mentioned in the above link. - -`gpg --keyid-format long --with-fingerprint spotify.pubkey` - -This should look like: - - [user@t-multimedia ~]$ gpg --keyid-format long --with-fingerprint spotify.pubkey - - gpg: WARNING: no command supplied. Trying to guess what you mean ... - pub rsa4096/D1742AD60D811D58 2020-09-08 [SC] [expires: 2021-12-02] - Key fingerprint = 8FD3 D9A8 D380 0305 A9FF F259 D174 2AD6 0D81 1D58 - uid Spotify Public Repository Signing Key - - -You can (and should) lookup the fingerprint on at least one (or more) keyservers as the above information might be outdated. - - - -Add the public key to the repository keyring -`apt-key add spotify.pubkey` - -Add the Spotify repository to your list of package sources: - -`echo deb http://repository.spotify.com stable non-free > /etc/apt/sources.list.d/spotify.list` - -Update the list of all known packages - -`apt-get update` - -Install Spotify -`apt-get install -y spotify-client` - -Create a spotify desktop-entry - -`cp -p /usr/share/spotify/spotify.desktop /usr/share/applications/` - -`cp /usr/share/spotify/icons/spotify-linux-16.png /usr/share/icons/hicolor/16x16/apps/spotify.png` - - -Installation of VLC -------------------- - -To play DVDs you can install VLC with the needed Codecs - -Download the public key which signs the VLC package repositories -In an AppVM which has Internet access: -- Open -- Repeat all steps to save the public signing key on the AppVM (see above / Spotify example) - `xclip -o > videolan.pubkey` - -Copy the public signing key over to the multimedia template VM -- copy the file via `qvm-copy-to-vm t-multimedia videolan.pubkey` -- or create a new file on the Template VM and copy the content of the clipboard (the public key) - Copy content of page to the Qubes Clipboard (Ctrl+C and then Shift+Ctrl+C) - Switch to the gnome terminal in the Multimedia Template VM - `nano videolan.pubkey` - Paste the content from the Qubes Clipboard into nano (Shift+Ctrl+V and then Paste) - Save the file (Ctrl+O Ctrl+X) - -Check the signature of the signing key - -`gpg --keyid-format long --with-fingerprint videolan.pubkey` - -This should look like: - - [user@t-multimedia ~]$ gpg --keyid-format long --with-fingerprint videolan.pubkey - - gpg: WARNING: no command supplied. Trying to guess what you mean ... - pub rsa2048/6BCA5E4DB84288D9 2013-08-27 [SC] - Key fingerprint = 8F08 45FE 77B1 6294 429A 7934 6BCA 5E4D B842 88D9 - uid VideoLAN APT Signing Key - sub rsa2048/ED1466D0288D4A2C 2013-08-27 [E] - -You can (and should) lookup the fingerprint on at least one (or more) keyservers as the above information might be outdated. - - - -Add the public key to the repository keyring -`apt-key add videolan.pubkey` - -Add the new VLC package repositories to your list of sources - -`echo "deb http://download.videolan.org/pub/debian/stable/ /" > /etc/apt/sources.list.d/vlc.list` - -`echo "deb-src http://download.videolan.org/pub/debian/stable/ /" >> /etc/apt/sources.list.d/vlc.list` - -Update package repositories - -`apt-get update` - -Install libdvdcss and VLC - -`apt-get install -y libdvdcss2 vlc` - - -Installation Google Chrome --------------------------- - -To play Videos with Netflix, Amazon Prime & Co using Chrome is a good option as it has all needed codecs included. -Hint: Using Chromium will not work for some reasons. - -Download the public key which signs the Google package repositories -In an AppVM which has Internet access: -- Open -- Repeat all steps to save the public signing key on the AppVM (see above / Spotify example) - `xclip -o > google.pubkey` - -Copy the public signing key over to the multimedia template VM -- copy the file via `qvm-copy-to-vm t-multimedia google.pubkey` -- or create a new file on the Template VM and copy the content of the clipboard (the public key) - Copy content of page to the Qubes Clipboard (Ctrl+C and then Shift+Ctrl+C) - Switch to the gnome terminal in the Multimedia Template VM - `nano google.pubkey` - Paste the content from the Qubes Clipboard into nano (Shift+Ctrl+V and then Paste) - Save the file (Ctrl+O Ctrl+X) - -Check the signature of the signing key (still in the AppVM where you downloaded the key) - -`gpg --keyid-format long --with-fingerprint google.pubkey` - -This should look like: - - [user@t-multimedia ~]$ gpg --keyid-format long --with-fingerprint videolan.pubkey - - gpg: WARNING: no command supplied. Trying to guess what you mean ... - pub rsa4096/7721F63BD38B4796 2016-04-12 [SC] - Key fingerprint = EB4C 1BFD 4F04 2F6D DDCC EC91 7721 F63B D38B 4796 - uid Google Inc. (Linux Packages Signing Authority) - sub rsa4096/1397BC53640DB551 2016-04-12 [S] [expired: 2019-04-12] - sub rsa4096/6494C6D6997C215E 2017-01-24 [S] [expired: 2020-01-24] - sub rsa4096/78BD65473CB3BD13 2019-07-22 [S] [expires: 2022-07-21] - -You can (and should) lookup the fingerprint on at least one (or more) keyservers as the above information might be outdated. - - - -or - - - -Add the public key to the repository keyring - -`apt-key add google.pubkey` - -Add the Google package repositories to your list of sources - -`echo "deb http://dl.google.com/linux/chrome/deb/ stable main"> /etc/apt/sources.list.d/google.list` - -Update package repositories - -`apt-get update` - -Install Chrome - -`apt-get install google-chrome-stable` - - -Create a Multimedia AppVM -------------------------- - -The last step is to create a multimedia AppVM (named "my-multimedia" here) based on the new multimedia template. - -`qvm-create --template t-multimedia --label orange my-multimedia` - +This content has moved to [Qubes Forum: Community Guides](https://forum.qubes-os.org/c/guides/14). [Learn more.](https://forum.qubes-os.org/t/announcement-qubes-community-project-has-been-migrated-to-the-forum/20367/) diff --git a/docs/configuration/mutt.md b/docs/configuration/mutt.md index 7aedb4c..deee4c7 100644 --- a/docs/configuration/mutt.md +++ b/docs/configuration/mutt.md @@ -1,217 +1 @@ - -Mutt -==== - -Mutt is a fast, standards-compliant, efficient MUA (Mail User Agent). In some areas it works better than Thunderbird+Enigmail, and is certainly faster and more responsive. - -Mutt lacks true MTA (Message Transfer Agent aka "SMTP client") and MRA (Mail -Retrieval Agent aka "IMAP/POP3 client"), thus there are some provisions -built-in. In principle it is only mail reader and composer. You may install -true MTA such as [Postfix](https://www.qubes-os.org/doc/postfix/) or Exim and MRA such as -[Fetchmail](https://www.qubes-os.org/doc/fetchmail/). Alternatively you can synchronize your mailbox -using [OfflineIMAP](https://github.com/OfflineIMAP/offlineimap) and just stick -to integrated SMTP support. You can even use integrated IMAP client, but it is -not very convenient. - -Installation ------------- - -`dnf install mutt cyrus-sasl-plain` - -`cyrus-sasl-plain` package is necessary for SMTP authentication to work. - -Configuration -------------- - -Mutt generally works out of the box. This configuration guide discusses only Qubes-specific setup. In this example we will have one TemplateVM and several AppVMs. It also takes advantage of [SplitGPG](https://www.qubes-os.org/doc/split-gpg/), which is assumed to be already working. - -**NOTE:** this requires `qubes-gpg-split >= 2.0.9`. 2.0.8 and earlier contains bug which causes this setup to hang in specific situations and does not allow to list keys. - -First, paste this to `/etc/Muttrc.local` in TemplateVM: - -~~~ -# specify your key or override in ~/.mutt/muttrc in AppVM -set pgp_sign_as="0xDEADBEEF" - -set pgp_use_gpg_agent = no - -# this needs qubes-gpg-split >= 2.0.8; 2.0.7 end earlier has had a deadlock on this -set pgp_decode_command="qubes-gpg-client-wrapper --status-fd=2 --batch %f" -#set pgp_decode_command="gpg --status-fd=2 %?p?--passphrase-fd=0? --no-verbose --quiet --batch --output - %f" - -set pgp_decrypt_command="$pgp_decode_command" - -set pgp_verify_command="qubes-gpg-client-wrapper --status-fd=2 --no-verbose --quiet --batch --output - --verify %s %f" - -set pgp_sign_command="qubes-gpg-client-wrapper --batch --armor --detach-sign --textmode %?a?-u %a? %f" -set pgp_clearsign_command="qubes-gpg-client-wrapper --batch --armor --textmode --clearsign %?a?-u %a? %f" - -# I found no option to add Charset armor header when it is UTF-8, since this is -# default (as specified in RFC4880). This is needed to workaround bug in -# Enigmail, which ignores RFC and without this header Thunderbird interprets -# plaintext as us-ascii. See https://sourceforge.net/p/enigmail/bugs/38/. - -### also note you must specify absolute path of pgpewrap when using debian -### e.g. /usr/lib/mutt/pgpewrap - -set pgp_encrypt_only_command="pgpewrap qubes-gpg-client-wrapper --batch --textmode --armor --always-trust %?a?--encrypt-to %a? --encrypt -- -r %r -- %f | sed -e '2iCharset: UTF-8'" -set pgp_encrypt_sign_command="pgpewrap qubes-gpg-client-wrapper --batch --textmode --armor --always-trust %?a?--encrypt-to %a? --encrypt --sign %?a?-u %a? -- -r %r -- %f | sed -e '2iCharset: UTF-8'" - -# we need to import both into vault and locally wrt $pgp_verify_command -set pgp_import_command="qubes-gpg-import-key %f; gpg --no-verbose --import %f" - -# those are unsupported by split-gpg -set pgp_export_command="gpg --no-verbose --export --armor %r" -set pgp_verify_key_command="gpg --no-verbose --batch --fingerprint --check-sigs %r" - -# read in the public key ring -set pgp_list_pubring_command="qubes-gpg-client-wrapper --no-verbose --batch --quiet --with-colons --list-keys %r" - -# read in the secret key ring -set pgp_list_secring_command="qubes-gpg-client-wrapper --no-verbose --batch --quiet --with-colons --list-secret-keys %r" - -# this set the number of seconds to keep in memory the passpharse used to encrypt/sign -# the more the less secure it will be -set pgp_timeout=600 - -# it's a regexp used against the GPG output: if it matches some line of the output -# then mutt considers the message a good signed one (ignoring the GPG exit code) -#set pgp_good_sign="^gpg: Good signature from" -set pgp_good_sign="^\\[GNUPG:\\] GOODSIG" - -# mutt uses by default PGP/GPG to sign/encrypt messages -# if you want to use S-mime instead set the smime_is_default variable to yes - -# automatically sign all outcoming messages -set crypt_autosign=yes -# sign only replies to signed messages -#set crypt_replysign - -# automatically encrypt outcoming messages -#set crypt_autoencrypt=yes -# encrypt only replies to signed messages -set crypt_replyencrypt=yes -# encrypt and sign replies to encrypted messages -set crypt_replysignencrypted=yes - -# automatically verify the sign of a message when opened -set crypt_verify_sig=yes - -# disable use of gpgme, which interferes with Split-GPG -# and defaults to 'yes' on Debian 9 and higher -set crypt_use_gpgme=no - -send-hook "~A" set pgp_autoinline=no crypt_autoencrypt=no -send-hook "~t @invisiblethingslab\.com" set crypt_autoencrypt=yes - -# vim:ft=muttrc -~~~ - -Then shutdown your TemplateVM. Next open your AppVM, create file `/home/user/.mutt/muttrc` and adjust for your needs: - -~~~ -# -# accounts -# -set from = "Wojciech Zygmunt Porczyk " -alternates '^woju@invisiblethingslab\.com$' -alternates '^wojciech@porczyk\.eu$' - -# -# crypto -# -set pgp_sign_as = "0xDEADBEEF" -send-hook "~t @my\.family\.com" set crypt_autoencrypt=no - -# -# lists -# - -# google groups -lists .*@googlegroups\.com - -subscribe (qubes-(users|devel)|othergroup)@googlegroups\.com -fcc-save-hook qubes-users@googlegroups\.com =list/qubes-users/ -fcc-save-hook qubes-devel@googlegroups\.com =list/qubes-devel/ -fcc-save-hook othergroup@googlegroups\.com =list/othergroup/ -~~~ - -You may also create `/home/user/.signature`: - -~~~ -regards, -Wojciech Porczyk -~~~ - -Some additional useful settings -------------------------------- - -In `muttrc`: - - ###qubes integration stuff - - #open links in a dispvm using urlview - #see below for sample .urlview - macro pager \cb 'urlview' 'Follow links with urlview' - - #override default mailcap MIME settings with qvm-open-in-dvm calls - #see sample .mailcap below - set mailcap_path=~/.mailcap - - bind attach view-mailcap - -Debian-specific options: - - #use debian mutt-patched package for mailbox sidebar hack - set sidebar_width = 30 - set sidebar_visible = no - set sidebar_delim='|' - - #show/hide sidebar - macro index S 'toggle sidebar_visible' - macro pager S 'toggle sidebar_visible' - - #navigate the sidebar folders - bind index CP sidebar-prev - bind index CN sidebar-next - bind index CO sidebar-open - bind pager CP sidebar-prev - bind pager CN sidebar-next - - -In `.urlview`: - - ### TODO: this doesn't work with encrypted emails -- - ### urlview can't find the links - ### - COMMAND qvm-open-in-dvm %s - - -In `.mailcap`: - - ### TODO: override most/all default mailcap settings to prevent - ### opening in muttvm - ### is there a way to do this polymorphically? i.e. not - ### listing every damn mimetype by hand - ### - ### also would be convenient to use mailcap's TEST feature to - ### show some html in mutt pager (e.g. with w3m, links or html2text), - ### else open others in dispvm - - # MS Word documents - application/msword; qvm-open-in-dvm %s - application/vnd.oasis.opendocument.spreadsheet; qvm-open-in-dvm %s - application/vnd.oasis.opendocument.text; qvm-open-in-dvm %s - - # Images - image/jpg; qvm-open-in-dvm %s - image/jpeg; qvm-open-in-dvm %s - image/png; qvm-open-in-dvm %s - image/gif; qvm-open-in-dvm %s - - # PDFs - application/pdf; qvm-open-in-dvm %s - - # HTML - text/html; w3m -T text/html '%s' | cat --squeeze-blank; nametemplate=%s.html; copiousoutput - text/html; qvm-open-in-dvm %s +This content has moved to [Qubes Forum: Community Guides](https://forum.qubes-os.org/c/guides/14). [Learn more.](https://forum.qubes-os.org/t/announcement-qubes-community-project-has-been-migrated-to-the-forum/20367/) diff --git a/docs/configuration/network-bridge-support.md b/docs/configuration/network-bridge-support.md index 71c374d..deee4c7 100644 --- a/docs/configuration/network-bridge-support.md +++ b/docs/configuration/network-bridge-support.md @@ -1,137 +1 @@ - -Network Bridge Support (EXPERIMENTAL and UNSUPPORTED) -===================================================== - -The Qubes development team does not support bridging the network interfaces found in NetVM and don't plan to support it at all. Several reasons for that: - -- Using a bridged VM is almost only necessary for developers testing or working on OSI layer 2 or layer 3 tools (MAC or routing protocols). If not for testing, such tools are almost only used directly on routers ...). -- Most of these tools can be anyway used directly inside the NetVM, which has direct access to the network card. -- It is also possible to use a secondary network card plugged into a specific development VM. -- Such a setup could break security features of Qubes such as AppVM firewalling. - -Now if you really want to work with OSI layer2 / layer 3 tools, that you don't have a secondary network card, or that you want to completely expose services of a given AppVM (at your own risk), a bridged setup may help you. - -Qubes manager patch (Qubes R2B2) --------------------------------- - -The following patches can be applied to the Qubes Manager GUI in order to add an option to easily bridge a VM. Use it at your own risk. If the patch breaks the Qubes Manager, you can try to restore the Qubes packages: - -~~~ -# qubes-dom-update qubes-core-dom0 qubes-manager -# yum reinstall qubes-core-dom0 -# yum reinstall qubes-manager -~~~ - -First, retrieve the attachment of this Wifi article in dom0. Then apply the three patches the following way after installing the patch tool : - -~~~ -# qubes-dom0-update patch -# patch /usr/lib64/python2.7/site-package/qubes/qubes.py < qubes.py-bridge.diff -# patch /usr/lib64/python2.7/site-package/qubesmanager/settings.py < settings.py-bridge.diff -# patch /usr/lib64/python2.7/site-package/qubesmanager/ui_settingsdlg.py < ui_settingsdlg.py-bridge.diff -~~~ - -Finally restart the qubes manager GUI. - -An option is available in the AppVM Settings to enable setting the NetVM in bridge mode. For a bridged AppVM, you should then select a NetVM instead of a FirewallVM/ ProxyVM, enable the Bridge option, and restart your AppVM. - -NetVM patch (Qubes R2B2) ------------------------- - -You need to modify manually the NetVM iptable script inside the NetVM. The reason is that by default the NetVM only accepts traffic coming from network interfaces called vif\* (in our case, we will use an additional interface called bridge0. The second reason is that all traffic is NATed by default. In our case, we want to forward traffic from the bridge interface without modifying it, while NATing traffic coming from vif\* interfaces. - -Modify manually the Template you use for your NetVM (not the NetVM itself). This is by default fedora-x86\_64. Edit the file /etc/sysconfig/iptables. You need to modify two parts of the file. - -- Starting from the line -A POSTROUTING -j MASQUERADE that you need to comment : - - ~~~ - # Bridge support - # Comment the following line - #-A POSTROUTING -j MASQUERADE - # Ensure packets coming from firewallVMs or AppVMs use NAT - -A POSTROUTING -m iprange --src-range 10.137.1.0-10.137.2.255 -j MASQUERADE - # Allow redirection of bridge packets (optional as POSTROUTING default is ACCEPT) - #-A POSTROUTING -o bridge+ -j ACCEPT - # End Bridge support - ~~~ - -- Starting from the line -A FORWARD -i vif+ -j ACCEPT: - - ~~~ - -A FORWARD -i vif+ -o vif+ -j DROP - -A FORWARD -i vif+ -j ACCEPT - # Bridge Support - -A FORWARD -i bridge+ -j ACCEPT - # End Bridge Support - -A FORWARD -j DROP - ~~~ - -Ensure that the IP addresses used by default in Qubes are in the form 10.137.1.\* or 10.137.2.\* by running ifconfig. Of course, this setup won't work with IPv6. - -Now you need to restart the NetVM and FirewallVM or only iptables in both VMs if you prefer: - -~~~ -# systemctl restart iptables -~~~ - -Create a Bridge inside the NetVM --------------------------------- - -A bridge can be created inside the standard network manager (the network icon in the taskbar). - -This requires: - -- creating a bridge that will be your main IP (ex: setup the bridge with DHCP) -- attach eth0 to your bridge - -Note: A wireless interface cannot be bridged. - -The bridge edition GUI is somewhat buggy as it does not remember all the parameters you set up. You can fix it by editing manually the files in /etc/NetworkManager/system-connections/. Here is one example for these files: - -- Bridge-DHCP - - ~~~ - [connection] - id=Bridge-DHCP - uuid=fd68198b-313a-47cb-9155-52e95cdc67f3 - type=bridge - autoconnect=false - timestamp=1363938302 - - [ipv6] - method=auto - - [ipv4] - method=auto - - [bridge] - interface-name=bridge0 - stp=false - ~~~ - -Note: Do not forget to put stp=false if you bridge only eth0 because sending BPDUs could make your admins angry :) - -- bridge0-eth0 - - ~~~ - [802-3-ethernet] - duplex=full - mac-address=88:AE:1D:AE:30:31 - - [connection] - id=bridge0-eth0 - uuid=38320e5b-226c-409e-9fd6-0fbf4d0460a0 - type=802-3-ethernet - autoconnect=false - timestamp=1363601650 - master=fd68198b-313a-47cb-9155-52e95cdc67f3 - slave-type=bridge - ~~~ - -If you do not manage to start your bridge, you can start it manually from a NetVM terminal: - -~~~ -$ nmcli con up id bridge0-eth0 -~~~ - -Now that the bridge is ready, the bridged AppVM can be started... +This content has moved to [Qubes Forum: Community Guides](https://forum.qubes-os.org/c/guides/14). [Learn more.](https://forum.qubes-os.org/t/announcement-qubes-community-project-has-been-migrated-to-the-forum/20367/) diff --git a/docs/configuration/network-printer.md b/docs/configuration/network-printer.md index 49c7a0b..deee4c7 100644 --- a/docs/configuration/network-printer.md +++ b/docs/configuration/network-printer.md @@ -1,47 +1 @@ - -Configuring a network printer for Qubes AppVMs -============================================== - -Where to configure printers and install drivers? ------------------------------------------------- - -One would normally want to configure a printer in a template VM, rather than in particular AppVMs. -This is because all the global settings made to AppVMs (those stored in its /etc, as well as binaries installed in /usr) would be discarded upon AppVM shutdown. -When printer is added and configured in a template VM, then all the AppVMs based on this template should automatically be able to use it (without the need for the template VM to be running, of course). - -Alternatively one can add a printer in a standalone VM, but this would limit the printer usage to this particular VM. - -Security considerations for network printers and drivers --------------------------------------------------------- - -Some printers require third-party drivers, typically downloadable from the vendor's website. -Such drivers are typically distributed in a form of ready to install RPM packages. -However, they are often unsigned, and additionally the downloads are available via HTTP connections only. -As a result, installation of such third-party RPMs in a default template VM exposes a risk of compromise of this template VM, which, in turn, leads automatically to compromise of all the AppVMs based on the template. -(Again, it's not buggy or malicious drivers that we fear here, but rather malicious installation scripts for those drivers). - -In order to mitigate this risk, one might consider creating a custom template (i.e. clone the original template) and then install the third-party, unverified drivers there. -Such template might then be made a DVM template for [DisposableVM creation](https://www.qubes-os.org/doc/disposablevm/), which should allow one to print any document by right-clicking on it, choosing "Open in DisposableVM" and print from there. -This would allow to print documents from more trusted AppVMs (based on a trusted default template that is not poisoned by third-party printer drivers). - -However, one should be aware that most (all?) network printing protocols are insecure, unencrypted protocols. -This means, that an attacker who is able to sniff the local network, or who is controlling the (normally untrusted) Qubes NetVM, will likely to be able to see the documents being printed. -This is a limitation of today's printers and printing protocols, something that cannot be solved by Qubes or any other OS. - -Additionally, the printer drivers as well as CUPS application itself, might be buggy and might get exploited when talking to a compromised printer (or by an attacker who controls the local network, or the default NetVM). -Consider not using printing from your more trusted AppVMs for this reason. - -Steps to configure a network printer in a template VM ----------------------------------------------------------- - -1. Start the "Printer Settings" App in a template VM (either via Qubes "Start Menu", or by launching the `system-config-printer` in the template). - You may need to install it first `sudo dnf install system-config-printer`. -2. Add/Configure the printer in the same way as one would do on any normal Linux. - You may need to allow network access from the template VM to your printer to complete configuration, as normally the template VM is not allowed any network access except to the Qubes proxy for software installation. - One can use Qubes Manager to modify firewall rules for particular VMs. -3. Optional: Test the printer by printing a test page. If it works, shut down the template VM. -4. Open an AppVM (make sure it's based on the template where you just installed the printer, normally all AppVMs are based on the default template), and test if printing works. - If it doesn't then probably the AppVM doesn't have networking access to the printer -- in that case adjust the firewall settings for that AppVM in Qubes Manager. - Also, make sure that the AppVM gets restarted after the template was shutdown. -5. Alternatively if you do not want to modify the firewall rules of the template VM (that have security scope) you can simply shut down the template VM without trying to print the test page (which will not work), start or restart an AppVM based on the template and test printing there. - +This content has moved to [Qubes Forum: Community Guides](https://forum.qubes-os.org/c/guides/14). [Learn more.](https://forum.qubes-os.org/t/announcement-qubes-community-project-has-been-migrated-to-the-forum/20367/) diff --git a/docs/configuration/postfix.md b/docs/configuration/postfix.md index adbc167..deee4c7 100644 --- a/docs/configuration/postfix.md +++ b/docs/configuration/postfix.md @@ -1,146 +1 @@ - -Postfix -======= - -Postfix is full featured MTA (Message Transfer Agent). Here we will configure it in smarthost mode as part of common [Mutt](https://www.qubes-os.org/doc/mutt/)+Postfix+[Fetchmail](https://www.qubes-os.org/doc/fetchmail/) stack. - -Installation ------------- - -`dnf install postfix procmail make cyrus-sasl cyrus-sasl-plain` - -Cyrus-sasl is installed to authenticate to remote servers. Procmail is not strictly necessary, but is useful to sort your incoming mail, for example to put each mailing list in its own directory. Make is also not necessary, but is used to keep Postfix lookup tables. - -You should also check `alternatives` command, to see if it is the default `mta`. It probably is not. You may need to `dnf remove ssmtp` or something - -Configuration -------------- - -In TemplateVM open `/etc/aliases` and add line: - -~~~ -root: user -~~~ - -and run `newaliases`. - -This is the only thing to do in TemplateVM, as MTA configuration is AppVM specific, so we will keep it in `/usr/local` (ie. `/rw/usrlocal`) in each AppVM. - -Now shutdown TemplateVM, start AppVM. Create directory `/usr/local/etc/postfix` and copy `/etc/postfix/master.cf` and `/etc/postfix/postfix-files` there. - -### Makefile - -Postfix keeps its lookup tables in bdb hash databases. They need to be compiled from source files. Postfix admins like to keep track of them by means of `/usr/local/etc/postfix/Makefile`: - -~~~ -all: $(addsuffix .db,$(shell sed -n -e '/^[^#].*hash:\/etc\/postfix/s:.*/::p' main.cf)) - newaliases -clean: - $(RM) *.db -.PHONY: all clean - -%.db: % - /usr/sbin/postmap hash:$< -~~~ - -### Postfix main configuration - -`/usr/local/etc/postfix/main.cf` (`/etc/postfix` is intentional, don't correct it): - -~~~ -mydestination = $myhostname, $myhostname.$mydomain, $myhostname.localdomain, localhost, localhost.$mydomain, localhost.localdomain, $mydomain, localdomain -mynetworks_style = host - -inet_protocols = ipv4 - -smtp_generic_maps = hash:/etc/postfix/generic -local_header_rewrite_clients = - -smtp_sender_dependent_authentication = yes -sender_dependent_relayhost_maps = hash:/etc/postfix/sender_relay -smtp_sasl_auth_enable = yes -smtp_sasl_password_maps = hash:/etc/postfix/saslpass -smtp_sasl_security_options = -smtp_tls_security_level = encrypt -smtp_sasl_mechanism_filter = plain, login -smtpd_relay_restrictions = permit_mynetworks,permit_sasl_authenticated,defer_unauth_destination -smtpd_sender_restrictions = check_sender_access hash:/etc/postfix/sender_access - -home_mailbox = .maildir/ -setgid_group = postdrop -mail_owner = postfix - -html_directory = no -manpage_directory = /usr/share/man -queue_directory = /var/spool/postfix -readme_directory = no - -mailbox_command = /usr/bin/procmail -sendmail_path = /usr/sbin/sendmail -newaliases_path = /usr/bin/newaliases -mailq_path = /usr/bin/mailq -alias_maps = hash:/etc/aliases -~~~ - -### Lookup tables - -`/usr/local/etc/postfix/generic` (put there your primary address): - -~~~ -@localhost your.mail@example.com -~~~ - -`/usr/local/etc/postfix/sender_relay`. This is an important file. Put all your SMTP servers there. Pay attention to port (smtp/submission). Square brackets have their special meaning, they are almost certainly needed. For more info consult Postfix manual. - -~~~ -your.mail@exmaple.com [mail.example.com]:submission -your.other@mail.com [smtp.mail.com]:smtp -~~~ - -`/usr/local/etc/postfix/saslpass`. Here you put passwords to above mentioned servers. It depends on your provider if you need to put whole email as username or just the part before `@`. - -~~~ -[mail.example.com]:submission your.mail:y0urP4ssw0rd -[smtp.mail.com]:smtp your.other@mail.com:supers3cret -~~~ - -`/usr/local/etc/postfix/sender_access`. I use it to nullroute known spam domains. If you do not need it, comment respective line in `main.cf`. - -~~~ -spamdomain1.com DISCARD -spamdomain2.com DISCARD -~~~ - -Now run `make` in `/usr/local/etc/postfix`. It will hopefully compile four above mentioned lookup tables (`generic.db`, `sender_relay.db`, `saslpass.db` and `sender_access`). - -### procmail - -Don't start postfix or fetchmail yet, first create `/home/user/.procmailrc`: - -~~~ -MAILDIR = "${HOME}/.maildir" -ORGMAIL = "${MAILDIR}/" -DEFAULT = "${MAILDIR}/" - -:0 -* ^List-Id:.*qubes-users\.googlegroups\.com -list/qubes-users/ - -:0 -* ^List-Id:.*qubes-devel\.googlegroups\.com -list/qubes-devel/ -~~~ - -Run ---- - -Open `/rw/config/rc.local` and add those two lines (before fetchmail lines, if you have them): - -~~~ -#!/bin/sh - -mount --bind /usr/local/etc/postfix /etc/postfix -systemctl --no-block start postfix -~~~ - -Make sure `/rw/config/rc.local` is executable (i.e., `chmod a+x /rw/config/rc.local`). Reboot your AppVM and you are done. +This content has moved to [Qubes Forum: Community Guides](https://forum.qubes-os.org/c/guides/14). [Learn more.](https://forum.qubes-os.org/t/announcement-qubes-community-project-has-been-migrated-to-the-forum/20367/) diff --git a/docs/configuration/qmenu.md b/docs/configuration/qmenu.md index 7658bec..deee4c7 100644 --- a/docs/configuration/qmenu.md +++ b/docs/configuration/qmenu.md @@ -1,86 +1 @@ -Manage Qubes via dmenu; qmenu -============================== - -[qmenu](https://github.com/sine3o14nnae/qmenu/) is a collection of tools that utilize -[dmenu](https://tools.suckless.org/dmenu/), a dynamic menu for X, to provide you with a drop down menu for Qubes specific tasks. - -When configured to execute these tools via hotkeys, you are able to list, start and stop your qubes, attach and detach your connected devices, -adjust your qube preferences, firewall rules, per-qube keyboard layouts, launch applications and more, very quickly with only the keyboard. - -List of qmenu tools: - -- qmenu-am - Launch domU and dom0 applications. - -- qmenu-dm - List and manage your connected devices. - -- qmenu-vm - List, manage and configure your qubes. - -Warning -------- - -qmenu is **not** included in the Qubes dom0 repositories. This page will show you how to install qmenu by cloning its repository -to a disposable qube and [copying its contents to dom0](https://www.qubes-os.org/doc/copy-from-dom0/#copying-to-dom0). -**However, this way of installing software in dom0 is not advised and can compromise the security of your system!** - -**Furthermore, qmenu is unreviewed third party software and is in no way endorsed by the Qubes team. You have to trust its maintainers -to not act maliciously and to protect it from malicious and unsafe contributions. Keep in mind that you are -installing these tools in _dom0_, so judge accordingly.** - -Installation ------------- - -- Install dmenu: - - [user@dom0 ~]$ sudo qubes-dom0-update dmenu - -- Start a disposable qube that is able to connect to the internet. **Do not use this qube for anything else!** -Then inside this qube; clone the qmenu repository with git: - - [user@dispXXXX ~]$ git clone https://github.com/sine3o14nnae/qmenu/ - -- Import the authors public key: - - [user@dispXXXX ~]$ gpg2 --keyserver pool.sks-keyservers.net --recv-keys 0xCBE6 0BC2 811F FE14 333F EE05 3435 0BCA 3DDE 9AD9 - -- Check the validity of the signed commit: - - [user@dispXXXX ~/qmenu/]$ git show --show-signature - -- Finally, decide what qmenu tools you want to use, replace 'XX' accordingly, then copy them to dom0, place them -inside your path and change their mode bits. - - [user@dom0 ~]$ qvm-run --pass-io --filter-escape-chars --no-color-output dispXXXX 'cat /home/user/qmenu/qmenu-XX' > /tmp/qmenu-XX - - [user@dom0 ~]$ sudo cp /tmp/qmenu-XX /usr/local/bin/ - - [user@dom0 ~]$ sudo chmod 755 /usr/local/bin/qmenu-XX - -- For `qmenu-vm`, you have to additionally follow the steps below to copy all the files in /home/user/qmenu/lib/qmenu_vm/ to dom0 and place them in /lib/qmenu_vm/. - - [user@dom0 ~]$ mkdir /tmp/qmenu_vm - - [user@dom0 ~]$ for file in fq_keyboard fq_logs fq_pm fqubes_prefs fqvm_appmenus fqvm_clone fqvm_create fqvm_device fqvm_firewall fqvm_pci fqvm_prefs fqvm_remove fqvm_run fqvm_service fqvm_tags fqvm_volume; do qvm-run --pass-io --filter-escape-chars --no-color-output dispXXXX "cat /home/user/qmenu/lib/qmenu_vm/$file" > /tmp/qmenu_vm/$file; done - - [user@dom0 ~]$ sudo cp -r /tmp/qmenu_vm/ /lib/ - - -Customization -------------- - -### qmenu ### - -The colors that correspond to a qube label can be adjusted by appending `--{LABEL}=#{HEX VALUE}` -for any qube label, when executing a qmenu tool. - -Try the following example for visually appealing colors: - -~~~ - --purple=#a020f0 --blue=#4363d8 --gray=#bebebe --green=#3cb44b --yellow=#ffe119 --orange=#f58231 --red=#e6194b --black=#414141 -~~~ - -### dmenu ### - -In order to customize and configure dmenu, instead of downloading it from the repositories, -you have to get it from [suckless](https://tools.suckless.org/dmenu/), compile it yourself -and [copy it to dom0](https://www.qubes-os.org/doc/copy-from-dom0/#copying-to-dom0). -**However, this way of installing software in dom0 is not advised and can compromise the security of your system!** +This content has moved to [Qubes Forum: Community Guides](https://forum.qubes-os.org/c/guides/14). [Learn more.](https://forum.qubes-os.org/t/announcement-qubes-community-project-has-been-migrated-to-the-forum/20367/) diff --git a/docs/configuration/rxvt.md b/docs/configuration/rxvt.md index 0d1ecfc..deee4c7 100644 --- a/docs/configuration/rxvt.md +++ b/docs/configuration/rxvt.md @@ -1,143 +1 @@ - -Rxvt -==== - -`rxvt-unicode` is an advanced and efficient vt102 emulator. Here is a quick guide to configuration in both dom0 and guest VM. - -Installation ------------- - -`dnf install rxvt-unicode-256color-ml` will bring both base `rxvt-unicode` and extension. -Let me also recommend excellent Terminus font: `dnf install terminus-fonts`. - -Xresources ----------- - -In TemplateVM create file `/etc/X11/Xresources.urxvt` and paste config below. -`!`-lines are comments and may be left out. -`#`-lines are directives to CPP (C preprocessor) and are necessary. -This shouldn't go to `/etc/X11/Xresources`, because that file is not preprocessed by default. - -~~~ -! CGA colour palette - -!*color0: #000000 -!*color1: #AA0000 -!*color2: #00AA00 -!*color3: #AA5500 -!*color4: #0000AA -!*color5: #AA00AA -!*color6: #00AAAA -!*color7: #AAAAAA -!*color8: #555555 -!*color9: #FF5555 -!*color10: #55FF55 -!*color11: #FFFF55 -!*color12: #5555FF -!*color13: #FF55FF -!*color14: #55FFFF -!*color15: #FFFFFF - -! Qubes' favourite tango palette (improved with cyan) - -#define TANGO_Butter1 #c4a000 -#define TANGO_Butter2 #edd400 -#define TANGO_Butter3 #fce94f -#define TANGO_Orange1 #ce5c00 -#define TANGO_Orange2 #f57900 -#define TANGO_Orange3 #fcaf3e -#define TANGO_Chocolate1 #8f5902 -#define TANGO_Chocolate2 #c17d11 -#define TANGO_Chocolate3 #e9b96e -#define TANGO_Chameleon1 #4e9a06 -#define TANGO_Chameleon2 #73d216 -#define TANGO_Chameleon3 #8ae234 -#define TANGO_SkyBlue1 #204a87 -#define TANGO_SkyBlue2 #3465a4 -#define TANGO_SkyBlue3 #729fcf -#define TANGO_Plum1 #5c3566 -#define TANGO_Plum2 #75507b -#define TANGO_Plum3 #ad7fa8 -#define TANGO_ScarletRed1 #a40000 -#define TANGO_ScarletRed2 #cc0000 -#define TANGO_ScarletRed3 #ef2929 -#define TANGO_Aluminium1 #2e3436 -#define TANGO_Aluminium2 #555753 -#define TANGO_Aluminium3 #888a85 -#define TANGO_Aluminium4 #babdb6 -#define TANGO_Aluminium5 #d3d7cf -#define TANGO_Aluminium6 #eeeeec - -*color0: TANGO_Aluminium1 -*color1: TANGO_ScarletRed2 -*color2: TANGO_Chameleon1 -*color3: TANGO_Chocolate2 -*color4: TANGO_SkyBlue1 -*color5: TANGO_Plum2 -*color6: #06989a -*color7: TANGO_Aluminium4 - -*color8: TANGO_Aluminium3 -*color9: TANGO_ScarletRed3 -*color10: TANGO_Chameleon3 -*color11: TANGO_Butter3 -*color12: TANGO_SkyBlue3 -*color13: TANGO_Plum3 -*color14: #34e2e2 -*color15: TANGO_Aluminium6 - -URxvt.foreground: #E0E0E0 -!URxvt.background: black -!URxvt.cursorColor: rgb:ffff/0000/0000 - -URxvt.cursorColor: TANGO_ScarletRed3 - -!URxvt.font: -*-terminus-*-*-*-*-14-*-*-*-*-*-iso8859-2 -!URxvt.boldFont: -*-terminus-*-*-*-*-14-*-*-*-*-*-iso8859-2 -URxvt.font: xft:Terminus:pixelsize=14:style=Bold -URxvt.boldFont: xft:Terminus:pixelsize=14:style=Bold -URxvt.italicFont: xft:Terminus:pixelsize=14:style=Regular -URxvt.boldItalicFont: xft:Terminus:pixelsize=14:style=Regular -URxvt.scrollBar: False -URxvt.visualBell: False - -! Qubes X11 passthrough does not support those, but in dom0 they are nice. -URxvt.background: rgba:0000/0000/0000/afff -URxvt.depth: 32 -URxvt.urgentOnBell: True - -! TODO: write qubes-rpc to handle printing -URxvt.print-pipe: cat > $(TMPDIR=$HOME mktemp urxvt.XXXXXX) - -! selection-to-clipboard violates -! http://standards.freedesktop.org/clipboards-spec/clipboards-latest.txt [1], -! but it does for greater good: urxvt has no other means to move PRIMARY to -! CLIPBOARD, so Qubes' clipboard won't work without it. Also the rationale given -! in [1] has little relevance to advanced terminal emulator, specifically there -! is no need for w32-style intuition and virtually no need to "paste over". -URxvt.perl-ext-common: default,selection-to-clipboard - -! Prevent rxvt from entering Keyboard symbols entry mode whenever you press -! ctrl+shift, e.g. to copy or paste something to/from Qubes' clipboard. -URxvt.iso14755_52: false - -URxvt.insecure: False - -! some termcap-aware software sometimes throw '$TERM too long' -!URxvt.termName: rxvt-256color -~~~ - -Then create script to automatically merge those to xrdb. -File `/etc/X11/xinit/xinitrc.d/urxvt.sh`: - -~~~ -#!/bin/sh - -[ -r /etc/X11/Xresources.urxvt ] && xrdb -merge /etc/X11/Xresources.urxvt -~~~ - -Shortcuts ---------- - -For each AppVM, go to *Qubes Manager \> VM Settings \> Applications*. -Find `rxvt-unicode` (or `rxvt-unicode (256-color) multi-language`) and add. +This content has moved to [Qubes Forum: Community Guides](https://forum.qubes-os.org/c/guides/14). [Learn more.](https://forum.qubes-os.org/t/announcement-qubes-community-project-has-been-migrated-to-the-forum/20367/) diff --git a/docs/configuration/screen-share.md b/docs/configuration/screen-share.md index adc6f0f..deee4c7 100644 --- a/docs/configuration/screen-share.md +++ b/docs/configuration/screen-share.md @@ -1,105 +1 @@ - -How to Share A Screen Across Qubes -================================== - -> Warning: -> This guide involves opening up a TCP port between qubes. This is discouraged from the security standpoint and should only be used as a last resort, use sparingly. - -## Terminology -PRESENTATION_QUBE is the Qube you want to view the screen from - -CONTENT_QUBE is the Qube that has the window you want to share - -## Setup The Shared Screen Server - -Choose one of these sub-sections depending on whether you want to open a new screen (increased isolation), or use an existing monitor or screen. - -### If You Want To Share a New Screen - -In the Content Qube: - -1. Install packages `sudo apt install xfwm4 tigervnc-standalone-server tigervnc-viewer` or `sudo dnf install xfwm4 tigervnc-server tigervnc` - -2. Enter the password by executing `vncpasswd` - - 1. You can generate secure enough passwords for this purpose using `openssl rand -base64 16 | tr -d '+/=' | head -c 8;echo` - - 2. Enter one password for read/write (first password and verify prompt) - - 3. Enter a different password for the view only password (second password and verify prompt) - -3. Start the server `vncserver :1 -xstartup /usr/bin/xfwm4 -geometry 1920x1080 -localhost no` - -4. View the shared screen `vncviewer -passwd ~/.vnc/passwd :1` - -5. Open applications `DISPLAY=:1 xterm` where xterm can be any binary on your system - -## If You Want To Share an Existing Monitor or Window - -In the Content Qube: - -1. Install packages `sudo apt install xfwm4 x11vnc x11-utils` or `sudo dnf install xfwm4 x11vnc xwininfo` - -2. Enter the password by executing `x11vnc -storepasswd` - - 1. You can generate secure enough passwords for this purpose using `openssl rand -base64 16 | tr -d '+/=' | head -c 8;echo` - -3. Start the server - - 1. If you want to share a window `x11vnc -viewonly -rfbauth ~/.vnc/passwd -rfbport 5901 -clip 1920x1080+0+0` - - - Replace `1920x1080+0+0` with the resolution (e.g. `1920x1080`) and offset (e.g. `+0+0`) of the screen area you want to share. The coordinates 0,0 are in the top left, increasing down and to the right. - - - Use `xrandr --listactivemonitors` in Dom0 to get a list of all monitors and their offsets. That command returns in the form `W/_xH/_+X+Y`. For example to share DP-1, with xrandr output of ` 0: +DP-1 1920/510x1080/287+1280+0 DP-1`, 1920x1080+1280+0 would share just that screen. - - - `arandr` is a useful graphical tool to show where all the monitors are in relation to each other. - - 2. If you want to share a monitor `x11vnc -viewonly -rfbauth ~/.vnc/passwd -rfbport 5901 -id pick` - - - This retrieves the numerical id of the next window you click on. - - 3. If you want to share all the monitors use `x11vnc -viewonly -rfbauth ~/.vnc/passwd -rfbport 5901` - -4. View the shared screen as specified in "View The Shared Screen" - -5. Open applications like normal - -## Qubes Connect TCP Service - -These steps are a simpler version of [The Qubes Firewall](https://www.qubes-os.org/doc/firewall/#opening-a-single-tcp-port-to-other-network-isolated-qube). In dom0 execute these steps: - -1. Edit /etc/qubes-rpc/policy/qubes.ConnectTCP - -2. Add the line: ` @default ask,target=` - - - (recommended) By specifying `ask`, dom0 will ask each time a connection is attempted on that port - - - (not recommended) Rather than specifying `ask` you can use `allow` to allow all connections without a prompt, this leaves you unaware of new attempted connections. - -3. After you are done sharing you screen, remove this line to prevent further unwanted connections - -## View The Shared Screen - -In the Presentation Qube: - -1. Install package `sudo apt install -y tigervnc-viewer` - -2. Bind TCP port using Qubes Connect TCP service `qvm-connect-tcp ::5901` - -3. Start the VNC Viewer `vncviewer -Shared -ViewOnly -RemoteResize=0 -SendPrimary=0 -SendClipboard=0 -SetPrimary=0 127.0.0.1:5901` - -4. Confirm that you want to connect to the Presentation Qube in the dom0 prompt - -5. Enter password for the VNC server you created above - -6. In your presentation software share the VNC viewer - -## Present - -In the Content Qube interact with the shared screen, the changes will be mirrored back to your Presentation Qube. - -## Notes - -- To reset the VNC password delete `~/.vnc/passwd` in the Content Qube - -- The Content Qube does not need to have access to the internet \ No newline at end of file +This content has moved to [Qubes Forum: Community Guides](https://forum.qubes-os.org/c/guides/14). [Learn more.](https://forum.qubes-os.org/t/announcement-qubes-community-project-has-been-migrated-to-the-forum/20367/) diff --git a/docs/configuration/shrink-volumes.md b/docs/configuration/shrink-volumes.md index d4f81c6..deee4c7 100644 --- a/docs/configuration/shrink-volumes.md +++ b/docs/configuration/shrink-volumes.md @@ -1,98 +1 @@ -Shrinking volumes -================= - -The procedure for shrinking a volume on Ext4 and most other filesystems is bit convoluted because online shrinking isn't supported and we don't want to process any untrusted data in dom0 for security reasons. - -**Shrinking volumes is dangerous** and this is why it isn't available in standard Qubes tools. If you have enough disk space, the recommended approach is to create a new VM with a smaller disk and move the data. However, this approach has two caveats: - -- it requires copying data, which can take a while -- it is limited to the private volume of VMs based on TemplateVMs - -**ALWAYS BACKUP your data before attempting to shrink a volume.**. - - -Qubes 4.0 (root and private volumes) ------------------------------------- - -Qubes 4.0 uses *thin* LVM storage: only the data present on a volume uses disk space, free space isn't allocated physically. If your only concern is disk space, you may simply be careful with how much data you store in a given volume and avoid having to shrink a volume (use `sudo lvs` in dom0 and compare the `LSize` vs `Data%` fields to find out about real disk usage). - -The instructions below show how to resize a Linux VM's private volume. For root volumes, swap the `-private` volume suffix with `-root`. For other OSes (eg. MS Windows) you'll have to use the OS' specific tools to resize the volume at step 4 instead of `resize2fs`, and to be careful to specify the right shrinked size at step 6. - -1. backup your data with `qvm-clone` , `qvm-backup`, or your own backup mechanism. Do not rely only on snapshots (yet) -2. stop the VM (eg. 'largeVM') whose volume has to be resized -3. start another VM (eg. 'tempVM') with largeVM's private volume attached: - - ~~~ - qvm-start --hddisk dom0:/dev/qubes_dom0/vm-largeVM-private tempVM - ~~~ - - Alternatively, you could setup a loop device in dom0 associated to largeVM's private volume and attach it to a running VM but this is outside the scope of this document (see `losetup` and `qvm-block`). - -4. in tempVM, resize the attached volume: - - ~~~ - sudo e2fsck -f /dev/xvdi - sudo resize2fs /dev/xvdi - ~~~ - - (eg. `` = `2G` ; see `man resize2fs` for allowed formats). - -5. shutdown tempVM - -6. in dom0, resize the lvm volume to the **SAME** size you used at step 4. (specifying a lower size than the underlying filesystem's size **will corrupt** the filesystem and either destroy some of your data or trigger filesystem exceptions when the filesystem tries to write at a location that doesn't exist): - - ~~~ - sudo lvresize -L /dev/qubes_dom0/vm-largeVM-private - ~~~ - - - -Qubes 3.2 (Linux VMs, private image only) ------------------------------------------ - -First you need to start VM without `/rw` mounted. One possibility is to interrupt its normal startup by adding the `rd.break` kernel option: - -~~~ -qvm-prefs -s kernelopts rd.break -qvm-start --no-guid -~~~ - -And wait for qrexec connect timeout (or simply press Ctrl-C). Then you can connect to VM console and shrink the filesystem: - -~~~ -sudo xl console -# you should get dracut emergency shell here -mount --bind /dev /sysroot/dev -chroot /sysroot -mount /proc -e2fsck -f /dev/xvdb -resize2fs /dev/xvdb -umount /proc -exit -umount /sysroot/dev -poweroff -~~~ - -Now you can resize the image: - -~~~ -truncate -s /var/lib/qubes/appvms//private.img -~~~ - -It is **critical** to use the same (or bigger for some safety margin) size in truncate call compared to the `resize2fs` call. Otherwise **you will lose your data!**. - -Then reset kernel options back to default: - -~~~ -qvm-prefs -s kernelopts default -~~~ - -Done. - -In order to avoid errors, you might want to first reduce the filesystem to a smaller size than desired (say 3G), then truncate the image to the target size (for example 4G), and lastly grow the filesystem to the target size. In order to do this, after the `truncate` step, start the vm again in maintenance mode and use the following command to extend the filesystem to the correct size: - -~~~ -resize2fs /dev/xvdb -~~~ - -With no argument, `resize2fs` grows the filesystem to match the underlying block device (the .img file you just shrunk). +This content has moved to [Qubes Forum: Community Guides](https://forum.qubes-os.org/c/guides/14). [Learn more.](https://forum.qubes-os.org/t/announcement-qubes-community-project-has-been-migrated-to-the-forum/20367/) diff --git a/docs/configuration/split-ssh.md b/docs/configuration/split-ssh.md index 7631e68..deee4c7 100644 --- a/docs/configuration/split-ssh.md +++ b/docs/configuration/split-ssh.md @@ -1,409 +1 @@ -# Qubes Split SSH - -Split SSH implements a concept similar to having a smart card with your private SSH keys, except that the role of the “smart card” is played by another Qubes AppVM. -This Qubes setup allows you to keep your SSH private keys in a vault VM (`vault`) while using an SSH Client VM (`ssh-client`) to access your remote server. -This is done by using Qubes's [qrexec][qrexec] framework to connect a local SSH Agent socket from your SSH Client VM to the SSH Agent socket within the vault VM. -This way the compromise of the domain you use to connect to your remote server does not allow the attacker to automatically also steal all your keys. -(We should make a rather obvious comment here that the so-often-used passphrases on private keys are pretty meaningless because the attacker can easily set up a simple backdoor which would wait until the user enters the passphrase and steal the key then.) - - ![diagram](/attachment/wiki/split-ssh/diagram.svg) - -## Security Benefits - -In the setup described in this guide, even an attacker who manages to gain access to the `ssh-client` VM will not be able to obtain the user’s private key since it is simply not there. -Rather, the private key remains in the `vault` VM, which is extremely unlikely to be compromised if nothing is ever copied or transferred into it. -In order to gain access to the vault VM, the attacker would require the use of, e.g., a general Xen VM escape exploit or a signed, compromised package which is already installed in the TemplateVM upon which the vault VM is based. - -## Overview - -1. Make sure the TemplateVM you plan to use is up to date. -2. Create `vault` and `ssh-client` AppVMs. -3. Create an ssh key in your `vault` AppVM and set up automatic key adding prompt. -4. Set up VM interconnection -5. (Strongly Encouraged) Create a KeePassXC Database and set up SSH Agent Integration in KeePassXC. - -## Preparing your system - -Make sure the templates you plan to base your AppVMs on are [up-to-date][update]. - -## [Creating AppVMs][appvm create] - -If you’ve installed Qubes OS using the default options, a few qubes including a vault AppVM has been created for you. -Skip the first step if you don't wish to create another vault. - -1. Create a new vault AppVM (`vault`) based on your chosen template. Set networking to `(none)`. - - ![vault creation](/attachment/wiki/split-ssh/vault-creation.png) - -2. Create a SSH Client AppVM (`ssh-client`). This VM will be used to make SSH connections to your remote machine. - - ![ssh-client creation](/attachment/wiki/split-ssh/client-creation.png) - -## Setting up SSH - -Install `ssh-askpass` in the template of your `vault` VM. It will be -used by `ssh-agent` to ask for confirmation, for keys added using -`ssh-add -c`. - -For Fedora templates:
-``` - sudo dnf install openssh-askpass -``` - -For Debian templates:
-``` -sudo apt-get install ssh-askpass-gnome -``` - -Perform the next steps in the AppVM `vault`. - -1. Generate an SSH key pair. -Skip this step if you already have your keys. -Note that it is *okay* to not enter a password for your private keys since the `vault` AppVM has no networking. -If you still want to encrypt your keys you must refer to the [Securing Your Private Key](#securing-your-private-key) section. - - ```shell_prompt - [user@vault ~]$ ssh-keygen -t ed25519 -a 500 - Generating public/private ed25519 key pair. - Enter file in which to save the key (/home/user/.ssh/id_ed25519): - Created directory '/home/user/.ssh'. - Enter passphrase (empty for no passphrase): - Enter same passphrase again: - Your identification has been saved in /home/user/.ssh/id_ed25519 - Your public key has been saved in /home/user/.ssh/id_ed25519.pub - The key fingerprint is: - SHA256:DBxSxZcp16d1NSVSid3m8HRipUDM2INghQ4Sx3jPEDo user@vault - The key's randomart image is: - +--[ED25519 256]--+ - | o==+++.@++o=*| - | o==o+ B BoOoB| - | Eoo* + *.O.| - | . o+ . o| - | S | - | | - | | - | | - | | - +----[SHA256]-----+ - ``` - **-t**: type
- **-a**: num_trials
- - Please note that the key fingerprint and the randomart image will differ. - - For more information about `ssh-keygen`, run `man ssh-keygen`. - -**Notice:** Skip the following steps if you plan on using KeePassXC. - -2. Make a new directory `~/.config/autostart` - - ``` - mkdir -p ~/.config/autostart - ``` - -3. Create the file `~/.config/autostart/ssh-add.desktop` - - - Open the file with e.g. `gedit` - - ``` - gedit ~/.config/autostart/ssh-add.desktop - ``` - - - Paste the following contents: - - ```shell_prompt - [Desktop Entry] - Name=ssh-add - Exec=ssh-add -c - Type=Application - ``` - - **Note:** If you've specified a custom name for your key using *-f*, you should adjust `Exec=ssh-add -c` to `Exec=ssh-add -c ` (the path must be absolute, e.g. `/home/user/.ssh/my_key`). - -## Setting Up VM Interconnection - -### In `dom0`: - -To control which VM is allowed as a client, which may act as the server and how we want this interaction to happen, we have to write a policy file for qrexec in `dom0`. - -1. Create and edit `/etc/qubes-rpc/policy/qubes.SshAgent`. - - - Open the file with e.g. `nano`. - - ``` - sudo nano /etc/qubes-rpc/policy/qubes.SshAgent - ``` - - - If you want to explicitly allow only this connection, add the following line: - - ```shell_prompt - ssh-client vault ask - ``` - - - If you want all of your VMs to potentially be an `ssh-client` or a `vault`, add the following line: - - ```shell_prompt - @anyvm @anyvm ask - ``` - - - If you want the input field to be "prefilled" by your `vault` VM, append `default_target=vault` so it looks like for example: - - ```shell_prompt - @anyvm @anyvm ask,default_target=vault - ``` - - **Note:** There are many ways to fine-tune this policy. For more details see the [Qubes qrexec documentation][PolicyFilesQubesOS]. - - -### In the Template of Your AppVM `vault`: - -We now need to write a small script that handles connection requests from `ssh-client` and forwards them to the SSH agent in your `vault`. As we are using qrexec as communication method we have to place it in a special location and have to name it just as the policy file we just created in `dom0`. - -1. Create and edit `/etc/qubes-rpc/qubes.SshAgent`. - - - Open the file with e.g. `gedit` - - ```shell_prompt - sudo gedit /etc/qubes-rpc/qubes.SshAgent - ``` - - - Paste the following contents: - - ```shell_prompt - #!/bin/sh - # Qubes App Split SSH Script - - # safeguard - Qubes notification bubble for each ssh request - notify-send "[$(qubesdb-read /name)] SSH agent access from: $QREXEC_REMOTE_DOMAIN" - - # SSH connection - socat - "UNIX-CONNECT:$SSH_AUTH_SOCK" - ``` - -2. Make it executable - -```shell_prompt -sudo chmod +x /etc/qubes-rpc/qubes.SshAgent -``` - -### In the AppVM `ssh-client` - -Theoretically, you can use SSH in any AppVM. -However, if you are considering split-SSH as an additional security layer it is probably reasonable to also think about which VMs you will be using SSH in. -For instance, you might want a dedicated `admin` domain for these purposes. -Depending on how many systems you plan to access and where they are located, it could also be preferable to have different VMs with different firewall rules for Intranet and Internet administration. - -We want to make sure that our `ssh-client` is prepared to use split-ssh right after the VM has started. -Therefore, we add a script in `rc.local` (Which will run at VM startup) to listen for responses from `vault` and make SSH use this connection by modifying the user’s `.bashrc`. - -1. Edit `/rw/config/rc.local`. - - - Open the file with e.g. `gedit`. - - ```shell_prompt - sudo gedit /rw/config/rc.local - ``` - - Add the following to the bottom of the file: - - ```shell_prompt - # SPLIT SSH CONFIGURATION >>> - # replace "vault" with your AppVM name which stores the ssh private key(s) - SSH_VAULT_VM="vault" - - if [ "$SSH_VAULT_VM" != "" ]; then - export SSH_SOCK="/home/user/.SSH_AGENT_$SSH_VAULT_VM" - rm -f "$SSH_SOCK" - sudo -u user /bin/sh -c "umask 177 && exec socat 'UNIX-LISTEN:$SSH_SOCK,fork' 'EXEC:qrexec-client-vm $SSH_VAULT_VM qubes.SshAgent'" & - fi - # <<< SPLIT SSH CONFIGURATION - ``` - -2. Edit `~/.bashrc` and add the following to the bottom of the file: - - - Open the file with e.g. `gedit` - - ```shell_prompt - gedit ~/.bashrc - ``` - - - Add the following to the bottom of the file: - - ```shell_prompt - # SPLIT SSH CONFIGURATION >>> - # replace "vault" with your AppVM name which stores the ssh private key(s) - SSH_VAULT_VM="vault" - - if [ "$SSH_VAULT_VM" != "" ]; then - export SSH_AUTH_SOCK="/home/user/.SSH_AGENT_$SSH_VAULT_VM" - fi - # <<< SPLIT SSH CONFIGURATION - ``` - -## Securing Your Private Key - -Although passwords wouldn't protect you against a full system compromise (attacker could place a keylogger), it's possible for an adversary to gain read-only access to some of your files (e.g., file shares or offline backups of data). -This becomes even more likely if you plan to also use your data outside of Qubes and not be able to modify anything. -Passwords are advisable for mitigating these threats . - -You can either [use the built-in password utility](#using-the-built-in-password-utility) of your private key combined with a graphical prompt or prefer to [use KeePassXC](#using-keepassxc). -Please note that since `ssh-askpass` prompt is displayed on `vault` VM boot, it is not possible to use both configurations simultaneously. - -### Using the Built-in Password Utility and `ssh-askpass` - -You should have added `ssh-askpass` to your vault template earlier when [setting up SSH](#setting-up-ssh). - -1. Either add a password to an existing private key with `ssh-keygen -p` or directly create a key pair with a password (enter password when prompted during the creation process, see [above](#setting-up-ssh)). -Note that the location and name of your private key may differ. - - ``` - [user@vault ~]$ ssh-keygen -p - Enter file in which the key is (/home/user/.ssh/id_rsa): /home/user/.ssh/id_ed25519 - Key has comment 'user@vault' - Enter new passphrase (empty for no passphrase): - Enter same passphrase again: - Your identification has been saved with the new passphrase. - ``` - -2. Shutdown the template and restart your `vault` VM. - -With this configuration you'll be prompted for entering your password every time you start your vault VM to be able to make use of your SSH key. - -### Using [KeePassXC][KeePassXC] - -**Note:** This part is for setting up *KeePassXC*, not KeePassX or KeePass. See the [KeePassXC FAQ][KeePassXC FAQ]. - -KeePassXC should be installed by default in both Fedora and Debian TemplateVMs. If it’s not or you're using another template, you can [install it manually](https://www.qubes-os.org/doc/software-update-domu/#installing-software-in-templatevms). - -**A note on managing your Qubes domains:** You might already be using KeePassXC to store your passwords. This guide explains how to set up a new KeePass database and use it exclusively for SSH keys. However, it is also possible to mix your passwords and SSH keys in one big database. Others might have dedicated databases for different kinds of passwords, potentially even in different `vault` VMs. There is no right or wrong here. Feel free to skip the first five steps if you want to use an existing database. - -1. Add KeepasXC to the Applications menu of the newly created AppVM for ease of access and launch it. - - ![vault adding keepass](/attachment/wiki/split-ssh/vault-adding-keepass.png) - - **Note:** Since the vault VM has no internet connection, you can safely deny automatic updates if prompted. - -2. Create a new database. - - ![create database](/attachment/wiki/split-ssh/create-database.png) - -3. Enter a name for your database and continue. - - ![naming screen](/attachment/wiki/split-ssh/naming-screen.png) - -4. Adjust the encryption settings. -Check the [KeePassXC User Guide][KeePassXC User Guide] for more information about these settings. - - ![encryption settings](/attachment/wiki/split-ssh/encryption-settings.png) - -5. Enter a password for your database. Take your time make a secure but also rememberable password. ([hint][Hint]) - - ![password screen](/attachment/wiki/split-ssh/password-screen.png) - -6. Add a new entry. - - ![adding new entry](/attachment/wiki/split-ssh/adding-new-entry.png) - -7. Set password to your SSH key passphrase. - - ![enter passphrase](/attachment/wiki/split-ssh/enter-passphrase.png) - -8. Go into the Advanced section and add your keys. - - ![adding keys](/attachment/wiki/split-ssh/adding-keys.png) - - **Note:** Technically, you only need to add the private key (`id_25519`) for the following steps to work. If you add the public key here, too, you can later on backup your kdbx file and have everything in one place. You can even delete your keys (`id_25519` and `id_25519.pub`) from your file system if you like. - -9. Enable "SSH Agent Integration" within the Application Settings. - - ![enable ssh agent integration](/attachment/wiki/split-ssh/enable-ssh-agent-integration.png) - -10. Restart KeePassXC - -11. Check the SSH Agent Integration status. - - ![check integration status](/attachment/wiki/split-ssh/check-integration-status.png) - -12. Open the entry you created and select your private key in the "SSH Agent" section. -Don't forget to also check the first two options. - - ![select private key](/attachment/wiki/split-ssh/select-private-key.png) - -#### Testing the KeePassXC Setup - -1. Close your KeePassXC database and run `ssh-add -L` in a `vault` VM terminal. It should return `The agent has no identities.` - - ```shell_prompt - [user@vault ~]$ ssh-add -L - The agent has no identities. - ``` - -2. Unlock your KeePassXC database and run `ssh-add -L` again. This time it should return your public key. - - ```shell_prompt - [user@vault ~]$ ssh-add -L - ssh-ed25519 user@vault-keepassxc - ``` - -## Test Your Configuration - -1. If you're using KeePassXC, shutdown KeePassXC on your vault VM. -If not, make sure your private key is not added to the ssh-agent in your vault VM (Check with `ssh-add -L`). -If it is, restart your vault VM and do not enter your password when it asks you to. - -2. Try fetching your identities on the SSH Client VM. - - ```shell_prompt - ssh-add -L - ``` - -3. Allow operation execution. (If you don't see the below prompt, check your VM interconnection setup.) - - ![operation execution](/attachment/wiki/split-ssh/operation-execution.png) - -It should return `The agent has no identities.`. - -If you're getting an error (e.g. `error fetching identities: communication with agent failed`), make sure your vault VM is running and check your VM interconnection setup. - -4. Launch KeePassXC and unlock your database. - -5. Repeat steps 1 and 2. - -Check if it returns `ssh-ed25519 ` - -If you're getting an error (e.g. `error fetching identities: communication with agent failed`), make sure your vault VM is running and check your VM interconnection setup. - -## Current limitations - -* It is possible for a malicious VM to hold onto an ssh-agent connection for more than one use. -Therefore, if you authorize usage once, assume that a malicious VM could then use it many more times. -In this case, though, the SSH Agent will continue to protect your private keys; only usage of it would be available to the malicious VM until it is shut down. -* The two actions below should allow the user to know what is requested before the operation gets approved, but has not been fully verified: - * configuring the vault to use `ssh-add -c` as described above - * configuring KeepassXC to "Require user confirmation when this key is used" - -Want more Qubes split magic? -Check out [Split-GPG][Split-GPG]. - -------------------------------- -This guide has been inspired by:
-Qubes Split SSH (Github: Jason Hennessey - henn) https://github.com/henn/qubes-app-split-ssh
-Using split ssh in QubesOS 4.0 (Kushal Das) https://kushaldas.in/posts/using-split-ssh-in-qubesos-4-0.html
-Using Split-SSH in Qubes 4 (Denis Zanin) https://deniszanin.com/using-split-ssh-gpg-in-qubes-os/
-R.I.S.K.S. https://19hundreds.github.io/risks-workflow/ssh-split-setup
- -Contributor(s): @shaaati, @invalid-error, @deeplow, @ephemer4l - -[CreateBackup]:https://www.qubes-os.org/doc/backup-restore/#creating-a-backup -[qrexec]: https://www.qubes-os.org/doc/qrexec/ -[update]: https://www.qubes-os.org/doc/software-update-domu/#updating-software-in-templatevms -[appvm create]: https://www.qubes-os.org/doc/getting-started/#adding-removing-and-listing-qubes -[PolicyFilesQubesOS]:https://www.qubes-os.org/doc/qrexec/#policy-files -[Split-GPG]:https://www.qubes-os.org/doc/split-gpg - -[KeePassXC]: https://keepassxc.org/project -[KeePassXCFedoraPackageSource]:https://src.fedoraproject.org/rpms/keepassxc -[KeePassXC download page]: https://keepassxc.org/download/ -[KeePassXC FAQ]: https://keepassxc.org/docs -[KeePassXC User Guide]: https://keepassxc.org/docs/KeePassXC_UserGuide.html#_database_settings - -[Hint]:https://xkcd.com/936 +This content has moved to [Qubes Forum: Community Guides](https://forum.qubes-os.org/c/guides/14). [Learn more.](https://forum.qubes-os.org/t/announcement-qubes-community-project-has-been-migrated-to-the-forum/20367/) diff --git a/docs/configuration/tips-and-tricks.md b/docs/configuration/tips-and-tricks.md index c37477c..deee4c7 100644 --- a/docs/configuration/tips-and-tricks.md +++ b/docs/configuration/tips-and-tricks.md @@ -1,50 +1 @@ - -Tips and Tricks -=============== -This section provides user suggested tips that aim to increase Qubes OS usability, security or that allow users to discover new ways to use your computer that are unique to Qubes OS. - -Opening links in your preferred AppVM -------------------------------------- -To increase both security and usability you can set an AppVM so that it automatically opens any link in an different AppVM of your choice. You can do this for example in the email AppVM, in this way you avoid to make mistakes like opening links in it. To learn more you can check [security guidelines](https://www.qubes-os.org/doc/security-guidelines/) and [security goals](https://www.qubes-os.org/security/goals/). - -The command `qvm-open-in-vm` lets you open a document or a URL in another VM. It takes two parameters: vmname and filename. - -For example, if you launch this command from your email AppVM: - -`qvm-open-in-vm untrusted https://duckduckgo.com` - -it will open duckduckgo.com in the `untrusted` AppVM (after you confirmed the request). - -If you want this to happen automatically you can create a .desktop file that advertises itself as a handler for http/https links, and then set this as your default browser. - -Open a text editor and copy and paste this into it: - - [Desktop Entry] - Encoding=UTF-8 - Name=BrowserVM - Exec=qvm-open-in-vm APPVMNAME %u - Terminal=false - X-MultipleArgs=false - Type=Application - Categories=Network;WebBrowser; - MimeType=x-scheme-handler/unknown;x-scheme-handler/about;text/html;text/xml;application/xhtml+xml;application/xml;application/vnd.mozilla.xul+xml;application/rss+xml;application/rdf+xml;image/gif;image/jpeg;image/png;x-scheme-handler/http;x-scheme-handler/https; - -Replace `APPVMNAME` with the AppVM name you want to open links in. Now save, in the AppVM that you want to modify, this file to `~/.local/share/applications/browser_vm.desktop` - -Finally, set it as your default browser: - -`xdg-settings set default-web-browser browser_vm.desktop` - -Credit: [Micah Lee](https://micahflee.com/2016/06/qubes-tip-opening-links-in-your-preferred-appvm/) - -Preventing data leaks ---------------------- -First make sure to read [Understanding and Preventing Data Leaks](https://www.qubes-os.org/doc/data-leaks/) section to understand the limits of this tip. - -Suppose that you have within a not so trusted environment - for example, a Windows VM - an application that tracks and reports its usage, or you simply want to protect your data. - -Start the Windows TemplateVM (which has no user data), install/upgrade apps; then start Windows AppVM (with data) in offline mode. So, if you worry (hypothetically) that your Windows or app updater might want to send your data away, this Qubes OS trick will prevent this. -This applies also to any TemplateBasedVM relative to its parent TemplateVM, but the privacy risk is especially high in the case of Windows. - -Credit: [Joanna Rutkovska](https://twitter.com/rootkovska/status/832571372085850112) - +This content has moved to [Qubes Forum: Community Guides](https://forum.qubes-os.org/c/guides/14). [Learn more.](https://forum.qubes-os.org/t/announcement-qubes-community-project-has-been-migrated-to-the-forum/20367/) diff --git a/docs/configuration/vpn.md b/docs/configuration/vpn.md index 2df9b37..deee4c7 100644 --- a/docs/configuration/vpn.md +++ b/docs/configuration/vpn.md @@ -1,316 +1 @@ - -How To make a VPN Gateway in Qubes -================================== - - - -Although setting up a VPN connection is not by itself Qubes specific, Qubes includes a number of tools that can make the client-side setup of your VPN more versatile and secure. This document is a Qubes-specific outline for choosing the type of VM to use, and shows how to prepare a ProxyVM for either NetworkManager or a set of fail-safe VPN scripts. - -Please refer to your guest OS and VPN service documentation when considering the specific steps and parameters for your connection(s); The relevant documentation for the Qubes default guest OS (Fedora) is [Establishing a VPN Connection.](https://docs.fedoraproject.org/en-US/Fedora/23/html/Networking_Guide/sec-Establishing_a_VPN_Connection.html) - -### NetVM - -The simplest case is to set up a VPN connection using the NetworkManager service inside your NetVM. Because the NetworkManager service is already started, you are ready to set up your VPN connection. However this has some disadvantages: - -- You have to place (and probably save) your VPN credentials inside the NetVM, which is directly connected to the outside world -- All your AppVMs which are connected to the NetVM will be connected to the VPN (by default) - -### AppVM - -While the NetworkManager service is not started here (for a good reason), you can configure any kind of VPN client in your AppVM as well. However this is only suggested if your VPN client has special requirements. - -### ProxyVM - -One of the best unique features of Qubes OS is its special type of VM called a ProxyVM. The special thing is that your AppVMs see this as a NetVM (or uplink), and your NetVMs see it as a downstream AppVM. Because of this, you can place a ProxyVM between your AppVMs and your NetVM. This is how the default sys-firewall VM functions. - -Using a ProxyVM to set up a VPN client gives you the ability to: - -- Separate your VPN credentials from your NetVM. -- Separate your VPN credentials from your AppVM data. -- Easily control which of your AppVMs are connected to your VPN by simply setting it as a NetVM of the desired AppVM. - -Set up a ProxyVM as a VPN gateway using NetworkManager ------------------------------------------------------- - -1. Create a new VM, name it, click the ProxyVM radio button, and choose a color and template. - - ![Create\_New\_VM.png](/attachment/wiki/VPN/Create_New_VM.png) - -2. Add the `network-manager` service to this new VM. - - ![Settings-services.png](/attachment/wiki/VPN/Settings-services.png) - -3. Set up your VPN as described in the NetworkManager documentation linked above. - -4. (Optional) Make your VPN start automatically. - - Edit `/rw/config/rc.local` and add these lines: - - ```bash - # Automatically connect to the VPN once Internet is up - while ! ping -c 1 -W 1 1.1.1.1; do - sleep 1 - done - PWDFILE="/rw/config/NM-system-connections/secrets/passwd-file.txt" - nmcli connection up file-vpn-conn passwd-file $PWDFILE - ``` - You can find the actual "file-vpn-conn" in `/rw/config/NM-system-connections/`. - - Create directory `/rw/config/NM-system-connections/secrets/` (You can put your `*.crt` and `*.pem` files here too). - Create a new file `/rw/config/NM-system-connections/secrets/passwd-file.txt`: - ``` - vpn.secrets.password:XXXXXXXXXXXXXX - ``` - And substitute "XXXXXXXXXXXXXX" for the actual password. - The contents of `passwd-file.txt` may differ depending on your VPN settings. See the [documentation for `nmcli up`](https://www.mankier.com/1/nmcli#up). - -5. (Optional) Make the network fail-close for the AppVMs if the connection to the VPN breaks. - - Edit `/rw/config/qubes-firewall-user-script` and add these lines: - ```bash - # Block forwarding of connections through upstream network device - # (in case the vpn tunnel breaks) - iptables -I FORWARD -o eth0 -j DROP - iptables -I FORWARD -i eth0 -j DROP - ip6tables -I FORWARD -o eth0 -j DROP - ip6tables -I FORWARD -i eth0 -j DROP - ``` - -6. Configure your AppVMs to use the new VM as a NetVM. - - ![Settings-NetVM.png](/attachment/wiki/VPN/Settings-NetVM.png) - -7. Optionally, you can install some [custom icons](https://github.com/Zrubi/qubes-artwork-proxy-vpn) for your VPN - - -Set up a ProxyVM as a VPN gateway using iptables and CLI scripts ----------------------------------------------------------------- - -This method is more involved than the one above, but has anti-leak features that also make the connection _fail closed_ should it be interrupted. -It has been tested with Fedora 30 and Debian 10 templates. - -Before proceeding, you will need to download a copy of your VPN provider's configuration file(s) and have your VPN login information handy. - -1. Create a new VM, name it, choose "provides network", and choose a color and template. - - ![Create\_New\_VM.png](/attachment/wiki/VPN/Create_New_VM.png) - - Note: Do not enable NetworkManager in the ProxyVM, as it can interfere with the scripts' DNS features. - If you enabled NetworkManager or used other methods in a previous attempt, do not re-use the old ProxyVM... - Create a new one according to this step. - - If your choice of TemplateVM doesn't already have the VPN client software, you'll need to install the software in the template before proceeding. The 'openvpn' package comes installed in the Fedora template, and in Debian it can be installed with the following command: - - sudo apt-get install openvpn - - Disable any auto-starting service that comes with the software package. - For example for OpenVPN. - - sudo systemctl disable openvpn-server@.service - sudo systemctl disable openvpn-client@.service - -2. Set up and test the VPN client. - Make sure the VPN VM and its TemplateVM is not running. - Run a terminal (CLI) in the VPN VM -- this will start the VM. - Then create a new `/rw/config/vpn` folder with: - - sudo mkdir /rw/config/vpn - - Copy your VPN configuration files to `/rw/config/vpn`. - Your VPN config file should be named `openvpn-client.ovpn` so you can use the scripts below as is without modification. Otherwise you would have to replace the file name. Files accompanying the main config such as `*.crt` and `*.pem` should also be placed in the `/rw/config/vpn` folder. - - Check or modify configuration file contents using a text editor: - - sudo gedit /rw/config/vpn/openvpn-client.ovpn - - Files referenced in `openvpn-client.ovpn` should not use absolute paths such as `/etc/...`. - - 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`. - - Make sure it already includes or add: - - redirect-gateway def1 - - The VPN client may not be able to prompt you for credentials when connecting to the server, so we'll add a reference to a file containing the VPN username and password. - For example for OpenVPN, add or modify `auth-user-pass` like so: - - auth-user-pass pass.txt - - Save the `/rw/config/vpn/openvpn-client.ovpn` file. - - Now make sure a `/rw/config/vpn/pass.txt` file actually exists. - - sudo gedit /rw/config/vpn/pass.txt - - Add: - - username - password - - Replace `username` and `password` with your actual username and password. - - **Test your client configuration:** - Run the client from a CLI prompt in the 'vpn' folder, preferably as root. - For example: - - sudo openvpn --cd /rw/config/vpn --config openvpn-client.ovpn - - Watch for status messages that indicate whether the connection is successful and test from another VPN VM terminal window with `ping`. - - ping 1.1.1.1 - - `ping` can be aborted by pressing the two keys `ctrl` + `c` at the same time. - DNS may be tested at this point by replacing addresses in `/etc/resolv.conf` with ones appropriate for your VPN (although this file will not be used when setup is complete). - Diagnose any connection problems using resources such as client documentation and help from your VPN service provider. - Proceed to the next step when you're sure the basic VPN connection is working. - -3. Create the DNS-handling script. - - sudo gedit /rw/config/vpn/qubes-vpn-handler.sh - - Add the following: - - ~~~ - #!/bin/bash - set -e - export PATH="$PATH:/usr/sbin:/sbin" - - case "$1" in - - up) - # To override DHCP DNS, assign DNS addresses to 'vpn_dns' env variable before calling this script; - # Format is 'X.X.X.X Y.Y.Y.Y [...]' - if [[ -z "$vpn_dns" ]] ; then - # Parses DHCP foreign_option_* vars to automatically set DNS address translation: - for optionname in ${!foreign_option_*} ; do - option="${!optionname}" - unset fops; fops=($option) - if [ ${fops[1]} == "DNS" ] ; then vpn_dns="$vpn_dns ${fops[2]}" ; fi - done - fi - - iptables -t nat -F PR-QBS - if [[ -n "$vpn_dns" ]] ; then - # Set DNS address translation in firewall: - for addr in $vpn_dns; do - iptables -t nat -A PR-QBS -i vif+ -p udp --dport 53 -j DNAT --to $addr - iptables -t nat -A PR-QBS -i vif+ -p tcp --dport 53 -j DNAT --to $addr - done - su - -c 'notify-send "$(hostname): LINK IS UP." --icon=network-idle' user - else - su - -c 'notify-send "$(hostname): LINK UP, NO DNS!" --icon=dialog-error' user - fi - - ;; - down) - su - -c 'notify-send "$(hostname): LINK IS DOWN !" --icon=dialog-error' user - - # Restart the VPN automatically - sleep 5s - sudo /rw/config/rc.local - ;; - esac - ~~~ - - Save the script. - Make it executable. - - sudo chmod +x /rw/config/vpn/qubes-vpn-handler.sh - -4. Configure client to use the DNS handling script. Using openvpn as an example, edit the config. - - sudo gedit /rw/config/vpn/openvpn-client.ovpn - - Add the following. - - script-security 2 - up 'qubes-vpn-handler.sh up' - down 'qubes-vpn-handler.sh down' - - Remove other instances of lines starting with `script-security`, `up` or `down` should there be any others. - Save the script. - **Restart the client and test the connection again** ...this time from an AppVM! - -5. Set up iptables anti-leak rules. - Edit the firewall script. - - sudo gedit /rw/config/qubes-firewall-user-script - - Clear out the existing lines and add: - - ~~~ - #!/bin/bash - # Block forwarding of connections through upstream network device - # (in case the vpn tunnel breaks): - iptables -I FORWARD -o eth0 -j DROP - iptables -I FORWARD -i eth0 -j DROP - ip6tables -I FORWARD -o eth0 -j DROP - ip6tables -I FORWARD -i eth0 -j DROP - - # Accept traffic to VPN - iptables -P OUTPUT ACCEPT - 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 - - # Block non-VPN traffic to clearnet - iptables -I OUTPUT -o eth0 -j DROP - # Allow traffic from the `qvpn` group to the uplink interface (eth0); - # Our VPN client will run with group `qvpn`. - iptables -I OUTPUT -p all -o eth0 -m owner --gid-owner qvpn -j ACCEPT - ~~~ - - Save the script. - Make it executable. - - sudo chmod +x /rw/config/qubes-firewall-user-script - -5. Set up the VPN's autostart. - - sudo gedit /rw/config/rc.local - - Clear out the existing lines and add: - - ~~~ - #!/bin/bash - VPN_CLIENT='openvpn' - VPN_OPTIONS='--cd /rw/config/vpn/ --config openvpn-client.ovpn --daemon' - - groupadd -rf qvpn ; sleep 2s - sg qvpn -c "$VPN_CLIENT $VPN_OPTIONS" - su - -c 'notify-send "$(hostname): Starting $VPN_CLIENT..." --icon=network-idle' user - ~~~ - - If you are using anything other than OpenVPN, change the `VPN_CLIENT` and `VPN_OPTIONS` variables to match your VPN software. - Save the script. - Make it executable. - - sudo chmod +x /rw/config/rc.local - -6. Restart the new VM! - The link should then be established automatically with a popup notification to that effect. - - -Usage ------ - -Configure your AppVMs to use the VPN VM as a NetVM... - -![Settings-NetVM.png](/attachment/wiki/VPN/Settings-NetVM.png) - -If you want to update your TemplateVMs through the VPN, you can enable the `qubes-updates-proxy` service for your new VPN VM and configure the [qubes-rpc policy](https://www.qubes-os.org/doc/software-update-domu/#updates-proxy). - - -Troubleshooting ---------------- - -See the [VPN Troubleshooting](https://www.qubes-os.org/doc/vpn-troubleshooting/) guide for tips on how to fix common VPN issues. +This content has moved to [Qubes Forum: Community Guides](https://forum.qubes-os.org/c/guides/14). [Learn more.](https://forum.qubes-os.org/t/announcement-qubes-community-project-has-been-migrated-to-the-forum/20367/) diff --git a/docs/configuration/w3m.md b/docs/configuration/w3m.md index 003b5fd..deee4c7 100644 --- a/docs/configuration/w3m.md +++ b/docs/configuration/w3m.md @@ -1,31 +1 @@ - -Reducing the fingerprint of the text-based web browser w3m -==== - -TL;DR: You can reduce the amount of information w3m gives about itself and the environment it is running in (and, by extension, you). **It will not make you anonymous; your fingerprint will still be unique.** But it may improve your privacy. - -[w3m](http://w3m.sourceforge.net/) 'is a text-based web browser as well as a pager like `more` or `less`. With w3m you can browse web pages through a terminal emulator window (xterm, rxvt or something like that). Moreover, w3m can be used as a text formatting tool which typesets HTML into plain text.' - -You can reduce the [browser fingerprint](https://panopticlick.eff.org/about#browser-fingerprinting) by applying the following changes to `~/.w3m/config` in any AppVM you want to use w3m in. (If you have not run w3m yet, you might need to copy the config file from elsewhere.) You can also apply the same changes to `/etc/w3m/config` in the relevant TemplateVM(s) to have them apply to multiple AppVMs; but make sure they are not reversed by the contents of `~/.w3m/config` in any of the AppVMs. (w3m reads `~/.w3m/config` after `/etc/w3m/config`). - -* Set `user_agent` to `user_agent Mozilla/5.0 (Windows NT 6.1; rv:45.0) Gecko/20100101 Firefox/45.0`. - - By default w3m identifies itself as `w3m/` + version number. The user agent `Mozilla/5.0 (Windows NT 6.1; rv:45.0) Gecko/20100101 Firefox/45.0` is the most common and the one used by the Tor Browser Bundle (TBB). One in fourteen browsers fingerprinted by Panopticlick has this value. - -* Make w3m use the same HTTP_ACCEPT headers the TBB by adding the following lines at the end of the file: - - accept_language en-US,en;q=0.5 - accept_encoding gzip, deflate - accept_media text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8 - - These changes will hide your computer's locale and some other information that may or may not be unique to the VM in which it is running. With the modifications above w3m will have the same headers as about one in fifteen browsers fingerprinted by Panopticlick. - -Testing these settings on returns a fingerprint that is distinguishable from that of the TBB (with JavaScript disabled) only by 'Screen Size (CSS)' and 'Browser supports HSTS?'.\* ( does not work with w3m.) Due to the low number of w3m users it is highly likely that you will have an unique browser fingerprint among the visitors of a website using somewhat sophisticated browser fingerprinting technology. But at least your browser fingerprint will not reveal your computer's locale settings or other specifics about it in the HTTP_ACCEPT headers. And while it may be inferred from your fingerprint that you use w3m, it is not be explicitly stated in the User-Agent header. - -**Reminder: Do not rely on these settings for anonymity. Using w3m is all but guaranteed to make you stand out in the crowd.** - -PS: You still need to delete cookies manually (`~/.w3m/cookie`) if you are not running w3m in a DispVM anyway. If you set w3m to not accept cookies, its fingerprint will change. (You can configure w3m to not use store cookies or accept new ones (or both), but the setting `use_cookie` seems to really mean `accept_cookie` and vice-versa, so maybe it is best to delete them manually for now.) - -* * * - -\* Does someone know how to fix this? +This content has moved to [Qubes Forum: Community Guides](https://forum.qubes-os.org/c/guides/14). [Learn more.](https://forum.qubes-os.org/t/announcement-qubes-community-project-has-been-migrated-to-the-forum/20367/) diff --git a/docs/configuration/zfs.md b/docs/configuration/zfs.md index 2f248be..deee4c7 100644 --- a/docs/configuration/zfs.md +++ b/docs/configuration/zfs.md @@ -1,188 +1 @@ - -ZFS in Qubes -============ - -**Use at your own risk**! - -Beware: Dragons might eat your precious data! - -Install ZFS in Dom0 -=================== - -Install DKMS style packages for Fedora (defunct in 0.6.2 due to spl/issues/284) ----------------------------------------------------------------------------------------------------- - -Fetch and install repository for DKMS style packages for your Dom0 Fedora version [http://zfsonlinux.org/fedora.html](http://zfsonlinux.org/fedora.html): - -~~~ -disp1# wget http://archive.zfsonlinux.org/fedora/zfs-release-1-1$(rpm -E %dist).noarch.rpm -dom0# qvm-run --pass-io disp1 'cat /home/user/zfs-release-1-1.fc18.noarch.rpm' > /home/user/zfs-release-1-1.fc18.noarch.rpm -dom0# sudo yum localinstall /home/user/zfs-release-1-1.fc18.noarch.rpm -dom0# sudo sed -i 's/$releasever/18/g' /etc/yum.repo.d/zfs.repo -dom0# sudo qubes-dom0-update @development-tools -dom0# sudo qubes-dom0-update zfs -~~~ - -Install DKMS style packages from git-repository ------------------------------------------------ - -Build and install your DKMS or KMOD packages as described in [http://zfsonlinux.org/generic-rpm.html](http://zfsonlinux.org/generic-rpm.html). - -### Prerequisites steps in AppVM (i.e. disp1) - -Checkout repositories for SPL and ZFS: - -~~~ -mkdir ~/repositories && cd ~/repositories -git clone https://github.com/zfsonlinux/spl.git -git clone https://github.com/zfsonlinux/zfs.git -~~~ - -Revert changes in SPL repository due to this bug: [https://github.com/zfsonlinux/spl/issues/284](https://github.com/zfsonlinux/spl/issues/284) - -~~~ -cd ~/repositories/spl -git config --global user.email "user@example.com" -git config --global user.name "user" -git revert e3c4d44886a8564e84aa697477b0e37211d634cd -~~~ - -### Installation steps in Dom0 - -Copy repositories over to Dom0: - -~~~ -mkdir ~/repositories -qvm-run --pass-io disp1 'tar -cf - -C ~/repositories/ {spl,zfs}' | tar -xpf - -C ~/repositories/ -~~~ - -Installing build requirements for SPL and ZFS DKMS modules: - -~~~ -sudo qubes-dom0-update dkms kernel-devel zlib-devel libuuid-devel libblkid-devel lsscsi bc autoconf automake binutils bison flex gcc gcc-c++ gdb gettext libtool make pkgconfig redhat-rpm-config rpm-build strace -~~~ - -Configure and build SPL DKMS packages: - -~~~ -cd ~/repositories/spl -./autogen.sh -./configure --with-config=user -make rpm-utils rpm-dkms -~~~ - -Configure and build ZFS DKMS packages: - -~~~ -cd ~/repositories/zfs -./autogen.sh -./configure --with-config=user -make rpm-utils rpm-dkms -~~~ - -Install SPL and ZFS packages (i.e. version 0.6.2): - -~~~ -sudo yum localinstall \ - ~/repositories/spl/spl-0.6.2-1.qbs2.x86_64.rpm \ - ~/repositories/spl/spl-dkms-0.6.2-1.qbs2.noarch.rpm \ - ~/repositories/zfs/zfs-0.6.2-1.qbs2.x86_64.rpm \ - ~/repositories/zfs/zfs-dkms-0.6.2-1.qbs2.noarch.rpm \ - ~/repositories/zfs/zfs-dracut-0.6.2-1.qbs2.x86_64.rpm \ - ~/repositories/zfs/zfs-test-0.6.2-1.qbs2.x86_64.rpm -~~~ - -Configure ZFS -============= - -Automatically load modules --------------------------- - -/etc/sysconfig/modules/zfs.modules - -~~~ -#!/bin/sh - -for module in spl zfs; do - modprobe ${module} >/dev/null 2>&1 -done -~~~ - -Make this file executable. - -Tuning ------- - -Tame the memory-eating dragon (i.e. 512 Mb zfs\_arc\_max): - -/etc/modprobe.d/zfs.conf - -~~~ -options zfs zfs_arc_max=536870912 -~~~ - -Setup a zpool with ZFS datasets -------------------------------- - -You can create a ZFS dataset for each AppVM, ServiceVM, HVM or TemplateVM or just use a pool as your backup location. - -Move your existing directory to a temporary location, or the ZFS mount will overlay your directory. - -Beware: VMs on a ZFS dataset aren't working, if your ZFS installation deserts you. - -So keep netvm, firewallvm and your templates on your root file-system (preferably on a SSD). - -~~~ -zpool create -m none -o ashift=12 -O atime=off -O compression=lz4 qubes mirror /dev/mapper/ /dev/mapper/ -zfs create -p qubes/appvms -zfs create -m /var/lib/qubes/backup-zfs qubes/backup -zfs create -m /var/lib/qubes/appvms/banking qubes/appvms/banking -zfs create -m /var/lib/qubes/appvms/personal qubes/appvms/personal -zfs create -m /var/lib/qubes/appvms/untrusted qubes/appvms/untrusted -zfs create -m /var/lib/qubes/appvms/work qubes/appvms/work -~~~ - -Have fun with zpool and zfs. - -Tips and Hints -============== - -Backup your data ----------------- - -You're depending on an huge amount of code for this file system, keep this in mind and backup your precious data. - -Encrypt underlying devices --------------------------- - -~~~ -dom0# cryptsetup -c aes-xts-plain64 luksFormat -dom0# cryptsetup luksOpen -~~~ - -With the use of cryptsetup a keyfile can be specified to decrypt devices. - -~~~ -dom0# head -c 256 /dev/random > /root/keyfile1 -dom0# chmod 0400 /root/keyfile1 -dom0# cryptsetup luksAddKey /root/keyfile1 -~~~ - -Decrypt devices on boot ------------------------ - -Add your devices to /etc/crypttab. - -~~~ - - none -~~~ - -Specifying a keyfile is especially useful, if ZFS should be ready during boot. - -Further Reading ---------------- - -- [http://www.open-zfs.org](http://www.open-zfs.org) -- [http://zfsonlinux.org](http://zfsonlinux.org) - +This content has moved to [Qubes Forum: Community Guides](https://forum.qubes-os.org/c/guides/14). [Learn more.](https://forum.qubes-os.org/t/announcement-qubes-community-project-has-been-migrated-to-the-forum/20367/) diff --git a/docs/configuration/zoom_dispvm.md b/docs/configuration/zoom_dispvm.md index 0699c3d..deee4c7 100644 --- a/docs/configuration/zoom_dispvm.md +++ b/docs/configuration/zoom_dispvm.md @@ -1,69 +1 @@ -# Running Zoom in a DispVM -## Intro -Zoom is a fairly widely-used video conferencing application that runs on a variety of platforms. In this guide we will go through the process of setting up a Disposable VM for Zoom. - -### Why we will use a DispVM -By running Zoom alone in a Disposable VM, we can improve the safety of using the application. DispVMs ensure that even if a Zoom exploit leads to the entire DispVM being compromised, it is *contained* to the DispVM which is destroyed once you shutdown the Qube or exit Zoom. No persistence, limited attack surface, and zero trust. - -## Step 0: Clone a TemplateVM -1. Open `Qubes Manager` -2. Right-click on the `debian-10` TemplateVM -3. Click `Clone Qube` -4. Name the cloned qube `videoconferencing` - -*Alternatively:* - -1. Open Terminal Emulator in dom0 -2. Clone the `debian-10` template to new template `videoconferencing`: - `qvm-clone --verbose debian-10 videoconferencing` - -## Step 1: Download Zoom for Debian 8.0+ 64-bit -### Download and import Zoom's signing key: -1. Open `Xfce Terminal` from `whonix-ws-15-dvm` **Make a note of the Qube name in the title. This will be used in step 2.** -2. Download Zoom's GPG key using wget: - `wget "https://zoom.us/linux/download/pubkey"` -3. Import Zoom's Public Key: - `gpg --import pubkey` -### Download and verify Zoom, then copy to TemplateVM: -1. Download Zoom using `wget`: - `wget "https://zoom.us/client/latest/zoom_amd64.deb"` -2. Verify `zoom_amd64.deb`: - * `sudo apt install -y dpkg-sig`: `Install dpkg-sig` so we can verify `zoom_amd64.deb` - * `dpkg-sig zoom_amd64.deb`: Verify `zoom_amd64.deb`. - * Expected output should include indicate a good signature, for example here's what I got running the command: - `GOODSIG _gpgbuilder 396060CADD8A75220BFCB369B903BF1861A7C71D 1590375377` -3. Copy `zoom_amd64.deb` to TemplateVM `videoconferencing`: - `qvm-copy zoom_amd64.deb` -4. Select the `videoconferencing` TemplateVM as the destination to copy `zoom_amd64.deb` to. -5. Shutdown the TemplateVM: - `sudo shutdown now` - -## Step 2: Install Zoom in TemplateVM -### Install Zoom in the `videoconferencing` TemplateVM: -1. Open `Terminal` from TemplateVM `videoconferencing` -2. Check QubesIncoming folder contents: - `ls QubesIncoming` -3. You should see a folder with the same name as the Qube name in the title from the end of step 2. **In the following example, the Qube name was disp6247.** -4. Change directory to the location of `zoom_amd64.deb`: - `cd ~/QubesIncoming/disp6247/` -5. Install Zoom using `apt-get`: - `sudo apt-get install -y ./zoom_amd64.deb` -6. Shutdown the TemplateVM - `sudo shutdown now` - -## Step 3: Create an AppVM for Zoom -1. Open `Create Qubes VM`. -2. Name the Qube `videoconferencing-dvm` and label it `red` to indicate the lowest level of trust. -3. Select `AppVM` as the type of qube to be created. *This is the default.* -4. Select `videoconferencing` as the template for the AppVM Qube. -5. Choose `sys-firewall` for networking. -6. Click `OK`. - -## Step 4: Add Zoom to the AppVM's list of applications & enable DispVM -1. Open `Qube Manager` -2. `Search` for the `videoconferencing` TemplateVM. Right-click it and select `Qube Settings` -3. Click the `Applications` tab. -4. Click `Zoom` to highlight it, then click the `>` button to add it to the AppVM's application list. -5. Click the `Advanced` tab. -6. Under the `Other` section, check the box labeled `Disposable VM Template` -7. Click `OK`. +This content has moved to [Qubes Forum: Community Guides](https://forum.qubes-os.org/c/guides/14). [Learn more.](https://forum.qubes-os.org/t/announcement-qubes-community-project-has-been-migrated-to-the-forum/20367/) diff --git a/docs/coreboot/x230.md b/docs/coreboot/x230.md index e9a4d4e..deee4c7 100644 --- a/docs/coreboot/x230.md +++ b/docs/coreboot/x230.md @@ -1,464 +1 @@ -# Coreboot on Lenovo X230 - -This howto describes how to install Coreboot on a Lenovo X230. -This document is still a draft and needs some cleanup. - -In order to flash the bios chip on the X230 you need special equipment to read and write to the two BIOS chips. -An easy way which for an in-place flashiung procedure is to use a raspberry pi and a special flashing clip to read from and write to the Bios chip. - -The setup looks like this: - -Lenovo X230 (target) BIOS Chip <-- Pomodo Flash Clip <-- Raspberry Pi <-- Building Machine. - -Because you need to build coreboot and this takes a long time on a raspberry pi, this howto assumes that you have an additional laptop/PC which will be used as building machine. -The building machine will compile the coreboot ROm file and the raspberry pi is only used to read and write from and to the target device. - -## Links -I have looked at the following ressources to learn more about coreboot adn write this howto - -- https://www.coreboot.org/Board:lenovo/x230 -- https://github.com/bibanon/Coreboot-ThinkPads/wiki/Hardware-Flashing-with-Raspberry-Pi -- [Coreboot on the ThinkPad X220 with a Raspberry Pi](https://tylercipriani.com/blog/2016/11/13/coreboot-on-the-thinkpad-x220-with-a-raspberry-pi/) -- [Karl Cordes - How to flash Coreboot on X220](https://karlcordes.com/coreboot-x220/) - Gute Anleitung für Anschluss FlashClip an Pi -- [Johannes' Blog - Coreboot on X220](https://wej.k.vu/coreboot/coreboot_on_the_lenovo_thinkpad_x220/) -- [Coreboot X230]( https://blog.noq2.net/corebooting-thinkpad-x230.html) -- [Flashing Coreboot on the T430 with a Raspberry Pi](https://nm-projects.de/2017/08/flashing-coreboot-on-the-t430-with-a-raspberry-pi/) -- https://kennyballou.com/blog/2017/01/coreboot-x230/ - -Additional info has been provided by the Coreboot Mailinglist: - -- https://mail.coreboot.org/pipermail/coreboot/2017-September/085173.html -- https://mail.coreboot.org/pipermail/coreboot/2017-September/085182.html -- https://mail.coreboot.org/pipermail/coreboot/2017-September/085185.html - -## Hardware: -the following parts are needed to build a Coreboot flashing devices: - -- Raspberry Pi 3 ~ 35 Eur - https://www.amazon.de/dp/B01CD5VC92/ -- 32 GB SDCard ~ 17 Eur - https://www.amazon.de/dp/B073S8LQSL/ -- Jumper Cables ~ 7 Eur - https://www.amazon.de/dp/B072NSLB98/ -- Pomona 5250 8-Pin Flash Clip ~ 12 Eur - https://www.digikey.de/product-detail/de/pomona-electronics/5250/501-1311-ND/745102 - -## physical setup -using a Raspberry Pi 3 Model B V1.2 the GPIO Layout looks like this: -(Hint you can get a very good overview of the layout by entering the `pinout` command on your pi: -``` -,--------------------------------. -| oooooooooooooooooooo J8 +==== -| 1ooooooooooooooooooo | USB -| +==== -| Pi Model 3B V1.2 | -| +----+ +==== -| |D| |SoC | | USB -| |S| | | +==== -| |I| +----+ | -| |C| +====== -| |S| | Net -| pwr |HDMI| |I||A| +====== -`-| |--------| |----|V|-------' - -Revision : a02082 -SoC : BCM2837 -RAM : 1024Mb -Storage : MicroSD -USB ports : 4 (excluding power) -Ethernet ports : 1 -Wi-fi : True -Bluetooth : True -Camera ports (CSI) : 1 -Display ports (DSI): 1 - -J8: - 3V3 (1) (2) 5V - GPIO2 (3) (4) 5V - GPIO3 (5) (6) GND - GPIO4 (7) (8) GPIO14 - GND (9) (10) GPIO15 -GPIO17 (11) (12) GPIO18 -GPIO27 (13) (14) GND -GPIO22 (15) (16) GPIO23 - 3V3 (17) (18) GPIO24 -GPIO10 (19) (20) GND - GPIO9 (21) (22) GPIO25 -GPIO11 (23) (24) GPIO8 - GND (25) (26) GPIO7 - GPIO0 (27) (28) GPIO1 - GPIO5 (29) (30) GND - GPIO6 (31) (32) GPIO12 -GPIO13 (33) (34) GND -GPIO19 (35) (36) GPIO16 -GPIO26 (37) (38) GPIO20 - GND (39) (40) GPIO21 - -For further information, please refer to https://pinout.xyz/ -``` - -Layout of pins if you look on the pi and, the GPIO pins are located on the left side, so that USB and ethernet ports are at the top: -``` - | USB | | USB | | RJ45 | - | | | | | | - +-----+ +-----+ +------+ - -e +-----+ -d | o o <- GND -g | o o | -e | o o | - | o o | -o | o o | -f | o o | - | o o | -R | o o | -a CS -> o o <- CLK -s | o o <- MISO -p | o o <- MOSI -b | o o <- 3.3V -e | o o | -r | o o | -r | o o | -y | o o | - | o o | -P | o o | -i | o o | - | o o | - +-----+ -``` -We need to connect 6 pins to the Pomona SOIC8 5250 Test Clip using the jumper cables. -you can take any color you want, to make it simpler for you, I'll add the colors I have used: - -connect 6 jumper cables to the raspberry pi GPIO pins: - -- GND black -- CS green -- CLK gray -- MISO white -- MOSI purple -- 3.3V blue - -Now connect the other end of the jumper cables to the Pomona Clip: -``` - MOSI (purple) 5 =| |= 4 GND (black) - CLK (gray) 6 =| |= 3 NC (empty) - NC (empt 7 =| |= 2 MISO (white) -3.3V/VCC (blue) 8 =|_*|= 1 CS (green) - (dot on top of the chip) -``` - -## Procedure - -- Setting up Raspberry Pi -- Install FlashROM -- Connect Flash Clip to Raspberry Pi -- Disassemble X230 Laptop -- Backup existing ROM -- Setting up Coreboot on building machine -- Compile Coreboot -- Configure Coreboot -- Flash new ROM - -## Prepare Build machine -You can use another Qubes Laptop as Building machine. -1) Clone the Debian template -``` -qvm-clone debian-9 t-coreboot -``` -2) launch a terminal in this template an install the following packages -``` -sudo apt-get install git wget build-essential gnat flex bison libncurses5-dev zlib1g-dev libfreetype6-dev unifont python3 -``` -3) Create an AppVM bases on this template -Important: increase private storage size, as the build process and the git repositories need some storage capacity. -Example 10GB - - -## Setting up Raspberry Pi - -1. Download Noobs -2. Install Raspbian -3. Enable SSH - -## Install FlashROM on Raspberry Pi -Flashrom is used to read the current ROM from the Bios Chip and make a backup of it. -It will also be used to flash the new coreboot Bios. -1) Install build enviroment and dependencies for flashrom - ``` - sudo apt-get install libftdi1 libftdi-dev libusb-dev libpci-dev m4 bison flex libncurses5-dev libncurses5 build-essential pciutils usbutils libpci-dev libusb-dev libftdi1 libftdi-dev zlib1g-dev subversion libusb-1.0 gnat wget zlib1g-dev - ``` - Problem: some packackes could not be installed: - [...] - Package flex is not available, but is referred to by another package. - This may mean that the package is missing, has been obsoleted, or - is only available from another source - [...] - - Solution: - delete all files in /var/lib/apt/lists -2) Download and install Flashrom - ``` - git clone https://github.com/flashrom/flashrom - cd flashrom - make - sudo make install - ``` -3) Enable the SPI device on the Raspberry Pi. - ``` - sudo raspi-config - # In the menu choose: - # - 5 Interfacing Options Configure connections to peripherals - # - P4 SPI Enable/Disable automatic loading of SPI kernel module - # - Would you like the SPI interface to be enabled? - # - Yes - sudo reboot - ``` -4) Modprobe SPI driver - ``` - sudo modprobe spi_bcm2835 - sudo modprobe spidev - ``` - - -## Prepare Build machine (the AppVM NOT the template) -### Setup Coreboot -Cloning the coreboot git. and recursively clone the necessary other gits. -``` -git clone --recursive https://github.com/coreboot/coreboot -cd ~/coreboot/3rdparty -git clone http://review.coreboot.org/p/blobs.git -``` - -### Setup Extraction Tool for binary blobs -Build and install the extraction tool for the binary blobs. -``` -cd ~/coreboot/util/ifdtool -make -sudo make install -``` - -## on Raspberry Pi -read existing BIOS and transfer it to build machine - -1) Read upper bios chip (4MB) - ``` - pi@raspberrypi:~ $ flashrom -p linux_spi:dev=/dev/spidev0.0,spispeed=1000 -c "MX25L3206E/MX25L3208E" -r x230-bios-top1.bin - flashrom p1.0-69-g3f7e341 on Linux 4.14.30-v7+ (armv7l) - flashrom is free software, get the source code at https://flashrom.org - - Using clock_gettime for delay loops (clk_id: 1, resolution: 1ns). - Found Macronix flash chip "MX25L3205D/MX25L3208D" (4096 kB, SPI) on linux_spi. - Reading flash... done. - - ``` - Repeat this two more times creating: x230-bios-top2.bin and x230-bios-top3.bin - -2) Read lower bios chip (8MB) - ``` - pi@raspberrypi:~ $ flashrom -p linux_spi:dev=/dev/spidev0.0,spispeed=1000 -c "MX25L6406E/MX25L6408E" -r x230-bios-bottom1.bin - flashrom p1.0-69-g3f7e341 on Linux 4.14.30-v7+ (armv7l) - flashrom is free software, get the source code at https://flashrom.org - - Using clock_gettime for delay loops (clk_id: 1, resolution: 1ns). - Found Eon flash chip "EN25QH64" (8192 kB, SPI) on linux_spi. - Reading flash... done. - - ``` - Repeat this 2 more times and create two more copies x230-bios-bottom2.bin and x230-bios-bottom3.bin - -3) verify that all files are identical - for the top 4MB bios chip: - ``` - pi@raspberrypi:~ $ md5sum x230-bios-top?.bin - 54bfde566dffa17760a6115f27309681 x230-bios-top1.bin - 54bfde566dffa17760a6115f27309681 x230-bios-top2.bin - 54bfde566dffa17760a6115f27309681 x230-bios-top3.bin - - ``` - for the lower 8MB bios chip: - ``` - pi@raspberrypi:~ $ md5sum x230-bios-bottom?.bin - ac7dffb64f7d11ec9b13cc9449e48a64 x230-bios-bottom1.bin - ac7dffb64f7d11ec9b13cc9449e48a64 x230-bios-bottom2.bin - ac7dffb64f7d11ec9b13cc9449e48a64 x230-bios-bottom3.bin - - ``` - -## on build machine: copy ROM files from raspberry pi - -4) Copy the ROMs from raspberry pi to the "build machine" - ``` - user@my-coreboot:~/coreboot/ROM$ scp pi@192.168.200.107:~/x230-bios-* . - pi@192.168.200.107's password: - x230-bios-bottom1.bin 100% 8192KB 10.8MB/s 00:00 - x230-bios-top1.bin 100% 4096KB 11.1MB/s 00:00 - ``` - -5) Merge two files into one ROM file - ``` - cat x230-bios-bottom1.bin x230-bios-top1.bin > x230-bios.rom - ``` - -6) move all rom files to ~/coreboot/ROM - ``` - mkdir ~/coreboot/ROM - mv x230-* ~/coreboot/ROM - ``` - - -### Extract Blobs from exracted ROM -``` -user@my-coreboot:~/coreboot/ROM$ cd ~/coreboot/ROM -user@my-coreboot:~/coreboot/ROM$ ifdtool -x x230-bios.rom -File x230-bios-bottom1.bin is 8388608 bytes - Flash Region 0 (Flash Descriptor): 00000000 - 00000fff - Flash Region 1 (BIOS): 00500000 - 00bfffff -Error while writing: Success - Flash Region 2 (Intel ME): 00003000 - 004fffff - Flash Region 3 (GbE): 00001000 - 00002fff - Flash Region 4 (Platform Data): 00fff000 - 00000fff (unused) -``` -you will now find the following files: -``` -user@my-coreboot:~/coreboot/ROM$ ls -la -total 36872 -drwxr-xr-x 2 user user 4096 Apr 6 00:48 . -drwxr-xr-x 10 user user 4096 Apr 6 00:43 .. --rw-r--r-- 1 user user 4096 Apr 6 00:48 flashregion_0_flashdescriptor.bin --rw-r--r-- 1 user user 7340032 Apr 6 00:48 flashregion_1_bios.bin --rw-r--r-- 1 user user 5230592 Apr 6 00:48 flashregion_2_intel_me.bin --rw-r--r-- 1 user user 8192 Apr 6 00:48 flashregion_3_gbe.bin --rw-r--r-- 1 user user 12582912 Apr 6 00:30 x230-bios.bin --rw-r--r-- 1 user user 8388608 Apr 5 23:38 x230-bios-bottom1.bin --rw-r--r-- 1 user user 4194304 Apr 5 23:38 x230-bios-top1.bin -``` - -## Extract VGA Blob -https://www.coreboot.org/VGA_support#UEFI_Method - -``` -cd ~/coreboot -sudo apt-get install qt5-default -git clone http://github.com/LongSoft/UEFITool.git -cd UEFITool -qmake -make -``` -Start UEFITool -``` -./UEFITool -``` -File > Open BIOS Image File -Open the ROM-file from the 4MB BIOS-Chip (x230-bios-top1.bin) or the merged ROM (x230-bios.bin) - -will generate the following messages: -"parseVolume: unknown file system FFF12B8D-7696-4C8B-A985-2747075B4F50 -parseBios: volume size stored in header 61000h (397312) differs from calculated using block map 40000h (262144) -parseVolume: unknown file system 00504624-8A59-4EEB-BD0F-6B36E96128E0 -parseBios: volume size stored in header 2F000h (192512) differs from calculated using block map 30000h (196608) -parseFile: invalid data checksum" - - -- Hit CTRL+F (Search...), 3rd Tab (Text) -- Search for: VGA Compatible BIOS - (Uncheck Unicode) -- Will show the following message in the lower part of the window: - ASCII text "VGA Compatible BIOS" found in Raw section at offset 22h -- Double click on the line in the message windows which bring you to the raw section -- Right Click on "Raw section" and choose "Extract Body" -- Save file as ~/coreboot/ROM/vga.rom - -## Copy the blobs to coreboot dir - -Create the "blob-directory" where coreboot looks for BLOBs: -``` -mkdir -p ~/coreboot/3rdparty/blobs/mainboard/lenovo/x230 -``` -In order to have the blobs available for coreboot the easiest way is to rename and copy them to the default locations: -``` -cp ~/coreboot/ROM/flashregion_0_flashdescriptor.bin ~/coreboot/3rdparty/blobs/mainboard/lenovo/x230/descriptor.bin -cp ~/coreboot/ROM/flashregion_2_intel_me.bin ~/coreboot/3rdparty/blobs/mainboard/lenovo/x230/me.bin -cp ~/coreboot/ROM/flashregion_3_gbe.bin ~/coreboot/3rdparty/blobs/mainboard/lenovo/x230/gbe.bin -cp ~/coreboot/ROM/vga.rom ~/coreboot/3rdparty/blobs/mainboard/lenovo/x230/pci8086,0166.rom -``` - -## Configure and build Coreboot - -1) Launch Configuration menu - ``` - cd ~/coreboot/ - make nconfig - ``` - - Enter to open Submenu, Escape to switch back. - F6 saves config to /home/user/coreboot/.config - F9 quits config menu - - ###FIXME: needs more information about which options to choose and how to import the Blobs - As a workarround, look at the config-file from my succesfull X230 Coreboot installation. - This file has to be places in ~/coreboot/.config - -2) build build-chain using 7 from total 8 cores on my W540 (adapt this to your possibilities) - and finally build coreboot - ``` - make crossgcc-i386 CPUS=7 - make iasl - make - ``` -The coreboot file should be located at ~/coreboot/build/coreboot.rom - - -## Split coreboot ROM -after building coreboot you need to the 12mb file into a 4mb and 8mb file. -``` -mkdir ~/coreboot/ROM-ready -# Split first 8MB of coreboot.rom (bottom-chip) -dd if=~/coreboot/build/coreboot.rom of=~/coreboot/ROM-ready/x230-coreboot-8mb.rom bs=1024 count=$[1024*8] skip=0 - -# Split last 4MB of coreboot.rom (top-chip) -dd if=~/coreboot/build/coreboot.rom of=~/coreboot/ROM-ready/x230-coreboot-4mb.rom bs=1024 count=$[1024*4] skip=$[1024*8] - -``` - -## Copy ROM to raspberry pi and flash -Transfer the two new ROM files over to the raspberry pi -``` -scp x230-coreboot-* pi@192.168.200.107:~/ -``` -I have moved the coreboot-ROM files to a new directory ~/ROM-ready on the raspberry pi - - -Logon to the pi and flash both chips: -``` -# write top chip (4MB) -pi@raspberrypi:~/ROM-ready $ sudo flashrom -p linux_spi:dev=/dev/spidev0.0,spispeed=1000 -c "MX25L3206E/MX25L3208E" -w x230-coreboot-4mb.rom -flashrom p1.0-69-g3f7e341 on Linux 4.14.30-v7+ (armv7l) -flashrom is free software, get the source code at https://flashrom.org - -Using clock_gettime for delay loops (clk_id: 1, resolution: 1ns). -Found Macronix flash chip "MX25L3205D/MX25L3208D" (4096 kB, SPI) on linux_spi. -Reading old flash chip contents... done. -Erasing and writing flash chip... Erase/write done. -Verifying flash... VERIFIED. - -# write bottom chip (8MB) -pi@raspberrypi:~/ROM-ready $ sudo flashrom -p linux_spi:dev=/dev/spidev0.0,spispeed=1000 -c "MX25L6406E/MX25L6408E" -w x230-coreboot-8mb.rom -flashrom p1.0-69-g3f7e341 on Linux 4.14.30-v7+ (armv7l) -flashrom is free software, get the source code at https://flashrom.org - -Using clock_gettime for delay loops (clk_id: 1, resolution: 1ns). -Found Eon flash chip "EN25QH64" (8192 kB, SPI) on linux_spi. -Reading old flash chip contents... done. -Erasing and writing flash chip... Erase/write done. -Verifying flash... VERIFIED. - -``` -## Test drive -now it is time to cross fingers and try if you was able to flash coreboot. -Remove the Pomodo-Clip, put your keyboard back, put your battery in and power on. -In case you run into any problems, you can always reflash your stock rom. - -If you have comments or need help, feel free to contact the contributors of this howto: -- https://github.com/one7two99 -- ... +This content has moved to [Qubes Forum: Community Guides](https://forum.qubes-os.org/c/guides/14). [Learn more.](https://forum.qubes-os.org/t/announcement-qubes-community-project-has-been-migrated-to-the-forum/20367/) diff --git a/docs/customization/awesomewm.md b/docs/customization/awesomewm.md index 5e6efc0..deee4c7 100644 --- a/docs/customization/awesomewm.md +++ b/docs/customization/awesomewm.md @@ -1,266 +1 @@ -# AwesomeWM Customizations - -This page focuses on [AwesomeWM](https://awesomewm.org) customizations specific to Qubes OS. For generic AwesomeWM customizations you might want to have a look at the [AwesomeWM website](https://awesomewm.org). - -Customizations for AwesomeWM are usually done at `~/.config/awesome/rc.lua`. The default file can be found at `/etc/xdg/awesome/rc.lua`. - -## Application menu - -Starting from Qubes 4.0 application menu entries specific to AwesomeWM can be put into `~/.config/awesome/xdg-menu/` following the freedesktop standard. The folder might have to be created. - -## Focus steal hardening - -The default Qubes OS AwesomeWM installation comes with the defaults set by the AwesomeWM developers for focus changes. Some users may want more tight control over window focus changes - especially since focus changes can have security implications when sensitive data is provided to an incorrect application or even Qube. - -### Definition - -For the below example we'll define _wanted focus changes_ as one of the below: - -* mouse move & click afterwards -* workspace/tag change -* pre-defined key combinations for focus changes (e.g. Mod-j & Mod-k) -* focused window moved to other tag 1 -* focused window closed 1 -* new window created in a workspace with only unfocused windows or in an empty workspace - -(1 These are allowed to cause a focus switch to another window according to a predefined algorithm as otherwise no window would be focused.) - -Everything else is considered an unwanted _focus steal_. - -In particular the following events are not meant to cause a focus change: - -* new window created in a workspace with a focused window -* unfocused window closed -* unfocused window moved to another tag/workspace -* application request -* mouse move without click (sloppy focus) - -For the below example other requests from applications to the window manager are meant to be ignored in general as well, e.g.: - -* windows shouldn't be able to maximize themselves without the user giving a respective command to the WM (simple test: Firefox F11 next to another window) -* windows shouldn't be able to change their size themselves -* windows shouldn't be able to modify their borders in any way - -Users may want to adjust their definitions and respective implementations according to their needs. - -### Implementation - -The implementation may be specific to the AwesomeWM version you're running. This guide refers to AwesomeWM version 4.3 which is available to Qubes 4.1 users. - -Please keep in mind that this guide may not be conclusive. Your mileage may vary. - -#### Remove unwanted focus changing key bindings - -The mouse bindings - -```lua -awful.button({ }, 4, awful.tag.viewnext), -awful.button({ }, 5, awful.tag.viewprev) -``` - -in the default _rc.lua_ may cause tag and thus focus changes without keyboard interaction and tend to happen accidentally. This doesn't suit our definition from above and should therefore be removed or commented out. - -#### Adjust rules for new windows - -The default window/client rule allows certain focus changes whenever new windows are created via `focus = awful.client.focus.filter`. These changes can be prevented entirely by setting `focus = false`. - -Alternatively users may provide their own focus filter functions. - -#### Never hide borders - -By default AwesomeWM may hide window borders incl. the Qubes colors for fullscreen or maximized windows. In order to prevent that, put the following two lines at the bottom of your _rc.lua_: - -```lua -beautiful.fullscreen_hide_border = false -beautiful.maximized_hide_border = false -``` - -#### Disable sloppy focus - -In your _rc.lua_ you'll find a section such as - -```lua --- Enable sloppy focus, so that focus follows mouse. -client.connect_signal("mouse::enter", function(c) - c:emit_signal("request::activate", "mouse_enter", {raise = false}) -end) -``` - -These enable _sloppy focus_ aka focus changes on mouse movements (without clicking) and should be removed or commented out to disable that behaviour. - -#### Enable right-click focus changes - -In your _rc.lua_ you should find a section which enables left-click focus changes such as - -```lua - awful.button({ }, 1, function (c) - c:emit_signal("request::activate", "mouse_click", {raise = true}) - end), -``` - -Add the following section below to enable focus changes on right mouse clicks: - -```lua - awful.button({ }, 3, function (c) - c:emit_signal("request::activate", "mouse_click", {raise = true}) - end), -``` - -If you want other mouse buttons to change the focus as well, feel free to add further entries (0 = all mouse buttons). - -#### Ignore requests from applications to the window manager - -Applications and running Qube windows may request from AwesomeWM to become focused. - -Handling of such requests is currently mostly implemented by AwesomeWM in the file `/usr/share/awesome/lib/awful/ewmh.lua`. You can either comment out the respective `client.connect_singal()` lines in that file (it will change back after each AwesomeWM update though) or disconnect the signals in your _rc.lua_ as well as use the built-in filter functionality. - -To do the latter, add the following lines to the end of your _rc.lua_: - -```lua -local ewmh = require("awful.ewmh") -ewmh.add_activate_filter(function(c, context, hints) return false end, "ewmh") --ignore client requests to become focused -client.disconnect_signal("request::urgent", ewmh.urgent) --ignore client requests to become an "urgent" window -client.disconnect_signal("request::geometry", ewmh.merge_maximization) --ignore client maximization requests -client.disconnect_signal("request::geometry", ewmh.client_geometry_requests) --ignore clients requesting to move themselves -``` - -#### Change the autofocus implementation - -The line `require("awful.autofocus")` in your _rc.lua_ loads a module that moves the focus to another window whenever a window is moved to another workspace or closed. In the AwesomeWM default implementation, this module keeps track of the order in which windows were focused and sets the focus to the last focused one whenever the currently focused window disappears. - -Some users may want to modify that default behaviour. - -In order to do that, you can copy the file `/usr/share/awesome/lib/awful/autofocus.lua` to e.g. `~/.config/awesome/autofocus_custom.lua` and replace the line mentioned above with `require("autofocus_custom")`. - -Then you can customise the focus behavior. - -For example, the following will make the focus move to the window under the mouse cursor whenever focus is lost and only use the history on tag switches: - -```lua ---------------------------------------------------------------------------- ---- Autofocus functions. --- --- When loaded, this module makes sure that there's always a client that will --- have focus on events such as tag switching, client unmanaging, etc. --- --- @author Julien Danjou <julien@danjou.info> --- @copyright 2009 Julien Danjou --- @module awful.autofocus ---------------------------------------------------------------------------- - -local client = client -local aclient = require("awful.client") -local ascreen = require("awful.screen") -local timer = require("gears.timer") - -local function filter_sticky(c) - return not c.sticky and aclient.focus.filter(c) -end - ---- Give focus when clients appear/disappear. --- --- @param obj An object that should have a .screen property. -function check_focus(obj) - if obj.screen == nil then return end - if not obj.screen.valid then return end - -- When no visible client has the focus... - if not client.focus or not client.focus:isvisible() then - local c = aclient.focus.history.get(screen[obj.screen], 0, filter_sticky) - if not c then - c = aclient.focus.history.get(screen[obj.screen], 0, aclient.focus.filter) - end - if c then - c:emit_signal("request::activate", "autofocus.check_focus", - {raise=false}) - end - end -end - ---- Check client focus (delayed). --- @param obj An object that should have a .screen property. -local function check_focus_delayed(obj) - timer.delayed_call(check_focus, {screen = obj.screen}) -end - ---- Give focus on tag selection change. --- --- @param tag A tag object -function check_focus_tag(t) - local s = t.screen - if (not s) or (not s.valid) then return end - s = screen[s] - check_focus({ screen = s }) - if client.focus and screen[client.focus.screen] ~= s then - local c = aclient.focus.history.get(s, 0, filter_sticky) - if not c then - c = aclient.focus.history.get(s, 0, aclient.focus.filter) - end - if c then - c:emit_signal("request::activate", "autofocus.check_focus_tag", - {raise=false}) - end - end -end - --- Clear any focus. -function clear_focus() - client.focus = nil -end - -local pending = false -local glib = require("lgi").GLib - ---focus the window under the mouse, if nothing is focused ---idea from https://github.com/awesomeWM/awesome/issues/2433 ---fallback: true|false - fall back to the focus history, if the mouse points --- nowhere (recommended default: false) -function check_focus_mouse(fallback) - if not pending then - pending = true - glib.idle_add(glib.PRIORITY_DEFAULT_IDLE, function() - pending = false - if not client.focus then - local c = mouse.current_client - if c then - client.focus = c - else - if fallback then - local t = ascreen.focused().selected_tag - if t then - check_focus_tag(t) - end - end - end - end - return false - end) - end -end - ---further delayed variant of check_focus_mouse(), required for just created windows -local function check_focus_mouse_delayed() - timer.delayed_call(check_focus_mouse) -end - ---make the focus follow the mouse on the below events, if nothing else is focused -client.connect_signal("manage", check_focus_mouse_delayed) --for empty workspaces or workspace without focused window -client.connect_signal("unmanage", check_focus_mouse_delayed) -client.connect_signal("tagged", check_focus_mouse_delayed) -client.connect_signal("untagged", check_focus_mouse_delayed) -client.connect_signal("property::hidden", check_focus_mouse_delayed) -client.connect_signal("property::minimized", check_focus_mouse_delayed) -client.connect_signal("property::sticky", check_focus_mouse_delayed) - ---use history on tag switch: -tag.connect_signal("property::selected", function (t) - timer.delayed_call(check_focus_tag, t) -end) -``` - -You might also want to add the `check_focus_mouse()` function to your Mod-j and Mod-k implementations to be able to obtain a focused window even if no window happens to be focused. - -# Troubleshooting - -Issues with e.g. your `rc.lua` configuration can be identified in dom0 from the `~/.xsession-errors` log. - -If AwesomeWM encounters an error, it'll also either display a red notification or return you to the display manager (usually the login screen). +This content has moved to [Qubes Forum: Community Guides](https://forum.qubes-os.org/c/guides/14). [Learn more.](https://forum.qubes-os.org/t/announcement-qubes-community-project-has-been-migrated-to-the-forum/20367/) diff --git a/docs/customization/dark-theme.md b/docs/customization/dark-theme.md index 88a6c83..deee4c7 100644 --- a/docs/customization/dark-theme.md +++ b/docs/customization/dark-theme.md @@ -1,182 +1 @@ - -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:** Changing the `Window Decorations` from `Plastik for Qubes` will remove the border color and the VM name. The problem with `Plastik for Qubes` is that it does not overwrite the background and text color for Minimize, Maximize and Close buttons. The three buttons are therefore 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) -========================================================== - -Almost all Qubes VMs use default applications based on the GTK toolkit. Therefore the description below is focused on tools from the Gnome Desktop Environment. - -Using "Gnome-Tweak-Tool" ------------------------- - -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 TemplateVM back to Archlinux. - -1. Start VM - - **Note:** Remember that if you want to make the change persistent, the change needs to be made in the TemplateVM, not the AppVM. - -2. Install `Gnome-Tweak-Tool` - - - Fedora - - sudo dnf install gnome-tweak-tool - - - Debian - - sudo apt-get install gnome-tweak-tool - -3. *(Only AppVM)* Stop TemplateVM and start AppVM - -4. 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) - -5. 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) - -6. *(Optional)* Modify Firefox - - **Note:** Firefox uses GTK style settings by default. This can create side effects such as unusable forms or search fields. One way to avoid this is to add the following line to `/rw/config/rc.local`: - - sed -i.bak "s/Exec=firefox %u/Exec=bash -c 'GTK_THEME=Adwaita:light firefox %u'/g" /usr/share/applications/firefox.desktop - -7. Restart VM or all applications - -Manually --------- - -Manually works for Debian, Fedora and Archlinux. - -1. Start VM - - **Note:** Remember that if you want to make the change persistent, the change needs to be made in the TemplateVM, not the AppVM. - -2. Enable `Global Dark Theme` - - 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 - -3. Follow steps 6 and 7 in: Using `Gnome-Tweak-Tool` +This content has moved to [Qubes Forum: Community Guides](https://forum.qubes-os.org/c/guides/14). [Learn more.](https://forum.qubes-os.org/t/announcement-qubes-community-project-has-been-migrated-to-the-forum/20367/) diff --git a/docs/customization/dpi-scaling.md b/docs/customization/dpi-scaling.md index 243d125..deee4c7 100644 --- a/docs/customization/dpi-scaling.md +++ b/docs/customization/dpi-scaling.md @@ -1,185 +1 @@ -DPI scaling -=========== - -Qubes OS passes on dom0's screen resolution to VMs (this can be seen in the output of `xrandr`) but doesn't pass on dom0's dpi value. Recent distributions have automatic scaling depending on the screen's resolution (eg. in fedora if the screen resolution is at least 192dpi and the screen height is greater than 1200 pixels) but for a variety of reasons one may have to set a custom dpi scaling value. - - -Dom0 ----- - -The simplest way to set dpi scaling in dom0 is to use the desktop environment's custom dpi feature: - -- Xfce: Qubes Menu → System Tools → Appearance → Fonts tab: Custom DPI setting: `xxx` -- KDE: Qubes Menu → System Settings → Font → Force font dpi: `xxx` -- i3: add `Xft.dpi: xxx` to `/home/user/.Xresources' in dom0 - -Replace `xxx` with a number that fits your setup and is a multiple of 6, as numbers that aren't sometimes result in annoying rounding errors that cause adjacent bitmap font sizes to not increment and decrement linearly. - -### Qubes Applications - -Qubes applications (e.g. Qubes Create VM, etc.) don't scale automatically, to solve this issue it is possible to set the `QT_SCALE_FACTOR` variables as described -[here](https://doc.qt.io/qt-6/highdpi.html#qt-scale-factor3). To test these -values first, open a terminal and type: - -~~~ -QT_SCALE_FACTOR=1.8 qubes-global-settings -~~~ - -You can try change the values for `QT_SCALE_FACTOR` to your -liking. - -Once you confirmed that this is working, you can make these settings permanent -by creating a file `/etc/profile.d/dpi_QT.sh` (in dom0) with -the following content and your own values: - -~~~ -#!/bin/sh - -export QT_SCALE_FACTOR=1.8 -~~~ - -Then make the script executable with - -~~~ -sudo chmod +x /etc/profile.d/dpi_QT.sh -~~~ - -And logout and login again to see the results. - - -VMs ---- - -The procedure for setting DPI scaling is different depending on whether gnome settings daemon is running or not: - -- if the daemon is stopped/not installed, applications honor the `Xft.dpi` [X resource](https://en.wikipedia.org/wiki/X_resources) which we can then use for scaling. -- if the daemon is running (`/usr/libexec/gsd-xsettings` process in Fedora), applications are prevented from using the `Xft.dpi` resource and `dconf` values have to set. - -Notes: -- the official `fedora-xx` template has the `gnome-settings-daemon` rpm installed by default while the `fedora-xx-minimal` template doesn't. -- DPI scaling with `xterm` (or any glib apps) requires the use of a xft font: - - for `xterm`, ctrl - right click in the terminal's windows and select 'TrueType Fonts' (make sure you have such fonts installed). - - or more generally, set the `faceName` Xresource, eg.: - - `*faceName: DejaVu Sans Mono:size=14:antialias=true` - - You may do so temporarily with the `xrdb -merge` command, or permanently in a `Xresources` file (see section below). - - -### VMs without gnome settings daemon ### - -Get the current value of `Xft.dpi`: - -~~~ -xrdb -query | grep Xft.dpi -~~~ - -Test with a different dpi value: in a terminal issue the following command and then start an application to check that the menus/fonts' size is increased/decreased; replace '144' with the value set in dom0 (it's possible to set a different value in VMs though): - -~~~ -echo Xft.dpi: 144 | xrdb -merge -~~~ - -Once you found a value that fits your setup you'll likely want to permanently set the `Xft.dpi` resource. You can do so on a per-template (system-wide) or per-VM basis: - -- add (or modify) `Xft.dpi: xxx` in the TemplateVM's Xresource file (`/etc/X11/Xresources` or `/etc/X11/Xresources/x11-common` for whonix-ws-template). -- or, add `Xft.dpi: xxx` to `$HOME/.Xresources` in each AppVM. - - -### VMs with gnome settings daemon ### - -We'll set the `scaling-factor` and `text-scaling-factor` dconf values in the `org.gnome.desktop.interface` schema. - -Get the current values: - -~~~ -gsettings get org.gnome.desktop.interface scaling-factor -gsettings get org.gnome.desktop.interface text-scaling-factor -~~~ - -Test with different values; notes: -- windows and menu/fonts should be resized dynamically -- when running the commands below the values will be automatically written to `$HOME/.config/dconf/user` -- replace `2` and `0.75` to suit your needs (`scaling-factor` **must** be an integer though) - -~~~ -gsettings set org.gnome.desktop.interface scaling-factor 2 -gsettings set org.gnome.desktop.interface text-scaling-factor 0.75 -~~~ - -If `gsd-xsettings` is running but nothing happens, examine the output of `dconf dump /`. If needed, reset any `xsettings` override: - -~~~ -gsettings reset org.gnome.settings-daemon.plugins.xsettings overrides -~~~ - -To store the dconf values system-wide - eg. when customizing templateVMs - copy the following text into `/etc/dconf/db/local.d/dpi` (replace `2` and `0.75` with your values): - -~~~ -[org/gnome/desktop/interface] -scaling-factor=uint32 2 -text-scaling-factor=0.75 -~~~ - -Then run `dconf update`. - -Note: the `scaling-factor` and `text-scaling-factor` values might already be set in an AppVM's user profile, in which case they'll override the system-wide ones. To use system-wide values, reset the user values like so in the AppVM(s): - -~~~ -gsettings reset org.gnome.desktop.interface scaling-factor -gsettings reset org.gnome.desktop.interface text-scaling-factor -~~~ - - -For more information on setting system-wide dconf values see [this page](https://help.gnome.org/admin/system-admin-guide/stable/dconf-custom-defaults.html.en). - -Troubleshooting -=============== - -Firefox and other GTK3 applications ------------------------------------ - -Even when setting the correct dpi values, some applications might have very -small icons or similar elements. This usually happens in Firefox for example. - -To mitigate this issue it is possible to set the `GDK_SCALE` and `GDK_DPI_SCALE` -variables as described -[here](https://wiki.archlinux.org/title/HiDPI#GDK_3_(GTK_3). To test these -values first, open a terminal and type: - -~~~ -export GDK_SCALE=2 -export GDK_DPI_SCALE=0.5 -firefox -~~~ - -You can try change the values for `GDK_SCALE` and `GDK_DPI_SCALE` to your -liking, but `GDK_SCALE` needs to be an integer value. - -Once you confirmed that this is working, you can make these settings permanent -by creating a file `/etc/profile.d/dpi_GDK.sh` (ideally in the template VM) with -the following content and your own values: - -~~~ -#!/bin/sh - -export GDK_SCALE=2 -export GDK_DPI_SCALE=0.5 -~~~ - - -Then make the script executable with - -~~~ -sudo chmod +x /etc/profile.d/dpi_GDK.sh -~~~ - -Resources -========= - -- ARCH Linux HiDPI wiki page: https://wiki.archlinux.org/index.php/HiDPI -- Gnome HiDPI wiki page: https://wiki.gnome.org/HowDoI/HiDpi -- Mozilla DPI-related Font Size Issues on Unix: https://www-archive.mozilla.org/unix/dpi.html -- Related official issue: https://github.com/QubesOS/qubes-issues/issues/1951 - -`Contributors: @taradiddles` +This content has moved to [Qubes Forum: Community Guides](https://forum.qubes-os.org/c/guides/14). [Learn more.](https://forum.qubes-os.org/t/announcement-qubes-community-project-has-been-migrated-to-the-forum/20367/) diff --git a/docs/customization/fedora-minimal-template-customization.md b/docs/customization/fedora-minimal-template-customization.md index 674dc9c..deee4c7 100644 --- a/docs/customization/fedora-minimal-template-customization.md +++ b/docs/customization/fedora-minimal-template-customization.md @@ -1,288 +1 @@ - -FEDORA Packages Recommendations -====================== - -(starting from a minimal template) - -Template installation ------------------------------- - -> [dom0]#qubes-dom0-update qubes-template-fedora-26-minimal - - -*Note*: If you have doubts about a set of tools or package you want to install, start installing and testing it in an AppVM. -You can then reproduce it later in your TemplateVM if you are satisfied. -That is the template philosophy in QubesOS. - -For more information on the uses of a minimal template read [this page][Minimal]. - -Standard tools installation -================ - -Administration (documented) ---------------------------------------------- - -> sudo pciutils vim-minimal less tcpdump telnet psmisc nmap nmap-ncat usbutils - -*Notes*: nmap can be used to discover hosts on a network (nmap -sP [network]), especially if you are inside a Microsoft network, because your AppVM will be protected/NATted behind the Qubes firewall. -(Microsoft / home networks make heavy use of autodiscovery technologies which require clients to be in the same local network (no firewall/no NAT), eg: your printer.) - -Some recommendations here: check your current network using the Network manager applet (eg: 192.168.1.65). -Then run nmap in your current AppVM/TemplateVM to search for the selected printer/equipment: - nmap -sP 192.168.1.-. -Don't forget to temporarily allow traffic via the Qubes Firewall if you are doing this in a TemplateVM. - -Administration (undocumented) -------------------------------------------------- - -> openssh keepassx openssl gnome-keyring man - -Dependency note: keepassx rely on qt which takes ~30MB - -Network VM (documented) ----------------------------------------- - -> NetworkManager NetworkManager-wifi network-manager-applet wireless-tools dbus-x11 tar tinyproxy iptables - -Network VM (undocumented) --------------------------------------------- - -> which dconf dconf-editor - -*Notes*: which is required for autostart scripts - -*Notes*: dconf is required to remember the VM settings that are changed (the gsetting backend will be in memory only if gconf is not installed). - -Network VM (manual operations - documented) ------------------------------------------------------------------------- - -Search for wireless firmware matching your wireless card (to be launched in network VM) - -> lspci; dnf search firmware - -ProxyVM/NetworkVM for 3G Modems --------------------------------------------- - -> ModemManager NetworkManager-wwan usb_modeswitch modem-manager-gui - -Dependency note: modem-manager-gui relies on webkit-gtk and is optional (NetworkManager can handle the modem alone) - -Source: [3GMODEM] - -ProxyVM for VPNs --------------------------------------------- - -Search for a VPN package for your particular vpn solution then [configure][VPNNM] NetworkManager - -> dnf search NetworkManager [openvpn\|openconnect\|openswat\|...] - -OR - -Refer to [this guide][VPN] which includes instructions for failsafe anti-leak VPN configuration using CLI scripts. (An early discussion about OpenVPN configuration can be viewed [here][OPENVPNSETUP].) Required packages will be `iptables` in addition to VPN software such as `openvpn`. - - -Printer Setup --------------------------------------------- - -> system-config-printer system-config-printer-applet cups - -Dependency Note: depends on python3 + python3 additional libraries which takes more than 40 M once installed. - -Dependency Note: cups depends on ghostscript and require installing additional printing fonts (not documented here), so it can takes several dozen of MB - -Manual operations ---------------------------- - -- Don't forget to restart your TemplateVM or only the cups service when you installed cups (systemctl start cups) - -- First you need to search for your printer. If you don't know its name or IP, search for it using nmap: check your current network using the Network manager applet (eg: 192.168.1.65). Then run nmap in your current AppVM/TemplateVM to search for the selected printer/equipement: nmap -sP 192.168.1.-. Don't forget to temporarily allow traffic via the Qubes Firewall if you are inside a TemplateVM. - -- Once you identified your printer, run system-config-printer GUI to install your printer - -- You may need to cancel the operation to install more adapted printer drivers (eg: if the driver cannot be found automatically). Use dnf search printername to find potential drivers (eg dnf search photosmart) - -GUI recommendations -====================== - -Lightweight packages recommendations ---------------------------------------------------------------- - -> lxterminal dejavu-sans-mono-fonts dejavu-sans-fonts gnome-settings-daemon - -*Note*: You need to install sans-mono fonts for the terminal or it will be unreadable (overlapping characters....), while the sans fonts are just to get nicer GUI menus. - -*Scite* is a nice notepad that can also highlight scripts with very light dependencies -> scite - -*Meld* allows easy comparison of two text files/ two configuration files. - -> meld - -*Thunar* is a light file manager usually used by xfce - -> thunar thunar-volman ntfs-3g - -Dependency Note: xfce4 dependencies (but still quite light ~1.4M downloads) - -Miscellaneous packages --------------------------- - -*pycairo* package is needed for file's contextual menu "Send to VM" to function (to actually popup dialog box and enter VM's name where the file will be sent to). - -*pinentry-gtk* package is responsible for pop-up dialog window where you enter password for your password protected gpg key. -Install this package in the qube holding your password protected gpg keys. -If you do not use password protected gpg keys, there is no need to install this package. - -GUI themes ------------------ - -Managing GUI theme / appearance is often complex because when you do not want to depend on a specific desktop system. - -For this reason, we need to customize themes for each GUI framework that our application depends on. - -This often includes GTK2, GTK3 (which us a different configuration/themes than GTK2), Qt. - -The appearance of Windows can only be changed in dom0, however, the appearance of all buttons, menus, icons, widgets are specific to each AppVM. - -### Packages - -Choose theme packages for each framework. I recommend the following documentation [THEMEPACKAGES] - -> clearlooks-phenix-gtk2-theme clearlooks-phenix-gtk3-theme - -You can search for other themes using `dnf search theme gtk`. - -You can check your currently installed theme packages (to eventually remove them) using `rpm -qa | grep theme`. - -### Tweaking theme and appearance - -First you can get an insight of installed Gtk theme and see how it will appear using lxappearance. - -I recommend not applying settings using lxappearance (do not click on apply) because it will create multiple configuration files. - -To remove these files, follow cleanup notes. - -#### Cleanup notes - -~~~ -rm ~/.gtkrc-2.0 -rm ~/.icons/default/index.theme -rm ~/.config/gtk-3.0/settings.ini -rm ~/.config/Trolltech.conf -~~~ - -Cleaning the whole dconf settings is also possible by removing the following file. Please note that it will remove all preferences set for gnome application (not only the themes) - -~~~ -rm ~/.config/dconf/user -~~~ - -*Note*: lxappearance only has an effect on gtk3 themes so it won't work to change gtk2 themes (used by Firefox, Thunderbird ...). - However, it is very lightweight and can be used to identify the name and look of themes you are interested in. - Once you have the name, you can apply it using gsetting command line or gconf-editor. - -*Note*: if you really want a GUI theme editor, you can install gnome-tweak-tools, but this tool has a lot - of gnome dependencies (~150MB of dependencies). You can install it and uninstall it as soon as you change your theme. - -#### Testing notes - -The following programs can be used to see if theme has been correctly applied: - -* GTK2 program: scite, thunderbird, firefox -* GTK3 program: lxterminal -* Qt program: keepassx - -*Note*: testing in a TemplateVM will not work as expected because gnome-settings-daemon is not started in TemplateVM. - so test your themes in an AppVM and then update the TemplateVM accordingly. - -### Forcing theme change for all AppVM depending on a TemplateVM - -This can be done for gtk themes by creating dconf global settings. I recommend reading these articles: - -[DCONF1] - -[DCONF2] - -#### Creating global file - - * Setup global config file: - - > mkdir /etc/dconf/db/qubes.d - - Edit/Create the following file: /etc/dconf/db/qubes.d/10-global-theme-settings: - - ~~~ - [org/gnome/desktop/interface] - cursor-theme="Adwaita" - gtk-theme="Clearlooks-Phenix" - icon-theme="Adwaita" - font-name="Cantarell 11" - monospace-font-name="Monospace 11" - ~~~ - - * Generate global config database - - > dconf update - - * Configure default user profile - - Edit/Create the following file: /etc/dconf/profile/user: - - ~~~ - user-db:user - system-db:qubes - ~~~ - -#### Locking configuration - -It should be noted that the user dconf settings stored in ~/.config/dconf/user always takes precedence over the global dconf settings. - -User dconf settings can be browsed using dconf-editor GUI. - -If you want to force specific settings to be applied for all user (so in our case for all AppVMs depending on the template), you need to create locks: - -> mkdir /etc/dconf/db/qubes.d/locks - -Edit/Create the following file: /etc/dconf/db/qubes.d/locks/theme.lock: - -~~~ -/org/gnome/desktop/interface/gtk-theme -~~~ - -Finally, regenerate the dconf database -> dconf update - -### Uniform look for Qt & GTK - -Getting an uniform look for Qt & GTK is not achieved yet. A good source is on the following link [UNIFORMTHEME] - -Two case: - -1. You installed packages of the theme you selected both for Qt, GTK2 and GTK3. - (eg: Adwaita which is the default theme. I have not found another cross framework theme on fedora default packages). - -2. You want to use the GTK theme you selected for Qt but there is no qt package. - In this case QGtkStyle will take precedence and convert the style automatically. - You can verify if it is enabled by searching for "style=GTK+" in /etc/xdg/Trolltech.conf. - If style is changed to another name, it will be used instead of your GTK theme. - -*Note*: check that ~/.config/Trolltech.conf in your AppVMs is not defining another "style=" because it will take precedence over your global Qt theme. - - -[3GMODEM]: https://www.codeenigma.com/community/blog/installing-3g-usb-modems-linux - -[OPENVPNSETUP]: https://groups.google.com/forum/#!searchin/qubes-users/openvpn$20setup/qubes-users/UbY4-apKScE/lhB_ouTnAwAJ - -[THEMEPACKAGES]: https://groups.google.com/forum/#!search/appvm$20theme/qubes-users/RyVeDiEZ6D0/YR4ITjgdYX0J - -[DCONF1]: http://www.mattfischer.com/blog/?p=431 - -[DCONF2]: https://wiki.gnome.org/Projects/dconf/SystemAdministrators - -[UNIFORMTHEME]: https://wiki.archlinux.org/index.php/Uniform_look_for_Qt_and_GTK_applications - -[Minimal]: ../templates/fedora-minimal/ - -[VPNNM]: ../vpn/#set-up-a-proxyvm-as-a-vpn-gateway-using-networkmanager - -[VPN]: ../vpn/#set-up-a-proxyvm-as-a-vpn-gateway-using-iptables-and-cli-scripts +This content has moved to [Qubes Forum: Community Guides](https://forum.qubes-os.org/c/guides/14). [Learn more.](https://forum.qubes-os.org/t/announcement-qubes-community-project-has-been-migrated-to-the-forum/20367/) diff --git a/docs/customization/gaming-hvm.md b/docs/customization/gaming-hvm.md index 7c4068a..deee4c7 100644 --- a/docs/customization/gaming-hvm.md +++ b/docs/customization/gaming-hvm.md @@ -1,349 +1 @@ -# Create a Gaming HVM - -## Hardware - -To have an 'HVM' for gaming, you must have - -- A dedicated GPU. By dedicated, it means: it is a secondary GPU, not - the GPU used to display dom0. In 2023, 'Nvidia' and 'Amd' GPU work. - Not tested with Intel GPUs. - -- A screen available for the gaming 'HVM'. (It can be a physical - monitor or just to have multiple cables connected to the screen and - switching between input source) - -- Dedicated gaming mouse and keyboard. - -- A lot of patience. GPU passthrough is not trivial, and you will need - to spend time debugging. - -## IOMMU Group - -You need to check what are the things/devices that are in the same IOMMU -group as the GPU you want to passthrough. You can't see your IOMMU Group -when you are using Xen (the information is hidden from dom0). So, start -a live linux distribution, enable iommu in the grub options (iommu=1 -iommu_amd=on), and then displayed the folder structure of -/sys/kernel/iommu_group - -``` bash -#!/bin/bash -shopt -s nullglob -for g in /sys/kernel/iommu_groups/*; do - echo "IOMMU Group ${g##*/}:" - for d in $g/devices/*; do - echo -e "\t$(lspci -nns ${d##*/})" -done -done -``` - -## GRUB modification - -You must hide your secondary GPU from dom0. To do that, you have to -modify the GRUB. In a dom0 Terminal, type: - -``` bash -qvm-pci -``` - -Then find the devices id for your secondary GPU. In my case, it is -`dom0:0a_00.0`{.text} and `dom0:0a_00.1`{.text}. Edit /etc/default/grub, -and add the PCI hiding. - -``` text -GRUB_CMDLINE_LINUX="... rd.qubes.hide_pci=0a:00.0,0a:00.1 " -``` - -then regenerate the grub - -``` bash -grub2-mkconfig -o /boot/grub2/grub.cfg -``` - -If you are using UEFI, the file to override with `grub2-mkconfig`{.text} -is `/boot/efi/EFI/qubes/grub.cfg`{.text}. - -Note: if after this step when you reboot the computer you get stuck in -the QubesOS startup that means you are trying to use the GPU you just -hide. Check your BIOS options. Also check the cables, BIOS have some GPU -priority based on the type of cable. For example, DisplayPort can be -favoured over HDMI. - -Once you have rebooted, in dom0, type `sudo lspci -vvn`{.bash}, you -should see "Kernel driver in use: pciback" for the GPU you just hide. - -## Patching stubdom-linux-rootfs.gz - -[github.com/QubesOS/qubes-issues/issues/4321](https://github.com/QubesOS/qubes-issues/issues/4321#issuecomment-423011787) - -Copy-paste of the comment: - -This is caused by the default TOLUD (Top of Low Usable DRAM) of 3.75G -provided by qemu not being large enough to accommodate the larger BARs -that a graphics card typically has. The code to pass a custom -max-ram-below-4g value to the qemu command line does exist in the -libxl_dm.c file of xen, but there is no functionality in libvirt to add -this parameter. It is possible to manually add this parameter to the -qemu commandline by doing the following in a dom0 terminal. (I modified -the code so it works with 4.1 and remove one of the original limitations -by restricting the modification to VM with a name starting with -"gpu\_\") - -``` bash -mkdir stubroot -cp /usr/libexec/xen/boot/qemu-stubdom-linux-rootfs stubroot/qemu-stubdom-linux-rootfs.gz -cd stubroot -gunzip qemu-stubdom-linux-rootfs.gz -cpio -i -d -H newc --no-absolute-filenames < qemu-stubdom-linux-rootfs -rm qemu-stubdom-linux-rootfs -nano init -``` - -Before the line - -``` text -# $dm_args and $kernel are separated with \n to allow for spaces in arguments -``` - -add: - -``` bash -# Patch 3.5 GB limit -vm_name=$(xenstore-read "/local/domain/$domid/name") -# Apply the patch only if the qube name start by "gpu_" -if [ $(echo "$vm_name" | grep -iEc '^gpu_' ) -eq 1 ]; then - dm_args=$(echo "$dm_args" | sed -n '1h;2,$H;${g;s/\(-machine\nxenfv\)/\1,max-ram-below-4g=3.5G/g;p}') -fi -``` - -Then execute: - -``` bash -find . -print0 | cpio --null -ov \ ---format=newc | gzip -9 > ../qemu-stubdom-linux-rootfs -sudo mv ../qemu-stubdom-linux-rootfs /usr/libexec/xen/boot/ -``` - -Note that this will apply the change to the HVM with a name starting -with \"gpu\_\". So you need to name your gaming HVM \"gpu_SOMETHING\". - -## Preparing the guest - -As of 2023, I recommend using a Linux guest instead of a window guest. - -### Windows - -Install a window VM, you can use this -[qvm-create-windows-qube](https://github.com/elliotkillick/qvm-create-windows-qube) - -### Linux - -Create a new standalone Qube based on the template of your choice. - -You must run the kernel provided by the guest distribution, because we -will use some non-default kernel module for the GPU driver. Just follow -the doc: -[managing-vm-kernel](https://www.qubes-os.org/doc/managing-vm-kernel/#distribution-kernel). - -Install the GPU drivers you need. - -## Pass the GPU - -In qubes settings for the HVM, go to the 'devices' tab, pass the ID -corresponding to your GPU. - -You may or may not need to add the option \"permissive\" or -\"no-strict-reset\". - -[Some word about the security implication of thoses -parameters.](https://www.qubes-os.org/doc/device-handling-security/#pci-security) - -``` bash -qvm-pci attach gpu_gaming_archlinux dom0:0a_00.0 -o permissive=True -o no-strict-reset=True -qvm-pci attach gpu_gaming_archlinux dom0:0a_00.1 -o permissive=True -o no-strict-reset=True -``` - -## Starting the guest - -This is where you will have a lot of issues to debug. - -For Linux guests, run 'sudo dmesg' to have all the kernel log indicating -you if there is a issue with your GPU driver. For some hardware, the MSI -calls won't work. You can work around that using for example -`pci=nomsi`{.text} or `NVreg_EnableMSI=0`{.text} or something else. -Check your drivers options. Check if alternative drivers exist (amdgpu, -nvidia, nouveau, nvidia-open, using drivers from the official website, -...). Check multiple kernel version. - -Some links that could help you to debug the issues you will have - -- https://forum.qubes-os.org/t/ryzen-7000-serie/ - -- https://dri.freedesktop.org/docs/drm/gpu/amdgpu.html - -For windows guests you will probably have the same issues but it will be -harder to debug. I recommend using the drivers from Windows Update -instead of the official drivers from the website of the constructor. - -Some things that may be useful for debugging: - -- Virsh (start, define, \...) - -- /etc/libvirt/libxl/ - -- xl - -- /etc/qubes/templates/libvirt/xen/by-name/ - -- /usr/lib/xen/boot/ - -- virsh -c xen:/// domxml-to-native xen-xm /etc/libvirt/libxl/\... - -Issues with the drivers could be related to -'qubes-vmm-xen-stubdom-linux', 'qubes-vmm-xen', and the Linux kernel you -will be using. - -## Linux guest --- Integration with QubesOS - -### Xorg - -Now Xorg and Pulseaudio. From XKCD: - -[![image](x11){width="\\linewidth"}](https://xkcd.com/963/) - -Things you need to install: - -- The Xorg input driver to support your mouse and keyboard - -- A pulseaudio gui client - -- Your favorite Windows Manager - -In my case, it is: - -``` bash -apt install xserver-xorg-input-kbd xserver-xorg-input-libinput xserver-xorg-input-mouse pavucontrol i3 -``` - -Then create a XORG configuration file for your GPU and screen. My file -named 'AOC.conf': - -``` xorg.conf -Section "ServerLayout" -Identifier "Gaming" -Screen 0 "AMD AOC" Absolute 0 0 -EndSection - -Section "Device" -Identifier "AMD" - -# name of the driver to use. Can be "amdgpu", "nvidia", or something else -Driver "amdgpu" - -# The BusID value will change after each qube reboot. -BusID "PCI:0:8:0" -EndSection - -Section "Monitor" -Identifier "AOC" -VertRefresh 60 -# https://arachnoid.com/modelines/ . IMPORTANT TO GET RIGHT. MUST ADJUST WITH EACH SCREEN. -Modeline "1920x1080" 172.80 1920 2040 2248 2576 1080 1081 1084 1118 -EndSection - -Section "Screen" -Identifier "AMD AOC" -Device "AMD" -Monitor "AOC" -EndSection -``` - -We can't know what is the correct BusID before the qube is started. And -it change after each reboot. So let's write a script --- named -\"xorgX1.sh\" --- that update this configuration file with the correct -value, then start a binary on the Xorg X screen n°1. - -``` bash -#!/bin/bash - -binary=${1:?binary required} - -# Find the correct BusID of the AMD GPU, then set it in the Xorg configuration file -pci=$(lspci | grep "VGA" | grep "NVIDIA|AMD/ATI" | cut -d " " -f 1 | cut -d ":" -f 2 | cut -d "." -f 1 | cut -d "0" -f 2) -sed -i "s/PCI:0:[0-9]:0/PCI:0:$pci:0/g" /home/user/AOC.conf - -# Pulseaudio setup -sudo killall pulseaudio -sudo sed -i "s/load-module module-vchan-sink.*/load-module module-vchan-sink domid=$(qubesdb-read -w /qubes-audio-domain-xid)/" /etc/pulse/qubes-default.pa -sudo rm /home/user/.pulse/client.conf -start-pulseaudio-with-vchan -sleep 5 && sudo chmod -R 777 /root/ & -sleep 5 && sudo chmod -R 777 /root/* & -sleep 5 && sudo cp /root/.pulse/client.conf /home/user/.pulse/client.conf && sudo chown -R user:user /home/user/.pulse/client.conf & - -setxkbmap fr -sudo setxkbmap fr - -# Start the Xorg server for the X screen number 1. -# The X screen n°0 is already used for QubesOS integration -sudo startx "$binary" -- :1 -config /home/user/AOC.conf -``` - -### Pulseaudio - -So you need to configure pulseaudio for Xorg multiseat. The archlinux -documentation explain that very well: [Xorg -multiseat](https://wiki.archlinux.org/index.php/Xorg_multiseat#Multiple_users_on_single_sound_card:_PulseAudio) -Use the option without system-mode deamon and adapt it to qube: Add the -following line to /etc/pulse/qubes-default.pa - -``` bash -load-module module-native-protocol-tcp auth-ip-acl=127.0.0.1 -``` - -Then add this config for root: - -``` bash -mkdir /root/.pulse -echo "default-server = 127.0.0.1" > /root/.pulse/client.conf -``` - -The sound was buggy/laggy on my computer. So tried to find a workaround -by playing with pulseaudio settings. It was more or less random tries, -so I can't really explain it: In `/etc/pulse/daemon.conf`{.text} add the -following lines: - -``` bash -default-fragments = 60 -default-fragment-size-msec = 1 -high-priority = no -realtime-scheduling = no -nice-level = 18 -``` - -In `/etc/pulse/qubes-default.pa`{.text} change - -``` bash -load-module module-udev-detect -``` - -to - -``` bash -load-module module-udev-detect tsched=0 -``` - -You can launch you favorite Windows Manager like that - -``` bash -sudo ./xorgX1.sh /usr/bin/i3 -``` - -### References - -- [Archlinux: - PulseAudio](https://wiki.archlinux.org/index.php/PulseAudio) - -- [Archlinux: - PulseAudio/Troubleshooting](https://wiki.archlinux.org/index.php/PulseAudio/Troubleshooting) - +This content has moved to [Qubes Forum: Community Guides](https://forum.qubes-os.org/c/guides/14). [Learn more.](https://forum.qubes-os.org/t/announcement-qubes-community-project-has-been-migrated-to-the-forum/20367/) diff --git a/docs/customization/language-localization.md b/docs/customization/language-localization.md index 01ff135..deee4c7 100644 --- a/docs/customization/language-localization.md +++ b/docs/customization/language-localization.md @@ -1,85 +1 @@ -Language Localization -===================== - -Enable UTF-8 in dom0 title bars -------------------------- - -You can enable UTF-8 characters in the title bar for all (non-Windows) qubes or on a per-qube basis. For an individual qube, this can be done using the Qube Manager's `Advanced` tab or, in a `dom0` terminal, via the command - - `qvm-features gui-allow-utf8-titles true` - -To change this given GUI option globally, set this feature in the Qube Manager's `Global Settings` plane, which will apply to all qubes using the GuiVM under which Qube Manager is running (usually `dom0`, or possibly in one of the alternative GuiVMs `sys-gui` or `sys-gui-gpu`). To set this property globally for all qubes running under a certain GuiVM, e.g. `dom0`, use the command - - `qvm-features dom0 gui-default-allow-utf8-titles true` - -or accordingly. - -**Note:** This does not work for Windows qubes. - -Changing the language of dom0 ------------------------------ - -In order to install an additional language in `dom0`, e.g. German: In a `dom0` terminal, execute - - `sudo qubes-dom0-update langpacks-de` - -Then reboot. - -Before logging in, the task panel will show - usually far to the right - the current language, e.g. `C.UTF-8`. Clicking on this value will open a menu where you can select the GUI language, i.e. the interface language of Qubes used in `dom0` and in the menus, like Whiskers. Note, however, that the language of some Qubes utilities like the Qube Manager does not change, and any Templates and AppVMs based on these Templates retain their language. - -This need only be done once; the selected language survives logging out and reboot. - -Changing the language of Templates and the AppVMs based on them ---------------------------------------------------------------- - -To change the language of existing Templates, you have to install the language packs in these Templates. - -For Fedora-based Templates, this is done (for German as an example) via - - `sudo dnf install langpacks-de` - -For debian-based Templates, the corresponding command is - - `sudo apt-get install language-pack-de language-pack-gnome-de language-pack-de-base language-pack-gnome-de-base` - -For other languages, the corresponding code has to be used, e.g. `fr` for French. After installing a language, it has to be selected/enabled via the settings of the Template. - -New Templates will be installed in their default language, usually English, and they have to be changed just like existing Templates. This could be alleviated by installing a “clean” Template from the repository, with nothing but the needed language packs before starting to create a new template–clone using one of these languages. For instance, when you need a totally new Template (e.g., Debian 12 when it comes out), you’ll have to create debian-12-de and regenerate all other Templates from that. - -The language of Windows Templates is determined at the installation of the operating system and can be changed afterwards if the installed edition is a multi-language edition; otherwise the language stays fixed. - -AppVMs started after this change will inherit the language from the corresponsing Template. - -How to set up pinyin input in Qubes ------------------------------------ - -The pinyin input method will be installed in a TemplateVM to make it available after restarts and across multiple AppVMs. - -1. In a TemplateVM, install `ibus-pinyin` via the package manager or terminal. - If the template is Fedora-based, run `sudo dnf install ibus-pinyin`. - If the template is Debian-based, run `sudo apt install ibus-pinyin` - -2. Shut down the TemplateVM. - -3. Start or restart an AppVM based on the template in which you installed `ibus-pinyin` and open a terminal. - -4. Run `ibus-setup`. - -5. You will likely get an error message telling you to paste the following into your bashrc: - - export GTK_IM_MODULE=ibus - export XMODIFIERS=@im=ibus - export QT_IM_MODULE=ibus - - Copy the text into your `~/.bashrc` file with your favorite text editor. - You will need to do this for any AppVM in which you wish to use pinyin input. - -6. Set up ibus input as you like using the graphical menu (add pinyin or intelligent pinyin to selections). - You can bring the menu back by issuing `ibus-setup` from a terminal. - -7. Set up your shortcut for switching between inputs. - By default it is super-space. - -If `ibus-pinyin` is not enabled when you restart one of these AppVMs, open a terminal and run `ibus-setup` to activate ibus again. - -For further discussion, see [this qubes-users thread](https://groups.google.com/forum/#!searchin/qubes-users/languge/qubes-users/VcNPlhdgVQM/iF9PqSzayacJ). +This content has moved to [Qubes Forum: Community Guides](https://forum.qubes-os.org/c/guides/14). [Learn more.](https://forum.qubes-os.org/t/announcement-qubes-community-project-has-been-migrated-to-the-forum/20367/) diff --git a/docs/customization/mirage-firewall.md b/docs/customization/mirage-firewall.md index 30e366c..deee4c7 100644 --- a/docs/customization/mirage-firewall.md +++ b/docs/customization/mirage-firewall.md @@ -1,78 +1 @@ -Mirage Firewall -=============== - -A unikernel firewall for Qubes OS. -This site will help collecting information about the mirage firewall, an interesting project from "talex5". - -To learn more about the Mirage Firewall, please make sure to read - -- https://github.com/mirage/qubes-mirage-firewall -- https://github.com/mirage/qubes-mirage-firewall/blob/master/README.md - -The Mirage Firewall for Qubes OS is a low ressource firewall, which uses a much smaller footprint -compared to the default ("fat") sys-firewall. - -This page is only to write down how to build the mirage firewall for Qubes OS. -Please make sure to read the above links to understand more about it. - -Most information from here has been put together reading the original docs above and following the discussion in the Qubes OS User Mailinglist / Google Groups: -https://groups.google.com/forum/#!topic/qubes-users/xfnVdd1Plvk - - -Build process on Qubes 4 -======================== -``` -MirageFWBuildVM=my-mirage-buildvm -TemplateVM=fedora-29 -MirageFWAppVM=sys-mirage-fw2 - -# create a new VM -qvm-create $MirageFWBuildVM --class=AppVM --label=red --template=$TemplateVM - - -# Resize private disk to 10 GB -qvm-volume resize $MirageFWBuildVM:private 10GB - -# Create a symbolic link to safe docker into the home directory -qvm-run --auto --pass-io --no-gui $MirageFWBuildVM \ - 'sudo mkdir /home/user/var_lib_docker && \ - sudo ln -s /var/lib/docker /home/user/var_lib_docker' - -# Install docker and git ~2min -qvm-run --pass-io --no-gui $MirageFWBuildVM \ - 'sudo qvm-sync-clock && \ - sudo dnf -y install docker git' - -# Launch docker -qvm-run --pass-io --no-gui $MirageFWBuildVM \ - 'sudo systemctl start docker' - -# Download and build mirage for qubes ~11min -qvm-run --pass-io --no-gui $MirageFWBuildVM \ - 'git clone https://github.com/mirage/qubes-mirage-firewall.git && \ - cd qubes-mirage-firewall && \ - git pull origin pull/52/head && \ - sudo ./build-with-docker.sh' - -# Copy the new kernel to dom0 -cd /var/lib/qubes/vm-kernels -qvm-run --pass-io $MirageFWBuildVM 'cat qubes-mirage-firewall/mirage-firewall.tar.bz2' | tar xjf - - -# create a new mirage fw appvm -qvm-create \ - --property kernel=mirage-firewall \ - --property kernelopts=None \ - --property memory=32 \ - --property maxmem=32 \ - --property netvm=sys-net \ - --property provides_network=True \ - --property vcpus=1 \ - --property virt_mode=pv \ - --label=green \ - --class StandaloneVM \ - $MirageFWAppVM - -# Change default NetVM to Mirage FW -qvm-start $MirageFWAppVM -qubes-prefs --set default_netvm $MirageFWAppVM -``` +This content has moved to [Qubes Forum: Community Guides](https://forum.qubes-os.org/c/guides/14). [Learn more.](https://forum.qubes-os.org/t/announcement-qubes-community-project-has-been-migrated-to-the-forum/20367/) diff --git a/docs/customization/removing-templatevm-packages.md b/docs/customization/removing-templatevm-packages.md index 9f5c247..deee4c7 100644 --- a/docs/customization/removing-templatevm-packages.md +++ b/docs/customization/removing-templatevm-packages.md @@ -1,88 +1 @@ - -# Removing TemplateVM Packages -When removing any packages from a default TemplateVM, be sure to check what's being removed by `apt autoremove` or `dnf`. -When removing certain packages, for instance Thunderbird, `apt` and `dnf` will attempt to remove many packages required by qubes for the template to function correctly under qubes. - -As an example from a terminal in a TemplateVM: -```shell_session -$ sudo apt remove thunderbird -Reading package lists... Done -Building dependency tree -Reading state information... Done -The following packages were automatically installed and are no longer required: - debugedit libjs-sphinxdoc libjs-underscore librpm3 librpmbuild3 librpmio3 - librpmsign3 libsqlite0 linux-headers-4.9.0-6-amd64 - linux-headers-4.9.0-6-common linux-image-4.9.0-6-amd64 python-backports-abc - python-cffi-backend python-concurrent.futures python-croniter - python-cryptography python-dateutil python-enum34 python-idna - python-iniparse python-ipaddress python-jinja2 python-libxml2 python-lzma - python-markupsafe python-msgpack python-openssl python-pyasn1 python-pycurl - python-requests python-rpm python-singledispatch python-six python-sqlite - python-sqlitecachec python-tornado python-tz python-urlgrabber - python-urllib3 python-xpyb python-yaml qubes-core-agent-dom0-updates - qubes-core-agent-passwordless-root qubes-gpg-split qubes-img-converter - qubes-input-proxy-sender qubes-mgmt-salt-vm-connector qubes-pdf-converter - qubes-usb-proxy rpm rpm-common rpm2cpio salt-common salt-ssh usbutils yum - yum-utils -Use 'sudo apt autoremove' to remove them. -The following packages will be REMOVED: - icedove lightning qubes-thunderbird qubes-vm-recommended thunderbird -0 upgraded, 0 newly installed, 5 to remove and 0 not upgraded. -After this operation, 151 MB disk space will be freed. -Do you want to continue? [Y/n] -``` - -Note all of the qubes packages are tracked as dependencies that will no longer be required. `apt remove` will only remove the packages listed, which is ok. -If, however you also run `apt autoremove` the other qubes packages necessary for TemplateVMs will be removed. - -If you'd still like to remove one of these applications without breaking your TemplateVM you have a couple different options. - -## Removing Only Packages Not Needed for a Qubes TemplateVM - -### Debian - 1. In your TemplateVM terminal run: - ```shell_session $ apt remove package-name``` - Note the packages "no longer required" - 2. If the list of "no longer required" packages includes anything beginning with `qubes-` or `salt-` make a note to yourself to **never** run `$ sudo apt autoremove` on this TemplateVM - -**Recommended but optional:** Use `apt-mark` to make `apt autoremove` safe again. -```shell_session -$ sudo apt-mark manual package-name package-name -``` - -Replace package-names with actual `qubes-*` and `salt-*` packages you'd like to retain. - -For example, still in your TemplateVM terminal: -```shell_session -$ sudo apt-mark manual qubes-core-agent-dom0-updates qubes-core-agent-passwordless-root qubes-gpg-split qubes-img-converter qubes-input-proxy-sender qubes-mgmt-salt-vm-connector qubes-pdf-converter salt-common salt-ssh qubes-usb-proxy -``` - -`$ apt autoremove` should now be safe to use. - -### Fedora -In your TemplateVM terminal, run: -```shell_session -$ dnf remove --noautoremove package-name -``` - - -## Recovering A TemplateVM which you've already removed needed qubes-* packages -If you've already removed packages, run `apt autoremove` and restarted your VM you've lost passwordless sudo access. -You can login as root, open a terminal in dom0 and run: -```shell_session -$ qvm-run -u root vmname xterm -``` -This will open an xterm terminal in the TemplateVM named `vmname` - -Once you're logged in as root, reinstall these packages & their dependencies: - -### Debian -```shell_session -$ sudo apt install qubes-core-agent-dom0-updates qubes-core-agent-passwordless-root qubes-gpg-split qubes-img-converter qubes-input-proxy-sender qubes-mgmt-salt-vm-connector qubes-pdf-converter salt-common salt-ssh -``` - -### Fedora -Similar to Debian for example (package names may vary): -```shell_session -$ sudo dnf install qubes-core-agent-dom0-updates qubes-core-agent-passwordless-root qubes-gpg-split qubes-img-converter qubes-input-proxy-sender qubes-mgmt-salt-vm-connector qubes-pdf-converter salt-common salt-ssh -``` +This content has moved to [Qubes Forum: Community Guides](https://forum.qubes-os.org/c/guides/14). [Learn more.](https://forum.qubes-os.org/t/announcement-qubes-community-project-has-been-migrated-to-the-forum/20367/) diff --git a/docs/customization/screenlockers.md b/docs/customization/screenlockers.md index 39d8c2e..deee4c7 100644 --- a/docs/customization/screenlockers.md +++ b/docs/customization/screenlockers.md @@ -1,128 +1 @@ - -# Custom screenlockers in Qubes OS - -## Security Considerations - -Most people use screenlockers on a daily basis to prevent unauthorized access to their computers during -e.g. coffee breaks. The screen lock functionality is thereby often part of a screensaver. -Qubes OS uses `xscreensaver' for that. - -While screenlockers cannot be assumed to withstand serious attacks, most users likely assume that -they cannot be bypassed within very little time. They also assume that screenlockers don't tend to -fail after a while. -Unfortunately both of these assumptions usually don't hold: - -- If one of the parent processes of a screenlocker (e.g. the X server) dies or restarts unexpectedly, the - screen locker will die and leave the screen unprotected. X server restarts may happen with various graphic - driver bugs, e.g. on something as simple as plugging a laptop into a docking station with a monitor. -- Screenlockers [tend to have bugs](https://www.jwz.org/blog/2015/04/i-told-you-so-again/) or - [bad/outdated design](http://blog.martin-graesslin.com/blog/2015/01/why-screen-lockers-on-x11-cannot-be-secure/). -- Other applications may request the screenlocker to be cleared or otherwise display - information [in front of the screenlocker window](https://github.com/QubesOS/qubes-issues/issues/5908). - -The default Qubes OS `xscreensaver` also suffers from these issues, but at least has high hardware coverage. -The Qubes OS design also helps to limit the scope of some of these issues (e.g. only dom0 applications can -request the screensaver to quit). - -In general it is _not_ advisable to rely on screenlocker security for anything serious. - -See [qubes-issues](https://github.com/QubesOS/qubes-issues/issues/1917) for further discussions. - -## Configuring a custom screenlocker - -Qubes OS can be configured to use whatever screenlocker you prefer. - -Thanks to `xss-lock` and `xflock4` (by default started via `/etc/xdg/autostart/xfce4-xss-lock.desktop`) -the below screenlockers should work right after their installation in dom0: - -- `xscreensaver-command -lock` -- `gnome-screensaver-command --lock` -- `xlock -mode blank` -- `slock` - -If you have multiple screenlockers installed, you might have to remove the others first. - -For other screenlockers you have to use the following dom0 command to enable them: - -``` -xfconf-query -c xfce4-session -p /general/LockCommand -s "[command to start your screenlocker]" --create -t string -``` - -Set an empty command to disable them. - -**Important Note**: -`xss-lock` continually requests a timeout (the one set via `xset s`) from the X server and if that timeout is hit, -it executes `xflock4`, which in turn executes your screenlocker. -However any bug in `xss-lock` (e.g. [this one](https://bugs.archlinux.org/task/64771) or possibly even just a X server disconnect), -may cause that trigger to _not_ happen. I.e. do **not** rely on that trigger for anything sensible, but use a keyboard screenlocker -hotkey instead! - -## Physlock - -[physlock](https://github.com/muennich/physlock) is an interesting screenlocker alternative as it simply uses the -tty logon mechanism as screen locking mechanism. It does not depend on the X server and is therefore not affected by -unexpected X server restarts. - -The below instructions provide an example of how to install and configure a non-default screenlocker. - -### Installation - -1. Install its build dependencies in dom0: `sudo qubes-dom0-update gcc make pam-devel systemd-devel` -2. Download the [physlock source code](https://github.com/muennich/physlock), verify its tag signatures - and copy it to dom0. -3. Follow the build and install instructions of its [README](https://github.com/muennich/physlock/blob/master/README.md). -4. In particular make sure to follow its PAM-related instructions (if you run into an endless `authentication failed` - loop on locking later, you likely forgot this point). - -### Configuration - -1. physlock uses the dom0 root password for unlocking, i.e. you'll have to set one with `sudo passwd`. -2. Create a helper script at `/usr/bin/screenlock`: - ``` - #!/bin/bash - - function isRunning { - pgrep -a '^physlock$' - } - - #parse args - keep_open=1 - if [[ "$1" == "--keep-open" ]] ; then - keep_open=0 - shift - fi - - #NOTE: for some sreason the full path is required below for xss-lock - isRunning || { /usr/local/bin/physlock -dms "$@" ; sleep 1 ; } - - #Idea: - #make xss-lock think that it controls the screenlocker, but in fact it doesn't - #reason: xss-lock may crash and we don't want it to take down the screen lock - if [ $keep_open -eq 0 ] ; then - stime=10 - while isRunning ; do - echo "Sleeping for ${stime}s..." - sleep $stime - done - fi - exit 0 - ``` -3. Make it executable with `chmod +x /usr/bin/screenlock`. -4. Make sure `/etc/xdg/autostart/xfce4-xss-lock.desktop` exists with `xss-lock xflock4` (does exist by default in Qubes OS 4). -5. As regular user, run `xfconf-query -c xfce4-session -p /general/LockCommand -s "/usr/bin/screenlock --keep-open" --create -t string` in dom0. -6. If you need audio during the screen lock, run `sudo usermod -a -G audio [your user]`. - -You can then use the command `screenlock` for custom hotkeys etc. - -To set the screenlocker timeout, use the xfce GUI or `xset`. - -For example you could create `/etc/xdg/autostart/xset.desktop` with the following content to set a timeout of 610s on startup: -``` -[Desktop Entry] -Name=xset -Comment=Set screensaver timeout -Exec=bash -c 'sleep 60 && xset s 610' -Terminal=false -Type=Application -StartupNotify=false -``` +This content has moved to [Qubes Forum: Community Guides](https://forum.qubes-os.org/c/guides/14). [Learn more.](https://forum.qubes-os.org/t/announcement-qubes-community-project-has-been-migrated-to-the-forum/20367/) diff --git a/docs/customization/secbrowser.md b/docs/customization/secbrowser.md index 3bdf7ac..deee4c7 100644 --- a/docs/customization/secbrowser.md +++ b/docs/customization/secbrowser.md @@ -1,97 +1 @@ -SecBrowser -========== - -NOTE: [SecBrowser is deprecated](https://www.whonix.org/wiki/SecBrowser). - -[SecBrowser](https://www.whonix.org/wiki/SecBrowser_™_in_Qubes_OS) is a security-focused browser that provides vulnerability surface reduction for users that need high security, thereby reducing the risk of infection from malicious, arbitrary code. A built-in security slider provides enhanced usability, as website features which have historically been used as attack vectors (like JavaScript) can be easily disabled. Without any customization, SecBrowser’s default configuration offers better security than Firefox, Google Chrome or Microsoft Edge.[[1]](https://2019.www.torproject.org/projects/torbrowser/design/) It also provides better protections from online tracking, [fingerprinting](https://www.whonix.org/wiki/Data_Collection_Techniques) and the [linkability](https://www.whonix.org/wiki/Data_Collection_Techniques#Fingerprinting_of_Browser_.28HTTP.29_Header) of activities across different websites. - -SecBrowser is a derivative of the Tor Browser Bundle, but without Tor. This means unlike Tor Browser, SecBrowser does not route traffic over the Tor network. Even without the aid of the Tor network, SecBrowser still benefits from the numerous [patches](https://gitweb.torproject.org/tor-browser.git) that Tor developers have merged into the code base. Even with developer skills, these enhancements would be arduous and time-consuming to duplicate in other browsers, with the outcome unlikely to match SecBrowser's many security benefits. While browser extensions can be installed to mitigate specific attack vectors, this ad hoc approach is insufficient. SecBrowser leverages the combines experience and knowledge of the Tor Project developers, Whonix developers and the battle-tested Tor Browser. - - -Security Enhancements ------------------------------------- - -**Table:** _SecBrowser Security and Privacy Benefits_ - - -| **Features** | **Description** | -|---------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| HTTPS Everywhere | This browser extension encrypts communications with many major websites, making your browsing more secure.[[2]](https://www.eff.org/https-everywhere) | -| NoScript | NoScript can provide significant protection with the correct configuration.[[3]](https://en.wikipedia.org/wiki/NoScript) NoScript blocks active (executable) web content and protects against [cross-site scripting](https://en.wikipedia.org/wiki/Cross-site_scripting) (XSS). "The add-on also offers specific countermeasures against security exploits". | -| DNS and Proxy Configuration Obedience | Proxy obedience is achieved through custom patches, Firefox proxy settings, and build flags. Plugins which can bypass proxy setting are disabled.[[4]](https://2019.www.torproject.org/projects/torbrowser/design/#proxy-obedience) | -| Reproducible Builds | Build security is achieved through a reproducible build process that enables anyone to produce byte-for-byte identical binaries to the ones the Tor Project releases.[[5]](https://blog.torproject.org/deterministic-builds-part-two-technical-details)[[6]](https://2019.www.torproject.org/projects/torbrowser/design/#BuildSecurity) | -| Slider Security | Enables improved security by disabling certain web features that can be used as attack vectors.[[7]](https://tb-manual.torproject.org/security-slider/)[[8]](https://2019.www.torproject.org/projects/torbrowser/design/#proxy-obedience) | -| WebRTC Disabled by Default | WebRTC can compromise the security of VPN tunnels, by exposing the external (real) IP address of a user.[[9]](https://en.wikipedia.org/wiki/WebRTC#Concerns)[[10]](https://torrentfreak.com/huge-security-flaw-leaks-vpn-users-real-ip-addresses-150130/) | - -Settings --------- - -While SecBrowser has numerous security enhancements they can come at a cost of decreased usability. Since it is also highly configurable, security settings and behavior can be customized according to personal requirements. - -* **Private Browsing Mode:** In the default configuration Tor Browser has private browsing mode enabled. This setting prevents browsing and download history as well as cookies from remaining persistent across browser restarts. While private browsing mode increases security, usability can be affected to the point that some websites will not function properly or not at all.[[11]](https://trac.torproject.org/projects/tor/ticket/10569) To enhance usability SecBrowser comes packaged with a custom `user_pref` that disables private browsing mode. If privacy is paramount users can enable private browsing mode by commenting out the corresponding user preference. - -* **Security Slider:** By default the security slider is set to "Safest" which is the highest security setting.This will prevent some web pages from functioning properly, so security needs must be weighed against the degree of usability that is required. - -* **Persistent NoScript Settings:** SecBrowser includes a `user_pref` that allows custom NoScript settings to persist across browser sessions. This is a security vs usability trade-off. - -* **Remember Logins and Passwords for Sites:** To increase usability, users have the option to save site login information such as user names or passwords. - -Privacy and Fingerprinting Resistance -------------------------------------- - -Research from a pool of 500,000 Internet users has shown that the vast majority (84%) have unique browser configurations and version information which makes them trackable across the Internet. When Java or Flash is installed, this figures rises to 94%.[[12]](https://www.eff.org/deeplinks/2010/05/every-browser-unique-results-fom-panopticlick) SecBrowser shares the fingerprint with around [three million](https://metrics.torproject.org/userstats-relay-country.html) other Tor Browser users, which allows people who use SecBrowser to "blend in" with the larger population and better protect their privacy. - -The [EFF has found](https://www.eff.org/deeplinks/2010/05/every-browser-unique-results-fom-panopticlick) that while most browsers are uniquely fingerprintable, resistance is afforded via four methods: - -* Disabling JavaScript with tools like NoScript. -* Use of Torbutton, which is bundled with SecBrowser and enabled by default. -* Use of mobile devices like Android and iPhone. -* Corporate desktop machines which are clones of one another. - -With JavaScript disabled, SecBrowser provides significant resistance to browser fingerprinting.[[13]](https://blog.torproject.org/effs-panopticlick-and-torbutton) - -* The User Agent is uniform for all Torbutton users. -* Plugins are blocked. -* The screen resolution is rounded down to 50 pixel multiples. -* The timezone is set to GMT. -* DOM Storage is cleared and disabled. - -The EFF's [Panoptickick](https://panopticlick.eff.org/) fingerprint test shows that SecBrowser resists fingerprinting. - -_Note:_ Because tracking techniques are complex, Panopticlick does not measure all forms of tracking and protection. - -* SecBrowser conveys 6.26 bits of identifying information. -* One in 76.46 browsers having the same fingerprint. -* Browser's that convey lower bits of identification are better at resisting fingerprinting.[[14]](https://33bits.wordpress.com/about/) - - -When Tor Browser's and SecBrowser's HTTP headers are compared using [Fingerprint central](https://fpcentral.irisa.fr/) the test results are near identical. - - -**Table:** _Tor Browser vs SecBrowser HTTP Headers Comparison_ - -_Percentage (%) out of 1652 with fingerprints tags [Firefox,Windows]:_ - -| Name | Value | Tor Browser | SecBrowser | -|---------------------------|-------------------------------------------------------------------|:-------------:|:-------------:| -| | | % | % | -| User-Agent | Mozilla/5.0 (Windows NT 6.1; rv:60.0) Gecko/20100101 Firefox/60.0 | 2.48 | 2.42 | -| Accept | text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8 | 97.15 | 97.15 | -| Host | fpcentral.irisa.fr | 90.44 | 90.43 | -| Content-Length | | 100.00 | 100.00 | -| Accepted-Language | en-US,en;q=0.5 | 32.63 | 32.95 | -| Referer | https://fpcentral.irisa.fr/ | 69.37 | 69.35 | -| Upgrade-Insecure-Requests | 1 | 83.05 | 83.04 | -| Accepting-Encoding | gzip, deflate, br | 82.14 | 82.13 | -| Content-Type | | 100.00 | 100.00 | -| Connection | close | 100.00 | 100.00 | - -Install SecBrowser ------------------- - -SecBrowser can be installed using `tb-updater` which is a package developed and maintained by Whonix developers. When run, `tb-updater` seamlessly automates the download and verification of SecBrowser (from The Tor Project's website). One of the many benefits of `tb-updater` is the ability to disable Tor is prebuilt into the software. This improves usability and is convenient since a security-focused browser (SecBrowser), is readily available. Unlike other manual methods of disabling Tor, this greatly simplifies the procedure and lessens the chance of a configuration error. To install SecBrowser in Qubes, users can follow the detailed instructions found on the designated [SecBrowser Wiki](https://www.whonix.org/wiki/SecBrowser_™_in_Qubes_OS) . - -Conclusion ----------- - -SecBrowser is a highly configurable security-focused browser that affords users with numerous options to fine tune their browser's security and usability. This can be achieved through user preferences (`user_pref`) or on the fly by means of an easy to use and intuitive security slider. This allows for seemless changes in security posture to meet changes in dynamic environments. SecBrowser's fingerprinting resistance provides strong protection against web tracking and can be combined with a VPN to further enhance privacy. SecBrowser can be used with any Debian 10 (buster) based operating system including [SecOS](https://forums.whonix.org/t/hardened-debian-security-focused-linux-distribution-based-on-debian-in-development-feedback-wanted/5943) (a Hardened Debian based OS) which is in active development and coming soon. +This content has moved to [Qubes Forum: Community Guides](https://forum.qubes-os.org/c/guides/14). [Learn more.](https://forum.qubes-os.org/t/announcement-qubes-community-project-has-been-migrated-to-the-forum/20367/) diff --git a/docs/customization/tailscale.md b/docs/customization/tailscale.md index f63bd8c..deee4c7 100644 --- a/docs/customization/tailscale.md +++ b/docs/customization/tailscale.md @@ -1,42 +1 @@ -How to Enable Tailscale in AppVM -================================== -Note: If you seek to enhance your privacy, you may also wish to consider a VPN proxy Qube. - -Tailscale is a mesh private network that lets you easily manage access to private resources, quickly SSH into devices on your network, and work securely from anywhere in the world. If you have devices in your private home network or at work at which you cannot use a VPN, Tailscale is a simple alternative with minimal setup. - -### Template VM - -In a `t-tailscale` template VM, install tailscale with the simple sh script, then stop the service: - -``` --curl -fsSL https://tailscale.com/install.sh | sh -systemctl stop tailscaled -``` - -### AppVM - -In your `tailscale` AppVM, use your favorite editor to sudo edit '/rw/config/rc.local', adding the following lines at the bottom of the file: - -``` -sudo systemctl start tailscaled -sudo tailscale up -``` - -Now make sure folder /rw/config/qubes-bind-dirs.d exists. - -``` -sudo mkdir -p /rw/config/qubes-bind-dirs.d -``` - -Create a file /rw/config/qubes-bind-dirs.d/50_user.conf with root rights. Edit the file 50_user.conf to append a folder or file name to the binds variable. - -``` -binds+=( '/var/lib/tailscale' ) -``` -Save. - -Reboot the app qube. - -Done. - -From now on any files within the /var/lib/tailscale folder will persist across reboots. Shutdown and reboot the VM. Enter a console and run `sudo tailscale up` again to get the Tailscale tunnel link to your VM. +This content has moved to [Qubes Forum: Community Guides](https://forum.qubes-os.org/c/guides/14). [Learn more.](https://forum.qubes-os.org/t/announcement-qubes-community-project-has-been-migrated-to-the-forum/20367/) diff --git a/docs/customization/terminal-defaults.md b/docs/customization/terminal-defaults.md index f71276d..deee4c7 100644 --- a/docs/customization/terminal-defaults.md +++ b/docs/customization/terminal-defaults.md @@ -1,29 +1 @@ -# Setting default terminal settings for a TemplateVM - -When you create a VM based on a TemplateVM, the `gnome-terminal` settings (font, color) are not inherited by default. This document describes how to set terminal defaults for all VMs *subsequently* created off a TemplateVM. - -(Previously-created VMs are unaffected.) - -This document only applies to `gnome-terminal` (the standard terminal) -and not XTerm, etc. - -Thanks to `unman` on qubes-users for explaining how to do this. - -## Define your defaults - -In dom0: -`qvm-run MYTEMPLATE gnome-terminal` - -In the terminal that pops up, adjust settings to your liking. - -## Save settings template-wide - -In the templateVM's terminal: -``` -sudo mkdir -p /etc/skel/.config/dconf -sudo cp ~/.config/dconf/user /etc/skel/.config/dconf/ -sudo reboot -``` - -Subsequently-created VMs should now use the chosen settings by default. - +This content has moved to [Qubes Forum: Community Guides](https://forum.qubes-os.org/c/guides/14). [Learn more.](https://forum.qubes-os.org/t/announcement-qubes-community-project-has-been-migrated-to-the-forum/20367/) diff --git a/docs/customization/windows-template-customization.md b/docs/customization/windows-template-customization.md index e5172df..deee4c7 100644 --- a/docs/customization/windows-template-customization.md +++ b/docs/customization/windows-template-customization.md @@ -1,162 +1 @@ - -Disable/Uninstall unnecessary features/services -============================= - -Windows features ----------------------------- - -Uninstall windows features from Control Panel > Turn windows features On/Off. - -Generally, it will be required to reboot after features are uninstalled. - -If you do not manage to uninstall some features, it is sometimes necessary to uninstall them one by one or two by two. - -Only keep: - - * Print and Document Service => Internet Printing Client - * Print and Document Service => Windows Fax and Scan (apparently it cannot be uninstalled) - * Windows search - -*Note*: Windows search is recommended because it is a nightmare to find something in menus if it is not enabled (it removes the search bar from the start menu, from the explorer, and from the control panel). - -*Note*: Unselecting windows media, .Net and Internet Explorer will uninstall these components. On a new install they are generally old versions anyway and it will be quicker to install directly the new versions later. - -Windows services ---------------------------- - -Disable the following services that are not required or have no sense in a VM context: - - * Base Filtering Engine (only required if you want to use Microsoft IPSEC) - * DHCP Client - * Function Discovery Provider Host - - this will not work anyway because SSDP discovery uses multicast - need to be on the same network which is not the case because of Qubes firewall - * Peer Name Resolution Protocol - * Peer Netwoking Grouping - * Peer Networking Identity Manager - * SSDP Discovery - * Security Center (is it only notifications ?) - * TCP/IP Netbios Help (is Netbios still really used by Windows ? Maybe for discovery only ?) - * Themes (if you don't care about theme) - * Volume Shadow Copy (see next note in the performance section) - * Windows defender - * Windows Firewall - -*Notes*: IP Helper is required as it is used by Qubes Agent to configure the IP address. - -Windows update --------------------------- - -I recommend disabling windows update (Never Check for Update) because checking for updates will start every time you start an AppVM if you haven't started your template in a while. - -Running windows update is also apparently IO hungry. - -Of course I recommend starting the template regularly and checking manually for updates. - -System properties ---------------------------- - -Right click on computer and go to Properties > Advanced > Performance: - - * If you don't care about visual effect, in Visual Effect select "Adjust for best performance" - * I personally tweak the page file size to gain some space on my root. - - In Advanced>Performances>Advanced tab, change Virtual memory: - - 1. unselect automatically manage paging file size for all drive - 2. click on drive C: - 3. select no paging file - 4. click on set - 5. click on drive d: - 6. select customer size - 7. use an initial size of 500 and a max size of 1000. If the page file is too small, you will notice a low memory pop up when working on windows. In this case, it often means that you should extend your AppVM RAM. - - * System Protection - - Here you can disable Shadow Folder because it has little sense in the case of Qubes because - - * we do regular backups of AppVMs/TemplateVMs; - * we can revert at least one template change if we break something. - - Select drives where system protection is enabled and click Configure. "Turn off system protection" "Delete all restore points" - - * Remote - - Unselect Allow Remote Assistance connections to this computer. - -Task scheduler ------------------------ - -Open the task scheduler and *disable* the following tasks. - -If you remove these tasks they may be recreated automatically by various windows management tools (such as defragmentation) - - * Autochk: All - * Application Experience: All - * Customer Experience Improvement Program: All - * Defrag: All - * DiskDiagnosis: All (the disk is virtual anyway so S.M.A.R.T. has no sense) - * Maintenance: All - * SystemRestore: All - * WindowsBackup: All - -Power options -------------- - -First, enable the "Power" Windows service. Then, set all of the following: - - * Put the computer to sleep: `Never` - * Turn the display off: `Never` - * Turn off hard disk after: Setting (Minutes): `0` - -Turn off hibernation. Open a command prompt (`cmd.exe`) as an administrator, -then execute: - - powercfg -h off - -The hibernation file (`C:\hyberfil.sys`) should now be deleted. - -Manual tasks that can/should be started in the template -------------------------------------------------------- - - * Disk defragmentation - - * Windows Update - - * Windows file cleaning - 1. Run windows drive cleaner as Administrator. - 2. Enable all the task and run the cleaner - - * CCleaner file cleaning - 1. Install CCleaner free - 2. Copy the attached ccleaner configuration file in CCleaner program file folder - 3. Run ccleaner with all option set except "wipe free space" (it will also remove user history and preferences) - 4. Run ccleaner only with the option "wipe free space". - - It will write zeros in all unused space. This will allow you to strip the root.img file later - - * TemplateVM stripping - - Ensure that you know what you are doing in this section as you may destroy by error your template root.img file. - - * If you ran ccleaner with "wipe free space", follow the following procedure - - 1. from dom0, go to /var/lib/templates-vm/yourtemplate - - 2. copy root.img using the following command - - > cp --sparse=always root.img root.img.clean - - 3. if the copy worked, you can move the new root file by running this command - - > mv root.img.clean root.img - - * If it doesn't manage to fill the free space with zeros, you can follow the following *unsafe* undocumented procedure - - 1. from dom0, go to /var/lib/templates-vm/yourtemplate - 2. check the partitioning to identify the filesystem offset of root.img - 3. mount the filesystem - 4. create a file with zeros inside the filesystem until the mounted filesystem is full - 5. remove the file - 6. unmount the partition - 7. make a copy of root.img in sparse mode. +This content has moved to [Qubes Forum: Community Guides](https://forum.qubes-os.org/c/guides/14). [Learn more.](https://forum.qubes-os.org/t/announcement-qubes-community-project-has-been-migrated-to-the-forum/20367/) diff --git a/docs/hardware/Autonomous Qubes-install (kickstart).md b/docs/hardware/Autonomous Qubes-install (kickstart).md index 1caec54..deee4c7 100644 --- a/docs/hardware/Autonomous Qubes-install (kickstart).md +++ b/docs/hardware/Autonomous Qubes-install (kickstart).md @@ -1,206 +1 @@ - - -## Note - Doc not finished yet! ## -This doc is reaching toward completion, however, has some errors that need correction first, as well as missing additions. - -To-do: -- Fix kickstart template, it has a couple of issues, like creating user account creation that does conflict with first-boot, Qubes's initial-setup. -- Include template variants (for example to illustrate how they are modified, but this is a low-priority to-do). -- Sorting and including/excluding the proper packages that are recommended or optional (recommended packages are high priority, optional packages are low priority). -- Completting the sections that mention "may be included in the future" found a few places in the doc. -- Fixing bad tips, advices or KS-template layouts (proof-reading, requires extra study/read-up (must be done before official Qubes doc PR summit), or help from someone with insight). -- Fixing poor explanations (proof-reading). -- Fixing typo's and spelling errors, grammer etc, (proof-reading). -- Any feedback or contributions, like helping toward finishing the to-do, is very welcome and appreciated. - - -## Introduction ## -The purpose of kickstart files is to install an operation system from start to end with less, or no human interaction at all. A kickstart file is therefore essentially a pre-configuration of any settings you may normally need to adjust during a normal Linux install. Here you may find instructions on how to get started with Qubes OS and kickstart files. - -In order to avoid confusion, please note that the use of the wording kickstarter template does not refer to Qubes templates, but rather a simple configuration file, which when loaded will semi or fully Autonomously install Qubes (or fedora/redhat/cent). - -
- -**Typical uses**
-_The list is not exhausted, there may be other uses not listed here._ -- Custom Qubes OS install. - - Please note that the kickstarter template does not use installer-default kickstarter layout, a layout which by default also is incomplete (evident by the settings and values you normally adjust during normal install of the operation-system, but are autonomously configured here in the kickstarter file). - - A greater degree of freedom to include/exclude commands, packages, or modify variables, which may otherwise not be changeable in the default installer. This gives you greater freedom to how you want your system to be set and organized. -- Swiftly installing or re-installing Qubes OS. - - May be used to smoothly and quickly recover should dom0 be suspected of any compromises. - - Various of scripts and automation can be included, to quickly restore everything in a clean state. - - Switching, or frequently switching to new or different hardware. -- Installing Qubes without graphic driver or card. - - May be useful if needing to upgrade kernel, drivers, or other parts, without re-building Qubes installer or being forced to wait for a future Qubes version. - - May be useful if installing Qubes from a remote location. -- Installing Qubes on a larger quantity of machines. - - Typically wanted in organizations or companies, but may also be useful for some private power-users. -- Constructing a Qubes installer for a friend or family, who may be less advanced computer users. - - Combine it with scripts, and they can easily recover themselves. - - Scripts can also be used to automate other things, like restoring backups (maybe include a popup confirm message). - - Kickstart file and all scripts can be put on the installer medium, other on a separate USB/medium. It makes it easier for the user if kept on a single device. - -_Once you constructed your kickstart file, using them is be faster than normal Qubes install. It may take some time in the beginning to get proper habits and adjusting your personal settings, but consider it a time investment to save time and hassles in the future. Note new Qubes version release distributions may be slightly different, sometimes this may or may not require changes to your kickstart file. Be sure to keep your kickstart file secured, or check it against any changes done by 3rd party sources. However kickstart files are simple enough to quickly review before use, be sure you check everything, packages as well._ -
- - -## Kickstart Template - Introduction to basics ## -_This section provides an introduction to the basics, you may skip if you're an average terminal user, and if you know how to load a kickstart file in grub._ - -This particular kickstart template introduced as a finished version in the example down below, will once initiated, install Qubes fully autonomously, without any human interaction to the selected drive. Be sure you put the correct drives and configurations. If you're not sure, then please disconnect other drives to ensure you do not mistakenly overwrite drives and their potential valuable data. - -Users who have NVMe disks, please use `nvme0n1` instead of `sda`. Keep in mind if you got more than one NVMe drive, that this changes nvme0n**X**p**Y** in a similar fashion to normal sd**XY**. For example `nvme0n3` is equivalent to `sdc`, and `nvme0n3p4` is equivalent to `sdc4`. - -Once installed, and Qubes is booting for the first time, and if you're asked to put a new username please use the same user-name in the Qubes initial-setup as you have put in your kickstart file. - -Kickstart files are very easy to use and initiated. Whether on the installer medium or on a seperate medium, you just need to include the kickstart file location in the installer command line. For Qubes 4, press the Tab key at early Qubes installer boot stage, before you start the installer. Insert `ks=hd:sda:/ks.cfg`. Keep in mind it can be modified logically. If the ks.cfg is named differently, if its in a folder, if you're using a different device (like for example sdc4), or you're pulling it from a network location, etc. Please look it up if more is needed to config. - -Copy and paste the below into a text editor, use nano, vi, or which text editor you prefer. Edit it to your needs, don't run it without first checking account details and drive install location. The name of the kickstart file is optional, but it must always end with `.cfg`. Naming it `ks.cfg` is recommended. Simply move it to anywhere the installer can reach it when booting, whether using the same medium or an extra separate medium. - -You may use any terminal to identify a second medium's location. But remember if you unplug, or shutdown the machine after plugging in two or more medium devices, that their hierarchy may change. Sometimes a machines BIOS/UEFI may behave oddly in this manner. Keep this in mind if you cannot start/load the kickstart file. Installer will inform you before it starts making changes to the drive, if the kickstart file cannot be found, or if there are instructions it cannot understand in the kickstart file. - -## Kickstart Template - Adjusting your modifications ## -_All variables that needs changing, are labelled `change`, which include credentials, drive letters, timezones, language. Scroll below the template to find instructions on how to adjust values, revoming or including commands, package inclusion, etc._ - - -``` -# Kickstart file, preconfiguring the Qubes installer settings. - -# Initializing installer -cdrom -text - -# Protective measures, including redundancy measures. -ignoredisk --only-use=change -firewall -network --hostname=dom0 -authconfig --enableshadow --passalgo=sha512 -sshpw --lock -rootpw --lock - -# Account details -keyboard --vckeymap=change --xlayouts='change' -lang en_change.UTF-8 -timezone change/change --isUtc -user --groups=wheel,qubes --name=change --password=change --iscryped - -# Disk and Partitioning -bootloader --location=mbr --boot-drive=change --password=change --iscrypted -clearpart --all --initlabel --drives=change -autopart - -# Boot settings -xconfig --startxonboot -firstboot --enable - - -%packages -@^qubes-xfce - -%end - - -%anaconda -pwpolicy root --minlen=0 --minquality=1 --notstrict --nochanges --emptyok -pwpolicy user --minlen=0 --minquality=1 --notstrict --nochanges --emptyok -pwpolicy luks --minlen=0 --minquality=1 --notstrict --nochanges --emptyok -%end -``` -
- - -## Adjusting credentials and encryption ## -- **All variables** that needs changing, are labelled `change`, which include credentials, drive letters, timezones, language. -- **Securing passwords** - The kickstart file can include passwords in plaintext, in which you simply write your password directly in the kickstarter file (not recommended), or with encrypted format (recommended). The ´--plaintext´ flag after passwords will instruct the use of plaintext in password databases, while ´--iscrypted´ flag after passwords will instruct to use hashed password values. - - **Note that pre-hashing your passwords** is important if your kickstart file is ever discovered. It may be best to assume the worst, so it is recommended to always use --isencrypted flag and include the hashed password values. - - **Basics of salt encryption** - Only creating hash values for your passwords is not enough to protect them, further protective measures are needed to increase the difficulty to gaining access, especially if you're using a short non-truly random password. This can be done by using salt encryption, which will generate a different hash value, even if you re-generate the same salt salted password again. Note that it will work on different machines even if the same password uses a different hash value, this is because the salted hash value includes the encrypted instructions that the encryption algorithm will read and understand, and ultimately in a more secure manner obtain the real hash for your password. Therefore it's fine to create your salted passwords elsewhere, whether on the same or a different secured system. Salt encrypted hashed passwords can only be understood by the legitimate programs, so be sure you do not mix them up with each others below. User login for grub2 encrypyion is always root. If you're curious to learn more, then you may find extra reading in the external sources headline further down below. -- **Grub2 encryption** - If you need to generate a hash password for the ´--iscrypted´ flag, then you can generate grub2 salted hash values in any secure terminal with grub2 installed. You may freely use any system, however make sure it is not compromised. Copy the whole line, starting from ´grub.pbkdf2.sha512...´. -- **Protecting the user-account** - Similar as for enhanced grub2 encryption, you may use ´--iscrypted´ to your user Linux profile, but keep in mind that Linux uses a different salt algorithm from grub2, so you'll need to adjust accordingly. Copy/paste this termianl to a clean dispVM, or use a clean fresh AppVM; `python -c 'import crypt,getpass;pw=getpass.getpass();print(crypt.crypt(pw) if (pw==getpass.getpass("Confirm: ")) else exit())'`. Just like with grub2, it'll ask for a password and a confirmation, before printing your salted hash. Copy/paste your hash value into the kickstart file user account password field. -- **Account name** - If you haven't already donr so, feel free to change it to any desired name. -- **LUKS disk encryption** - Will be included before official Qubes doc PR. -- **If you prefer not to encrypt grub2** - To disable, remove `--password=change --iscrypted` from the bootloader kickstarter line. -- **If you prefer not to encrypt disk** - Will be included before official Qubes doc PR. - - -## Adjusting drive letters ## -- All variables that needs changing, are labelled `change`, which include credentials, drive letters, timezones, language. -- Will be included before official Qubes doc PR. - - -## Adjusting timezones and language ## -- All variables that needs changing, are labelled `change`, which include credentials, drive letters, timezones, language. -- Will be included before official Qubes doc PR. - - -## Adjusting included packages ## -**Optional package list** -_List is not finished, will be updated._ -``` -@base -@base-x -@xfce-desktop-qubes -@xfce-extra-plugins -@xfce-media -@kde-desktop-qubes -@sound-basic -@fonts -@hardware-support -@qubes -@anaconda-tools -``` - -## Including or excluding kickstart commands ## -- Will be included before official Qubes doc PR. - - -## Kickstart uses gone wrong - Examples to avoid ## - - Keep any fully autonomous kickstart USB's, or the medium of choice, locked-up, properly labelled, or avoid other scenarios where it may mistakenly be booted, by you or someone else. - - It may be useful to have at least one manual option to select, before the installer starts on its own. - - If you have other partitions or drives, be extremely careful and delicate. - - Think at least twice before you boot from the kickstart file, so you don't overwrite anything important. - - If you're not 100% sure of what you're doing, then pull out the other drives first. The kickstart file may install on the wrong drive or partitions if it is not set correctly. - - When making semi kickstart files, be mindful of which settings that need to be disabled in order for the kickstart file to properly halt. -
- -## Qubes kickstart usage: Tips and tricks that may make a difference ## -- **Graphics issues** - - If you're trying to get Qubes installed, for example on a machine without graphics, and you need sys-net and sys-firewall to update and repair dom0, then you may want to insert a network cable that does not require a password. - - If you do not have an RJ45 network port, then you can permanently or temporarily move the USB controller into your sys-net. Tell the Qubes installers initial setup at first boot, to make sys-net include sys-usb, so that sys-net holds your USB controllers. This way you can find your, or buy, a cheap USB to RJ45 network converter. - - Instructions on how to enable password based networking without graphic drivers are possible, like wireless networking. But in its current form is not included in this doc. It may however be included in the future. -- **Updating Qubes offline (without network)** - - Instructions on how to securely download updates on a different computer and install via USB or other mediums is possible. May be included in the future. -- **Reaching dom0 Terminal** - - Five different easy ways to get terminal on an empty system, to identity drive order/numbers. - - Let the Qubes installer boot normally. When or if it fails, switch to tty2 or tty3 to get terminal. If this does not work (it may sometimes not be reachable on a failed boot), then proceed to next point below. - - Put the number `3` after `quiet` in the boot Linux boot parameters. This boots the system into a non-graphical dom0 terminal (similar effect to using tty#). - - Boot from the Qubes installer, pick troubleshoot, and then the option to rescue an existing Qubes system (even if there is no Qubes system installed). When requested to pick between 4-5 options, kick the skip to shell (if you only need to do `lsblk` for disk information, then this is sufficient), or continue into existing Qubes dom0 if you need it for other extra reasons. - - Use a Live boot from a different distro, however unlike the above, this does not load most or all Qubes sub-systems, and also risks exposing dom0. This is the least desired method. - - Preferably use another Linux distro you trust. For example Fedora live, the distro which dom0 is based on. - - The Qubes Live (Alpha) medium may also work, however this is currently untested. Using any of the first 3 options above should be sufficient. - -## Qubes booting: Tips and tricks that may make a difference ## -General issues with Qubes booting or installing issues can be found here [found here](https://github.com/Qubes-Community/Contents/blob/master/docs/hardware/Boot-or-install-issue-compendium.md). Be mindful that you may, or may not, need to combine these two docs (depending on if you got multiple boot/install problems). For example you may need to fix the booting issues, but the kickstart file may still be helpful if you encounter some types of install issues, or graphic-boot issues during the installer (where graphics can be fixed later, once succeeding in text-mode install). - - -## Insight, guides, and other external resources ## -- **Resources** - - Official Anaconda kickstart developer documentation guide
-https://github.com/clumens/pykickstart/blob/master/docs/kickstart-docs.rst - - Official Fedora Kickstart guide (Adjusted for fedora 27)
-https://docs.fedoraproject.org/f27/install-guide/advanced/Kickstart_Installations.html. - - Official RedHat Documentation guide
-https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/6/html/installation_guide/ch-kickstart2 - - Wiki - Salt Cryptography
-https://en.wikipedia.org/wiki/Salt_(cryptography) - -
- -- **Qubes resources** - - Here you may find the post this doc originally was inspired from.
-https://groups.google.com/forum/#!msg/qubes-users/-9qRHSkwfy8/CCx08nnTVEAJ - -
- - -## Consideration before submitting updates to this doc ## -This doc is originally submitted by the fully independent volunteer group, Qubes Community Collaboration (QCC). You're naturally free to submit improvements of this doc to the Qubes OS staff for review on your own , but you can also choose to go through our channels at https://github.com/Qubes-Community/Contents/issues if you would like to improve the doc through the community collaboration. Feel free to start up an issue at QCC to discuss this doc and how to proceed. This potentially saves the Qubes OS staff time and resources, while still preserving transparency, and it helps improving doc PR summits further when worked out, improved, and shaped by a community. If its your first time submitting to GitHub but you would like to be independent, then we at QCC still encourage you get some GitHub experience through our channels first, before submitting anything official Qubes OS on your own. Credit to author(s) will always be preserved. +This content has moved to [Qubes Forum: Community Guides](https://forum.qubes-os.org/c/guides/14). [Learn more.](https://forum.qubes-os.org/t/announcement-qubes-community-project-has-been-migrated-to-the-forum/20367/) diff --git a/docs/hardware/fixing-booting-issues-compendium.md b/docs/hardware/fixing-booting-issues-compendium.md index f72bd8c..deee4c7 100644 --- a/docs/hardware/fixing-booting-issues-compendium.md +++ b/docs/hardware/fixing-booting-issues-compendium.md @@ -1,41 +1 @@ - -## Note - Doc is not finished and under construction ## -This doc is in its early development phase, and will be continuerly added to, and is intended for multiple users to add in their own install/boot issue experiences, or adding problems/solutions to issues that is found and collected from other users. - -**To-do table** -- To do the to-do table (uhue, the irony, but in a hurry atm). -- Feel free to add to the to-do list though, or the doc itself below. - - -## Fixes to booting and installing issues compendium ## - -**Reaching Qubes 4.0 boot installer configuration** -- In Qubes 4.0, and maybe 4.1. although it may have been fixed in the upcoming 4.1. version, you will need to use the `Tab` key instead of the `e` key like you normally do to change settings in the Grub boot installer menu. - - It looks different to Grub, here little changes except for the bottom of the screen, which will include a brief couple of lines where you can change settings. - - You may include the kickstart script here, and you can also do other settings changes like blacklisting drivers, or enabling drivers, and so on. -- **Some BIOS cause irritating issues, and how to avoid/fix** - - One such scenario are if you cannot find your boot device despite it having worked previously, and settings have not changed in BIOS. If this happens, it often works to enter the BIOS, making no changes, and choose "save and exit". This refreshes the BIOS settings, and the drive can be booted. - - Other times the BIOS may "reset" on its own without any warning, for example if you change hardware or at any time had temporairly removed any hardware (internal hardware, not counting USB devices, etc.). If you're having issues, make sure this is not the case by checking the BIOS settings. Off-topic, but worth including: The BIOS reset can also lead to disabling the IOMMU security settings if it is disabled in the default factury profile, and if you don't notice the BIOS reset, then this will leave your system becoming vulnurable. Please consider using Anti-Evil-Maid (AEM) to protect against these, but be mindful of the trade-off's of using AEM. [You can find official information about AEM here](https://www.qubes-os.org/doc/anti-evil-maid/). -- **Disabling Secure Boot, and hidden bugs** - - Currently Qubes OS do not hold a secure boot key/license, so secure boot will not work with Qubes. - - The Qubes OS staff have stated that they do not endorse secure boot, because it has short-comings and issues. - - Currently your only option is to disable secure-boot. - - Please remember that other installed dual-boot systems that depend on secure-boot may stop working if you disable secure-boot. This isn't only Windows, but include some Linux distributions that have choosen to support secure-boot. - - In general it's also discouraged to run dual-boot systems, whether Linux, Windows or other, because it weakens the isolation protection that dom0 seeks to maximize. - - High profile targets, or just unlucky badly infected systems, make dual-boot a significant threath to dom0, encryption is not enough (anything in various device firmware (like drive firmwares), BIOS/UEFI, or Grub itself, can be infected and exploited). Keeping your system clean, preferably without previous history of previous system installs, is desireable (If this is all new to you, then you're encouraged to read up on general and common Qubes security). - - A hidden bug appears on "some" motherboards/BIOS versions, where it may not always be enough to just disable secure-boot, but also deleting the secure-boot keys (if available). - - Remember to check the motherboard manual if you can restore the keys on a later point if you need them later! - - It is unknown how common the bug is, it's probably not widespread, but it has at least one anecdotal case on a desktop ASUS Z170 Pro motherboard. -- **Unsupported graphic-cards and dual graphic-cards** - - You gain little or no benifit by putting a powerful graphiccard in dom0, unless your goal is many screens, or extreme resolutions. Most modern internal graphic cards can easily run a 4K screen, or a couple of dual-screens in 2K-3K graphic resolution. - - Some dual-graphic motherboards have adjustable BIOS settings that affects both internal and external, like shared memory or simiar effects. Be sure you check these settings if you have trouble booting. - - Do not do this if you do not know what you're doing, changing such settings could give you a black screen at boot or damage your system (especially on systems that have overclocking features, whether you intend to overclock or not, such BIOS typically have many more settings outside the overclocking section, which may or may not be dangerous for your systems well-being to change). - - One way to fix bad BIOS settings that cause a black-screen, that normally works and assuming no damage was caused, is to temporarily remove the CMOS battery on the motherboard to reset it (or switch jumpers, see your motherboard manual). - - If you have a laptop or an exotic system then it may be hard to reach such a reset functionality, but similar most laptops have simple BIOS's, which as a result means it may be less easily set to a bad setting requiring a reset (but still be careful). - - If you use an unsurported graphic-card by Qubes OS, then it requires troubleshooting (like the above kickstart graphic fix tip), or it may not be possilbe (missing drivers/support for fedora systems). - - (Nvidia/Intel graphics): If you have a dual-graphic system (Onboard-Intel/External-Nvidia), then it may be easier to go with the on-board Intel graphics which is better supported than nvidia drivers. The nouveau drivers are preferred, sincenthe offical nvidia drivers are closed source Proprietary code and shouldn't be trusted in the dom0 environment, and can also be quite troublesome to install as well. - - (AMD graphics): The onboard/external graphic cards by AMD which tend to be more supported on Linux in general, although it is uncertain if its better supported than onboard intel graphics (Onboard intel may probably generally be a bit better than AMD, but many AMD cards seem to work quite neatly as well). - - More effort is being put into making AMD graphics work in Linux, for example the Linux Kernel 4.17 will include support for AMDGPU in the kernel itself, where you no longer need to provide a newer linux-firmware package and then enable it yourself in the kernel settings during Grub start-up, but from then onwards, should just work out-of-the-box. - - This presumes the right version of AMDGPU is in the kernel (from 4.17. upwards) and that your AMD graphic-card isn't too new for the kernel (reasonable to assume within 6 months to 12 months), or possibly too old. - - Currently dom0 graphics is not passthrough but is run directly in the domo environment, and therefore does not need to have passthrough capability, however, and be mindful, that this may or may not change in Qubes 4.1. where graphics may become isolated from dom0, which may potentially bring new passthrough graphic issues to life. - - This new isolation feature may possibly be optional, just like PV/HVM/PVH, sys-usb isolation, and similar user-choices, depending on what the developers finds to be the best approach to avoid hardware conflicts, so keep this possibility in mind for the future. +This content has moved to [Qubes Forum: Community Guides](https://forum.qubes-os.org/c/guides/14). [Learn more.](https://forum.qubes-os.org/t/announcement-qubes-community-project-has-been-migrated-to-the-forum/20367/) diff --git a/docs/hardware/hardware-selection.md b/docs/hardware/hardware-selection.md index c2d7725..deee4c7 100644 --- a/docs/hardware/hardware-selection.md +++ b/docs/hardware/hardware-selection.md @@ -1,206 +1 @@ -# Hardware Selection Tree # - -Selecting the appropriate hardware for Qubes R4.0 can be a complex choice. -This document aims to simplify that. -Click on the links, read the supporting information if desired, reach a conclusion. - -You may also want to check [these links](/docs/misc/iaq.md#xen-passthrough-compatible-video-cards) if you plan to use GPU passthrough (more suitable to desktop computers: laptop users will likely have a hard time finding a hardware combination that fits their needs since most of the supported graphics adapters are secondary adapters). - -**Note** Qubes OS does not endorse any of the manufacturers or methods listed. - -### Start here ### - -Are you concerned about potential manufacturer [hardware backdoors](https://libreboot.org/faq.html#intel)? - -[Yes](/docs/hardware/hardware-selection.md/#concerned) -[No](/docs/hardware/hardware-selection.md/#unconcerned) - -### Concerned ### - -Are you concerned about [blobs](https://www.coreboot.org/Binary_situation) being used to initialize hardware? - -[Yes](/docs/hardware/hardware-selection.md/#init) -[No](/docs/hardware/hardware-selection.md/#mecleaner) -[No, but I want AMD](/docs/hardware/hardware-selection.md/#amd) - -### Init ### - -Nearly all R4.0 capable systems require at least a CPU microcode blob, and often one for video BIOS. -However, there are still some options when it comes to running the [proprietary, unaudited code](https://www.coreboot.org/Intel_Management_Engine#Freedom_and_security_issues) for hardware initialization. -Do you want: - -[AMD](/docs/hardware/hardware-selection.md/#amd) -[Intel](/docs/hardware/hardware-selection.md/#intel) - -### AMD ### - -If you don't mind older/used hardware, there are some options if you do not want [PSP initialization](https://libreboot.org/faq.html#amd-platform-security-processor-psp). -All new AMD hardware comes with PSP. -In theory there is an option to partially disable it, but no motherboard/BIOS manufacturers have made it available yet. -Please update this if you are aware of any manufacturers that have. - -Form factor? - -[Laptop](/docs/hardware/hardware-selection.md/#amd-laptop) -[Desktop](/docs/hardware/hardware-selection.md/#amd-desktop) - -### AMD Laptop ### - -DIY corebooted used [Lenovo G505s](https://www.coreboot.org/Board:lenovo/g505s) with [microcode patch](https://review.coreboot.org/#/c/coreboot/+/22843/). - -### AMD Desktop ### - -DIY or commercially available corebooted (or librebooted?) [KCMA-D8](https://www.coreboot.org/Board:asus/kcma-d8)/[KGPE-D16](https://www.coreboot.org/Board:asus/kgpe-d16). -Vikings is one vendor that appears to sell these. -If used with Opteron Series 2 processors, no microcode blob is required. However, it is still recommended to include current microcode due to vulnerabilities. - -### Intel ### - -Unfortunately, all R4.0 capable Intel hardware requires use of at least the [BUP portion](https://github.com/corna/me_cleaner/wiki/HAP-AltMeDisable-bit) of Intel ME. -[Weaknesses](https://mobile.twitter.com/rootkovska/status/938458875522666497) have been found in this proprietary, non-owner-controlled code. -There are some ways to restrict Intel ME after the initial BUP. - -[Commercial](/docs/hardware/hardware-selection.md/#intel-commercial) -[DIY](/docs/hardware/hardware-selection.md/#intel-diy) - -### Intel Commercial ### - -These vendors have systems available that partially disable Intel ME after the initial hardware initialization: Insurgo ([Qubes Certified](https://www.qubes-os.org/news/2019/07/18/insurgo-privacybeast-qubes-certification/)), System76, Purism, Dell. -Implementations vary, so research the vendors. -Prefer ones that use Heads or Coreboot instead of closed-source, [proprietary](https://www.kb.cert.org/vuls/id/758382) [UEFI firmware](https://www.securityweek.com/researchers-find-several-uefi-vulnerabilities). -Search the [HCL](https://www.qubes-os.org/hcl/) for a compatible system. -[Search the mailing list](https://www.mail-archive.com/qubes-users@googlegroups.com/) for additional reports. - -### Intel DIY ### - -Closed-source, proprietary UEFI firmware has its own [set](https://www.kb.cert.org/vuls/id/758382) of [vulnerabilities](https://www.securityweek.com/researchers-find-several-uefi-vulnerabilities). -Do these concern you? - -[Yes](/docs/hardware/hardware-selection.md/#coreboot) -[No](/docs/hardware/hardware-selection.md/#mecleaner) - -### Coreboot ### - -Cross reference [Coreboot](https://www.coreboot.org/Supported_Motherboards) capable systems with the [HCL](https://www.qubes-os.org/doc/hcl). -See also the [board freedom index](https://www.coreboot.org/Board_freedom_levels). -[Search the mailing list](https://www.mail-archive.com/qubes-users@googlegroups.com/) for additional reports. -Flash your system with Coreboot, including [ME_Cleaner](https://github.com/corna/me_cleaner). - -[Heads](http://osresearch.net/) also offers some interesting capabilities beyond Coreboot, but has a smaller list of [supported boards](https://github.com/osresearch/heads/tree/master/boards). - -### MECleaner ### - -You can partially disable Intel ME while still running vendor UEFI firmware. -Search the [HCL](https://www.qubes-os.org/hcl/) for a compatible system. -[Search the mailing list](https://www.mail-archive.com/qubes-users@googlegroups.com/) for additional reports. -Follow the instructions [here](https://github.com/corna/me_cleaner). - -### Unconcerned ### - -Search the [HCL](https://www.qubes-os.org/hcl/) for an R4.0 compatible system. -[Search the mailing list](https://www.mail-archive.com/qubes-users@googlegroups.com/) for additional reports. - -## Additional Notes ## -If selecting a desktop, you may also want to include and use a third party NIC in an expansion slot instead of the onboard Ethernet. -This is often not an option in laptops with manufacturer firmware due to the use of NIC whitelists, but you can use a USB based ethernet or wifi adapter instead with either desktop or laptop. -Optionally, disable DHCP on the subnet(s) your Qubes device connects to. -This will help avoid overt network communications from onboard management. -
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
+This content has moved to [Qubes Forum: Community Guides](https://forum.qubes-os.org/c/guides/14). [Learn more.](https://forum.qubes-os.org/t/announcement-qubes-community-project-has-been-migrated-to-the-forum/20367/) diff --git a/docs/localization/keyboard-multiple-layouts.md b/docs/localization/keyboard-multiple-layouts.md index ca831b7..deee4c7 100644 --- a/docs/localization/keyboard-multiple-layouts.md +++ b/docs/localization/keyboard-multiple-layouts.md @@ -1,53 +1 @@ -Using multiple keyboard layouts -=============================== - -The [official Qubes OS faq entry](https://www.qubes-os.org/faq/#my-keyboard-layout-settings-are-not-behaving-correctly-what-should-i-do) only covers how to change the layout *globally* - ie. both for dom0 and VMs, with a *single* layout. - -This document shows several ways of using *multiple* keyboard layouts and being able to *quickly* switch between them. - -Recommended setup ------------------ - -Run `setxkbmap` in *each* VM. Dom0 stays untouched (running `setxkbmap` in dom0 too will interfere with the VM's `setxkbmap` setup). - -For instance the following command would alternate between the US English and the Bulgarian phonetic layout when pressing both shift keys: - -~~~ -setxkbmap -layout "us,bg(phonetic)" -option "grp:shifts_toggle" -~~~ - -To automatically run the `setxkbmap` command when the VM starts, add a `/etc/xdg/autostart/setxkbmap.desktop` file in the VM's *template* with the following content: - -~~~ -[Desktop Entry] -Name=Configure multiple keyboard layouts -Exec=setxkbmap -layout "us,bg(phonetic)" -option "grp:shifts_toggle" -Terminal=true -Type=Application -~~~ - -Note: for some reason, with `Terminal=false` the setxkbmap settings aren't applied until one runs `setxkbmap` without options in a terminal. Setting `Terminal=true` works around this problem, but you will notice a terminal flicker at startup. - -If you prefer to have a per-vm setup rather than per-template, create a `/rw/config/setxkbmap.desktop` with the same content as above and add the following line to `/rw/config/rc.local`: - -~~~ -cp /rw/config/setxkbmap.desktop /etc/xdg/autostart -~~~ - -Note: the reason we can't put the `setxkbmap` command in the `rc.local` script is because the X server isn't running when `rc.local` is executed. - -Alternatively, you could add the `setxkbmap` command to your profile's `.bashrc` file if you use terminals to start applications. - - -Alternative setups ------------------- - -- Configure a keyboard shortcut in dom0 that would run `qvm-run vname 'setxkbmap ...'`, where the VM is the one whose window is under the mouse pointer (using `xprop -id $(xdotool getactivewindow`) ). An advantage is that it doesn't require tweaking VMs or templates, but this is a bit convoluted and `qvm-run` is sometimes slow when the system is under heavy I/O usage, so the layout switch doesn't happen immediately which is annoying. -- Change the layout with `setxkbmap` *only in dom0*. This isn't optimal because: - - there is no way to know which layout is used when typing the password in the xscreensaver's password field. - - sometimes the keyboard layout would not be propagated to one of the VMs, requiring a reboot of the VM. -- Once Qubes OS gains support for keyboard layout propagation from dom0 to VMs (see [this official issue](https://github.com/QubesOS/qubes-issues/issues/1396)) the desktop environment's keyboard layout switcher (eg. Xfce Keyboard Layout switcher) could be used instead of `setxkbmap`. It is not clear however if this solution won't have the same issues as above. -- Change the layout in dom0 with `localectl`: it's a no-go as it requires a reboot - - -`Contributors: @taradiddles` +This content has moved to [Qubes Forum: Community Guides](https://forum.qubes-os.org/c/guides/14). [Learn more.](https://forum.qubes-os.org/t/announcement-qubes-community-project-has-been-migrated-to-the-forum/20367/) diff --git a/docs/localization/multi-language-support-dom0.md b/docs/localization/multi-language-support-dom0.md index dfcc174..deee4c7 100644 --- a/docs/localization/multi-language-support-dom0.md +++ b/docs/localization/multi-language-support-dom0.md @@ -1,63 +1 @@ -Using multiple languages in dom0 -================================ - -Installing additional languages -------------------------------- - -Switching languages is pretty easy in your domUs. However, in dom0, there's only -English available after installation if no additional languages have been installed. -To install more languages in dom0, use the following command: - -~~~ -sudo qubes-dom0-update glibc-langpack-LANGUAGE -~~~ - -Note that `LANGUAGE` should be a valid language code, e.g. `en` for English, `de` for -German, `it` for Italian and so on. - -You can check which languages are available on your system using: - -~~~ -localectl list-locales -~~~ - -Setting a language globally ---------------------------- - -If you want to switch your whole dom0 from English to some other language, -edit the file `/etc/locale.conf` to include your language code for the `LANG=` value. -For example, to change your dom0 to Italian, the file `/etc/locale.conf` should contain: - -~~~ -LANG="it_IT.UTF-8" -~~~ - -Important: Using some language other than English is not officially supported, i.e. you -might still get a lot of English content which has not been translated to your desired language. - -Setting only some formats -------------------------- - -If you just want to change some format specifiers, you can add the `LC_*` identifier -in the same file, below the `LANG=` code. Avoid the `LC_ALL` identifier, because it overwrites -all previous settings! For example, to use German time formats but still use the English -language as default for anything else, you would write the following in `/etc/locale.conf`: - -~~~ -LANG="en_US.UTF-8" -LC_TIME="de_DE.UTF-8" -~~~ - -Those codes must be supported by your dom0 (check with `localectl list-locales`). - -After you finished editing, check your new setup with `localectl status`. You might need -to logout and login back again to enable your changes in the environment (e.g. in the window -manager or its applets). - -You might also want to inspect the changes introduced by adding/editing one `LC_*` rule -in the config file. Use `locale -k $rule` for this purpose, e.g. `locale -k LC_TIME` to -show the formats exported by the setting of the `LC_TIME`. - -If you see "broken characters" like `�` somewhere, check the encoding of the affected -application. The default terminal emulator in dom0 does not use Unicode as default -encoding and therefore has some problems when it's not adjusted accordingly. +This content has moved to [Qubes Forum: Community Guides](https://forum.qubes-os.org/c/guides/14). [Learn more.](https://forum.qubes-os.org/t/announcement-qubes-community-project-has-been-migrated-to-the-forum/20367/) diff --git a/docs/misc/qubes-evaluation-walkthrough.md b/docs/misc/qubes-evaluation-walkthrough.md index c3dfca3..deee4c7 100644 --- a/docs/misc/qubes-evaluation-walkthrough.md +++ b/docs/misc/qubes-evaluation-walkthrough.md @@ -1,114 +1 @@ -Evaluating Qubes - Walkthrough -============================ - -Thinking about using qubes? -This document is not about how to use qubes securely. -This document is a walkthrough, about how to evaluate qubes in order to answer the question "is qubes for me"? - -You should evaulate qubes on a scratch system using a blank hard drive. -After evaluating, if you decide that qubes is right for you, you should then delete your evaulation installation from the hard disk and install qubes for real, this time actually caring about the security of your data. - -Part 1 - Install Qubes -====================== - -- Find compatible hardware - - select a system to install qubes on by using https://www.qubes-os.org/doc/system-requirements/ and https://www.qubes-os.org/hcl/ - - the primary compatibility issues as of 4.0 are: - - that your CPU/motherboard has (working and enabled) IOMMU support (Installation instructions say that IOMMU - - the compatibility of your graphics card - - and USB issues when using USB keyboards & mice. - - Also, despite saying that you can run it in 4 Gigs, you'll want at least 8 Gigs to evaluate 4.0 - -- Install Qubes 4.0 on a blank hard drive - - Follow the installation instructions at https://www.qubes-os.org/doc/installation-guide/ - - Allow the installer to create the default qubes for you - - -Part 2 - Use/Evaluate Qubes -=========================== - -Your top priority in evaluating qubes should be to get email operational. - -Normally, in qubes you increase your security by dividing your work into differnt domains, domains which you give names like "work", or "personal", or "turn-based-stragey-games". During this evaluation we'll create a qube called "eval-qube" which you can consider to be your "real computer" where you will store all your data during evaulation. - - - Select the "Q icon" in the far upper left, then select "Create Qubes VM". - - change the name to "eval-qube" - - Color does not matter yet and can be changed later - - Leave type as "Qube based on a template (AppVM)" - - You need to choose a "template domain" that will run you applications. You can choose either fedora-32 (which uses dnf) or debian-10 (which uses apt, apt-get, and apt-cache). Choose the one you are most familiar with. (and remember which one you chose for later) - - Leave networking at "default (sys-net)" - - Click "OK" - - -Note: It would be nice to document a option for using thunderbird here, but as of 2021-05-12 the current version of thunderbird has broken compatibility with the qubes plugin - -set up mutt: - -- We decided earlier to store your data in the "eval-qube" domain, but in qubes you don't install your applications in the same domain as your data, so we will need to install mutt in the "template domain" that you selected earlier. This may sound strange but there is a good reason for it (the reason is documented in the qubes documentation, and wont be repeated here). -- Start the terminal for the template you chose by selecting the upper left "Q icon" then "Template: debian-10" (or "Template: fedora-32") then "Terminal" -- wait for 30 seconds till the terminal pops up. -- install all the packages that you will need to use mutt. They are listed in the doument https://github.com/ddevz/Contents/blob/master/docs/configuration/mutt.md - - for example, if using debian: apt-get update; apt-get install mutt fetchmail procmail urlview (expand this) - - if using fedora, then: dnf mutt ??? (research this) -- after you have these things installed, then shut down the template VM - -- next, add "mutt" to the menu - - select the upper left "Q icon", then "Domain: eval-qube", then "qube settings" - - go to "applications" - - mutt should be in the left hand column. select mutt then press the ">" button to move it to the right column. - - press apply then ok. - -- next set up mutt -- start a terminal by selecting the upper left "Q icon", then "Domain: eval-qube", then terminal" -- set up mutt via the instructions at https://github.com/ddevz/Contents/blob/master/docs/configuration/mutt.md (wrong link, use correct link) . The important parts to get working first: - 1. you want to set it up so you are able to recieve email. - - This will depend on if you want to use pop, imap, or the gmail protocal (find out what the gmail protocal is) depending on what type of email server you have. for pop you'd want to set up fetchmail and procmail to get your mail. for gmail you'd use sasl-something? for imap youd... ??? - 1. set up urlview - follow the instructions for configuring urlview listed at - 1. use the .muttrc configurations -- Now start mutt by selecting the upper left "Q icon", then "Domain: eval-qube", then "mutt" -- wait 30 seconds or so for mutt to start - - Now that you are running mutt, select each email one by one, and press enter on each email you want to view. (you can press q to stop viewing a email) - -We finally get to your first qubes feature: -When you are viewing a email (I.E before you hit q) and that email has a link displayed on the screen, but you have no evidence that you should just blindly trust the link is safe, hit Ctrl-B. It will display a list of all links in the email. select the link you want, hit enter and it will open the link in a web browser with a red border around it. It may take 30 seconds or so to load, but that is because this web browser is special as it's actually running in a seperate (disposable) virtual machine. View the web page, and when you are done close the web browser. When the web browser closes, the (disposable) virtual machine is destroyed, so even if it did comprimize the system running the web browser, that system (virtual machine) has been destroyed and the system with your email has not been comprimized. - -Dealing with downloads in a disposable VM: -========================================== - -Now open a link like that from mutt again, but this time once you get to firefox, download something. Suppose that link was a location of a download, in which case you should download that. If it wasn't a link to a download then just browse around the internet until you find something to download and download it. - -Click on the download icon in the upper right hand corner of the firefox window, then find your download, right click on it, and select "open containing folder" - -You are now in a filebrowser, and can inspect the file. You can view it if its a picture, you can unzip/untar it if its a zip or tar file. You are still in the disposable virtual machine so you wont hurt your email VM by unzipping it here. - -If you are finished with the download you can close the browser and the file manager, which will cause the disposable virtual machine to be destroyed. However, if after inspecting the file, you decide you need to keep a copy of a file, then before closing everything out you can right click in the file browser, select "copy to VM", select "work" as the target and click "OK". Then open another terminal on your system running mutt, and look in ~/QubesIncoming/disp{some number}/ for your file. - -Webbrowsing without mutt -======================== - -You can run firefox in a disposable VM without launching it from mutt by selecting the upper left "Q icon", then "Disposable: debian-10 DVM" then "firefox". Use the same procedure as above to evaluate downloads and to transfer files back to your "eval-qube". - -Remember! This is a disposable VM, meaning that any bookmarks that you add will be lost after you close the VM! - -Also, if you know what tor is, you can easily run torbrowser instead by selecting the upper left "Q icon", then "Disposable: whonix-ws-15-dvm" then selecting "tor browser" - -Note: Eventually you will try to bookmark something in the disposable VM. Naturally when you create a bookmark in a disposable VM and then destroy the VM, the next time you create a disposable VM your bookmark will be gone. There is a solution for this called "split browser" this will not be part of the evaluation here, but know that a solution exists. You can read about it here: https://github.com/rustybird/qubes-app-split-browser - - -Configure your terminal to use cut and paste: -============================================= - -Out of the box, qubes cut and paste works well with basically everything but terminals. unfortunately mutt needs a terminal to display in. - -Select some text on the terminal with your mouse, go to the "edit" menu and look at the "copy" option. You will note that the keybinding to copy is is "Shift-Ctrl-C" instead of just "Ctrl-V". Why not "Ctrl-V"? Because Ctrl-V might mean something in mutt, or in your editor, and the terminal does not want to interfere with the operation of the program running in the terminal. - -however, "Shift-Ctrl-C" is same keybinding that qubes uses for something, and they cant both use the keybinding and both be useable at the same time, so you'll need to change this. So go to "Edit" menu and select "preferences", then go to "shortcuts". go to "copy" and double click on where it says "Shift-Ctrl-C" then when it says "New accellerator" hit Super+Shift+C ("super" is the "windows key"). -now go to "paste" and double click on where it says "Shift-Ctrl-V" then when it says "New accellerator" hit Super+Shift+V - -Note: it is largely unknown, and not displayed in the shortcut list, but terminals can *also* use Ctrl-Ins and Shift-Ins for cut and paste. However reaching that far across the keyboard for such a unmemorable keybinding could make you give up on qubes, so we are fixing it here. - -Using cut and paste in qubes: -============================= - -Now go to mutt and open the link in firefox again, but this time instead of downloading something, browse the net and find a URL that we will imagine that we want to email to the person. while viewing a email in mutt, press "r" to respond to that person. hit enter twice to get through the "to" and "subject" fields. Now we are going to cut and paste the URL we found in a disposable VM into a email in our eval-qube/"real computer". In qubes instead of the sequence being Ctrl-C, Ctrl-V, the sequence is Ctrl-C, Ctrl-Shift-C, Ctrl-Shift-V, Ctrl-V. This key sequence only takes a tiny fraction of a second more time to hit then Ctrl-C, Ctrl-V so the sequence works quite well. So go to the firefox in the disposable VM, select the whole URL and press Ctrl-C, Ctrl-Shift-C, then go to the window with mutt in it and press Ctrl-Shift-V, but instead of hitting Ctrl-V, hit Super-Shift-C (remember "super" is the windows key). (why? because your pasting in a terminal) - +This content has moved to [Qubes Forum: Community Guides](https://forum.qubes-os.org/c/guides/14). [Learn more.](https://forum.qubes-os.org/t/announcement-qubes-community-project-has-been-migrated-to-the-forum/20367/) diff --git a/docs/mumble/README.md b/docs/mumble/README.md index 23ac154..deee4c7 100644 --- a/docs/mumble/README.md +++ b/docs/mumble/README.md @@ -1,90 +1 @@ -# Exposing Mumble server running in Qubes using Wireguard - -To secure communications over Mumble, you should control the machine on which -the Mumble server is running. You can run the server locally and expose it -to the world through VPS using wireguard. - -You need to setup Wireguard on your VPS and locally first. -See [the guide][wireguard]. Create a separate qube for Mumble server -and do local part of the guide in it. - -Let's say your `mumble` qube has Wireguard IP 192.168.66.10 and -your VPS has external IP 1.2.3.4 and network interface eth0. -Mumble server (murmurd) is running on port 64738 locally, but let's say -you want to expose it at port 1.2.3.4:3333. - -## Port forwarding - -On VPS run the following: - -``` -# iptables -t nat -A PREROUTING -i eth0 -p udp -m udp --dport 3333 -j DNAT --to-destination 192.168.66.10:64738 -# iptables -t nat -A PREROUTING -i eth0 -p tcp -m tcp --dport 3333 -j DNAT --to-destination 192.168.66.10:64738 -``` - -Make sure to forward both UDP and TCP. It won't work without TCP and -it will work slower without UDP. - -In `mumble` qube: - -``` -sudo iptables -I INPUT 1 -p tcp -m tcp --dport 64738 -j ACCEPT -sudo iptables -I INPUT 1 -p udp -m udp --dport 64738 -j ACCEPT -``` - -## Install Mumble server - -In `mumble` qube: - -``` -sudo apt-get install -y mumble-server -``` - -You can configure it using `sudo dpkg-reconfigure mumble-server` or -set password in `/etc/mumble-server.ini` (variable `serverpassword`) and -run `sudo service mumble-server restart`. - -Then connect from all Mumble clients through endpoint 1.2.3.4:3333. -It should work at this point. - -## Making the server persistent - -Qubes removes all system files when a qube is restarted. If you install -Mumble server from scratch every time, it won't remember any configuration, -rooms, registered users, etc. Also clients will show a warning about new key. - -So you should either make the qube standalone or use the following trick. - -All the files you need to preserve are the following: - - * /etc/mumble-server.ini - * /var/lib/mumble-server/mumble-server.sqlite - -Finish configuration and connect from all expected clients and then stop the server: - -``` -$ sudo service mumble-server stop -``` - -and save the files in home directory: - -``` -$ sudo cp /etc/mumble-server.ini /var/lib/mumble-server/mumble-server.sqlite /home/user -``` - -Now you can restart the qube. -After that you can run the following script to start the server: - -``` -set -x - -sudo apt-get install -y mumble-server -sudo service mumble-server stop -sudo cp /home/user/mumble-server.ini /etc/mumble-server.ini -sudo cp /home/user/mumble-server.sqlite /var/lib/mumble-server/mumble-server.sqlite -sudo service mumble-server start -sudo iptables -I INPUT 1 -p tcp -m tcp --dport 64738 -j ACCEPT -sudo iptables -I INPUT 1 -p udp -m udp --dport 64738 -j ACCEPT -``` - -[wireguard]: ../wireguard +This content has moved to [Qubes Forum: Community Guides](https://forum.qubes-os.org/c/guides/14). [Learn more.](https://forum.qubes-os.org/t/announcement-qubes-community-project-has-been-migrated-to-the-forum/20367/) diff --git a/docs/os/centos.md b/docs/os/centos.md index 9aa94d1..deee4c7 100644 --- a/docs/os/centos.md +++ b/docs/os/centos.md @@ -1,77 +1 @@ - -# CentOS Template - -If you would like to use a stable, predictable, manageable and reproducible distribution in your AppVMs, you can install the CentOS template, provided by Qubes in ready to use binary package. For the minimal and Xfce versions, please see the [Minimal TemplateVMs] and [Xfce TemplateVMs] pages. - - -## Installation - -The standard CentOS TemplateVM can be installed with the following command in dom0, where `X` is the desired version number: - - [user@dom0 ~]$ sudo qubes-dom0-update --enablerepo=qubes-templates-community qubes-template-centos-X - -To switch, reinstall and uninstall a CentOS TemplateVM that is already installed in your system, see *How to [switch], [reinstall] and [uninstall]*. - -#### After Installing - -After a fresh install, we recommend to [Update the TemplateVM](https://www.qubes-os.org/doc/software-update-vm/). - -## CentOS 8 End of Life - -With the end of 2021, CentOS ended its life in its stable form and started functioning as CentOS Stream, a development branch for Red Hat® Enterprise Linux®. As a result, it stopped receiving proven, stable updates and its use, especially in production environments, became risky. This is a very serious problem for many companies and individuals around the world. So there was an urgent need to find a new source of updates for CentOS in order to keep it in the infrastructure. A complete solution to this problem is support switching, that is, pointing to a new repository from which CentOS will be downloading stable updates. Such a solution is offered by various Enterprise Linux vendors such as AlmaLinux, EuroLinux or Rocky Linux. It is worth mentioning that both CentOS and RHEL and AlmaLinux/EuroLinux/Rocky Linux are systems built on the same source code, so they provide the same functionality. They differ mainly in branding. - -It's up to the user to decide, which Enterprise Linux 8 they want to migrate to. There are some differences mainly in the time it takes to release updates, errata, major and minor releases, etc. but it's up to the user to do their own research for that in order to provide an unbiased opinion. - -### How to migrate your CentOS 8 template - -We'll use vendors' migration scripts for migrating our CentOS 8 template. - -The scripts will perform various operations that may require connecting the template to the Internet. - -The scripts are located in - -- https://github.com/AlmaLinux/almalinux-deploy - for AlmaLinux -- https://github.com/EuroLinux/eurolinux-migration-scripts - for EuroLinux -- https://github.com/rocky-linux/rocky-tools - for Rocky Linux - -Please read their manuals for a successful operation. - -Please update your CentOS 8 template to the latest officially released CentOS 8.5 before running the scripts. - -#### How to update to CentOS 8.5 - -Edit your CentOS 8 repositories so they point to release 8.5 in CentOS Vault. You can use the following commands: - -``` -sudo sed -i -e '/mirrorlist=http:\/\/mirrorlist.centos.org\/?release=$releasever&arch=$basearch&repo=/ s/^#*/#/' -e '/baseurl=http:\/\/mirror.centos.org\/$contentdir\/$releasever\// s/^#*/#/' -e '/^\[BaseOS\]/a baseurl=https://mirror.rackspace.com/centos-vault/8.5.2111/BaseOS/$basearch/os' /etc/yum.repos.d/CentOS-Base.repo -sudo sed -i -e '/mirrorlist=http:\/\/mirrorlist.centos.org\/?release=$releasever&arch=$basearch&repo=/ s/^#*/#/' -e '/baseurl=http:\/\/mirror.centos.org\/$contentdir\/$releasever\// s/^#*/#/' -e '/^\[AppStream\]/a baseurl=https://mirror.rackspace.com/centos-vault/8.5.2111/AppStream/$basearch/os' /etc/yum.repos.d/CentOS-AppStream.repo -sudo sed -i -e '/mirrorlist=http:\/\/mirrorlist.centos.org\/?release=$releasever&arch=$basearch&repo=/ s/^#*/#/' -e '/baseurl=http:\/\/mirror.centos.org\/$contentdir\/$releasever\// s/^#*/#/' -e '/^\[cr\]/a baseurl=https://mirror.rackspace.com/centos-vault/8.5.2111/ContinuousRelease/$basearch/os' /etc/yum.repos.d/CentOS-CR.repo -sudo sed -i -e '/mirrorlist=http:\/\/mirrorlist.centos.org\/?release=$releasever&arch=$basearch&repo=/ s/^#*/#/' -e '/baseurl=http:\/\/mirror.centos.org\/$contentdir\/$releasever\// s/^#*/#/' -e '/^\[Devel\]/a baseurl=https://mirror.rackspace.com/centos-vault/8.5.2111/Devel/$basearch/os' /etc/yum.repos.d/CentOS-Devel.repo -sudo sed -i -e '/mirrorlist=http:\/\/mirrorlist.centos.org\/?release=$releasever&arch=$basearch&repo=/ s/^#*/#/' -e '/baseurl=http:\/\/mirror.centos.org\/$contentdir\/$releasever\// s/^#*/#/' -e '/^\[extras\]/a baseurl=https://mirror.rackspace.com/centos-vault/8.5.2111/extras/$basearch/os' /etc/yum.repos.d/CentOS-Extras.repo -sudo sed -i -e '/mirrorlist=http:\/\/mirrorlist.centos.org\/?release=$releasever&arch=$basearch&repo=/ s/^#*/#/' -e '/baseurl=http:\/\/mirror.centos.org\/$contentdir\/$releasever\// s/^#*/#/' -e '/^\[fasttrack\]/a baseurl=https://mirror.rackspace.com/centos-vault/8.5.2111/fasttrack/$basearch/os' /etc/yum.repos.d/CentOS-fasttrack.repo -sudo sed -i -e '/mirrorlist=http:\/\/mirrorlist.centos.org\/?release=$releasever&arch=$basearch&repo=/ s/^#*/#/' -e '/baseurl=http:\/\/mirror.centos.org\/$contentdir\/$releasever\// s/^#*/#/' -e '/^\[HighAvailability\]/a baseurl=https://mirror.rackspace.com/centos-vault/8.5.2111/HighAvailability/$basearch/os' /etc/yum.repos.d/CentOS-HA.repo -sudo sed -i -e '/mirrorlist=http:\/\/mirrorlist.centos.org\/?release=$releasever&arch=$basearch&repo=/ s/^#*/#/' -e '/baseurl=http:\/\/mirror.centos.org\/$contentdir\/$releasever\// s/^#*/#/' -e '/^\[centosplus\]/a baseurl=https://mirror.rackspace.com/centos-vault/8.5.2111/centosplus/$basearch/os' /etc/yum.repos.d/CentOS-centosplus.repo -sudo sed -i -e '/mirrorlist=http:\/\/mirrorlist.centos.org\/?release=$releasever&arch=$basearch&repo=/ s/^#*/#/' -e '/baseurl=http:\/\/mirror.centos.org\/$contentdir\/$releasever\// s/^#*/#/' -e '/^\[PowerTools\]/a baseurl=https://mirror.rackspace.com/centos-vault/8.5.2111/PowerTools/$basearch/os' /etc/yum.repos.d/CentOS-PowerTools.repo -``` - -Then update your system with `sudo dnf update -y --allowerasing` - -After the update has finished, remove the new `.repo` files which point to a non-existent mirrorslist with: - -``` -sudo rm -f /etc/yum.repos.d/CentOS-Linux-*.repo -``` - -You're now able to use the aformentioned migration scripts to migrate your CentOS 8.5 to your desired Enterprise Linux 8. - -## Want to contribute? - -* [How can I contribute to the Qubes Project?](https://www.qubes-os.org/doc/contributing/) - -* [Guidelines for Documentation Contributors](https://www.qubes-os.org/doc/doc-guidelines/) - -[switch]: https://www.qubes-os.org/doc/templates/#switching -[reinstall]: https://www.qubes-os.org/doc/reinstall-template/ -[uninstall]: https://www.qubes-os.org/doc/templates/#uninstalling -[Minimal TemplateVMs]: https://www.qubes-os.org/doc/templates/minimal/ -[Xfce TemplateVMs]: https://www.qubes-os.org/doc/templates/xfce/ +This content has moved to [Qubes Forum: Community Guides](https://forum.qubes-os.org/c/guides/14). [Learn more.](https://forum.qubes-os.org/t/announcement-qubes-community-project-has-been-migrated-to-the-forum/20367/) diff --git a/docs/os/gentoo.md b/docs/os/gentoo.md index a077ceb..deee4c7 100644 --- a/docs/os/gentoo.md +++ b/docs/os/gentoo.md @@ -1,30 +1 @@ - -# Gentoo Template - -If you would like to use a stable, predictable, manageable and reproducible distribution in your AppVMs, you can install the Gentoo template, provided by Qubes in ready to use binary package. For the minimal and Xfce versions, please see the [Minimal TemplateVMs] and [Xfce TemplateVMs] pages. - - -## Installation - -The standard Gentoo TemplateVM can be installed with the following command in dom0: - - [user@dom0 ~]$ sudo qubes-dom0-update --enablerepo=qubes-templates-community qubes-template-gentoo - -To switch, reinstall and uninstall a Gentoo TemplateVM that is already installed in your system, see *How to [switch], [reinstall] and [uninstall]*. - -#### After Installing - -After a fresh install, we recommend to [Update the TemplateVM](https://www.qubes-os.org/doc/software-update-vm/). We highlight that the template memory/CPU allocation certainly need to be adjusted in some cases. As Gentoo is a *linux source distribution*, the template needs resources to perform updates or installing any packages. By default, each TemplateVM has *2 VCPUs* for *4000 MB Max memory* allocated. If needed, double those values, *4 VCPUs* for *8000 MB Max memory*. For example, it has been observed failing updates or builds with *4 VCPUs* for *4000 MB Max memory* due to out of memory issue. For more general considerations, we refer to the official [Gentoo Handbook]. - -## Want to contribute? - -* [How can I contribute to the Qubes Project?](https://www.qubes-os.org/doc/contributing/) - -* [Guidelines for Documentation Contributors](https://www.qubes-os.org/doc/doc-guidelines/) - -[switch]: https://www.qubes-os.org/doc/templates/#switching -[reinstall]: https://www.qubes-os.org/doc/reinstall-template/ -[uninstall]: https://www.qubes-os.org/doc/templates/#uninstalling -[Minimal TemplateVMs]: https://www.qubes-os.org/doc/templates/minimal/ -[Xfce TemplateVMs]: https://www.qubes-os.org/doc/templates/xfce/ -[Gentoo Handbook]: https://wiki.gentoo.org/wiki/Handbook:AMD64 \ No newline at end of file +This content has moved to [Qubes Forum: Community Guides](https://forum.qubes-os.org/c/guides/14). [Learn more.](https://forum.qubes-os.org/t/announcement-qubes-community-project-has-been-migrated-to-the-forum/20367/) diff --git a/docs/os/linux-hvm-tips.md b/docs/os/linux-hvm-tips.md index e821f52..deee4c7 100644 --- a/docs/os/linux-hvm-tips.md +++ b/docs/os/linux-hvm-tips.md @@ -1,53 +1 @@ - -Tips for Linux in HVM domain -============================ - -How to fix bootup kernel error -------------------------------- - -If the HVM pauses on boot and shows a series of warnings, visit [HVM Troubleshooting](https://www.qubes-os.org/doc/hvm-troubleshooting/#hvm-pauses-on-boot-followed-by-kernel-error) for a fix. - -Screen resolution ------------------ - -Some kernel/Xorg combinations use only 640x480 in HVM, which is quite small. -To enable maximum resolution, some changes in the Xorg configuration are needed: -1. Force "vesa" video driver -2. Provide wide horizontal synchronization range - -To achieve it (all commands to be run as root): - -1. Generate XOrg configuration (if you don't have it): - ~~~ - X -configure :1 && mv ~/xorg.conf.new /etc/X11/xorg.conf - ~~~ - -1. Add HorizSync line to Monitor section, it should look something like: - ~~~ - Section "Monitor" - Identifier "Monitor0" - VendorName "Monitor Vendor" - ModelName "Monitor Model" - HorizSync 30.0 - 60.0 - EndSection - ~~~ - -1. Change driver to "vesa" in Device section: - ~~~ - Section "Device" - # (...) - Identifier "Card0" - Driver "vesa" - VendorName "Technical Corp." - BoardName "Unknown Board" - BusID "PCI:0:2:0" - EndSection - ~~~ - -Now you should get resolution of at least 1280x1024 and should be able to choose other modes. - -Qubes agents ------------- - -Linux Qubes agents are written primarily for PV qubes, but it is possible to run them also in a HVM qube. -However some work may be required to achieve this. Check [this thread](https://groups.google.com/group/qubes-devel/browse_thread/thread/081df4a43e49e7a5). +This content has moved to [Qubes Forum: Community Guides](https://forum.qubes-os.org/c/guides/14). [Learn more.](https://forum.qubes-os.org/t/announcement-qubes-community-project-has-been-migrated-to-the-forum/20367/) diff --git a/docs/os/netbsd.md b/docs/os/netbsd.md index e406c92..deee4c7 100644 --- a/docs/os/netbsd.md +++ b/docs/os/netbsd.md @@ -1,18 +1 @@ - -How to Create a NetBSD VM -========================= - -1. Create a StandaloneVM with the default template. -2. Replace `vmlinuz` with the `netbsd-INSTALL_XEN3_DOMU` kernel. -3. During setup, choose to install on the `xbd1` hard disk. -4. Attach the CD to the VM. -5. Configure the networking. -6. Optionally enable SSHD during the post-install configuration. -7. Replace the kernel with `netbsd-XEN3_DOMU`. -8. The VM may fail to boot automatically, in which case you must explicitly - specify `xbd1a` as the root device when prompted. - -For further discussion, please see this [thread] and this [guide]. - -[thread]: https://groups.google.com/group/qubes-devel/msg/4015c8900a813985 -[guide]: https://wiki.xen.org/wiki/How_to_install_a_NetBSD_PV_domU_on_a_Debian_Squeeze_host_%28Xen_4.0.1%29 +This content has moved to [Qubes Forum: Community Guides](https://forum.qubes-os.org/c/guides/14). [Learn more.](https://forum.qubes-os.org/t/announcement-qubes-community-project-has-been-migrated-to-the-forum/20367/) diff --git a/docs/os/pentesting.md b/docs/os/pentesting.md index 6fc9f2f..deee4c7 100644 --- a/docs/os/pentesting.md +++ b/docs/os/pentesting.md @@ -1,26 +1 @@ - -**Legal notice:** - -The usage of penetration testing tools outside your own laboratory environment requires the permission of the organization you attack. Penetration testing without permission can have legal consequences. - -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, colloquially known as a pen test, is an authorised simulated attack on a computer system that looks for security weaknesses, potentially gaining access to the system's features and data." (Source: [Wikipedia](https://en.wikipedia.org/wiki/Penetration_test)). - -Penetration Testing Distributions ---------------------------------- - -The following instructions explain how to install a penetration testing distribution within Qubes OS. - -- [BlackArch](https://www.qubes-os.org/doc/pentesting/blackarch/) -- [Kali](https://www.qubes-os.org/doc/pentesting/kali/) -- [PenTester Framework (PTF)](https://www.qubes-os.org/doc/pentesting/ptf/) -- [Parrot](https://www.parrotsec.org/docs/parrot-on-qubesos.html) - -Using Qubes OS to host a "hacking" laboratory ---------------------------------------------- - -Qubes OS is a hypervisor based operating system. Qubes OS can host various operating systems such as Linux, Unix or Windows and run them in parallel. Qubes OS can therefore be used to host your own "hacking" laboratory. +This content has moved to [Qubes Forum: Community Guides](https://forum.qubes-os.org/c/guides/14). [Learn more.](https://forum.qubes-os.org/t/announcement-qubes-community-project-has-been-migrated-to-the-forum/20367/) diff --git a/docs/os/pentesting/blackarch.md b/docs/os/pentesting/blackarch.md index 211b488..deee4c7 100644 --- a/docs/os/pentesting/blackarch.md +++ b/docs/os/pentesting/blackarch.md @@ -1,89 +1 @@ - -**General reminder:** - -- 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 providers. - -Please keep in mind that using such a VM or VMs based on the template for security and privacy critical tasks is not recommended. - -How to Create a BlackArch VM -============================ - -[BlackArch](https://www.blackarch.org) Linux is an [Arch Linux](https://www.archlinux.org)-based distribution for penetration testers and security researchers. The repository contains [1434](https://www.blackarch.org/tools.html) tools. - -- List of [tools](https://www.blackarch.org/tools.html) -- [Installation Instructions](https://www.blackarch.org/downloads.html) - -Create ArchLinux Based BlackArch Template ------------------------------------------ - -1. Create ArchlLinux Template - - - Follow the [Archlinux Template instructions](https://www.qubes-os.org/doc/building-archlinux-template/) - - -2. Update Template - - sudo pacman -Syyu - -3. Clone template - - 1. Via Qubes VM Manager - - 2. Via command line - - qvm-clone archlinux blackarch - -4. Install BlackArch repository - - $ curl -O https://blackarch.org/strap.sh - - # The SHA1 sum should match: 34b1a3698a4c971807fb1fe41463b9d25e1a4a09 - $ sha1sum strap.sh - - # Set execute bit - $ chmod +x strap.sh - - # Run strap.sh - $ sudo ./strap.sh - -5. 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 - -6. Create a AppVMs based on the `blackarch` template - - - (Optional) Attach necessary devices - -Alternative Options to BlackArch --------------------------------- - -- [Kali](https://www.qubes-os.org/doc/pentesting/kali/) -- [PenTester Framework (PTF)](https://www.qubes-os.org/doc/pentesting/ptf/) -- [Pentesting](https://www.qubes-os.org/doc/pentesting/) +This content has moved to [Qubes Forum: Community Guides](https://forum.qubes-os.org/c/guides/14). [Learn more.](https://forum.qubes-os.org/t/announcement-qubes-community-project-has-been-migrated-to-the-forum/20367/) diff --git a/docs/os/pentesting/kali.md b/docs/os/pentesting/kali.md index 63d9af3..deee4c7 100644 --- a/docs/os/pentesting/kali.md +++ b/docs/os/pentesting/kali.md @@ -1,206 +1 @@ - -How to create a Kali Linux VM -=============================== -Warnings --------------- -* 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 providers. -* Please keep in mind that using such a template for security and privacy critical tasks is not recommended. -* Kali Linux distribution is a rolling distribution based on Debian testing release, so it will always have a newer software base than available in the Qubes OS Debian template. Keep in mind that this may result in problems (especially in regard to package dependencies) not covered by this tutorial. - -From the official ISO file -================================================== -Only use this method if you want the full Kali GUI (desktop, fancy menus, etc.). -It comes at the cost of much greater resources consumption. - -1. Download the Kali ISO -2. [Create a new HVM][qubes-new-hvm] -3. Start the HVM with attached CD/DVD -```shell_session -$ qvm-start --cdrom :/home/user/Downloads/.iso -``` - -From a Debian template -================================================================ -This is the recommended method. -Easier to maintain and less demanding on resources, but you won’t have the full Kali GUI. - -If you need to install custom kernel modules (wifi drivers, …) you need to use the kernel provided by Kali instead of the kernel provided by Qubes, see [Managing VM Kernel.](https://www.qubes-os.org/doc/managing-vm-kernel/) - -The steps can be summarized as: - -1. Install Qubes stable Debian template -2. Upgrade from Debian `stable` to Debian `testing` for Qubes repositories -3. Add `testing` and `securitytesting` Qubes repositories -4. Replace the content of `/etc/apt/sources.list` file with the Kali repository -5. Update the template - -Get Kali Linux PGP key ------------------------ -**CAUTION:** Before proceeding, please carefully read [On Digital Signatures and Key Verification][qubes-verifying-signatures]. -This website cannot guarantee that any PGP key you download from the Internet is authentic. -In order to obtain a trusted fingerprint, check its value against multiple sources. -Then, check the keys you download against your trusted fingerprint. - -This step is required since by (security) default TemplateVM do not have a -direct Internet connectivity. Users understanding the risks of enabling such -access can change this configuration in firewall settings for the TemplateVM. - -1. Retrieve the Kali Linux PGP key using a DisposableVM. - -```shell_session -$ gpg --keyserver hkps://keys.openpgp.org --recv-key 44C6513A8E4FB3D30875F758ED444FF07D8D0BF6 -$ gpg --list-keys --with-fingerprint 44C6513A8E4FB3D30875F758ED444FF07D8D0BF6 -$ gpg --export --armor 44C6513A8E4FB3D30875F758ED444FF07D8D0BF6 > kali-key.asc -``` - -2. **DO NOT TURN OFF** the DisposableVM, the `kali-key.asc` file will be copied in - the Kali Linux template for a further step. - -3. Make sure the key is the authentic Kali key. - See the [Kali website] for further advice and instructions on verification. - -Create a Kali Linux (rolling) template ----------------------------------------- -These instructions will show you how to upgrade a Debian TemplateVM to Kali Linux. - -1. (Optional) Check for latest Debian stable template and install it (if not already done) - -```shell_session -# qubes-dom0-update --action="search all" qubes-template-debian -# qubes-dom0-update -``` - -2. Clone `debian-X` template - -```shell_session -$ qvm-clone debian- kali-rolling -``` - -3. Check the name of currently used repository in `/etc/apt/sources.list.d/qubes-r.list` and current testing [Debian release][Debian-releases]. Update repository list accordingly - -```shell_session -# sed -i 's///g' /etc/apt/sources.list.d/qubes-r.list -``` - -e.g. in this example we update `bullseye` stable repository to `bookworm` testing repository - -```shell_session -# sed -i 's/bullseye/bookworm/g' /etc/apt/sources.list.d/qubes-r.list -``` - -4. Enable the QubesOS `testing` and `securitytesting` repositories - -In `/etc/apt/sources.list.d/qubes-r.list`, enable the `testing` and `securitytesting` repository. -We do that to reduce the 'dependency hell' between Qubes repository and Kali repository. - -5. Copy the Kali PGP key from the DisposableVM to the new template: - -```shell_session -$ qvm-copy kali-key.asc -``` - - The DisposableVM can now be turned off. - -6. Add the Kali PGP key to the list of keys trusted to authenticate packages: - -```shell_session -# cd /home/user/QubesIncoming/dispXXX && gpg --dearmor kali-key.asc -# cp kali-key.asc.gpg /etc/apt/trusted.gpg.d/kali-key.gpg -``` - - - -7. Replace Debian repositories with Kali repository - -```shell_session -# echo 'deb https://http.kali.org/kali kali-rolling main non-free contrib' > /etc/apt/sources.list -``` - -8. Replace conflicted packages to work around dependency issues -```shell_session -# apt-get remove && apt-get install -``` -e.g. in this example we replace `gcc8` with `gcc6` -```shell_session -# apt-get remove libgcc-8-dev && apt-get install libc6-dev -``` - -**Note:** This kind of dependency issue will pop up and disappear without notice. -Such issues arise because of the differences of dependencies in packages from -the Kali repository, the Qubes testing repository and the Debian testing -repository. -So this step [step 8] is currently needed. But it will not always be the case. - -9. Update the template - -**Note:** During execution of the update, carefully read list of packages to be removed. If it contains `qubes-vm-dependencies` package, terminate operation and try to resolve missing dependencies first. For other `qubes-*` packages, it is up to you to decide if you need them. - -10. Ensure a terminal can be opened in the new template. - -```shell_session -$ qvm-run -a kali-rolling gnome-terminal -``` - -Install the Kali tools ------------------------------- -At this point you should have a working template and you can install the tools you need. -You can find [a list of Kali Linux `Metapackages` here](https://www.kali.org/tools/kali-meta/) -Keep in mind that the tools you will install can easily take more than 10 GB, [so you will need to **grow** the size of the VM system storage.][qubes-resize-disk-image] - -Fix Qubes PulseAudio (audio and microphone) ---------------------------------------------- -Installing the `kali-defaults` package (which is included in many Kali metapackages including `kali-linux-core`) causes Kali PulseAudio configurations files to be installed that interfere with what Qubes provides. This breaks audio and microphone throughput for that qube. - -To fix this, simply do one of the following in the Kali Linux TemplateVM: - -### Remove just the conflicting PulseAudio configuration files - -1. Remove the configuration files by running the following command: - -```shell_session -# rm /usr/lib/systemd/user/pulseaudio.service.d/kali_pulseaudio.conf /usr/lib/systemd/user/pulseaudio.socket.d/kali_pulseaudio.socket.conf -``` - -### Uninstall the entire `kali-defaults` package - -1. Assess the function and contents of the package to see if you need it: - - See description: `apt show kali-defaults` - - See installed files: `dpkg -L kali-defaults` -2. If you determine that the package is unnecessary, then uninstall it - - `sudo apt remove kali-defaults` - -Finally, for both of these options, the Kali Linux qube will have to be restarted for these changes to take effect. - -Alternative Options to Kali Linux -=================================== -* [PenTester Framework][PTF], with [PTF Qubes OS guide][qubes-ptf] -* BlackArch Linux, with [BA Qubes OS guide][qubes-blackarch] -* more on the [Penetration Testing page][qubes-pentesting] - - -Notes -============= -Thanks to the people in [the discussion thread](https://github.com/QubesOS/qubes-issues/issues/1981). - -[qubes-verifying-signatures]: https://www.qubes-os.org/security/verifying-signatures/ -[qubes-pentesting]: https://www.qubes-os.org/doc/pentesting/ -[qubes-blackarch]: https://www.qubes-os.org/doc/pentesting/blackarch/ -[qubes-ptf]: https://www.qubes-os.org/doc/pentesting/ptf/ -[qubes-template-debian-install]: https://www.qubes-os.org/doc/templates/debian/#install -[qubes-resize-disk-image]: https://www.qubes-os.org/doc/resize-disk-image/ -[qubes-new-hvm]: https://www.qubes-os.org/doc/standalone-and-hvm/ - -[kali]: https://www.kali.org/ -[kali-vbox]: https://www.offensive-security.com/kali-linux-vmware-virtualbox-image-download/ -[kali website]: https://docs.kali.org/introduction/download-official-kali-linux-images - -[PTF]: https://www.trustedsec.com/may-2015/new-tool-the-pentesters-framework-ptf-released/ - -[katoolin]: https://github.com/LionSec/katoolin -[katoolin-howto]: http://www.tecmint.com/install-kali-linux-tools-using-katoolin-on-ubuntu-debian/ - -[Debian-releases]: https://www.debian.org/releases/ - -[Debian-security-naming-convention]: https://www.mail-archive.com/debian-security@lists.debian.org/msg41223.html - +This content has moved to [Qubes Forum: Community Guides](https://forum.qubes-os.org/c/guides/14). [Learn more.](https://forum.qubes-os.org/t/announcement-qubes-community-project-has-been-migrated-to-the-forum/20367/) diff --git a/docs/os/pentesting/ptf.md b/docs/os/pentesting/ptf.md index 8febee3..deee4c7 100644 --- a/docs/os/pentesting/ptf.md +++ b/docs/os/pentesting/ptf.md @@ -1,114 +1 @@ - -**General reminder:** - -- 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 providers. - -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 -==================================================== - -"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)) - -**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 example requires a newer Ruby version than Debian 8 has in the repositories. Therefore 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. - -Create Debian Based Penetration Testers Framework (PTF) Template ----------------------------------------------------------------- - -1. Create PTF template - - 1. Follow [Create Debian Based Kali Template](https://www.qubes-os.org/doc/pentesting/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 - -3. 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. - -4. Install/Update modules (tools) - - 1. Start PTF - - sudo ptf - - ![PTF start banner](/attachment/wiki/PTF/ptf-banner.png) - - 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 - -5. Create an AppVM based on the `ptf` template - - - (Optional) Attach necessary devices - - -Alternative Options to PTF --------------------------- - -- [BlackArch](https://www.qubes-os.org/doc/pentesting/blackarch/) -- [Kali](https://www.qubes-os.org/doc/pentesting/kali/) -- [Pentesting](https://www.qubes-os.org/doc/pentesting/) +This content has moved to [Qubes Forum: Community Guides](https://forum.qubes-os.org/c/guides/14). [Learn more.](https://forum.qubes-os.org/t/announcement-qubes-community-project-has-been-migrated-to-the-forum/20367/) diff --git a/docs/os/ubuntu.md b/docs/os/ubuntu.md index d091cfd..deee4c7 100644 --- a/docs/os/ubuntu.md +++ b/docs/os/ubuntu.md @@ -1,52 +1 @@ - -Ubuntu template(s) -================== - -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 provided by Qubes in ready to use binary packages, because Canonical does not allow redistribution of a modified Ubuntu. -The redistribution is not allowed by their [Intellectual property rights policy][IP]. - -Building the Template -------- - -Templates can be built using [Qubes Builder][builder] -(You can also access documentation in the [source code repository][repo].) - -Please carefully read the [instructions][builder] for setting up and using Qubes Builder. -To quickly prepare the builder configuration, you can use the `setup` script available in the repository - it will interactively ask you which templates you want to build. -Select one of the Ubuntu version options. -On the "Choose Pre-Built Packages Repositories" page you must not select either option. -This is because Qubes does not provide offical Pre-Built packages for Ubuntu. - -Once you have completed setup, in the qubes-builder directory, run: -``` -make qubes-vm -make template -``` - -The build for Ubuntu 16.04 LTS (Xenial) is straightforward. - -The build for Ubuntu 18.04 LTS (Bionic) is straightforward. - - - -Installing the template -------- - -You must copy the template you have built in to dom0 and install it there. -Rather than do this manually, there is a script you can use. - -In dom0, run : -``` -qvm-run -p 'cat /home/user/qubes-builder/qubes-src/linux-template-builder/rpm/install-templates.sh ' > install-templates.sh -``` -If you have built other templates, edit the `install-templates.sh` to ensure you only retain the templates you want to install. -Then run `./install-templates.sh` - ----------- -If you want to help in improving the template, feel free to [contribute][contrib]. - -[IP]: https://www.ubuntu.com/legal/terms-and-policies/intellectual-property-policy -[repo]: https://github.com/QubesOS/qubes-builder/blob/master/README.md -[builder]: https://www.qubes-os.org/doc/qubes-builder/ -[contrib]: https://www.qubes-os.org/doc/contributing/ +This content has moved to [Qubes Forum: Community Guides](https://forum.qubes-os.org/c/guides/14). [Learn more.](https://forum.qubes-os.org/t/announcement-qubes-community-project-has-been-migrated-to-the-forum/20367/) diff --git a/docs/os/windows/windows-migrate41.md b/docs/os/windows/windows-migrate41.md index 932ba71..deee4c7 100644 --- a/docs/os/windows/windows-migrate41.md +++ b/docs/os/windows/windows-migrate41.md @@ -1,48 +1 @@ -Migrating Windows VMs from Qubes R4.0 to R4.1 -============================================= - -For Windows 7, 10 and 11, there is a way to migrate backups created under Qubes R4.0 to R4.1. For this, the version of Qubes Windows Tools (QWT) 4.1-67, available from [tabit-pro/qubes-windows-tools-cross](https://github.com/tabit-pro/qubes-windows-tools-cross/releases), has to be installed under Qubes R4.0, selecting the option to install the Xen PV disk driver, which emulates SCSI disks. For template VMs, the option to move user profiles may be selected, too. Then, the backup may be created, and this backup can be restored under Qubes R4.1, resulting in a VM well integrated into Qubes R4.1. If `qvm-features audio-model ich6` is set, Windows even will have audio, although for Windows 10 and 11 somewhat scratchy. - -While this is somewhat straightforward, things get difficult if QWT 4.0.1.3 was installed in the VM. Prior to installing version 4.1-67, the old version has to be removed, which can be quite tricky for Windows 10 and 11. - -Preparation for Windows 7 -------------------------- - - - Uninstall QWT 4.0.1.3, using the standard procedure from the system control panel of Windows. This will most likely result in a crash. - - Restart Windows again, hitting the F8 key, select the restart menu, and there select a start in safe mode. - - The system will start gain, but in a rather useless way. Just shut it down, and reboot again. - - Now Windows will start normally. Check in the control panel, if there are any Xen drivers left. If so, uninstall them. - - In the Windows device manager, check if there is still a (probably non working) Xen PV disk device. If so, uninstall it. Otherwise, QWT 4.1-67 will not install. - - In the control panel, check again, if the Xen drivers are removed. A Xen Bus Package (version 8.2.1.8) may remain and cannot be removed, but does no harm. Any other Xen drivers should have disappeared. - - There probably will be a drive `D:` containing the private user data. For Qubes, R4.1, QWT will expect this drive to be called `Q:`, so it has to be renamed: - - Start the command prompt as administrator, i.e. right click on the Command Prompt icon (All Programs -> Accessories) and choose "Run as administrator" - - In the command prompt type `diskmgmt.msc` - - In the disk manager, select the volume `Private (D:)` - - Select the option `Change Drive Letter and Path` - - Select option `Change...` - - Select the letter `Q` - - Click `OK` in all still open windows of the disk manager and terminate it. - -Preparation for Windows 10 and 11 ---------------------------------- -If there is a drive `D:` from this earlier installation of Qubes Windows Tools, it will probably contain incomplete private data; especially the folder `AppData` containing program configuration data will be missing. In this situation, it may be better to perform a new Windows installation, because repair may be difficult and trouble-prone. -- First, be sure that the automatic repair function is disabled. In a command window, execute `bcdedit /set recoveryenabled NO`, and check that this worked by issuing the command `bcdedit`, without parameters, again. -- Now, uninstall QWT 4.0.1.3, using the Apps and Features function of Windows. This will most likely result in a crash. -- Restart Windows again, possibly two or three times, until repair options are offered. By hitting the F8 key, select the restart menu, and there select a start in safe mode (in German, it's option number 4). -- The system will start gain, but in a rather useless way. Just shut it down, and reboot again. -- Now Windows will start normally. Check in the Apps and Features display, if there are any Xen drivers left. If so, uninstall them. -- In the Windows device manager, check if there is still a (probably non working) Xen PV disk device. If so, uninstall it. Otherwise, QWT 4.1-67 will not install. -- In the Apps and Features display, check again, if the Xen drivers are removed. A Xen Bus Package (version 8.2.1.8) may remain and cannot be removed, but does no harm. Any other Xen drivers should have disappeared. - -Transferring the Windows Qube ------------------------------ - -- Now, finally, after one additional reboot, Qubes Windows Tools 4.1-67 can be installed. The option `Move user profiles` should be used **if and only if** there was **no** separate drive `D:` in the earlier Windows installation. -- After one more reboot, the backup for R4.1 may be created. -- This backup can be installed in Qubes R4.1 and will (probably) work. - -The PV disk drivers used for migration can be removed after successful installation of the VM under Qubes R4.1. For this, the QWT installation has to be started, the option Change has to be selected, and the PV disk driver must be unselected. After completion, the VM has to be rebooted. For Windows 10 and 11, the VM will crash with the error INACCESSIBLE BOOT DEVICE, which can be repaired as described above. - -After successful uninstallation of the PV disk drivers, the disks will appear as QEMU ATA disks. - -:warning: **Caution:** This change may lead Windows to declare that the hardware has changed and that in consequence, the activation is no longer valid, possibly complaining that the use of the software is no longer lawful. It should be possible to reactivate the software if a valid product key is provided. +This content has moved to [Qubes Forum: Community Guides](https://forum.qubes-os.org/c/guides/14). [Learn more.](https://forum.qubes-os.org/t/announcement-qubes-community-project-has-been-migrated-to-the-forum/20367/) diff --git a/docs/os/windows/windows-tools.md b/docs/os/windows/windows-tools.md index 4e2eddf..deee4c7 100644 --- a/docs/os/windows/windows-tools.md +++ b/docs/os/windows/windows-tools.md @@ -1,335 +1 @@ -:warning: *The content below describes Qubes Windows Tools installation in Qubes R4.0. The text has been updated to reflect the newer R4.1 release and QWT recent development. Please see [this updated document](https://github.com/Qubes-Community/Contents/blob/master/docs/os/windows/windows-tools41.md) for instructions for Qubes R4.1 and the updated version of Qubes Windows Tools.* - -Qubes Windows Tools -=================== - -Qubes Windows Tools are a set of programs and drivers that provide integration of Windows AppVMs with the rest of the Qubes system. Currently the following features are available for Windows VMs after installation of those tools: - -- **Qubes Video Driver** - provides for the Seamless GUI mode that integrates apps windows onto the common Qubes trusted desktop -- **File sender/receiver** - Support for [secure clipboard copy/paste](https://www.qubes-os.org/doc/copy-paste/) between the Windows VM and other AppVMs -- **File sender/receiver** - Support for [secure file exchange](https://www.qubes-os.org/doc/copying-files/) between the Windows VM and other AppVMs -- **Copy/Edit in Disposable VM** - Support for editing files in DisposableVMs as well as for qvm-run and generic qrexec for the Windows VM (e.g. ability to run custom service within/from the Windows VM) -- **Xen PV drivers** for Windows that increase performance compared to qemu emulated devices - -Below is a breakdown of the feature availability depending on the windows version: - -| Feature | Windows 7 x64 | Windows 10 x64 | -| ------------------------------------ | :------------: | :------------: | -| Qubes Video Driver | + | - | -| Qubes Network Setup | + | + | -| Private Volume Setup (move profiles) | + | + | -| File sender/receiver | + | + | -| Clipboard Copy/Paste | + | + | -| Application shortcuts | + | + | -| Copy/Edit in Disposable VM | + | + | -| Block device | + | + | -| USB device | + | + | -| Audio | - | - | - -Qubes Windows Tools are open source and are distributed under a GPL license. - -NOTES: -- Qubes Windows Tools are currently unmaintained -- Currently only 64-bit versions of Windows 7 and Windows 10 are supported by Qubes Windows Tools. Only emulated SVGA GPU is supported (although [there has been reports](https://groups.google.com/forum/#!topic/qubes-users/cmPRMOkxkdA) on working GPU passthrough). -- __This page documents the process of installing Qubes Windows Tools on versions up to R3.2.__. Installation on Qubes R4.0 is possible but is a work in progress and there are limitations/bugs (see [issue #3585](https://github.com/QubesOS/qubes-issues/issues/3585)). - -Installing Windows OS in a Qubes VM ------------------------------------ - -Please refer to [this page](https://www.qubes-os.org/doc/windows-vm/) for instructions on how to install Windows in a Qubes VM. - -NOTE: It is strongly suggested to enable autologon for any Windows HVMs that will have Qubes Tools installed. To do so, run `netplwiz` command from the `Win+R`/Start menu and uncheck the *Users must enter a user name and password to use this computer* option. - -Installing Qubes guest tools in Windows 10 VMs ----------------------------------------------- - -This will allow you to install the Qubes Windows Tools on Windows 10 both as a StandaloneVM as well as a Template VM and a corresponding AppVM. But some features are not available: - -> **Note:** seamless mode is currently not available for windows. Please check the top of this document for the full feature availability breakdown. - - 1. In the Windows 10 VM, download from the [XEN website](https://xenproject.org/downloads/windows-pv-drivers/windows-pv-drivers-9-series/windows-pv-drivers-9-0-0/) the installation kits for Xen bus (`xenbus`) and storage drivers (`xenvbd`) Version 9.0.0 (two files`xenvbd.tar`and `xenbus.tar`). - - 2. Use an archive extractor like [7-zip](https://www.7-zip.org/) to extract the contents of the `.tar` files. - - 3. Install `xenvbd` and `xenbus` by starting the file `dpinst.exe` from the `x64` directories of the extracted tar-files. If during installation, the Xen driver requests a reboot, select "No" and let the installation continue. - - 4. After installation, reboot. - - 5. Download the Qubes Windows Tools (`qubes-tools-4.0.1.3.exe`) from [the qubes FTP server](https://ftp.qubes-os.org/qubes-windows-tools/) and move it to `C:\`. - - 6. Check the integrity of the file `qubes-tools-4.0.1.3.exe`by comparing its hash checksum. This can be done using the Windows command `certutil` on the windows command prompt (`cmd.exe`) and specifying an appropriate hash algorithm like: - - certutil -hashfile C:\qubes-tools-4.0.1.3.exe SHA256 - - And compare it the value to `148A2A993F0C746B48FA6C5C9A5D1B504E09A7CFBA3FB931A4DCF86FDA4EC9B1` (**it has to exactly match for security reasons**). If it matches, feel free to continue the installation. If not, repeat the download to make sure it was not corrupted due to a network problem. If keeps on not matching it might be an attacker attempting to do something nasty to your system -- Ask for support. - - > **Note**: this is a workaround for installing the qubes windows tools on windows 10 since the standard way is broken. - - 7. Install Qubes Windows Tools 4.0.1.3 by starting `qubes-tools-4.0.1.3.exe`, not selecting the `Xen PV disk drivers` and the `Move user profiles` (which would probably lead to problems in Windows, anyhow). If during installation, the Xen driver requests a reboot, select "No" and let the installation continue - the system will be rebooted later. - - 8. Shut down Windows and wait until the VM is really stopped, i.e. Qubes shows no more activity. - - 9. On a `dom0` terminal write: *(where `` is the name of your Windows 10 VM)* - - qvm-features gui 1 - qvm-prefs qrexec_timeout 300 - - 10. Reboot Windows. If the VM starts, but does not show any window then shutdown Windows from the Qube manager, wait until it has really stopped, and reboot Windows once more. - - 11. Now the system should be up, with QWT running correctly. - - 12. Lastly to enable file copy operations to a Windows 10 VM the `default_user` property should be set the `` that you use to login to the Windows VM. This can be done via the following command on a `dom0` terminal: *(where `` is the name of your Windows 10 VM)* - - `qvm-prefs default_user ` - - > **Note:** If this property is not set or set to a wrong value, files copied to this VM are stored in the folder `C:\Windows\System32\config\systemprofile\Documents\QubesIncoming\`. - > If the target VM is an AppVM, this has the consequence that the files are stored in the corresponding TemplateVM and so are lost on AppVM shutdown. - - -Installing Qubes guest tools in Windows 7 VMs ---------------------------------------------- - -First, make sure that `qubes-windows-tools` is installed in your system: - -~~~ -sudo qubes-dom0-update qubes-windows-tools -~~~ - -(If the above command does not work, it could be that the Qubes Tools are not in the stable repo yet. Try installing from the testing repo instead.) - -You can also install the package from testing repositories, where we usually publish new versions first: - -~~~ -sudo qubes-dom0-update --enablerepo=qubes-dom0-current-testing qubes-windows-tools -~~~ - -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. To do that: - -- Start command prompt as Administrator, i.e. right click on the Command Prompt icon (All Programs -> Accessories) 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`: - -~~~ -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. - -Qubes 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: - -~~~ -qvm-prefs -~~~ - -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 qrexec_timeout 300 -~~~ - -Xen PV drivers and Qubes Windows Tools --------------------------------------- - -Installing Xen's PV drivers in the VM will lower its resources usage when using network and/or I/O intensive applications, but *may* come at the price of system stability (although Xen's PV drivers on a Win7 VM are usually very stable). There are two ways of installing the drivers: - -1. installing the drivers independently, from Xen's [official site](https://www.xenproject.org/developers/teams/windows-pv-drivers.html) -2. installing Qubes Windows Tools (QWT), which bundles Xen's PV drivers. - -Notes about using Xen's VBD (storage) PV driver: -- **Windows 7:** installing the driver requires a fully updated VM or else you'll likely get a BSOD and a VM in a difficult to fix state. Updating Windows takes *hours* and for casual usage there isn't much of a performance between the disk PV driver and the default one; so there is likely no need to go through the lengthy Windows Update process if your VM doesn't have access to untrusted networks and if you don't use I/O intensive apps. If you plan to update your newly installed Windows VM it is recommended that you do so *before* installing Qubes Windows Tools (QWT). If QWT are installed, you should temporarily re-enable the standard VGA adapter in Windows and disable Qubes' (see the section above). -- the option to install the storage PV driver is disabled by default in Qubes Windows Tools -- in case you already had QWT installed without the storage PV driver and you then updated the VM, you may then install the driver from Xen's site (xenvbd.tar). - -**Caution:** Installing the version 9.0.0 Xen drivers on Windows 7 (a system without QWT - QWT uninstalled) leads to an unbootable system. The drivers install without error, but after reboot, the system aborts the reboot saying `Missing driver xenbus.sys`. - -- **Windows 10:** The version 9.0.0 Xen drivers have to be installed before installing Qubes Windows Tools. Installing them on a system with QWT installed is likely to produce a system which crashes or has the tools in a non-functional state. Even if the tools were installed and then removed before installing the Xen drivers, they probably will not work as expected. - - -With Qubes Windows Tools installed the early graphical console provided in debugging mode isn't needed anymore since Qubes' display driver will be used instead of the default VGA driver: - -~~~ -qvm-prefs -s win7new debug false -~~~ - - -Using Windows AppVMs in seamless mode -------------------------------------- - -> **Note:** This feature is only available for Windows 7 - -Once you start a Windows-based AppVM with Qubes Tools installed, you can easily start individual applications from the VM (note the `-a` switch used here, which will auto-start the VM if it is not running): - -~~~ -qvm-run -a my-win7-appvm explorer.exe -~~~ - -![windows-seamless-4.png](/attachment/wiki/WindowsAppVms/windows-seamless-4.png) ![windows-seamless-1.png](/attachment/wiki/WindowsAppVms/windows-seamless-1.png) - -Also, the inter-VM services work as usual -- e.g. to request opening a document or URL in the Windows AppVM from another VM: - -~~~ -[user@work ~]$ qvm-open-in-vm work-win7 roadmap.pptx -~~~ - -~~~ -[user@work ~]$ qvm-open-in-vm work-win7 https://invisiblethingslab.com -~~~ - -... just like in the case of Linux AppVMs. Of course all those operations are governed by central policy engine running in Dom0 -- if the policy doesn't contain explicit rules for the source and/or target AppVM, the user will be asked whether to allow or deny the operation. - -Inter-VM file copy and clipboard works for Windows AppVMs the same way as for Linux AppVM (except that we don't provide a command line wrapper, `qvm-copy-to-vm` in Windows VMs) -- to copy files from Windows AppVMs just right-click on the file in Explorer, and choose: Send To-\> Other AppVM. - -To simulate CTRL-ALT-DELETE in the HVM (SAS, Secure Attention Sequence), press Ctrl-Alt-Home while having any window of this VM in the foreground. - -![windows-seamless-7.png](/attachment/wiki/WindowsAppVms/windows-seamless-7.png) - -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. The latter is the default. - -Using template-based Windows AppVMs ------------------------------------ - -Qubes allows HVM VMs to share a common root filesystem from a select Template VM, just as for Linux AppVMs. This mode is not limited to Windows AppVMs, and can be used for any HVM (e.g. FreeBSD running in a HVM). - -In order to create a HVM TemplateVM one can use the following command, suitably adapted: - -~~~ -qvm-create --class TemplateVM win-template --property virt_mode=HVM --property kernel='' -l green -~~~ - -... , set memory as appropriate, and install Windows OS (or other OS) into this template the same way as you would install it into a normal HVM -- please see instructions on [this page](https://www.qubes-os.org/doc/hvm-create/). - -If you use this Template as it is, then any HVMs that use it will effectively be DisposableVMs - the User directory will be wiped when the HVN is closed down. - -If you want to retain the User directory between reboots, then it would make sense to store the `C:\Users` directory on the 2nd disk which is automatically exposed by Qubes to all HVMs. -This 2nd disk is backed by the `private.img` file in the AppVMs' and is not reset upon AppVMs reboot, so the user's directories and profiles would survive the AppVMs reboot, unlike the "root" filesystem which will be reverted to the "golden image" from the Template VM automatically. -To facilitate such separation of user profiles, Qubes Windows Tools provide an option to automatically move `C:\Users` directory to the 2nd disk backed by `private.img`. -It's a selectable feature of the installer, enabled by default, but working only for Windows 7. -If that feature is selected during installation, completion of the process requires two reboots: - -- 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. - -For Windows 10, the user directories have to be moved manually, because the automatic transfer during QWT installation is bound to crash due to undocumented new features of NTFS, and a system having the directory `users`on another disk than `C:` will break on Windows update. So the following steps should be taken: - -- The Windows disk manager may be used to add the private volume as disk `D:`, and you may, using the documented Windows operations, move the user directories `C:\users\\Documents` to this new disk, allowing depending AppVMs to have their own private volumes. Moving the hidden application directories `AppData`, however, is likely to invite trouble - the same trouble that occurs if, during QWT installation, the option `Move user profiles` is selected. - -- Configuration data like those stored in directories like `AppData` still remain in the TemplateVM, such that their changes are lost each time the AppVM shuts down. In order to make permanent changes to these configuration data, they have to be changed in the TemplateVM, meaning that applications have to be started there, which violates and perhaps even endangers the security of the TemplateVM. Such changes should be done only if absolutely necessary and with great care. It is a good idea to test them first in a cloned TemplateVM before applying them in the production VM. - -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 settings 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 it: - -~~~ -qvm-create --property virt_mode=hvm --template --label