suzanne.soy/qubes-doc
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge branch 'patch-8' of https://github.com/awokd/qubes-doc into awokd-patch-8

Browse Source
This commit is contained in:
Andrew David Wong 2018-02-22 00:09:20 -06:00
commit 8726b58cc2
No known key found for this signature in database
GPG Key ID: 8CE137352A019A17
1 changed files with 97 additions and 76 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -9,17 +9,20 @@ redirect_from:
VM kernel managed by dom0 VM kernel managed by dom0
========================= =========================
By default VMs kernels are provided by dom0. This means that: By default, VMs kernels are provided by dom0. This means that:
1. You can select kernel version in VM settings; 1. You can select the kernel version in VM settings;
2. You can modify kernel options in VM settings; 2. You can modify kernel options in VM settings;
3. You can **not** modify any of above from inside of VM; 3. You can **not** modify any of the above from inside a VM;
4. Installing additional kernel modules is cumbersome. 4. Installing additional kernel modules is cumbersome.
To select which kernel a given VM will use, you can use either use Qubes Manager (VM settings, advanced tab), or `qvm-prefs` tool: *Note* In the examples below, although the specific version numbers might be old, the commands have been verified on R3.2 with debian-9 and fedora-26 templates.
At the time of writing, there is a blocking issue for R4.0 [3563](https://github.com/QubesOS/qubes-issues/issues/3563).
To select which kernel a given VM will use, you can either use Qubes Manager (VM settings, advanced tab), or the `qvm-prefs` tool:
~~~ ~~~
[user@dom0 ~]$ qvm-prefs my-appvm -s kernel [user@dom0 ~]$ qvm-prefs -s my-appvm kernel
Missing kernel version argument! Missing kernel version argument!
Possible values: Possible values:
1) default 1) default
@ -29,11 +32,11 @@ Possible values:
- 3.18.17-4 - 3.18.17-4
- 3.19.fc20 - 3.19.fc20
- 3.18.10-2 - 3.18.10-2
[user@dom0 ~]$ qvm-prefs my-appvm -s kernel 3.18.17-4 [user@dom0 ~]$ qvm-prefs -s my-appvm kernel 3.18.17-4
[user@dom0 ~]$ qvm-prefs my-appvm -s kernel default [user@dom0 ~]$ qvm-prefs -s my-appvm kernel default
~~~ ~~~
To check/change the default kernel you can go either to "Global settings" in Qubes Manager, or use `qubes-prefs` tool: To check/change the default kernel you can either go to "Global settings" in Qubes Manager, or use the `qubes-prefs` tool:
~~~ ~~~
[user@dom0 ~]$ qubes-prefs [user@dom0 ~]$ qubes-prefs
@ -49,7 +52,9 @@ updatevm : sys-firewall
Installing different kernel using Qubes kernel package Installing different kernel using Qubes kernel package
---------------------------------- ----------------------------------
VM kernels are packages by Qubes team in `kernel-qubes-vm` packages. Generally the system will keep the 3 newest available versions. You can list them with the `rpm` command: VM kernels are packages by Qubes team in `kernel-qubes-vm` packages.
Generally, the system will keep the three newest available versions.
You can list them with the `rpm` command:
~~~ ~~~
[user@dom0 ~]$ rpm -qa 'kernel-qubes-vm*' [user@dom0 ~]$ rpm -qa 'kernel-qubes-vm*'
@ -58,10 +63,11 @@ kernel-qubes-vm-3.18.16-3.pvops.qubes.x86_64
kernel-qubes-vm-3.18.17-4.pvops.qubes.x86_64 kernel-qubes-vm-3.18.17-4.pvops.qubes.x86_64
~~~ ~~~
If you want a more recent version, you can check `qubes-dom0-unstable` repository. As the name suggests, keep in If you want a more recent version, you can check the `qubes-dom0-unstable` repository.
mind that those packages may be less stable than the default ones. There is also the `kernel-latest-qubes-vm` package which should provide a more recent (non-LTS) kernel, but has received much less testing.
As the names suggest, keep in mind that those packages may be less stable than the default ones.
Checking available versions in `qubes-dom0-unstable` repository: To check available versions in the `qubes-dom0-unstable` repository:
~~~ ~~~
[user@dom0 ~]$ sudo qubes-dom0-update --enablerepo=qubes-dom0-unstable --action=list kernel-qubes-vm [user@dom0 ~]$ sudo qubes-dom0-update --enablerepo=qubes-dom0-unstable --action=list kernel-qubes-vm
@ -82,7 +88,7 @@ kernel-qubes-vm.x86_64 1000:3.18.17-4.pvops.qubes @qubes-dom0-cached
~~~ ~~~
Installing new version from `qubes-dom0-unstable` repository: Installing a new version from `qubes-dom0-unstable` repository:
~~~ ~~~
[user@dom0 ~]$ sudo qubes-dom0-update --enablerepo=qubes-dom0-unstable kernel-qubes-vm [user@dom0 ~]$ sudo qubes-dom0-update --enablerepo=qubes-dom0-unstable kernel-qubes-vm
@ -127,24 +133,25 @@ Failed:
kernel-qubes-vm.x86_64 1000:3.18.10-2.pvops.qubes kernel-qubes-vm.x86_64 1000:3.18.10-2.pvops.qubes
Complete! Complete!
[marmarek@dom0 ~]$ [user@dom0 ~]$
~~~ ~~~
In the above example, it tries to remove 3.18.10-2.pvops.qubes kernel (to keep only 3 installed), but since some VM uses it, it fails. Installation of new package is unaffected by this event. In the above example, it tries to remove the 3.18.10-2.pvops.qubes kernel (to keep only three installed), but since some VM uses it, it fails.
Installation of the new package is unaffected by this event.
The newly installed package is set as default VM kernel. The newly installed package is set as the default VM kernel.
Installing different VM kernel based on dom0 kernel Installing different VM kernel based on dom0 kernel
--------------------------------------------------- ---------------------------------------------------
It is possible to package kernel installed in dom0 as VM kernel. This makes it It is possible to package a kernel installed in dom0 as a VM kernel.
possible to use VM kernel, which is not packaged by Qubes team. This includes: This makes it possible to use a VM kernel which is not packaged by Qubes team.
* using Fedora kernel package This includes:
* using manually compiled kernel * using a Fedora kernel package
* using a manually compiled kernel
To prepare such VM kernel, you need to install `qubes-kernel-vm-support` To prepare such a VM kernel, you need to install the `qubes-kernel-vm-support` package in dom0 and also have matching kernel headers installed (`kernel-devel` package in the case of a Fedora kernel package).
package in dom0 and also have matching kernel headers installed (`kernel-devel` You can install requirements using `qubes-dom0-update`:
package in the case of Fedora kernel package). You can install required stuff using `qubes-dom0-update`:
~~~ ~~~
[user@dom0 ~]$ sudo qubes-dom0-update qubes-kernel-vm-support kernel-devel [user@dom0 ~]$ sudo qubes-dom0-update qubes-kernel-vm-support kernel-devel
@ -187,10 +194,9 @@ Installed:
Complete! Complete!
~~~ ~~~
Then you can call `qubes-prepare-vm-kernel` tool to actually package the Then you can call the `qubes-prepare-vm-kernel` tool to actually package the kernel.
kernel. The first parameter is kernel version (exactly as seen by the kernel), The first parameter is kernel version (exactly as seen by the kernel), the second one (optional) is short name.
the second one (optional) is short name being visible in Qubes Manager and This is visible in Qubes Manager and the `qvm-prefs` tool.
`qvm-prefs` tool.
~~~ ~~~
[user@dom0 ~]$ sudo qubes-prepare-vm-kernel 4.1.9-6.pvops.qubes.x86_64 4.1.qubes [user@dom0 ~]$ sudo qubes-prepare-vm-kernel 4.1.9-6.pvops.qubes.x86_64 4.1.qubes
@ -207,14 +213,18 @@ Using kernel installed in the VM
**This option is available only in Qubes R3.1 or newer** **This option is available only in Qubes R3.1 or newer**
It is possible to use kernel installed in the VM (in most cases - TemplateVM). It is possible to use a kernel installed in the VM (in most cases - TemplateVM).
This is possible thanks to PV GRUB2 - GRUB2 running in the VM. To make it happen, you need to: This is possible thanks to PV GRUB2 - GRUB2 running in the VM.
To make it happen, at a high level you need to:
1. Install PV GRUB2 in dom0 - package is named `grub2-xen`. 1. Install PV GRUB2 (`grub2-xen`) in dom0.
2. Install kernel in the VM. As with all VM software installation - this needs to be done in TemplateVM (of StandaloneVM if you are using one). 2. Install kernel in the VM (see below for Fedora and Debian steps).
3. Set VM kernel to `pvgrub2` value. You can use `pvgrub2` in selected VMs, not necessary all of them, even when its template has kernel installed. You can still use dom0-provided kernel for selected VMs. As with all VM software installation - this needs to be done in a TemplateVM (or StandaloneVM if you are using one).
3. Set VM kernel to `pvgrub2` value.
You can use `pvgrub2` in selected VMs, but it's not necessary in all of them, even if its template has a kernel installed.
You can still use a dom0-provided kernel for selected VMs.
**WARNING: When using kernel from within VM, `kernelopts` parameter is ignored.** **WARNING: When using a kernel from within a VM, the `kernelopts` parameter is ignored.**
### Installing PV GRUB2 ### Installing PV GRUB2
@ -226,28 +236,31 @@ sudo qubes-dom0-update grub2-xen
### Installing kernel in Fedora VM ### Installing kernel in Fedora VM
In Fedora based VM, you need to install `qubes-kernel-vm-support` package. This In a Fedora based VM, you need to install the `qubes-kernel-vm-support` package.
package includes required additional kernel module and initramfs addition This package includes the additional kernel module and initramfs addition required to start a Qubes VM (for details see [template implementation](/doc/template-implementation/)).
required to start Qubes VM (for details see Additionally, you need some GRUB tools to create its configuration.
[template implementation](/doc/template-implementation/)). Additionally you Note: You don't need an actual grub bootloader as it is provided by dom0, but having one shouldn't hurt.
need some GRUB tools to create its configuration. Note: you don't need actual
grub bootloader as it is provided by dom0. But having one also shouldn't harm.
~~~ ~~~
sudo yum install qubes-kernel-vm-support grub2-tools sudo dnf install qubes-kernel-vm-support grub2-tools
~~~ ~~~
Then install whatever kernel you want. If you are using distribution kernel Then install whatever kernel you want.
package (`kernel` package), initramfs and kernel module should be handled You need to also ensure you have the `kernel-devel` package for the same kernel version installed.
automatically, but you need to ensure you have `kernel-devel` package for the
same kernel version installed. If you are using a manually built kernel, you need
to handle this on your own. Take a look at `dkms` and `dracut` documentation.
Especially `dkms autoinstall` command may be useful.
When kernel is installed, you need to create GRUB configuration. If you are using a distribution kernel package (`kernel` package), the initramfs and kernel modules may be handled automatically.
You may want to adjust some settings in `/etc/default/grub`, for example lower If you are using a manually built kernel, you need to handle this on your own.
`GRUB_TIMEOUT` to speed up VM startup. Then you need to generate actual configuration: Take a look at the `dkms` documentation, especially the `dkms autoinstall` command may be useful.
In Fedora it can be done using `grub2-mkconfig` tool: If you did not see the `kernel` install rebuild your initramfs, or are using a manually built kernel, you will need to rebuild it yourself with the following (replace version numbers with those appropriate for your kernel):
~~~
dracut -f /boot/initramfs-4.14.16-200.fc26.x86_64.img 4.14.16-200.fc26.x86_64
~~~
Once the kernel is installed, you need to create a GRUB configuration.
You may want to adjust some settings in `/etc/default/grub`; for example, lower `GRUB_TIMEOUT` to speed up VM startup.
Then, you need to generate the actual configuration:
In Fedora it can be done using the `grub2-mkconfig` tool:
~~~ ~~~
sudo grub2-mkconfig -o /boot/grub2/grub.cfg sudo grub2-mkconfig -o /boot/grub2/grub.cfg
@ -259,29 +272,34 @@ You can safely ignore this error message:
grub2-probe: error: cannot find a GRUB drive for /dev/mapper/dmroot. Check your device.map grub2-probe: error: cannot find a GRUB drive for /dev/mapper/dmroot. Check your device.map
~~~ ~~~
Then shutdown the VM. From now you can set `pvgrub2` as VM kernel and it will Then shutdown the VM.
start kernel configured within VM. Now you can set `pvgrub2` as the VM kernel and it will start the kernel configured within your VM.
**Note:** On first boot the VM will automatically allocate swap space.
This can take a while to complete- longer than your `qrexec_timeout` setting, which will make the VM appear to have hung on boot.
To confirm this is the case, see [Troubleshooting](/doc/managing-vm-kernel/#troubleshooting) below or just wait for five minutes and shutdown the VM.
It should respond normally on future boots.
### Installing kernel in Debian VM ### Installing kernel in Debian VM
In Debian based VM, you need to install `qubes-kernel-vm-support` package. This In a Debian based VM, you need to install the `qubes-kernel-vm-support` package.
package includes required additional kernel module and initramfs addition This package includes the additional kernel module and initramfs addition required to start a Qubes VM (for details see [template implementation](/doc/template-implementation/)).
required to start Qubes VM (for details see Additionally, you need some GRUB tools to create its configuration.
[template implementation](/doc/template-implementation/)). Additionally you Note: You don't need an actual grub bootloader as it is provided by dom0, but having one shouldn't hurt.
need some GRUB tools to create its configuration. Note: you don't need actual
grub bootloader as it is provided by dom0. But having one also shouldn't harm.
~~~ ~~~
sudo apt-get update sudo apt update
sudo apt-get install qubes-kernel-vm-support grub2-common sudo apt install qubes-kernel-vm-support grub2-common
~~~ ~~~
If prompted for a GRUB install device, choose `/dev/mapper/dmroot`.
You will receive an error about GRUB failed to install to it, but just continue anyways.
Ignore warnings about `version '...' has bad syntax`. Ignore warnings about `version '...' has bad syntax`.
Then install whatever kernel you want. If you are using distribution kernel Then install whatever kernel you want.
package (`linux-image-amd64` package), initramfs and kernel module should be If you are using a distribution kernel package (`linux-image-amd64` package), the initramfs and kernel modules should be handled automatically.
handled automatically. If not, or you are building kernel manually, do this on If not, or you are building the kernel manually, do this using `dkms` and `initramfs-tools`:
using `dkms` and `initramfs-tools`:
sudo dkms autoinstall -k <kernel-version> # replace this <kernel-version> with actual kernel version sudo dkms autoinstall -k <kernel-version> # replace this <kernel-version> with actual kernel version
sudo update-initramfs -u sudo update-initramfs -u
@ -303,10 +321,9 @@ The output should look like this:
$ sudo update-initramfs -u $ sudo update-initramfs -u
update-initramfs: Generating /boot/initrd.img-3.16.0-4-amd64 update-initramfs: Generating /boot/initrd.img-3.16.0-4-amd64
When kernel is installed, you need to create GRUB configuration. When the kernel is installed, you need to create a GRUB configuration.
You may want to adjust some settings in `/etc/default/grub`, for example lower You may want to adjust some settings in `/etc/default/grub`; for example, lower `GRUB_TIMEOUT` to speed up VM startup.
`GRUB_TIMEOUT` to speed up VM startup. Then you need to generate actual configuration: Then, you need to generate the actual configuration with the `update-grub2` tool:
In Fedora it can be done using `update-grub2` tool:
~~~ ~~~
sudo mkdir /boot/grub sudo mkdir /boot/grub
@ -319,17 +336,21 @@ You can safely ignore this error message:
grub2-probe: error: cannot find a GRUB drive for /dev/mapper/dmroot. Check your device.map grub2-probe: error: cannot find a GRUB drive for /dev/mapper/dmroot. Check your device.map
~~~ ~~~
Then shutdown the VM. From now you can set `pvgrub2` as VM kernel and it will Then shutdown the VM.
start kernel configured within VM. Now you can set `pvgrub2` as the VM kernel and it will start the kernel configured within your VM.
When starting the VM you can safely ignore any warnings about a missing module 'dummy-hcd' When starting the VM you can safely ignore any warnings about a missing module 'dummy-hcd'.
**Note:** on first boot the VM will automatically allocate swap space.
This can take a while to complete- longer than your `qrexec_timeout` setting, which will make the VM appear to have hung on boot.
To confirm this is the case, see [Troubleshooting](/doc/managing-vm-kernel/#troubleshooting) below or just wait for five minutes and shutdown the VM.
It should respond normally on future boots.
### Troubleshooting ### Troubleshooting
In the event of a problem, you can access the VM console (using `sudo xl console VMNAME` in dom0) to access In case of problems, you can access the VM console using `sudo xl console VMNAME` in dom0, then access the GRUB menu.
the GRUB menu. You need to call it just after starting VM (until `GRUB_TIMEOUT` You need to call it just after starting the VM (until `GRUB_TIMEOUT` expires); for example, in a separate dom0 terminal window.
expires) - for example in a separate dom0 terminal window.
In any case you can later access VM logs (especially VM console log (`guest-VMNAME.log`). In any case you can later access the VM's logs (especially the VM console log `guest-VMNAME.log`).
You can always set kernel back to some dom0-provided value to fix VM kernel installation. You can always set the kernel back to some dom0-provided value to fix a VM kernel installation.