mirror of
https://github.com/QubesOS/qubes-doc.git
synced 2025-05-02 06:46:11 -04:00
Merge branch 'master' into vm-troubleshooting
This commit is contained in:
Enjeck Cleopatra
GitHub
commit
23c0523810
79 changed files with 2123 additions and 1204 deletions
|
|
@ -31,7 +31,7 @@ The scripts here all run as root.
|
|||
|
||||
~~~
|
||||
# Add entry to /etc/hosts
|
||||
echo '127.0.0.1 example.com >> /etc/hosts
|
||||
echo '127.0.0.1 example.com' >> /etc/hosts
|
||||
~~~
|
||||
|
||||
- `/rw/config/qubes-ip-change-hook` - script runs in NetVM after every external IP change and on "hardware" link status change.
|
||||
|
|
@ -85,29 +85,30 @@ Sample config (included in default installation):
|
|||
|
||||
~~~
|
||||
# Sample configuration file for Qubes GUI daemon
|
||||
# For syntax go http://www.hyperrealm.com/libconfig/libconfig_manual.html
|
||||
# For syntax go https://www.hyperrealm.com/libconfig/libconfig_manual.html
|
||||
|
||||
global: {
|
||||
# default values
|
||||
#allow_fullscreen = false;
|
||||
#override_redirect_protection = true;
|
||||
#allow_utf8_titles = false;
|
||||
#secure_copy_sequence = "Ctrl-Shift-c";
|
||||
#secure_paste_sequence = "Ctrl-Shift-v";
|
||||
#windows_count_limit = 500;
|
||||
#audio_low_latency = false;
|
||||
#audio_low_latency = true;
|
||||
#log_level = 1;
|
||||
#trayicon_mode = "border1";
|
||||
#startup_timeout = 91;
|
||||
#startup_timeout = 45;
|
||||
};
|
||||
|
||||
# most of setting can be set per-VM basis
|
||||
|
||||
VM: {
|
||||
work: {
|
||||
#allow_utf8_titles = true;
|
||||
allow_utf8_titles = true;
|
||||
};
|
||||
video-vm: {
|
||||
#allow_fullscreen = true;
|
||||
allow_fullscreen = true;
|
||||
};
|
||||
};
|
||||
~~~
|
||||
|
|
|
|||
|
|
@ -55,6 +55,8 @@ If you wish to use a [Minimal TemplateVM](/doc/templates/minimal/) as a Disposab
|
|||
|
||||
## Customization of DisposableVM
|
||||
|
||||
_**Note:** If you are trying to customize Tor Browser in a Whonix DisposableVM, please consult the [Whonix documentation](https://www.whonix.org/wiki/Tor_Browser/Advanced_Users#DVM_Template_Customization)._
|
||||
|
||||
It is possible to change the settings for each new DisposableVM.
|
||||
This can be done by customizing the DisposableVM Template on which it is based:
|
||||
|
||||
|
|
@ -64,7 +66,7 @@ This can be done by customizing the DisposableVM Template on which it is based:
|
|||
|
||||
2. Change the qube's settings and/or applications, as desired. Some examples of changes you may want to make include:
|
||||
- Changing Firefox's default startup settings and homepage.
|
||||
- Changing default editor, image viewer.
|
||||
- Changing default editor, image viewer. In Debian-based templates this can be done with the `mimeopen` command.
|
||||
- Changing the DisposableVM's default NetVM. For example, you may wish to set the NetVM to "none." Then, whenever you start a new DisposableVM, you can choose your desired ProxyVM manually (by changing the newly-started DisposableVMs settings). This is useful if you sometimes wish to use a DisposableVM with a Whonix Gateway, for example. It is also useful if you sometimes wish to open untrusted files in a network-disconnected DisposableVM.
|
||||
|
||||
4. Shutdown the qube (either by `poweroff` from qube's terminal, or `qvm-shutdown` from dom0 terminal).
|
||||
|
|
@ -80,7 +82,7 @@ The only exception is if you require something like VM to VM communication and h
|
|||
To create one that has no PCI devices attached, such as for `sys-firewall`:
|
||||
|
||||
~~~
|
||||
qvm-create -C DispVM -l red <sys-VMName>
|
||||
qvm-create -C DispVM -l green <sys-VMName>
|
||||
qvm-prefs <sys-VMName> autostart true
|
||||
qvm-prefs <sys-VMName> netvm <sys-net>
|
||||
qvm-prefs <sys-VMName> provides_network true
|
||||
|
|
|
|||
|
|
@ -25,10 +25,13 @@ That's it. After logging out, you can select i3 in the login manager.
|
|||
|
||||
### Customization
|
||||
|
||||
**Caution:** The following external resources may not have been reviewed by the Qubes team.
|
||||
|
||||
* [xdg_autostart_script](https://gist.github.com/SietsevanderMolen/7b4cc32ce7b4884513b0a639540e454f)
|
||||
* [i3bar_script](https://gist.github.com/SietsevanderMolen/e7f594f209dfaa3596907e427b657e30)
|
||||
* [terminal_start_script](https://gist.github.com/SietsevanderMolen/7c6f2b5773dbc0c08e1509e49abd1e96)
|
||||
* [i3 config with dmenu-i3-window-jumper](https://github.com/anadahz/qubes-i3-config/blob/master/config)
|
||||
* [dmenu script to open a terminal in a chosen VM](https://gist.github.com/dmoerner/65528941dd20b05c98ee79e92d7e0183)
|
||||
|
||||
## Compilation and installation from source
|
||||
|
||||
|
|
|
|||
|
|
@ -33,7 +33,7 @@ In most cases, the GUI tool Qube Settings (available for every qube from the Sta
|
|||
|
||||
|
||||
In case of standalone qubes and templates, just change the Disk Storage settings above.
|
||||
In case of template-based qubes, the private storage (the /home directory and user files) can be changed in the qube's own settings, but the system root image is [inherited from the template](/getting-started/#appvms-qubes-and-templatevms), and so it must be changed in the template settings.
|
||||
In case of template-based qubes, the private storage (the /home directory and user files) can be changed in the qube's own settings, but the system root image is [inherited from the template](/getting-started/), and so it must be changed in the template settings.
|
||||
If you are increasing the disk image size for Linux-based qubes installed from Qubes OS repositories in Qubes 4.0 or later, changing the settings above is all you need to do - in other cases, you may need to do more, according to instructions below.
|
||||
See also the OS-specific follow-up instructions below.
|
||||
|
||||
|
|
|
|||
|
|
@ -464,6 +464,26 @@ Whonix Gateway TemplateVM
|
|||
|
||||
Whonix Workstation TemplateVM
|
||||
|
||||
#### `update.qubes-dom0`
|
||||
|
||||
Updates dom0
|
||||
|
||||
#### `update.qubes-vm`
|
||||
|
||||
Updates domUs. Example to update all TemplateVMs:
|
||||
|
||||
sudo qubesctl --skip-dom0 --templates state.sls update.qubes-vm
|
||||
|
||||
Useful options:
|
||||
|
||||
- `--max-concurrency` --- Limits how many templates are updated at the same time.
|
||||
Adjust to your available RAM.
|
||||
The default is 4, and the GUI updater sets it to 1.
|
||||
- `--targets=vm1,vm2,...` --- Limit to specific VMs, instead of all of them.
|
||||
(Use instead of `--templates` or `--standalones`.)
|
||||
- `--show-output` --- Show an update summary instead of just OK/FAIL.
|
||||
|
||||
For other options, see `qubesctl --help`.
|
||||
|
||||
## The `qubes` Pillar Module
|
||||
|
||||
|
|
@ -488,6 +508,7 @@ Template name on which a given VM is based (if any).
|
|||
|
||||
VM which provides network to the given VM
|
||||
|
||||
|
||||
## Debugging
|
||||
|
||||
The output for each VM is logged in `/var/log/qubes/mgmt-VM_NAME.log`.
|
||||
|
|
|
|||
|
|
@ -1,245 +0,0 @@
|
|||
---
|
||||
layout: doc
|
||||
title: UEFI Troubleshooting
|
||||
permalink: /doc/uefi-troubleshooting/
|
||||
---
|
||||
|
||||
Troubleshooting UEFI related problems
|
||||
========================================
|
||||
|
||||
Change installer kernel parameters in UEFI
|
||||
---------------------
|
||||
|
||||
If you've installed successfully in legacy mode but had to change some kernel parameters for it to work, you should try installing in UEFI mode with the same parameters.
|
||||
|
||||
**Change the xen configuration on a USB media**
|
||||
01. Attach the usb disk, mount the EFI partition (second partition available on the disk)
|
||||
02. As `su`, edit your xen config (`EFI/BOOT/BOOTX64.cfg`) changing the `kernel` key to add your kernel parameters on the boot entry of your choice
|
||||
03. Install using your modified boot entry
|
||||
|
||||
**Change xen configuration directly in an iso image**
|
||||
01. Get EFI partition boundaries `parted Qubes-R4.0-rc4-x86_64.iso unit B print`
|
||||
02. Using the start address and the size of the EFI partition, setup a loop device for it `sudo losetup -o 524288 --sizelimit 30562304 /dev/loop0 Qubes-R4.0-rc4-x86_64.iso`
|
||||
03. Mount the loop device `sudo mount /dev/loop0 /mnt`
|
||||
04. Edit `EFI/BOOT/BOOTX64.cfg` to add your params to the `kernel` configuration key
|
||||
05. Save your changes, unmount and dd to usb device
|
||||
|
||||
|
||||
Installation freezes before displaying installer
|
||||
-----------------------------------------------------------
|
||||
|
||||
Some systems can freeze with the default UEFI install options.
|
||||
You can try the following to remove `noexitboot` and `mapbs`.
|
||||
If you have an Nvidia card, see also [Nvidia Troubleshooting](/doc/nvidia-troubleshooting/#disabling-nouveau).
|
||||
|
||||
1. Follow the [steps here](/doc/uefi-troubleshooting/#change-installer-kernel-parameters-in-uefi) to edit the `[qubes-verbose]` section of your installer's `BOOTX64.cfg`.
|
||||
You want to comment out the `mapbs` and `noexitboot` lines.
|
||||
The end result should look like this:
|
||||
|
||||
~~~
|
||||
[qubes-verbose]
|
||||
options=console=vga efi=attr=uc
|
||||
# noexitboot=1
|
||||
# mapbs=1
|
||||
kernel=vmlinuz inst.stage2=hd:LABEL=Qubes-R4.0-x86_64 i915.alpha_support=1
|
||||
ramdisk=initrd.img
|
||||
~~~
|
||||
|
||||
2. Boot the installer and continue to install as normal, but don't reboot the system at the end when prompted.
|
||||
3. Go to `tty2` (Ctrl-Alt-F2).
|
||||
4. Use your preferred text editor (`nano` works) to edit `/mnt/sysimage/boot/efi/EFI/qubes/xen.cfg`, verifying the `noexitboot` and `mapbs` lines are not present.
|
||||
This is also a good time to make permanent any other changes needed to get the installer to work, such as `nouveau.modeset=0`.
|
||||
For example:
|
||||
|
||||
~~~
|
||||
[4.14.18-1.pvops.qubes.x86_64]
|
||||
options=loglvl=all dom0_mem=min:1024M dom0_mem=max:4096M iommu=no-igfx ucode=scan efi=attr=uc
|
||||
~~~
|
||||
|
||||
5. Go back to `tty6` (Ctrl-Alt-F6) and click `Reboot`.
|
||||
6. Continue with setting up default templates and logging in to Qubes.
|
||||
|
||||
|
||||
Installation freezes before displaying installer / disable EFI runtime services
|
||||
------------------------------------------------------------------------------
|
||||
|
||||
On some early, buggy UEFI implementations, you may need to disable EFI under Qubes completely.
|
||||
This can sometimes be done by switching to legacy mode in your BIOS/UEFI configuration.
|
||||
If that's not an option there, or legacy mode does not work either, you can try the following to add `efi=no-rs`.
|
||||
Consider this approach as a last resort, because it will make every Xen update a manual process.
|
||||
|
||||
1. Follow the [steps here](/doc/uefi-troubleshooting/#change-installer-kernel-parameters-in-uefi) to edit the `[qubes-verbose]` section of your installer's `xen.cfg`.
|
||||
You want to modify the `efi=attr=uc` setting and comment out the `mapbs` and `noexitboot` lines.
|
||||
The end result should look like this:
|
||||
|
||||
~~~
|
||||
[qubes-verbose]
|
||||
options=console=vga efi=no-rs
|
||||
# noexitboot=1
|
||||
# mapbs=1
|
||||
kernel=vmlinuz inst.stage2=hd:LABEL=Qubes-R4.0-x86_64 i915.alpha_support=1
|
||||
ramdisk=initrd.img
|
||||
~~~
|
||||
|
||||
2. Boot the installer and continue to install as normal, until towards the end when you will receive a warning about being unable to create the EFI boot entry.
|
||||
Click continue, but don't reboot the system at the end when prompted.
|
||||
3. Go to `tty2` (Ctrl-Alt-F2).
|
||||
4. Use your preferred text editor (`nano` works) to edit `/mnt/sysimage/boot/efi/EFI/qubes/xen.cfg`, adding the `efi=no-rs` option to the end of the `options=` line.
|
||||
For example:
|
||||
|
||||
~~~
|
||||
[4.14.18-1.pvops.qubes.x86_64]
|
||||
options=loglvl=all dom0_mem=min:1024M dom0_mem=max:4096M iommu=no-igfx ucode=scan efi=no-rs
|
||||
~~~
|
||||
|
||||
5. Execute the following commands:
|
||||
|
||||
~~~
|
||||
cp -R /mnt/sysimage/boot/efi/EFI/qubes /mnt/sysimage/boot/efi/EFI/BOOT
|
||||
mv /mnt/sysimage/boot/efi/EFI/BOOT/xen-*.efi /mnt/sysimage/boot/efi/EFI/BOOT/BOOTX64.efi
|
||||
mv /mnt/sysimage/boot/efi/EFI/BOOT/xen.cfg /mnt/sysimage/boot/efi/EFI/BOOT/BOOTX64.cfg
|
||||
~~~
|
||||
|
||||
6. Go back to `tty6` (Ctrl-Alt-F6) and click `Reboot`.
|
||||
7. Continue with setting up default templates and logging in to Qubes.
|
||||
|
||||
Whenever there is a kernel or Xen update for Qubes, you will need to follow [these steps](/doc/uefi-troubleshooting/#boot-device-not-recognized-after-installing) because your system is using the fallback UEFI bootloader in `[...]/EFI/BOOT` instead of directly booting to the Qubes entry under `[...]/EFI/qubes`.
|
||||
|
||||
|
||||
Installation completes successfully but then boot loops or hangs on black screen
|
||||
---------------------
|
||||
|
||||
There is a [common bug in UEFI implementation](http://xen.markmail.org/message/f6lx2ab4o2fch35r) affecting mostly Lenovo systems, but probably some others too.
|
||||
While some systems need `mapbs` and/or `noexitboot` disabled to boot, others require them enabled at all times.
|
||||
Although these are enabled by default in the installer, they are disabled after the first stage of a successful install.
|
||||
You can re-enable them either as part of the install process:
|
||||
|
||||
1. Perform installation normally, but don't reboot the system at the end yet.
|
||||
2. Go to `tty2` (Ctrl-Alt-F2).
|
||||
3. Enable `mapbs` and/or `noexitboot` on the just installed system.
|
||||
Edit `/mnt/sysimage/boot/efi/EFI/qubes/xen.cfg` (you can use `vi` or `nano` editor) and add to every kernel section:
|
||||
|
||||
mapbs=1
|
||||
noexitboot=1
|
||||
|
||||
**Note:** You must add these parameters on two separate new lines (one
|
||||
parameter on each line) at the end of each section that includes a kernel
|
||||
line (i.e., all sections except the first one, since it doesn't have a
|
||||
kernel line).
|
||||
|
||||
4. Go back to `tty6` (Ctrl-Alt-F6) and click `Reboot`.
|
||||
5. Continue with setting up default templates and logging in to Qubes.
|
||||
|
||||
Or if you have already rebooted after the first stage install and have encountered this issue, by:
|
||||
|
||||
1. Boot into [rescue mode](/doc/uefi-troubleshooting/#accessing-installer-rescue-mode-on-uefi).
|
||||
2. Enable `mapbs` and/or `noexitboot` on the just installed system.
|
||||
Edit `/mnt/sysimage/boot/efi/EFI/qubes/xen.cfg` (you can use `vi` or `nano` editor) and add to every kernel section:
|
||||
|
||||
mapbs=1
|
||||
noexitboot=1
|
||||
|
||||
**Note:** You must add these parameters on two separate new lines (one
|
||||
parameter on each line) at the end of each section that includes a kernel
|
||||
line (i.e., all sections except the first one, since it doesn't have a
|
||||
kernel line).
|
||||
|
||||
3. Type `reboot`.
|
||||
4. Continue with setting up default templates and logging in to Qubes.
|
||||
|
||||
|
||||
Installation completes successfully but then system crash/restarts on next boot
|
||||
-------------------------------------------
|
||||
|
||||
Some Dell systems and probably others have [another bug in UEFI firmware](http://markmail.org/message/amw5336otwhdxi76).
|
||||
These systems need `efi=attr=uc` enabled at all times.
|
||||
Although this is enabled by default in the installer, it is disabled after the first stage of a successful install.
|
||||
You can re-enable it either as part of the install process:
|
||||
|
||||
1. Perform installation normally, but don't reboot the system at the end yet.
|
||||
2. Go to `tty2` (Ctrl-Alt-F2).
|
||||
3. Execute:
|
||||
|
||||
sed -i -e 's/^options=.*/\0 efi=attr=uc/' /mnt/sysimage/boot/efi/EFI/qubes/xen.cfg
|
||||
|
||||
4. Go back to `tty6` (Ctrl-Alt-F6) and click `Reboot`.
|
||||
5. Continue with setting up default templates and logging in to Qubes.
|
||||
|
||||
Or if you have already rebooted after the first stage install and have encountered this issue, by:
|
||||
|
||||
1. Boot into [rescue mode](/doc/uefi-troubleshooting/#accessing-installer-rescue-mode-on-uefi).
|
||||
2. Execute:
|
||||
|
||||
sed -i -e 's/^options=.*/\0 efi=attr=uc/' /mnt/sysimage/boot/efi/EFI/qubes/xen.cfg
|
||||
|
||||
3. Type `reboot`.
|
||||
4. Continue with setting up default templates and logging in to Qubes.
|
||||
|
||||
|
||||
Boot device not recognized after installing
|
||||
------------------------------------------
|
||||
|
||||
Some firmware will not recognize the default Qubes EFI configuration.
|
||||
As such, it will have to be manually edited to be bootable.
|
||||
This will need to be done after every kernel and Xen update to ensure you use the most recently installed versions.
|
||||
|
||||
1. Copy the `/boot/efi/EFI/qubes/` directory to `/boot/efi/EFI/BOOT/` (the contents of `/boot/efi/EFI/BOOT` should be identical to `/boot/efi/EFI/qubes` besides what is described in steps 2 and 3):
|
||||
|
||||
cp -r /boot/efi/EFI/qubes/. /boot/efi/EFI/BOOT
|
||||
|
||||
2. Rename `/boot/efi/EFI/BOOT/xen.cfg` to `/boot/efi/EFI/BOOT/BOOTX64.cfg`:
|
||||
|
||||
mv /boot/efi/EFI/BOOT/xen.cfg /boot/efi/EFI/BOOT/BOOTX64.cfg
|
||||
|
||||
3. Copy `/boot/efi/EFI/qubes/xen-*.efi` to `/boot/efi/EFI/qubes/xen.efi` and `/boot/efi/EFI/BOOT/BOOTX64.efi`.
|
||||
For example, with Xen 4.8.3 (you may need to confirm file overwrite):
|
||||
|
||||
cp /boot/efi/EFI/qubes/xen-4.8.3.efi /boot/efi/EFI/qubes/xen.efi
|
||||
cp /boot/efi/EFI/qubes/xen-4.8.3.efi /boot/efi/EFI/BOOT/BOOTX64.efi
|
||||
|
||||
|
||||
Installation finished but "Qubes" boot option is missing and xen.cfg is empty
|
||||
--------------------------------------------------------------------------------------
|
||||
|
||||
In some cases installer fails to finish EFI setup and leave the system without a Qubes-specific EFI configuration.
|
||||
In such a case you need to finish those parts manually.
|
||||
You can do that just after installation (switch to `tty2` with Ctrl-Alt-F2), or by booting from installation media in [rescue mode](/doc/uefi-troubleshooting/#accessing-installer-rescue-mode-on-uefi).
|
||||
|
||||
1. Examine `/boot/efi/EFI/qubes` (if using Qubes installation media, it's in `/mnt/sysimage/boot/efi/EFI/qubes`). You should see 4 files there:
|
||||
|
||||
- xen.cfg (empty, size 0)
|
||||
- xen-(xen-version).efi
|
||||
- vmlinuz-(kernel-version)
|
||||
- initramfs-(kernel-version).img
|
||||
|
||||
2. Copy `xen-(xen-version).efi` to `xen.efi`:
|
||||
|
||||
cd /mnt/sysimage/boot/efi/EFI/qubes
|
||||
cp xen-*.efi xen.efi
|
||||
|
||||
3. Create xen.cfg with this content (adjust kernel version, and filesystem
|
||||
locations, below values are based on default installation of Qubes 3.2):
|
||||
|
||||
[global]
|
||||
default=4.4.14-11.pvops.qubes.x86_64
|
||||
|
||||
[4.4.14-11.pvops.qubes.x86_64]
|
||||
options=loglvl=all dom0_mem=min:1024M dom0_mem=max:4096M
|
||||
kernel=vmlinuz-4.4.14-11.pvops.qubes.x86_64 root=/dev/mapper/qubes_dom0-root rd.lvm.lv=qubes_dom0/root rd.lvm.lv=qubes_dom0/swap i915.preliminary_hw_support=1 rhgb quiet
|
||||
ramdisk=initramfs-4.4.14-11.pvops.qubes.x86_64.img
|
||||
|
||||
4. Create boot entry in EFI firmware (replace `/dev/sda` with your disk name and `-p 1` with `/boot/efi` partition number):
|
||||
|
||||
efibootmgr -v -c -u -L Qubes -l /EFI/qubes/xen.efi -d /dev/sda -p 1 "placeholder /mapbs /noexitboot"
|
||||
|
||||
|
||||
Accessing installer Rescue mode on UEFI
|
||||
---------------------------------------
|
||||
|
||||
In UEFI mode, the installer does not have a boot menu, but boots directly into the installation wizard.
|
||||
To get into Rescue mode, you need to switch to tty2 (Ctrl+Alt+F2) and then execute:
|
||||
|
||||
~~~
|
||||
pkill -9 anaconda
|
||||
anaconda --rescue
|
||||
~~~
|
||||
Loading…
Add table
Add a link
Reference in a new issue