diff --git a/external/building-guides/building-archlinux-template.md b/external/building-guides/building-archlinux-template.md index c3766df4..854da0f7 100644 --- a/external/building-guides/building-archlinux-template.md +++ b/external/building-guides/building-archlinux-template.md @@ -9,454 +9,3 @@ redirect_from: - /wiki/BuildingArchlinuxTemplate/ --- -Archlinux template building instructions -=========================================== - -**These are the instructions for Qubes 4.0. They will take you step by step through the entire process start to finish** - -1: Create and configure a qube for template building ------------------------------------------------------------- -* The qube should be based on a Fedora template. I named the qube - `build-archlinux2`, based on the minimal Fedora template. - -![arch-template-01](/attachment/wiki/ArchlinuxTemplate/arch-template-01.png) - -* Ensure there is at least 15GB of free space in the private storage. - -![arch-template-02](/attachment/wiki/ArchlinuxTemplate/arch-template-02.png) - - -2: Create GitHub Account (optional) -------------------------------------------- -* It can be helpful. Creating only a basic account is all that is needed. This will allow you to help, going forward, with the Qubes project. You could be help edit errors in documentation. It can also be of use building other templates. -* Create user account here https://github.com - -![arch-template-03](/attachment/wiki/ArchlinuxTemplate/arch-template-03.png) - -3: Install necessary packages to `build-archlinux2` qube for "Qubes Automated Build System" ------------------------------------------------------------------------------------------------ -```shell_session -# dnf install git make -``` - -4: Downloading and verifying the integrity of the "Qubes Automated Build System" ---------------------------------------------------------------------------------- -* Import the Qubes master key -```shell_session -$ gpg --import /usr/share/qubes/qubes-master-key.asc -``` -* Verify its fingerprint, set as 'trusted'. [This is described here](/doc/VerifyingSignatures). -* Download the Qubes developers' keys. -```shell_session -$ wget https://keys.qubes-os.org/keys/qubes-developers-keys.asc -$ gpg --import qubes-developers-keys.asc -``` - -* Download the latest stable qubes-builder repository: -```shell_session -$ git clone https://github.com/QubesOS/qubes-builder.git /home/user/qubes-builder/ -``` -* Verify the integrity of the downloaded repository. The last line should read `gpg: Good signature from`... -```shell_session -$ cd /home/user/qubes-builder/ -$ git tag -v $(git describe) -``` -* Install the remaining dependencies -```shell_session -$ make install-deps -``` - -5: Run the 'setup' script to build the builder.conf file -------------------------------------------------------------- - -( The manual way would be to copy an example config like '**/home/user/qubes-builder/example-configs/qubes-os-r4.0.conf**' to '**/home/user/qubes-builder/builder.conf**' and edit the file ) -* Run the 'setup' script located in '**/home/user/qubes-builder/**' Make sure you are in directory '**qubes-builder**' -```shell_session -$ cd /home/user/qubes-builder/ -$ ./setup -``` -![arch-template-04](/attachment/wiki/ArchlinuxTemplate/arch-template-04.png) - -* Install the missing dependencies - -![arch-template-05](/attachment/wiki/ArchlinuxTemplate/arch-template-05.png) - -* First screen will ask you to import 'Qubes-Master-Signing-key.asc'. The 'setup' script not only downloads but confirms the key to that of the key on Qubes-OS website. - * Select '**YES**' - * Select '**OK**' Press '**Enter**' - -![arch-template-06](/attachment/wiki/ArchlinuxTemplate/arch-template-06.png) - -* Next screen will ask you to import Marek Marczykowski-Goracki (Qubes OS signing key). Again 'setup' will confirm this key to the fingerprint. - * Select '**YES**' - * Select '**OK**' Press '**Enter**' - -![arch-template-07](/attachment/wiki/ArchlinuxTemplate/arch-template-07.png) - -* This screen will give you the choice of which Qubes Release to build the template for. - * Select '**Qubes Release 4.0**' - * Select '**OK**' Press '**Enter**' - -![arch-template-08](/attachment/wiki/ArchlinuxTemplate/arch-template-08.png) - -* Screen "**Choose Repos To Use To Build Packages**" - * Select 'QubesOS/qubes- Stable - Default Repo' - * Select '**OK**' Press '**Enter**' - - -![arch-template-09](/attachment/wiki/ArchlinuxTemplate/arch-template-09.png) - -* Screen "**Git Clone Faster**" - * Select '**OK**' Press '**Enter**' - -![arch-template-10](/attachment/wiki/ArchlinuxTemplate/arch-template-10.png) - -* Screen '**Choose Pre-Build Packages Repositories**' - * Select nothing, Press '**Enter**' - -![arch-template-11](/attachment/wiki/ArchlinuxTemplate/arch-template-11.png) - -* Screen "**Build Template Only?**" - * Select '**Yes**' Press '**Enter**' - -![arch-template-12](/attachment/wiki/ArchlinuxTemplate/arch-template-12.png) - -* Screen '**Template Distribution Selection**' will give choices of distributions to build - * Deselect everything - * Select '**archlinux**' - -![arch-template-13](/attachment/wiki/ArchlinuxTemplate/arch-template-13.png) - -* Screen '**Builder Plugin Selection**' will give choices of builder plugins to use for the build. - * Deselect everything - * Select '**builder-archlinux**' - * Select '**OK**' Press **Enter** - -![arch-template-14](/attachment/wiki/ArchlinuxTemplate/arch-template-14.png) - -* Screen '**Get sources**' wants to download additional packages needed for the choosen plugin/s. - * Select '**Yes**' Press '**Enter**' - -![arch-template-15](/attachment/wiki/ArchlinuxTemplate/arch-template-15.png) - -* Then wait for download to finish and press '**OK**' - -6: Get all the require sources for the build ------------------------------------------------ -```shell_session -$ make get-sources -``` - -7: Make all the require Qubes Components ------------------------------------------------- -* **Note:** You can run a single command to build all the Qubes components or you can run them each individually. - Both ways below: -* Single command to build all Qubes components together: (this command can take a long time to process depending of your pc proccessing power) -```shell_session -$ make qubes-vm -``` -* These are the indivual component 'make' commands: -```shell_session -$ make vmm-xen-vm -$ make core-vchan-xen-vm -$ make core-qubesdb-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 vmm-xen-vm -$ make core-vchan-xen-vm -$ make core-qubesdb-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 -``` - -8: Make the actual Archlinux template ----------------------------------------- -```shell_session -$ make template -``` - -9: Transfer Template into Dom0 ----------------------------------- -* You need to ensure these two files are in the '**noarch**' directory -```shell_session -$ cd /home/user/qubes-builder/qubes-src/linux-template-builder/rpm/ -$ ls -install-templates.sh -$ cd noarch -$ ls -qubes-template-archlinux-X.X.X-XXXXXXXXXXXX.noarch.rpm -``` - -![arch-template-16](/attachment/wiki/ArchlinuxTemplate/arch-template-16.png) - -* **Transfer the install-templates.sh script file into Dom0** - *Note: as there is not a typical file transfer method for Dom0, for security reasons, this less than simple transfer function has to be used* - * Switch to Dom0 and open a terminal window. -```shell_session -$ qvm-run --pass-io build-archlinux2 'cat /home/user/qubes-builder/qubes-src/linux-template-builder/rpm/install-templates.sh' > install-templates.sh -$ chmod +x install-templates.sh -$ ./install-templates.sh -``` -* If everything went correct there should be a Archlinux template listed in your Qubes Manager - -Debugging the build process -=============================== -Archlinux use bleeding edge version of everything, so it is usually the -first template to break when new software version came out. -So an important point is to understand how to debug the template, how to fix -it, and then do a pull request :). -[My personal building script is here](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 QubesOS repositories - -After the command: -```shell_session -$ make get-sources -``` - -And before the command: -```shell_session -$ make qubes-vm -``` - -you can put your custom code by replacing the qubes-src/ directories. -For example: - -```shell_session -$ rm -Rf "$directory/qubes-src/gui-agent-linux/" -$ cp -R ~/qubes-gui-agent-linux "$directory/qubes-src/gui-agent-linux" -``` - -Example ------------------------ - -Launch the build -```shell_session -$ ./build_arch.sh -``` -It crash -~~~~ -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**. -Nor 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**". -```shell_session -$ 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 we need to modify the file **/archlinux/PKGBUILD** of the repository -"qubes-gui-agent-linux". -Let's clone "qubes-gui-agent-linux", be sure to checkout the correct -branch (example: `release4.0` instead of master ), and then edit the **/archlinux/PKGBUILD** -to do the modification you want to try. -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 - -```shell_session -$ rm -Rf "~/qubes-builder/qubes-src/gui-agent-linux/" -$ cp -R ~/qubes-gui-agent-linux "~/qubes-builder/qubes-src/gui-agent-linux" -``` -and retry to build the template. -If it build successfully and that the template work as expected, do a pull request on github to share your fix. - -Debugging the qube runtime -================================================================ -If you are able to launch a terminal and execute command, just use your usual -archlinux-fu to fix the issue. -If you are not able to launch a terminal, then, shutdown the qube, create a new -DisposableVM, [mount the Archlinux disk in the DisposableVM](/doc/mount-lvm-image/), chroot to it, and then use -your archlinux-fu. -Below, and 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 archlinux template and moved to dom0 and installed the template. -Then I tried to open a terminal in 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' -~~~~ -how can I debug this qube? - -Answer ---------- -I tried to rebuild archlinux and got the same issue. -The issue come 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](/doc/mount-lvm-image/) ) -```shell_session -$ ./mount_lvm_image.sh /dev/qubes_dom0/vm-archlinux-minimal-root fedora-dvm -``` -then in the newly created DisposableVM we mount the disk and chroot to it -```shell_session -# mount /dev/xvdi3 /mnt -# chroot /mnt -``` -Then check the journal: -~~~~ -[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 we saw is: -~~~~ -/usr/lib/qubes/init/setup-rwdev.sh: line 16: cmp: command not found -~~~~ -Let's check `setup-rwdev.sh`: -~~~~ -[root@disp9786 /]# cat /usr/lib/qubes/init/setup-rwdev.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 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 - #................. -~~~~ - -That is definitely something that we want to be working. So the binary `cmp` is missing, let's find it: - -```shell_session -# pacman -Fy cmp -``` -It is in `core/diffutils`, that, for some 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 a 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. - -```bash -$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): - -``` -[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 the maintainer gpg key as trusted. -Currently, no one want to provide binary packages. - -**So this package is currently useless.** - -If in the future, enough people think it is better to restart providing binary packages instead of the current "Do It Yourself" way, the gpg key and fingerprint of the new maintainer should 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 diff --git a/external/building-guides/building-non-fedora-template.md b/external/building-guides/building-non-fedora-template.md index 14577e70..54225da9 100644 --- a/external/building-guides/building-non-fedora-template.md +++ b/external/building-guides/building-non-fedora-template.md @@ -9,161 +9,3 @@ redirect_from: - /wiki/BuildingNonFedoraTemplate/ --- -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](/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 diff --git a/external/building-guides/building-whonix-template.md b/external/building-guides/building-whonix-template.md index 1e3160a6..136d9798 100644 --- a/external/building-guides/building-whonix-template.md +++ b/external/building-guides/building-whonix-template.md @@ -7,89 +7,3 @@ redirect_from: - /en/doc/building-whonix-template/ --- -## 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](/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! - - diff --git a/external/configuration-guides/change-time-zone.md b/external/configuration-guides/change-time-zone.md index 8204c5d3..b30e569e 100644 --- a/external/configuration-guides/change-time-zone.md +++ b/external/configuration-guides/change-time-zone.md @@ -6,33 +6,3 @@ redirect_from: - /doc/change-time-zone/ --- -# 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 - diff --git a/external/configuration-guides/disk-trim.md b/external/configuration-guides/disk-trim.md index 84329e36..0b4dccdd 100644 --- a/external/configuration-guides/disk-trim.md +++ b/external/configuration-guides/disk-trim.md @@ -9,105 +9,3 @@ redirect_from: - /wiki/DiskTRIM/ --- -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). - - * **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 ----------- - -If you have enabled LUKS in dom0, discards will not get passed down to the storage device. - -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. -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. diff --git a/external/configuration-guides/external-audio.md b/external/configuration-guides/external-audio.md index 742ca3a9..cf946cca 100644 --- a/external/configuration-guides/external-audio.md +++ b/external/configuration-guides/external-audio.md @@ -9,48 +9,3 @@ redirect_from: - /wiki/ExternalAudio/ --- -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](/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 -~~~ diff --git a/external/configuration-guides/fetchmail.md b/external/configuration-guides/fetchmail.md index fd32ce3d..09e76d8d 100644 --- a/external/configuration-guides/fetchmail.md +++ b/external/configuration-guides/fetchmail.md @@ -9,100 +9,3 @@ redirect_from: - /wiki/Fetchmail/ --- -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](/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](/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. diff --git a/external/configuration-guides/install-nvidia-driver.md b/external/configuration-guides/install-nvidia-driver.md index dbb875b0..73485558 100644 --- a/external/configuration-guides/install-nvidia-driver.md +++ b/external/configuration-guides/install-nvidia-driver.md @@ -9,134 +9,3 @@ redirect_from: - /wiki/InstallNvidiaDriver/ --- -# 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)](/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-260.19.44.run" is used. Copy it to dom0. Every next step is done in dom0. - -See [this page](/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-260.19.44.run --ui=none --no-x-check --keep --no-nouveau-check --no-kernel-module -~~~ - -### 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 refused to install it on Xen kernel. Firstly ensure that kernel-devel package installed all needed files. This should consist of: - -- */usr/src/kernels/2.6.34.1-12.xenlinux.qubes.x86\_64* -- */lib/modules/2.6.34.1-12.xenlinux.qubes.x86\_64/build* symlinked to the above directory -- */usr/src/kernels/2.6.34.1-12.xenlinux.qubes.x86\_64/arch/x64/include/mach-xen* should be present (if not - take it from kernel sources) - -If all the files are not there correct the errors manually. To build the kernel module, enter *NVIDIA-Linux-x86\_64-260.19.44/kernel* directory and execute: - -~~~ -make -IGNORE_XEN_PRESENCE=1 CC="gcc -DNV_VMAP_4_PRESENT -DNV_SIGNAL_STRUCT_RLIM" make -f Makefile.kbuild -mv /lib/modules/2.6.34.1-12.xenlinux.qubes.x86_64/kernel/drivers/video/nvidia.ko /lib/modules/2.6.34.1-12.xenlinux.qubes.x86_64/extra/ -~~~ - -Ignore any errors while inserting nvidia.ko (at the end of make phase). - -### Disable nouveau: - -~~~ -cat /etc/modprobe.d/nouveau-disable.conf -# blacklist isn't enough... -install nouveau /bin/true -~~~ - -Add *rdblacklist=nouveau* option to /boot/grub/menu.lst (at the end of line containing *vmlinuz*). - -### Configure Xorg - -Finally, you should configure Xorg to use nvidia driver. You can use *nvidia-xconfig* or do it manually: - -~~~ -X -configure -mv /root/xorg.conf.new /etc/X11/xorg.conf -# replace Driver in Device section by "nvidia" -~~~ - -Reboot to verify all this works. - -## 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](/doc/nvidia-troubleshooting/#lack-of-video-output-during-nvidia-driver-installation) guide for troubleshooting steps. - diff --git a/external/configuration-guides/multiboot.md b/external/configuration-guides/multiboot.md index 9a69e2b6..4293444d 100644 --- a/external/configuration-guides/multiboot.md +++ b/external/configuration-guides/multiboot.md @@ -6,211 +6,3 @@ redirect_from: - /doc/multiboot/ --- -Multibooting Qubes -======================================== - -Introduction ---------------------- - -You should think carefully before dual booting Qubes on your box. -Read the [guidelines](/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](/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 -~~~ diff --git a/external/configuration-guides/multimedia.md b/external/configuration-guides/multimedia.md index 0beac0a5..7fb03ed2 100644 --- a/external/configuration-guides/multimedia.md +++ b/external/configuration-guides/multimedia.md @@ -9,233 +9,3 @@ redirect_from: - /wiki/Multimedia/ --- -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 --with-fingerprint spotify.pubkey` - -This should look like: - - [user@t-multimedia ~]$ `gpg --with-fingerprint spotify.pubkey` - - pub 4096R/130D1D45 2019-07-15 Spotify Public Repository Signing Key - - Key fingerprint = 2EBF 997C 15BD A244 B6EB F5D8 4773 BD5E 130D 1D45 - -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 --with-fingerprint videolan.pubkey` - -This should look like: - - [user@t-multimedia ~]$ `gpg --with-fingerprint videolan.pubkey` - - pub 2048R/B84288D9 2013-08-27 VideoLAN APT Signing Key - - Key fingerprint = 8F08 45FE 77B1 6294 429A 7934 6BCA 5E4D B842 88D9 - - sub 2048R/288D4A2C 2013-08-27 - -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 --with-fingerprint google.pubkey` - -This should look like: - - [user@t-multimedia ~]$ `gpg --with-fingerprint google.pubkey` - - pub 4096R/D38B4796 2016-04-12 Google Inc. (Linux Packages Signing Authority) - - - - Key fingerprint = EB4C 1BFD 4F04 2F6D DDCC EC91 7721 F63B D38B 4796 - - sub 4096R/640DB551 2016-04-12 [expires: 2019-04-12] - - sub 4096R/997C215E 2017-01-24 [expires: 2020-01-24] - -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` - diff --git a/external/configuration-guides/mutt.md b/external/configuration-guides/mutt.md index 36e19e20..c0568991 100644 --- a/external/configuration-guides/mutt.md +++ b/external/configuration-guides/mutt.md @@ -9,219 +9,3 @@ redirect_from: - /wiki/Mutt/ --- -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](/doc/postfix/) or Exim and MRA such as -[Fetchmail](/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](/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 diff --git a/external/configuration-guides/network-bridge-support.md b/external/configuration-guides/network-bridge-support.md index 2b1f0d35..83ee20b4 100644 --- a/external/configuration-guides/network-bridge-support.md +++ b/external/configuration-guides/network-bridge-support.md @@ -9,139 +9,3 @@ redirect_from: - /wiki/NetworkBridgeSupport/ --- -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... diff --git a/external/configuration-guides/network-printer.md b/external/configuration-guides/network-printer.md index 66722a56..efca1ebf 100644 --- a/external/configuration-guides/network-printer.md +++ b/external/configuration-guides/network-printer.md @@ -9,48 +9,3 @@ redirect_from: - /wiki/NetworkPrinter/ --- -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](/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). -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. - diff --git a/external/configuration-guides/postfix.md b/external/configuration-guides/postfix.md index a72bfa61..97fd3049 100644 --- a/external/configuration-guides/postfix.md +++ b/external/configuration-guides/postfix.md @@ -144,13 +144,3 @@ 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. diff --git a/external/configuration-guides/rxvt.md b/external/configuration-guides/rxvt.md index ad397140..8676c3df 100644 --- a/external/configuration-guides/rxvt.md +++ b/external/configuration-guides/rxvt.md @@ -9,145 +9,3 @@ redirect_from: - /wiki/Rxvt/ --- -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. diff --git a/external/configuration-guides/tips-and-tricks.md b/external/configuration-guides/tips-and-tricks.md index 386fd43b..55e774af 100644 --- a/external/configuration-guides/tips-and-tricks.md +++ b/external/configuration-guides/tips-and-tricks.md @@ -6,52 +6,3 @@ redirect_from: - /doc/tips-and-tricks/ --- -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](/doc/security-guidelines/) and [security goals](/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](/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) - diff --git a/external/configuration-guides/vpn.md b/external/configuration-guides/vpn.md index 00a87637..2371f233 100644 --- a/external/configuration-guides/vpn.md +++ b/external/configuration-guides/vpn.md @@ -10,313 +10,3 @@ redirect_from: - /wiki/VPN/ --- -How To make a VPN Gateway in Qubes -================================== - - - -Although setting up a VPN connection is not by itself Qubes specific, Qubes includes a number of tools that can make the client-side setup of your VPN more versatile and secure. This document is a Qubes-specific outline for choosing the type of VM to use, and shows how to prepare a ProxyVM for either NetworkManager or a set of fail-safe VPN scripts. - -Please refer to your guest OS and VPN service documentation when considering the specific steps and parameters for your connection(s); The relevant documentation for the Qubes default guest OS (Fedora) is [Establishing a VPN Connection.](https://docs.fedoraproject.org/en-US/Fedora/23/html/Networking_Guide/sec-Establishing_a_VPN_Connection.html) - -### NetVM - -The simplest case is to set up a VPN connection using the NetworkManager service inside your NetVM. Because the NetworkManager service is already started, you are ready to set up your VPN connection. However this has some disadvantages: - -- You have to place (and probably save) your VPN credentials inside the NetVM, which is directly connected to the outside world -- All your AppVMs which are connected to the NetVM will be connected to the VPN (by default) - -### AppVM - -While the NetworkManager service is not started here (for a good reason), you can configure any kind of VPN client in your AppVM as well. However this is only suggested if your VPN client has special requirements. - -### ProxyVM - -One of the best unique features of Qubes OS is its special type of VM called a ProxyVM. The special thing is that your AppVMs see this as a NetVM (or uplink), and your NetVMs see it as a downstream AppVM. Because of this, you can place a ProxyVM between your AppVMs and your NetVM. This is how the default sys-firewall VM functions. - -Using a ProxyVM to set up a VPN client gives you the ability to: - -- Separate your VPN credentials from your NetVM. -- Separate your VPN credentials from your AppVM data. -- Easily control which of your AppVMs are connected to your VPN by simply setting it as a NetVM of the desired AppVM. - -Set up a ProxyVM as a VPN gateway using NetworkManager ------------------------------------------------------- - -1. Create a new VM, name it, click the ProxyVM radio button, and choose a color and template. - - ![Create\_New\_VM.png](/attachment/wiki/VPN/Create_New_VM.png) - -2. Add the `network-manager` service to this new VM. - - ![Settings-services.png](/attachment/wiki/VPN/Settings-services.png) - -3. Set up your VPN as described in the NetworkManager documentation linked above. - -4. (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.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 - ;; - 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' - - su - -c 'notify-send "$(hostname): Starting $VPN_CLIENT..." --icon=network-idle' user - groupadd -rf qvpn ; sleep 2s - sg qvpn -c "$VPN_CLIENT $VPN_OPTIONS" - ~~~ - - If you are using anything other than OpenVPN, change the `VPN_CLIENT` and `VPN_OPTIONS` variables to match your VPN software. - Save the script. - Make it executable. - - sudo chmod +x /rw/config/rc.local - -6. Restart the new VM! - The link should then be established automatically with a popup notification to that effect. - - -Usage ------ - -Configure your AppVMs to use the VPN VM as a NetVM... - -![Settings-NetVM.png](/attachment/wiki/VPN/Settings-NetVM.png) - -If you want to 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](/doc/software-update-domu/#updates-proxy). - - -Troubleshooting ---------------- - -See the [VPN Troubleshooting](/doc/vpn-troubleshooting/) guide for tips on how to fix common VPN issues. diff --git a/external/configuration-guides/w3m.md b/external/configuration-guides/w3m.md index b02f58bf..69db4a79 100644 --- a/external/configuration-guides/w3m.md +++ b/external/configuration-guides/w3m.md @@ -9,33 +9,3 @@ redirect_from: - /wiki/W3m/ --- -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? diff --git a/external/configuration-guides/zfs.md b/external/configuration-guides/zfs.md index c9a6e862..709a2577 100644 --- a/external/configuration-guides/zfs.md +++ b/external/configuration-guides/zfs.md @@ -9,190 +9,3 @@ redirect_from: - /wiki/ZFS/ --- -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) - diff --git a/external/customization-guides/dark-theme.md b/external/customization-guides/dark-theme.md index 5a4dea63..785a3b8f 100644 --- a/external/customization-guides/dark-theme.md +++ b/external/customization-guides/dark-theme.md @@ -6,184 +6,3 @@ redirect_from: - /doc/dark-theme/ --- -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` diff --git a/external/customization-guides/fedora-minimal-template-customization.md b/external/customization-guides/fedora-minimal-template-customization.md index 2016d025..e1553d2a 100644 --- a/external/customization-guides/fedora-minimal-template-customization.md +++ b/external/customization-guides/fedora-minimal-template-customization.md @@ -7,290 +7,3 @@ redirect_from: redirect_from: /en/doc/fedora-minimal-template-customization/ --- -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 diff --git a/external/customization-guides/language-localization.md b/external/customization-guides/language-localization.md index b466efa0..a1b4888a 100644 --- a/external/customization-guides/language-localization.md +++ b/external/customization-guides/language-localization.md @@ -9,44 +9,3 @@ redirect_from: - /wiki/LanguageLocalization/ --- -Language Localization -===================== - -Enable UTF-8 in dom0 title bars -------------------------- - -You can enable UTF-8 characters in the title bar for all qubes or on a per-qube basis. Follow the instructions [here](/doc/config-files/#gui-and-audio-configuration-in-dom0) for further information. - -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). diff --git a/external/customization-guides/removing-templatevm-packages.md b/external/customization-guides/removing-templatevm-packages.md index c2a905a3..a8d1d1e8 100644 --- a/external/customization-guides/removing-templatevm-packages.md +++ b/external/customization-guides/removing-templatevm-packages.md @@ -6,90 +6,3 @@ redirect_from: - /doc/removing-templatevm-packages/ --- -# 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 -``` diff --git a/external/customization-guides/windows-template-customization.md b/external/customization-guides/windows-template-customization.md index 6e7a6915..f5cb6fe7 100644 --- a/external/customization-guides/windows-template-customization.md +++ b/external/customization-guides/windows-template-customization.md @@ -7,164 +7,3 @@ redirect_from: redirect_from: /en/doc/windows-template-customization/ --- -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. diff --git a/external/os-guides/centos.md b/external/os-guides/centos.md index bdd9a02f..d12eaf37 100644 --- a/external/os-guides/centos.md +++ b/external/os-guides/centos.md @@ -6,31 +6,3 @@ redirect_from: - /doc/templates/centos/ --- -# 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](/doc/software-update-vm/). - -## Want to contribute? - -* [How can I contribute to the Qubes Project?](/doc/contributing/) - -* [Guidelines for Documentation Contributors](/doc/doc-guidelines/) - -[switch]: /doc/templates/#switching -[reinstall]: /doc/reinstall-template/ -[uninstall]: /doc/templates/#uninstalling -[Minimal TemplateVMs]: /doc/templates/minimal/ -[Xfce TemplateVMs]: /doc/templates/xfce/ diff --git a/external/os-guides/gentoo.md b/external/os-guides/gentoo.md index 51ecf998..dacaabb8 100644 --- a/external/os-guides/gentoo.md +++ b/external/os-guides/gentoo.md @@ -5,33 +5,3 @@ redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/os/tem redirect_from: - /doc/templates/gentoo/ --- - -# 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](/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?](/doc/contributing/) - -* [Guidelines for Documentation Contributors](/doc/doc-guidelines/) - -[switch]: /doc/templates/#switching -[reinstall]: /doc/reinstall-template/ -[uninstall]: /doc/templates/#uninstalling -[Minimal TemplateVMs]: /doc/templates/minimal/ -[Xfce TemplateVMs]: /doc/templates/xfce/ -[Gentoo Handbook]: https://wiki.gentoo.org/wiki/Handbook:AMD64 \ No newline at end of file diff --git a/external/os-guides/linux-hvm-tips.md b/external/os-guides/linux-hvm-tips.md index 3b05a75f..11acabb2 100644 --- a/external/os-guides/linux-hvm-tips.md +++ b/external/os-guides/linux-hvm-tips.md @@ -9,55 +9,3 @@ redirect_from: - /wiki/LinuxHVMTips/ --- -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](/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). diff --git a/external/os-guides/netbsd.md b/external/os-guides/netbsd.md index e9ebcfd9..41f7cc2c 100644 --- a/external/os-guides/netbsd.md +++ b/external/os-guides/netbsd.md @@ -6,20 +6,3 @@ redirect_from: - /doc/netbsd/ --- -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 diff --git a/external/os-guides/pentesting.md b/external/os-guides/pentesting.md index cb46986e..b832f0fb 100644 --- a/external/os-guides/pentesting.md +++ b/external/os-guides/pentesting.md @@ -6,27 +6,3 @@ redirect_from: - /doc/pentesting/ --- -**Legal notice:** - -The usage of penetration testing tools outside your own laboratory environment requires the permission of the organization you attack. Penetration testing without 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](/doc/pentesting/blackarch/) -- [Kali](/doc/pentesting/kali/) -- [PenTester Framework (PTF)](/doc/pentesting/ptf/) - -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. diff --git a/external/os-guides/pentesting/blackarch.md b/external/os-guides/pentesting/blackarch.md index 3d27ee14..8a0bf8e4 100644 --- a/external/os-guides/pentesting/blackarch.md +++ b/external/os-guides/pentesting/blackarch.md @@ -7,91 +7,3 @@ redirect_from: - /doc/blackarch/ --- -**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](/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](/doc/pentesting/kali/) -- [PenTester Framework (PTF)](/doc/pentesting/ptf/) -- [Pentesting](/doc/pentesting/) diff --git a/external/os-guides/pentesting/kali.md b/external/os-guides/pentesting/kali.md index 3b5f704f..5c9ffc33 100644 --- a/external/os-guides/pentesting/kali.md +++ b/external/os-guides/pentesting/kali.md @@ -7,180 +7,3 @@ redirect_from: - /doc/kali/ --- -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.](/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.gnupg.net --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 `buster` stable repository to `bullseye` testing repository - -```shell_session -# sed -i 's/buster/bullseye/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 -# cat /home/user/QubesIncoming/dispXXX/kali-key.asc | apt-key add - -``` - - This command should return: `OK`. - -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 `gcc8` to work around a dependency issue - -```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://tools.kali.org/kali-metapackages) -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] - -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]: /security/verifying-signatures/ -[qubes-pentesting]: /doc/pentesting/ -[qubes-blackarch]: /doc/pentesting/blackarch/ -[qubes-ptf]: /doc/pentesting/ptf/ -[qubes-template-debian-install]: /doc/templates/debian/#install -[qubes-resize-disk-image]: /doc/resize-disk-image/ -[qubes-new-hvm]: /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 - diff --git a/external/os-guides/pentesting/ptf.md b/external/os-guides/pentesting/ptf.md index 50423f70..ddd8a60f 100644 --- a/external/os-guides/pentesting/ptf.md +++ b/external/os-guides/pentesting/ptf.md @@ -7,116 +7,3 @@ redirect_from: - /doc/ptf/ --- -**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](/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](/doc/pentesting/blackarch/) -- [Kali](/doc/pentesting/kali/) -- [Pentesting](/doc/pentesting/) diff --git a/external/os-guides/ubuntu.md b/external/os-guides/ubuntu.md index 7d433544..fe9a8ed4 100644 --- a/external/os-guides/ubuntu.md +++ b/external/os-guides/ubuntu.md @@ -10,54 +10,3 @@ redirect_from: - /wiki/Templates/Ubuntu/ --- -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]: /doc/qubes-builder/ -[contrib]: /doc/contributing/ diff --git a/external/os-guides/windows/windows-tools.md b/external/os-guides/windows/windows-tools.md index ffd01651..e33e5166 100644 --- a/external/os-guides/windows/windows-tools.md +++ b/external/os-guides/windows/windows-tools.md @@ -15,335 +15,3 @@ redirect_from: - /wiki/WindowsTools/ --- -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](/doc/copy-paste/) between the Windows VM and other AppVMs -- ***File sender/receiver** - Support for [secure file exchange](/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](/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. - - 9. On a `dom0` terminal write: *(where `` is the name of your Windows 10 VM)* - - qvm-features gui 1 - - 10. Reboot Windows. If the VM starts, but does not show any window then shutdown Windows from the Qube manager 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 -s 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](/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