Compare commits
18 Commits
fdd7df6ad8
...
4113865941
| Author | SHA1 | Date |
|---|---|---|
Piotr Bartman-Szwarc
|
4113865941 | |
unman
|
fe9d993a90 | |
|
unman
|
dc3f55a403 | |
|
unman
|
10811e675c | |
|
unman
|
3ed945c65a | |
|
unman
|
12d53886f0 | |
|
unman
|
72756af8fc | |
|
unman
|
2f701a7190 | |
Dr. Gerhard Weck
|
6df6dea5fd | |
Ludovic Bellier
|
661a2ca160 | |
Aidan Leuenberger
|
6fb630189f | |
Dmitry V. Levin
|
7a15cd1a16 | |
Dr. Gerhard Weck
|
387619a113 | |
Piotr Bartman
|
d074437e20 | |
Rafał Wojdyła
|
9da0acc630 | |
|
Rafał Wojdyła
|
e284f64909 | |
|
Rafał Wojdyła
|
875fc70ebf | |
Ben Grande
|
09ec281344 |
|
|
@ -14,7 +14,7 @@ title: Qubes builder details
|
|||
<div class="alert alert-warning" role="alert">
|
||||
<i class="fa fa-exclamation-circle"></i>
|
||||
<b>Note:</b> This information concerns the old Qubes builder (v1). It supports
|
||||
only building Qubes 4.1 or earlier.<br>The build process has been completely rewritten in <a href="https://github.com/QubesOS/qubes-builderv2/">qubes-builder v2</a>. This can be be used for building Qubes R4.1 and later, and all related components.</div>
|
||||
only building Qubes 4.1 or earlier.<br>The build process has been completely rewritten in <a href="https://github.com/QubesOS/qubes-builderv2/">qubes-builder v2</a>. This can be used for building Qubes R4.1 and later, and all related components.</div>
|
||||
|
||||
Components Makefile.builder file
|
||||
--------------------------------
|
||||
|
|
|
|||
|
|
@ -13,7 +13,7 @@ title: Qubes builder
|
|||
<div class="alert alert-warning" role="alert">
|
||||
<i class="fa fa-exclamation-circle"></i>
|
||||
<b>Note:</b> These instructions concern the older Qubes builder (v1). It supports
|
||||
only building Qubes 4.1 or earlier.<br>The build process has been completely rewritten in <a href="https://github.com/QubesOS/qubes-builderv2/">qubes-builder v2</a>. This can be be used for building Qubes R4.1 and later, and all related components.
|
||||
only building Qubes 4.1 or earlier.<br>The build process has been completely rewritten in <a href="https://github.com/QubesOS/qubes-builderv2/">qubes-builder v2</a>. This can be used for building Qubes R4.1 and later, and all related components.
|
||||
</div>
|
||||
|
||||
**Note: See [ISO building instructions](/doc/qubes-iso-building/) for a streamlined overview on how to use the build system.**
|
||||
|
|
|
|||
|
|
@ -15,7 +15,7 @@ title: Qubes ISO building
|
|||
<div class="alert alert-warning" role="alert">
|
||||
<i class="fa fa-exclamation-circle"></i>
|
||||
<b>Note:</b> These instructions concern the older Qubes builder (v1). It supports
|
||||
only building Qubes 4.1 or earlier.<br>The build process has been completely rewritten in <a href="https://github.com/QubesOS/qubes-builderv2/">qubes-builder v2</a>. This can be be used for building Qubes R4.1 and later, and all related components.
|
||||
only building Qubes 4.1 or earlier.<br>The build process has been completely rewritten in <a href="https://github.com/QubesOS/qubes-builderv2/">qubes-builder v2</a>. This can be used for building Qubes R4.1 and later, and all related components.
|
||||
</div>
|
||||
|
||||
Build Environment
|
||||
|
|
|
|||
|
|
@ -10,253 +10,80 @@ ref: 50
|
|||
title: Windows debugging
|
||||
---
|
||||
|
||||
Debugging Windows code can be tricky in a virtualized environment. The guide below assumes Xen hypervisor and Windows 7 VMs.
|
||||
Debugging Windows code can be tricky in a virtualized environment. The guide below assumes Qubes 4.2 and Windows 7 or later VMs.
|
||||
|
||||
User-mode debugging is usually straightforward if it can be done on one machine. Just duplicate your normal debugging environment in the VM.
|
||||
|
||||
Things get complicated if you need to perform kernel debugging or troubleshoot problems that only manifest on system boot, user logoff or similar. For that you need two Windows VMs: the *host* and the *target*. The *host* will contain [WinDbg](https://msdn.microsoft.com/en-us/library/windows/hardware/ff551063(v=vs.85).aspx) installation, your source code and private symbols. The *target* will run the code being debugged. Both will be linked by virtual serial ports.
|
||||
Things get complicated if you need to perform kernel debugging or troubleshoot problems that only manifest on system boot, user logoff or similar. For that you need two Windows VMs: the *host* and the *target*. The *host* will contain the debugger, your source code and private symbols. The *target* will run the code being debugged. We will use kernel debugging over network which is supported from Windows 7 onwards. The main caveat is that Windows kernel supports only specific network adapters for this, and the default one in Qubes won't work.
|
||||
|
||||
- First, you need to prepare separate copies of both *target* and *host* VM configuration files with some changes. Copy the files from **/var/lib/qubes/appvms/vmname/vmname.conf** to some convenient location, let's call them **host.conf** and **target.conf**.
|
||||
- In both copied files add the following line at the end: `serial = 'pty'`. This will make Xen connect VM's serial ports to dom0's ptys.
|
||||
- From now on you need to start both VMs like this: `qvm-start --custom-config=/your/edited/host.conf host`
|
||||
- To connect both VM serial ports together you will either need [socat](http://www.dest-unreach.org/socat/) or a custom utility described later.
|
||||
- To determine which dom0 pty corresponds to VM's serial port you need to read xenstore, example script below:
|
||||
## Important note
|
||||
|
||||
```bash
|
||||
#!/bin/sh
|
||||
- Do not install Xen network PV drivers in the target VM. Network kernel debugging needs a specific type of NIC or it won't work, the network PV drivers interfere with that.
|
||||
|
||||
id1=$(xl domid "$1-dm")
|
||||
tty1=$(xenstore-read /local/domain/${id1}/device/console/3/tty)
|
||||
echo $tty1
|
||||
```
|
||||
- If you have kernel debugging active when the Xen PV drivers are being installed, make sure to disable it before rebooting (`bcdedit /set debug off`). You can re-enable debugging after the reboot. The OS won't boot otherwise. I'm not sure what's the exact cause. I know that busparams for the debugging NIC change when PV drivers are installed (see later), but even changing that accordingly in the debug settings doesn't help -- so it's best to disable debug for this one reboot.
|
||||
|
||||
Pass it a running VM name and it will output the corresponding pty name.
|
||||
## Modifying the NIC of the target VM
|
||||
|
||||
- To connect both ptys you can use [socat](http://www.dest-unreach.org/socat/) like that:
|
||||
You will need to create a custom libvirt config for the target VM. See [the documentation](https://dev.qubes-os.org/projects/core-admin/en/latest/libvirt.html) for overview of how libvirt templates work in Qubes. The following assumes the target VM is named `target-vm`.
|
||||
|
||||
```bash
|
||||
#!/bin/sh
|
||||
- Edit `/usr/share/qubes/templates/libvirt/xen.xml` to prepare our custom config to override just the NIC part of the global template:
|
||||
- add `{% raw %}{% block network %}{% endraw %}` before `{% raw %}{% if vm.netvm %}{% endraw %}`
|
||||
- add `{% raw %}{% endblock %}{% endraw %}` after the matching `{% raw %}{% endif %}{% endraw %}`
|
||||
- Copy `/usr/share/qubes/templates/libvirt/devices/net.xml` to `/etc/qubes/templates/libvirt/xen/by-name/target-vm.xml`.
|
||||
- Add `<model type='e1000'/>` to the `<interface>` section.
|
||||
- Enclose everything within `{% raw %}{% block network %}{% endraw %}` + `{% raw %}{% endblock %}{% endraw %}`.
|
||||
- Add `{% raw %}{% extends 'libvirt/xen.xml' %}{% endraw %}` at the start.
|
||||
- The final `target-vm.xml` should look something like this:
|
||||
|
||||
id1=$(xl domid "$1-dm")
|
||||
id2=$(xl domid "$2-dm")
|
||||
tty1=$(xenstore-read /local/domain/${id1}/device/console/3/tty)
|
||||
tty2=$(xenstore-read /local/domain/${id2}/device/console/3/tty)
|
||||
socat $tty1,raw $tty2,raw
|
||||
```
|
||||
~~~
|
||||
{% raw %}
|
||||
{% extends 'libvirt/xen.xml' %}
|
||||
{% block network %}
|
||||
<interface type='ethernet'>
|
||||
<mac address="{{ vm.mac }}" />
|
||||
<ip address="{{ vm.ip }}" />
|
||||
<backenddomain name="{{ vm.netvm.name }}" />
|
||||
<script path='vif-route-qubes' />
|
||||
<model type='e1000' />
|
||||
</interface>
|
||||
{% endblock %}
|
||||
{% endraw %}
|
||||
~~~
|
||||
|
||||
...but there is a catch. Xen seems to process the traffic that goes through serial ports and changes all **0x0a** bytes into **0x0d, 0x0a** pairs (newline conversion). I didn't find a way to turn that off (setting ptys to raw mode didn't change anything) and it's not mentioned anywhere on the Internet, so maybe it's something on my system. If the above script works for you then you don't need anything more in dom0.
|
||||
- Start `target-vm` and verify in the device manager that a "Intel PRO/1000 MT" adapter is present.
|
||||
|
||||
- On the *target* system, run `bcdedit /set debug on` on the console to turn on kernel debugging. It defaults to the first serial port.
|
||||
- On the *host* system, install [WinDbg](https://msdn.microsoft.com/en-us/library/windows/hardware/ff551063(v=vs.85).aspx) and start the kernel debug (Ctrl-K), choose **com1** as the debug port.
|
||||
- Reboot the *target* VM.
|
||||
- Run the above shell script in dom0.
|
||||
- If everything is fine you should see the proper kernel debugging output in WinDbg. However, if you see something like that:
|
||||
## Host and target preparation
|
||||
|
||||
- On `host-vm` you will need WinDbg, which is a part of the [Windows SDK](https://developer.microsoft.com/en-us/windows/downloads/windows-sdk/).
|
||||
- Copy the `Debuggers` directory from Windows SDK to `target-vm`.
|
||||
- In both `host-vm` and `target-vm` switch the windows network to private (it tends to be public by default).
|
||||
- Either turn off the windows firewall or enable all ICMP-in rules in both VMs.
|
||||
- In `firewall-vm` edit `/rw/config/qubes-firewall-user-script` to connect both Windows VMs, add:
|
||||
- `iptables -I FORWARD 2 -s <target-vm-ip> -d <host-vm-ip> -j ACCEPT`
|
||||
- `iptables -I FORWARD 2 -s <host-vm-ip> -d <target-vm-ip> -j ACCEPT`
|
||||
- run `/rw/config/qubes-firewall-user-script` so the changes take effect immediately
|
||||
- Make sure both VMs can ping each other.
|
||||
- In `target-vm`:
|
||||
- start elevated `cmd` session
|
||||
- `cd sdk\Debuggers\x64`
|
||||
- `kdnet` should show that the NIC is supported, note the busparams:
|
||||
|
||||
~~~
|
||||
Network debugging is supported on the following NICs:
|
||||
busparams=0.6.0, Intel(R) PRO/1000 MT Network Connection, KDNET is running on this NIC.
|
||||
~~~
|
||||
|
||||
- `bcdedit /debug on`
|
||||
- `bcdedit /dbgsettings net hostip:<host-vm-ip> port:50000 key:1.1.1.1` (you can customize the key)
|
||||
- `bcdedit /set "{dbgsettings}" busparams x.y.z` (use the busparams `kdnet` has shown earlier)
|
||||
- In `host-vm` start WinDbg: `windbg -k net:port=50000,key=1.1.1.1`. It will listen for target's connection.
|
||||
- Reboot `target-vm`, debugging should start:
|
||||
|
||||
~~~
|
||||
Opened \\.\com1
|
||||
Waiting to reconnect...
|
||||
Connected to Windows 7 7601 x64 target at (Wed Mar 19 20:35:43.262 2014 (UTC + 1:00)), ptr64 TRUE
|
||||
Kernel Debugger connection established.
|
||||
Symbol search path is: srv*c:\symbols*https://msdl.microsoft.com/download/symbols
|
||||
Executable search path is:
|
||||
... Retry sending the same data packet for 64 times.
|
||||
The transport connection between host kernel debugger and target Windows seems lost.
|
||||
please try resync with target, recycle the host debugger, or reboot the target Windows.
|
||||
Unable to read KTHREAD address fffff8000281ccc0
|
||||
**************************************************************************
|
||||
Unable to read debugger data block header
|
||||
**************************************************************************
|
||||
Unable to read KTHREAD address fffff8000281ccc0
|
||||
Unable to read PsLoadedModuleList
|
||||
Unable to read KTHREAD address fffff8000281ccc0
|
||||
**************************************************************************
|
||||
Unable to read debugger data block header
|
||||
**************************************************************************
|
||||
Connected to target 10.137.0.19 on port 50000 on local IP 10.137.0.20.
|
||||
You can get the target MAC address by running .kdtargetmac command.
|
||||
Connected to Windows 10 19041 x64 target at (Thu Aug 3 14:05:48.069 2023 (UTC + 2:00)), ptr64 TRUE
|
||||
~~~
|
||||
|
||||
...then you're most likely a victim of the CRLF issue mentioned above. To get around it I wrote a small utility that basically does what socat would do and additionally corrects those replaced bytes in the stream. It's not pretty but it works:
|
||||
|
||||
```c
|
||||
#include <errno.h>
|
||||
#include <stdio.h>
|
||||
#include <fcntl.h>
|
||||
#include <termios.h>
|
||||
|
||||
int fd1, fd2;
|
||||
char mark = ' ';
|
||||
|
||||
void out(unsigned char c)
|
||||
{
|
||||
static int count = 0;
|
||||
static unsigned char buf[17] = {0};
|
||||
|
||||
// relay to ouptput port
|
||||
write(fd2, &c, 1);
|
||||
fprintf(stderr, "%c", mark);
|
||||
|
||||
/* dump all data going over the line
|
||||
if (count == 0)
|
||||
fprintf(stderr, "%c", mark);
|
||||
fprintf(stderr, "%02x ", c);
|
||||
if (c >= 0x20 && c < 0x80)
|
||||
buf[count] = c;
|
||||
else
|
||||
buf[count] = '.';
|
||||
count++;
|
||||
if (count == 0x10)
|
||||
{
|
||||
count = 0;
|
||||
fprintf(stderr, " %s\n", buf);
|
||||
}
|
||||
*/
|
||||
}
|
||||
|
||||
int main(int argc, char* argv[])
|
||||
{
|
||||
unsigned char c = 0;
|
||||
struct termios tio;
|
||||
ssize_t size;
|
||||
|
||||
if (argc < 3)
|
||||
{
|
||||
fprintf(stderr, "Usage: %s pty1 pty2 [mark character]\n", argv[0]);
|
||||
return EINVAL;
|
||||
}
|
||||
|
||||
fd1 = open(argv[1], O_RDONLY | O_NOCTTY);
|
||||
if (fd1 <= 0)
|
||||
{
|
||||
perror("open fd1");
|
||||
return errno;
|
||||
}
|
||||
fd2 = open(argv[2], O_WRONLY | O_NOCTTY);
|
||||
if (fd2 <= 0)
|
||||
{
|
||||
perror("open fd2");
|
||||
return errno;
|
||||
}
|
||||
/*
|
||||
// This doesn't make any difference which supports the theory
|
||||
// that it's Xen who corrupts the byte stream.
|
||||
cfmakeraw(&tio);
|
||||
if (tcsetattr(fd1, TCSANOW, &tio) < 0)
|
||||
{
|
||||
perror("tcsetattr 1");
|
||||
return errno;
|
||||
}
|
||||
if (tcsetattr(fd2, TCSANOW, &tio) < 0)
|
||||
{
|
||||
perror("tcsetattr 2");
|
||||
return errno;
|
||||
}
|
||||
*/
|
||||
if (argc == 4)
|
||||
mark = argv[3][0];
|
||||
|
||||
while (1)
|
||||
{
|
||||
size = read(fd1, &c, 1);
|
||||
if (size <= 0)
|
||||
break;
|
||||
|
||||
parse:
|
||||
if (c == 0x0d)
|
||||
{
|
||||
size = read(fd1, &c, 1);
|
||||
if (size <= 0)
|
||||
{
|
||||
out(0x0d);
|
||||
break;
|
||||
}
|
||||
if (c == 0x0a)
|
||||
{
|
||||
out(0x0a);
|
||||
}
|
||||
else
|
||||
{
|
||||
out(0x0d);
|
||||
goto parse;
|
||||
}
|
||||
}
|
||||
else
|
||||
out(c);
|
||||
}
|
||||
|
||||
close(fd1);
|
||||
close(fd2);
|
||||
return 0;
|
||||
}
|
||||
```
|
||||
|
||||
> This utility is a unidirectional relay so you need to run two instances to get duplex communication, like:
|
||||
>
|
||||
> #!/bin/sh
|
||||
>
|
||||
> id1=$(xl domid "$1-dm")
|
||||
> id2=$(xl domid "$2-dm")
|
||||
> tty1=$(xenstore-read /local/domain/${id1}/device/console/3/tty)
|
||||
> tty2=$(xenstore-read /local/domain/${id2}/device/console/3/tty)
|
||||
> ./ptycrlf ${tty1} ${tty2} - &
|
||||
> ./ptycrlf ${tty2} ${tty1} + &
|
||||
|
||||
> With this everything should be good:
|
||||
>
|
||||
> ~~~
|
||||
> Opened \\.\com1
|
||||
> Waiting to reconnect...
|
||||
> Connected to Windows 7 7601 x64 target at (Wed Mar 19 20:56:31.371 2014 (UTC + 1:00)), ptr64 TRUE
|
||||
> Kernel Debugger connection established.
|
||||
> Symbol search path is: srv*c:\symbols*https://msdl.microsoft.com/download/symbols
|
||||
> Executable search path is:
|
||||
> Windows 7 Kernel Version 7601 MP (1 procs) Free x64
|
||||
> Built by: 7601.18247.amd64fre.win7sp1_gdr.130828-1532
|
||||
> Machine Name:
|
||||
> Kernel base = 0xfffff800`0261a000 PsLoadedModuleList = 0xfffff800`0285d6d0
|
||||
> System Uptime: not available
|
||||
> ~~~
|
||||
|
||||
# Debugging HVMs in the Qubes R4.0
|
||||
|
||||
There are two main issues to be adopted to get all things to work in the R4.0.
|
||||
|
||||
## Add a virtual serial port
|
||||
|
||||
Qemu in the stub domain with virtual serial port added in a recommended way (```<serial type="pty"/>```) fails to start (Could not open '/dev/hvc1': No such device). It seems like a lack of multiple xen consoles support/configuration. The only way that I have found is to attach serial port explicitly to the available console.
|
||||
|
||||
1. Unpack stub domain in dom0:
|
||||
|
||||
```shell_session
|
||||
$ mkdir stubroot
|
||||
$ cp /usr/lib/xen/boot/stubdom-linux-rootfs stubroot/stubdom-linux-rootfs.gz
|
||||
$ cd stubroot
|
||||
$ gunzip stubdom-linux-rootfs.gz
|
||||
$ cpio -i -d -H newc --no-absolute-filenames < stubdom-linux-rootfs
|
||||
$ rm stubdom-linux-rootfs
|
||||
```
|
||||
|
||||
2. Edit Init script to remove last loop and to add "-serial /dev/hvc0" to the qemu command line.
|
||||
|
||||
3. Apply changes:
|
||||
|
||||
```shell_session
|
||||
$ find . -print0 | cpio --null -ov --format=newc | gzip -9 > ../stubdom-linux-rootfs
|
||||
$ sudo mv ../stubdom-linux-rootfs /usr/lib/xen/boot
|
||||
```
|
||||
|
||||
## Connect two consoles
|
||||
|
||||
Run the following script:
|
||||
|
||||
```shell
|
||||
debugname1=win7new
|
||||
debugname2=win7dbg
|
||||
id1=$(xl domid "$debugname1-dm")
|
||||
id2=$(xl domid "$debugname2-dm")
|
||||
|
||||
tty1=$(xenstore-read /local/domain/${id1}/console/tty)
|
||||
tty2=$(xenstore-read /local/domain/${id1}/console/tty)
|
||||
|
||||
socat $tty1,raw $tty2,raw
|
||||
```
|
||||
|
||||
Happy debugging!
|
||||
|
|
|
|||
|
|
@ -71,7 +71,7 @@ The review procedure is as follows:
|
|||
1. Someone, S, wishes to make a change to a package, P.
|
||||
2. S submits a fast-forwardable pull request against the fork of P's repo owned by [QubesOS-contrib](https://github.com/QubesOS-contrib).
|
||||
3. The PM reviews the pull request.
|
||||
If the the pull request passes the PM's review, the PM adds a [signed](/doc/code-signing/) *comment* on the pull request stating that it has passed review.
|
||||
If the pull request passes the PM's review, the PM adds a [signed](/doc/code-signing/) *comment* on the pull request stating that it has passed review.
|
||||
(In cases in which S = PM, the PM can simply add a [signed](/doc/code-signing/) *tag* to the HEAD commit prior to submitting the pull request.)
|
||||
If the pull request does not pass the PM's review, the PM leaves a comment on the pull request explaining why not.
|
||||
4. The QCR reviews the pull request.
|
||||
|
|
|
|||
|
|
@ -62,94 +62,98 @@ yet documented.
|
|||
The API should be implemented as a set of qrexec calls. This is to make it easy
|
||||
to set the policy using current mechanism.
|
||||
|
||||
| call | dest | argument | inside | return | note |
|
||||
| ------------------------------------- | --------- | --------- | ----------------------------------------- | --------------------------------------------------------- | ---- |
|
||||
| `admin.vmclass.List` | `dom0` | - | - | `<class>\n` |
|
||||
| `admin.vm.List` | `dom0|<vm>` | - | - | `<name> class=<class> state=<state>\n` |
|
||||
| `admin.vm.Create.<class>` | `dom0` | template | `name=<name> label=<label>` | - |
|
||||
| `admin.vm.CreateInPool.<class>` | `dom0` | template | `name=<name> label=<label> `<br/>`pool=<pool> pool:<volume>=<pool>` | - | either use `pool=` to put all volumes there, <br/>or `pool:<volume>=` for individual volumes - both forms are not allowed at the same time
|
||||
| `admin.vm.CreateDisposable` | template | - | - | name | Create new DisposableVM, `template` is any AppVM with `dispvm_allowed` set to True, or `dom0` to use default defined in `default_dispvm` property of calling VM; VM created with this call will be automatically removed after its shutdown; the main difference from `admin.vm.Create.DispVM` is automatic (random) name generation.
|
||||
| `admin.vm.Remove` | vm | - | - | - |
|
||||
| `admin.label.List` | `dom0` | - | - | `<property>\n` |
|
||||
| `admin.label.Create` | `dom0` | label | `0xRRGGBB` | - |
|
||||
| `admin.label.Get` | `dom0` | label | - | `0xRRGGBB` |
|
||||
| `admin.label.Index` | `dom0` | label | - | `<label-index>` |
|
||||
| `admin.label.Remove` | `dom0` | label | - | - |
|
||||
| `admin.property.List` | `dom0` | - | - | `<property>\n` |
|
||||
| `admin.property.Get` | `dom0` | property | - | `default={True|False} `<br/>`type={str|int|bool|vm|label|list} <value>` | Type `list` is added in R4.1. Values are of type `str` and each entry is suffixed with newline character.
|
||||
| `admin.property.GetAll` | `dom0` | - | - | `<property-name> <full-value-as-in-property.Get>\n` | Get all the properties in one call. Each property is returned on a separate line and use the same value encoding as property.Get method, with an exception that newlines are encoded as literal `\n` and literal `\` are encoded as `\\`.
|
||||
| `admin.property.GetDefault` | `dom0` | property | - | `type={str|int|bool|vm|label|list} <value>` | Type `list` is added in R4.1. Values are of type `str` and each entry is suffixed with newline character.
|
||||
| `admin.property.Help` | `dom0` | property | - | `help` |
|
||||
| `admin.property.HelpRst` | `dom0` | property | - | `help.rst` |
|
||||
| `admin.property.Reset` | `dom0` | property | - | - |
|
||||
| `admin.property.Set` | `dom0` | property | value | - |
|
||||
| `admin.vm.property.List` | vm | - | - | `<property>\n` |
|
||||
| `admin.vm.property.Get` | vm | property | - | `default={True|False} `<br/>`type={str|int|bool|vm|label|list} <value>` | Type `list` is added in R4.1. Each list entry is suffixed with a newline character.
|
||||
| `admin.vm.property.GetAll` | vm | - | - | `<property-name> <full-value-as-in-property.Get>\n` | Get all the properties in one call. Each property is returned on a separate line and use the same value encoding as property.Get method, with an exception that newlines are encoded as literal `\n` and literal `\` are encoded as `\\`.
|
||||
| `admin.vm.property.GetDefault` | vm | property | - | `type={str|int|bool|vm|label|type} <value>` | Type `list` is added in R4.1. Each list entry is suffixed with a newline character.
|
||||
| `admin.vm.property.Help` | vm | property | - | `help` |
|
||||
| `admin.vm.property.HelpRst` | vm | property | - | `help.rst` |
|
||||
| `admin.vm.property.Reset` | vm | property | - | - |
|
||||
| `admin.vm.property.Set` | vm | property | value | - |
|
||||
| `admin.vm.feature.List` | vm | - | - | `<feature>\n` |
|
||||
| `admin.vm.feature.Get` | vm | feature | - | value |
|
||||
| `admin.vm.feature.CheckWithTemplate` | vm | feature | - | value |
|
||||
| `admin.vm.feature.CheckWithNetvm` | vm | feature | - | value |
|
||||
| `admin.vm.feature.CheckWithAdminVM` | vm | feature | - | value |
|
||||
| `admin.vm.feature.CheckWithTemplateAndAdminVM`| vm | feature | - | value |
|
||||
| `admin.vm.feature.Remove` | vm | feature | - | - |
|
||||
| `admin.vm.feature.Set` | vm | feature | value | - |
|
||||
| `admin.vm.tag.List` | vm | - | - | `<tag>\n` |
|
||||
| `admin.vm.tag.Get` | vm | tag | - | `0` or `1` | retcode? |
|
||||
| `admin.vm.tag.Remove` | vm | tag | - | - |
|
||||
| `admin.vm.tag.Set` | vm | tag | - | - |
|
||||
| `admin.vm.firewall.Get` | vm | - | - | `<rule>\n` | rules syntax as in [firewall interface](/doc/vm-interface/#firewall-rules-in-4x) with addition of `expire=` and `comment=` options; `comment=` (if present) must be the last option
|
||||
| `admin.vm.firewall.Set` | vm | - | `<rule>\n` | - | set firewall rules, see `admin.vm.firewall.Get` for syntax
|
||||
| `admin.vm.firewall.Reload` | vm | - | - | - | force reload firewall without changing any rule
|
||||
| `admin.vm.device.<class>.Attach` | vm | device | options | - | `device` is in form `<backend-name>+<device-ident>` <br/>optional options given in `key=value` format, separated with spaces; <br/>options can include `persistent=True` to "persistently" attach the device (default is temporary)
|
||||
| `admin.vm.device.<class>.Detach` | vm | device | - | - | `device` is in form `<backend-name>+<device-ident>`
|
||||
| `admin.vm.device.<class>.Set.persistent`| vm | device | `True`\|`False` | - | `device` is in form `<backend-name>+<device-ident>`
|
||||
| `admin.vm.device.<class>.List` | vm | - | - | `<device> <options>\n` | options can include `persistent=True` for "persistently" attached devices (default is temporary)
|
||||
| `admin.vm.device.<class>.Available` | vm | device-ident | - | `<device-ident> <properties> description=<desc>\n` | optional service argument may be used to get info about a single device, <br/>optional (device class specific) properties are in `key=value` form, <br/>`description` must be the last one and is the only one allowed to contain spaces
|
||||
| `admin.pool.List` | `dom0` | - | - | `<pool>\n` |
|
||||
| `admin.pool.ListDrivers` | `dom0` | - | - | `<pool-driver> <property> ...\n` | Properties allowed in `admin.pool.Add`
|
||||
| `admin.pool.Info` | `dom0` | pool | - | `<property>=<value>\n` |
|
||||
| `admin.pool.Add` | `dom0` | driver | `<property>=<value>\n` | - |
|
||||
| `admin.pool.Set.revisions_to_keep` | `dom0` | pool | `<value>` | - |
|
||||
| `admin.pool.Remove` | `dom0` | pool | - | - |
|
||||
| `admin.pool.volume.List` | `dom0` | pool | - | volume id |
|
||||
| `admin.pool.volume.Info` | `dom0` | pool | vid | `<property>=<value>\n` |
|
||||
| `admin.pool.volume.Set.revisions_to_keep`| `dom0` | pool | `<vid> <value>` | - |
|
||||
| `admin.pool.volume.ListSnapshots` | `dom0` | pool | vid | `<snapshot>\n` |
|
||||
| `admin.pool.volume.Snapshot` | `dom0` | pool | vid | snapshot |
|
||||
| `admin.pool.volume.Revert` | `dom0` | pool | `<vid> <snapshot>` | - |
|
||||
| `admin.pool.volume.Resize` | `dom0` | pool | `<vid> <size_in_bytes>` | - |
|
||||
| `admin.pool.volume.Import` | `dom0` | pool | `<vid>\n<raw volume data>` | - |
|
||||
| `admin.pool.volume.CloneFrom` | `dom0` | pool | vid | token, to be used in `admin.pool.volume.CloneTo` | obtain a token to copy volume `vid` in `pool`;<br/>the token is one time use only, it's invalidated by `admin.pool.volume.CloneTo`, even if the operation fails |
|
||||
| `admin.pool.volume.CloneTo` | `dom0` | pool | `<vid> <token>` | - | copy volume pointed by a token to volume `vid` in `pool` |
|
||||
| `admin.vm.volume.List` | vm | - | - | `<volume>\n` | `<volume>` is per-VM volume name (`root`, `private`, etc), `<vid>` is pool-unique volume id
|
||||
| `admin.vm.volume.Info` | vm | volume | - | `<property>=<value>\n` |
|
||||
| `admin.vm.volume.Set.revisions_to_keep`| vm | volume | value | - |
|
||||
| `admin.vm.volume.ListSnapshots` | vm | volume | - | snapshot | duplicate of `admin.pool.volume.`, but with other call params |
|
||||
| `admin.vm.volume.Snapshot` | vm | volume | - | snapshot | id. |
|
||||
| `admin.vm.volume.Revert` | vm | volume | snapshot | - | id. |
|
||||
| `admin.vm.volume.Resize` | vm | volume | size_in_bytes | - | id. |
|
||||
| `admin.vm.volume.Import` | vm | volume | raw volume data | - | id. |
|
||||
| `admin.vm.volume.ImportWithSize` | vm | volume | `<size_in_bytes>\n<raw volume data>` | - | new version of `admin.vm.volume.Import`, allows new volume to be different size |
|
||||
| `admin.vm.volume.Clear` | vm | volume | - | - | clear contents of volume |
|
||||
| `admin.vm.volume.CloneFrom` | vm | volume | - | token, to be used in `admin.vm.volume.CloneTo` | obtain a token to copy `volume` of `vm`;<br/>the token is one time use only, it's invalidated by `admin.vm.volume.CloneTo`, even if the operation fails |
|
||||
| `admin.vm.volume.CloneTo` | vm | volume | token, obtained with `admin.vm.volume.CloneFrom` | - | copy volume pointed by a token to `volume` of `vm` |
|
||||
| `admin.vm.CurrentState` | vm | - | - | `<state-property>=<value>\n` | state properties: `power_state`, `mem`, `mem_static_max`, `cputime`
|
||||
| `admin.vm.Start` | vm | - | - | - |
|
||||
| `admin.vm.Shutdown` | vm | - | - | - |
|
||||
| `admin.vm.Pause` | vm | - | - | - |
|
||||
| `admin.vm.Unpause` | vm | - | - | - |
|
||||
| `admin.vm.Kill` | vm | - | - | - |
|
||||
| `admin.backup.Execute` | `dom0` | config id | - | - | config in `/etc/qubes/backup/<id>.conf`, only one backup operation of given `config id` can be running at once |
|
||||
| `admin.backup.Info` | `dom0` | config id | - | backup info | info what would be included in the backup
|
||||
| `admin.backup.Cancel` | `dom0` | config id | - | - | cancel running backup operation
|
||||
| `admin.Events` | `dom0|vm` | - | - | events |
|
||||
| `admin.vm.Stats` | `dom0|vm` | - | - | `vm-stats` events, see below | emit VM statistics (CPU, memory usage) in form of events
|
||||
| call | dest | argument | inside | return | note |
|
||||
|------------------------------------------------|------------|--------------|---------------------------------------------------------------------|-----------------------------------------------------| ---- |
|
||||
| `admin.vmclass.List` | `dom0` | - | - | `<class>\n` |
|
||||
| `admin.vm.List` | `dom0 | <vm>` | - | - | `<name> class=<class> state=<state>\n` |
|
||||
| `admin.vm.Create.<class>` | `dom0` | template | `name=<name> label=<label>` | - |
|
||||
| `admin.vm.CreateInPool.<class>` | `dom0` | template | `name=<name> label=<label> `<br/>`pool=<pool> pool:<volume>=<pool>` | - | either use `pool=` to put all volumes there, <br/>or `pool:<volume>=` for individual volumes - both forms are not allowed at the same time
|
||||
| `admin.vm.CreateDisposable` | template | - | - | name | Create new DisposableVM, `template` is any AppVM with `dispvm_allowed` set to True, or `dom0` to use default defined in `default_dispvm` property of calling VM; VM created with this call will be automatically removed after its shutdown; the main difference from `admin.vm.Create.DispVM` is automatic (random) name generation.
|
||||
| `admin.vm.Remove` | vm | - | - | - |
|
||||
| `admin.label.List` | `dom0` | - | - | `<property>\n` |
|
||||
| `admin.label.Create` | `dom0` | label | `0xRRGGBB` | - |
|
||||
| `admin.label.Get` | `dom0` | label | - | `0xRRGGBB` |
|
||||
| `admin.label.Index` | `dom0` | label | - | `<label-index>` |
|
||||
| `admin.label.Remove` | `dom0` | label | - | - |
|
||||
| `admin.property.List` | `dom0` | - | - | `<property>\n` |
|
||||
| `admin.property.Get` | `dom0` | property | - | `default={True |False} `<br/>`type={str|int|bool|vm|label|list} <value>` | Type `list` is added in R4.1. Values are of type `str` and each entry is suffixed with newline character.
|
||||
| `admin.property.GetAll` | `dom0` | - | - | `<property-name> <full-value-as-in-property.Get>\n` | Get all the properties in one call. Each property is returned on a separate line and use the same value encoding as property.Get method, with an exception that newlines are encoded as literal `\n` and literal `\` are encoded as `\\`.
|
||||
| `admin.property.GetDefault` | `dom0` | property | - | `type={str |int|bool|vm|label|list} <value>` | Type `list` is added in R4.1. Values are of type `str` and each entry is suffixed with newline character.
|
||||
| `admin.property.Help` | `dom0` | property | - | `help` |
|
||||
| `admin.property.HelpRst` | `dom0` | property | - | `help.rst` |
|
||||
| `admin.property.Reset` | `dom0` | property | - | - |
|
||||
| `admin.property.Set` | `dom0` | property | value | - |
|
||||
| `admin.vm.property.List` | vm | - | - | `<property>\n` |
|
||||
| `admin.vm.property.Get` | vm | property | - | `default={True |False} `<br/>`type={str|int|bool|vm|label|list} <value>` | Type `list` is added in R4.1. Each list entry is suffixed with a newline character.
|
||||
| `admin.vm.property.GetAll` | vm | - | - | `<property-name> <full-value-as-in-property.Get>\n` | Get all the properties in one call. Each property is returned on a separate line and use the same value encoding as property.Get method, with an exception that newlines are encoded as literal `\n` and literal `\` are encoded as `\\`.
|
||||
| `admin.vm.property.GetDefault` | vm | property | - | `type={str |int|bool|vm|label|type} <value>` | Type `list` is added in R4.1. Each list entry is suffixed with a newline character.
|
||||
| `admin.vm.property.Help` | vm | property | - | `help` |
|
||||
| `admin.vm.property.HelpRst` | vm | property | - | `help.rst` |
|
||||
| `admin.vm.property.Reset` | vm | property | - | - |
|
||||
| `admin.vm.property.Set` | vm | property | value | - |
|
||||
| `admin.vm.feature.List` | vm | - | - | `<feature>\n` |
|
||||
| `admin.vm.feature.Get` | vm | feature | - | value |
|
||||
| `admin.vm.feature.CheckWithTemplate` | vm | feature | - | value |
|
||||
| `admin.vm.feature.CheckWithNetvm` | vm | feature | - | value |
|
||||
| `admin.vm.feature.CheckWithAdminVM` | vm | feature | - | value |
|
||||
| `admin.vm.feature.CheckWithTemplateAndAdminVM` | vm | feature | - | value |
|
||||
| `admin.vm.feature.Remove` | vm | feature | - | - |
|
||||
| `admin.vm.feature.Set` | vm | feature | value | - |
|
||||
| `admin.vm.tag.List` | vm | - | - | `<tag>\n` |
|
||||
| `admin.vm.tag.Get` | vm | tag | - | `0` or `1` | retcode? |
|
||||
| `admin.vm.tag.Remove` | vm | tag | - | - |
|
||||
| `admin.vm.tag.Set` | vm | tag | - | - |
|
||||
| `admin.vm.firewall.Get` | vm | - | - | `<rule>\n` | rules syntax as in [firewall interface](/doc/vm-interface/#firewall-rules-in-4x) with addition of `expire=` and `comment=` options; `comment=` (if present) must be the last option
|
||||
| `admin.vm.firewall.Set` | vm | - | `<rule>\n` | - | set firewall rules, see `admin.vm.firewall.Get` for syntax
|
||||
| `admin.vm.firewall.Reload` | vm | - | - | - | force reload firewall without changing any rule
|
||||
| `admin.vm.device.<class>.Attach` | vm | device | assignment-serialization | - | `device` is in form `<backend-name>+<device-ident>` <br/>optional options given in `key=value` format, separated with spaces; <br/>options can include `persistent=True` to "persistently" attach the device (default is temporary)
|
||||
| `admin.vm.device.<class>.Detach` | vm | device | - | - | `device` is in form `<backend-name>+<device-ident>`.
|
||||
| `admin.vm.device.<class>.Assign` | vm | device | assignment-serialization | - | `device` is in form `<backend-name>+<device-ident>` <br/> `assignment-serialization` is specified in the section Device Serialization.
|
||||
| `admin.vm.device.<class>.Unassign` | vm | device | - | - | `device` is in form `<backend-name>+<device-ident>`.
|
||||
| `admin.vm.device.<class>.Set.required` | vm | device | `True`\|`False` | - | `device` is in form `<backend-name>+<device-ident>`
|
||||
| `admin.vm.deviceclass.List` | vm | - | - | `<deviceclass>\n` |
|
||||
| `admin.vm.device.<class>.Available` | vm | device-ident | - | `<device-ident> <device-serialization>\n` | optional service argument may be used to get info about a single device, <br/> `device-serialization` is specified in the section Device Serialization.
|
||||
| `admin.vm.device.<class>.Assigned` | vm | device-ident | - | `<device-ident> <assignment-serialization>\n` | optional service argument may be used to get info about a single device, <br/> `assignment-serialization` is specified in the section Device Serialization.
|
||||
| `admin.vm.device.<class>.Attached` | vm | device-ident | - | `<device-ident> <assignment-serialization>\n` | optional service argument may be used to get info about a single device, <br/> `assignment-serialization` is specified in the section Device Serialization.
|
||||
| `admin.pool.List` | `dom0` | - | - | `<pool>\n` |
|
||||
| `admin.pool.ListDrivers` | `dom0` | - | - | `<pool-driver> <property> ...\n` | Properties allowed in `admin.pool.Add`
|
||||
| `admin.pool.Info` | `dom0` | pool | - | `<property>=<value>\n` |
|
||||
| `admin.pool.Add` | `dom0` | driver | `<property>=<value>\n` | - |
|
||||
| `admin.pool.Set.revisions_to_keep` | `dom0` | pool | `<value>` | - |
|
||||
| `admin.pool.Remove` | `dom0` | pool | - | - |
|
||||
| `admin.pool.volume.List` | `dom0` | pool | - | volume id |
|
||||
| `admin.pool.volume.Info` | `dom0` | pool | vid | `<property>=<value>\n` |
|
||||
| `admin.pool.volume.Set.revisions_to_keep` | `dom0` | pool | `<vid> <value>` | - |
|
||||
| `admin.pool.volume.ListSnapshots` | `dom0` | pool | vid | `<snapshot>\n` |
|
||||
| `admin.pool.volume.Snapshot` | `dom0` | pool | vid | snapshot |
|
||||
| `admin.pool.volume.Revert` | `dom0` | pool | `<vid> <snapshot>` | - |
|
||||
| `admin.pool.volume.Resize` | `dom0` | pool | `<vid> <size_in_bytes>` | - |
|
||||
| `admin.pool.volume.Import` | `dom0` | pool | `<vid>\n<raw volume data>` | - |
|
||||
| `admin.pool.volume.CloneFrom` | `dom0` | pool | vid | token, to be used in `admin.pool.volume.CloneTo` | obtain a token to copy volume `vid` in `pool`;<br/>the token is one time use only, it's invalidated by `admin.pool.volume.CloneTo`, even if the operation fails |
|
||||
| `admin.pool.volume.CloneTo` | `dom0` | pool | `<vid> <token>` | - | copy volume pointed by a token to volume `vid` in `pool` |
|
||||
| `admin.vm.volume.List` | vm | - | - | `<volume>\n` | `<volume>` is per-VM volume name (`root`, `private`, etc), `<vid>` is pool-unique volume id
|
||||
| `admin.vm.volume.Info` | vm | volume | - | `<property>=<value>\n` |
|
||||
| `admin.vm.volume.Set.revisions_to_keep` | vm | volume | value | - |
|
||||
| `admin.vm.volume.ListSnapshots` | vm | volume | - | snapshot | duplicate of `admin.pool.volume.`, but with other call params |
|
||||
| `admin.vm.volume.Snapshot` | vm | volume | - | snapshot | id. |
|
||||
| `admin.vm.volume.Revert` | vm | volume | snapshot | - | id. |
|
||||
| `admin.vm.volume.Resize` | vm | volume | size_in_bytes | - | id. |
|
||||
| `admin.vm.volume.Import` | vm | volume | raw volume data | - | id. |
|
||||
| `admin.vm.volume.ImportWithSize` | vm | volume | `<size_in_bytes>\n<raw volume data>` | - | new version of `admin.vm.volume.Import`, allows new volume to be different size |
|
||||
| `admin.vm.volume.Clear` | vm | volume | - | - | clear contents of volume |
|
||||
| `admin.vm.volume.CloneFrom` | vm | volume | - | token, to be used in `admin.vm.volume.CloneTo` | obtain a token to copy `volume` of `vm`;<br/>the token is one time use only, it's invalidated by `admin.vm.volume.CloneTo`, even if the operation fails |
|
||||
| `admin.vm.volume.CloneTo` | vm | volume | token, obtained with `admin.vm.volume.CloneFrom` | - | copy volume pointed by a token to `volume` of `vm` |
|
||||
| `admin.vm.CurrentState` | vm | - | - | `<state-property>=<value>\n` | state properties: `power_state`, `mem`, `mem_static_max`, `cputime`
|
||||
| `admin.vm.Start` | vm | - | - | - |
|
||||
| `admin.vm.Shutdown` | vm | - | - | - |
|
||||
| `admin.vm.Pause` | vm | - | - | - |
|
||||
| `admin.vm.Unpause` | vm | - | - | - |
|
||||
| `admin.vm.Kill` | vm | - | - | - |
|
||||
| `admin.backup.Execute` | `dom0` | config id | - | - | config in `/etc/qubes/backup/<id>.conf`, only one backup operation of given `config id` can be running at once |
|
||||
| `admin.backup.Info` | `dom0` | config id | - | backup info | info what would be included in the backup
|
||||
| `admin.backup.Cancel` | `dom0` | config id | - | - | cancel running backup operation
|
||||
| `admin.Events` | `dom0 | vm` | - | - | events |
|
||||
| `admin.vm.Stats` | `dom0 | vm` | - | - | `vm-stats` events, see below | emit VM statistics (CPU, memory usage) in form of events
|
||||
|
||||
Volume properties:
|
||||
|
||||
|
|
@ -301,6 +305,58 @@ destination_vm: sys-net
|
|||
destination_path: ncftpput -u my-ftp-username -p my-ftp-pass -c my-ftp-server /directory/for/backups
|
||||
```
|
||||
|
||||
## Device Serialization
|
||||
|
||||
Both device and assignment serialization is ASCII-encoded and contains
|
||||
space-separated key-value pairs. The format includes an `=` between the key
|
||||
and value, and the value is always enclosed in single quotes (`'`).
|
||||
Values may contain spaces or even single quotes, which are escaped with a backslash.
|
||||
If a value is not set (`None`), it is represented as `'unknown'`.
|
||||
For boolean values, `True` is represented as `'yes'`, and `False` as `'no'`.
|
||||
The order of key-value pairs is irrelevant. Keys starting with `_`
|
||||
are considered extra properties and are saved in `data` or `options`
|
||||
for device or assignment respectively.
|
||||
|
||||
Information about the serialization format of specific properties can be found below.
|
||||
|
||||
Format:
|
||||
```
|
||||
<ident> <property_1>='<value_1>' <property_2>='<value_2>' <property_3>='<value_3>'...
|
||||
```
|
||||
|
||||
Detailed serialization format for a device:
|
||||
|
||||
- `ident='<ident>'`
|
||||
- `backend_domain='<backend_domain.name>'`
|
||||
- `devclass='<devclass>'`
|
||||
- `vendor='<vendor>'`
|
||||
- `product='<product>'`
|
||||
- `manufacturer='<manufacturer>'`
|
||||
- `name='<name>'`
|
||||
- `serial='<serial>'`
|
||||
- `self_identity='<self_identity>'`
|
||||
- `interfaces='<interface1><interface2>...'`
|
||||
Each device interface is represented with a 7-character length. Each device has at least one interface. Since the length of the interface representation is known, they are serialized as a single string with each interface representation concatenated one after another. The order is irrelevant.
|
||||
- `parent_ident='<parent.ident>' parent_devclass='<parent.devclass>'`
|
||||
- `attachment='<attachment.name>'`
|
||||
- `_<key1>='<value1>' _<key2>='<value2>' ...` (extra parameters)
|
||||
|
||||
Detailed serialization format for an assignment:
|
||||
|
||||
- `ident='<ident>'`
|
||||
- `backend_domain='<backend_domain.name>'`
|
||||
- `devclass='<devclass>'`
|
||||
- `frontend_domain='<frontend_domain.name>'`
|
||||
- `required='<yes/no>'` (default 'no')
|
||||
- `attach_automatically='<yes/no>'` (default 'no')
|
||||
- `_<key1>='<str(value1)>' _<key2>='<str(value2)>' ...` (options)
|
||||
|
||||
Example device serialization:
|
||||
|
||||
```
|
||||
1-1.1.1 manufacturer='unknown' self_identity='0000:0000::?******' serial='unknown' ident='1-1.1.1' product='Qubes' vendor='ITL' name='Some untrusted garbage' devclass='bus' backend_domain='vm' interfaces=' ******u03**01' _additional_info='' _date='06.12.23' parent_ident='1-1.1' parent_devclass='None'
|
||||
```
|
||||
|
||||
## General notes
|
||||
|
||||
- there is no provision for `qvm-run`, but there already exists `qubes.VMShell` call
|
||||
|
|
|
|||
|
|
@ -251,6 +251,6 @@ It is a [socket-based Qubes RPC service](/doc/qrexec-socket-services/). Requests
|
|||
There are two endpoints:
|
||||
|
||||
- `policy.Ask` - ask the user about whether to execute a given action
|
||||
- `policy.Notify` - notify the user about about an action.
|
||||
- `policy.Notify` - notify the user about an action.
|
||||
|
||||
See [qrexec-policy-agent.rst](https://github.com/QubesOS/qubes-core-qrexec/blob/master/Documentation/qrexec-policy-agent.rst) for protocol details.
|
||||
|
|
|
|||
|
|
@ -49,7 +49,7 @@ In the case of Qubes, `qubes-gui` does not transfer all changed pixels via vchan
|
|||
and pass this to dom0 via the deprecated `MFNDUMP` message.
|
||||
- New `qubes-gui` versions will rely on `qubes-drv` having allocated
|
||||
memory using gntalloc, and then pass the grant table indexes gntalloc
|
||||
has chosen to the GUI daemon using using the `WINDOW_DUMP` message.
|
||||
has chosen to the GUI daemon using the `WINDOW_DUMP` message.
|
||||
|
||||
Now, `qubes-guid` has to tell the dom0 Xorg server about the location of the buffer.
|
||||
There is no supported way (e.g. Xorg extension) to do this zero-copy style.
|
||||
|
|
|
|||
|
|
@ -67,7 +67,7 @@ There are three issue **types**: `T: bug`, `T: enhancement`, and `T: task`.
|
|||
- `T: enhancement` --- Type: enhancement. A new feature that does not yet exist **or** improvement of existing functionality.
|
||||
- `T: task` --- Type: task. An action item that is neither a bug nor an enhancement.
|
||||
|
||||
Every open issue should have **exactly one** type. An open issue should not have more than one type, and it should not lack a type entirely. Bug reports are for problems in things that already exist. If something doesn't exist yet, but you think it ought to exist, then use `T: enhancement` instead. If something already exists, but you think it could be improved in some way, you should again use `T: enhancement`. `T: task` is for issues that fall under under neither `T: bug` nor `T: enhancement`.
|
||||
Every open issue should have **exactly one** type. An open issue should not have more than one type, and it should not lack a type entirely. Bug reports are for problems in things that already exist. If something doesn't exist yet, but you think it ought to exist, then use `T: enhancement` instead. If something already exists, but you think it could be improved in some way, you should again use `T: enhancement`. `T: task` is for issues that fall under neither `T: bug` nor `T: enhancement`.
|
||||
|
||||
#### Priority
|
||||
|
||||
|
|
|
|||
|
|
@ -419,7 +419,7 @@ account is **not** required. Any email address will work.) To post a message to
|
|||
the list, address your email to `qubes-project@googlegroups.com`. If your post
|
||||
does not appear immediately, please allow time for moderation to occur. To
|
||||
unsubscribe, send a blank email to
|
||||
`qubes-project+unsubscribe@googlegroups.com`. This list also also has a
|
||||
`qubes-project+unsubscribe@googlegroups.com`. This list also has a
|
||||
[traditional mail
|
||||
archive](https://www.mail-archive.com/qubes-project@googlegroups.com/) and an
|
||||
optional [Google Groups web
|
||||
|
|
|
|||
|
|
@ -60,7 +60,7 @@ In this example, we want to make `/var/lib/tor` persistent. Enter all of the fol
|
|||
|
||||
From now on, all files in the `/var/lib/tor` directory will persist across reboots.
|
||||
|
||||
You can make make as many files or folders persist as you want simply by making multiple entries in the `50_user.conf` file, each on a separate line.
|
||||
You can make as many files or folders persist as you want simply by making multiple entries in the `50_user.conf` file, each on a separate line.
|
||||
For example, if you added the file `/etc/tor/torrc` to the `binds` variable, any modifications to *that* file would also persist across reboots.
|
||||
|
||||
```
|
||||
|
|
|
|||
|
|
@ -27,7 +27,7 @@ Additionally, if you want to have menu entries for starting applications in disp
|
|||
[user@dom0 ~]$ qvm-features <DISPOSABLE_TEMPLATE> appmenus-dispvm 1
|
||||
```
|
||||
|
||||
**Note:** Application shortcuts that existed before setting this feature will not be updated automatically. Please go the the "Applications" tab in the qube's "Settings" dialog and unselect all existing shortcuts by clicking "<<", then click "OK" and close the dialog. Give it a few seconds time and then reopen and re-select all the shortcuts you want to see in the menu. See [this page](/doc/managing-appvm-shortcuts) for background information.
|
||||
**Note:** Application shortcuts that existed before setting this feature will not be updated automatically. Please go the "Applications" tab in the qube's "Settings" dialog and unselect all existing shortcuts by clicking "<<", then click "OK" and close the dialog. Give it a few seconds time and then reopen and re-select all the shortcuts you want to see in the menu. See [this page](/doc/managing-appvm-shortcuts) for background information.
|
||||
|
||||
## Security
|
||||
|
||||
|
|
|
|||
|
|
@ -197,7 +197,7 @@ you would install it into a normal HVM. Generally, you should install in to the
|
|||
first "system" disk. (Resize it as needed before starting installation.)
|
||||
|
||||
You can then create a new qube using the new template. If you use this Template
|
||||
as is, then any HVMs based on it it will effectively be disposables. All file
|
||||
as is, then any HVMs based on it will effectively be disposables. All file
|
||||
system changes will be wiped when the HVM is shut down.
|
||||
|
||||
Please see [this
|
||||
|
|
|
|||
|
|
@ -42,7 +42,7 @@ qvm-volume config vmname:private revisions_to_keep 2
|
|||
```
|
||||
|
||||
With the VM stopped, you may revert to an older snapshot of the private volume
|
||||
from the the above list of "Available revisions (for revert)", where the last
|
||||
from the above list of "Available revisions (for revert)", where the last
|
||||
item on the list with the largest integer is the most recent snapshot:
|
||||
|
||||
```
|
||||
|
|
|
|||
|
|
@ -118,7 +118,7 @@ From here, you can navigate the boot screen using the arrow keys on your keyboar
|
|||
* Install Qubes OS
|
||||
* Test this media and install Qubes OS
|
||||
* Troubleshooting - verbose boot
|
||||
* Rescue a Qubes SO system
|
||||
* Rescue a Qubes OS system
|
||||
* Install Qubes OS 4.2.1 using kernel-latest
|
||||
|
||||
Select the option to test this media and install Qubes OS.
|
||||
|
|
|
|||
|
|
@ -86,7 +86,7 @@ If you are a hardware vendor, you can have your hardware certified as compatible
|
|||
|
||||
**Note:** This section describes the requirements for hardware *certification*, *not* the requirements for *running* Qubes OS. For the latter, please see the [system requirements](/doc/system-requirements/). A brief list of the requirements described in this section is available [here](/doc/system-requirements/#qubes-certified-hardware).
|
||||
|
||||
A basic requirement is that all Qubes-certified devices must be be available for purchase with Qubes OS preinstalled. Customers may be offered the option to select from a list of various operating systems (or no operating system at all) to be preinstalled, but Qubes OS must be on that list in order to maintain Qubes hardware certification.
|
||||
A basic requirement is that all Qubes-certified devices must be available for purchase with Qubes OS preinstalled. Customers may be offered the option to select from a list of various operating systems (or no operating system at all) to be preinstalled, but Qubes OS must be on that list in order to maintain Qubes hardware certification.
|
||||
|
||||
One of the most important security improvements introduced with the release of Qubes 4.0 was to replace paravirtualization (PV) technology with **hardware-enforced memory virtualization**, which recent processors have made possible thanks to so-called Second Level Address Translation ([SLAT](https://en.wikipedia.org/wiki/Second_Level_Address_Translation)), also known as [EPT](https://ark.intel.com/Search/FeatureFilter?productType=processors&ExtendedPageTables=true&MarketSegment=Mobile) in Intel parlance. SLAT (EPT) is an extension to Intel VT-x virtualization, which originally was capable of only CPU virtualization but not memory virtualization and hence required a complex Shadow Page Tables approach. We hope that embracing SLAT-based memory virtualization will allow us to prevent disastrous security bugs, such as the infamous [XSA-148](https://xenbits.xen.org/xsa/advisory-148.html), which --- unlike many other major Xen bugs --- regrettably did [affect](https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-022-2015.txt) Qubes OS. Consequently, we require SLAT support of all certified hardware beginning with Qubes OS 4.0.
|
||||
|
||||
|
|
|
|||
|
|
@ -425,6 +425,64 @@ templates and even her Bitcoin full node qube, but she'll skip them if she
|
|||
doesn't have time or space, since she knows she can always recreate them again
|
||||
later and download what she needs from the Internet.
|
||||
|
||||
## John, the teacher
|
||||
|
||||
John is a teacher at a high school, teaching mathematics and history. He is used
|
||||
to setting up his workstation but has not the time or inclination to dive deeper
|
||||
into technical details. So he has installed Qubes in a rather simple way mainly
|
||||
using the installation defaults and just adding a few well-documented features
|
||||
like Split GPG.
|
||||
|
||||
[](/attachment/doc/Simple_Setup.png)
|
||||
|
||||
- **One qube for surfing.** `untrusted` is just the standard qube coming with the Qubes
|
||||
installation, based on the standard Fedora template, but with Thunderbird removed.
|
||||
It is intended for surfing arbitrary locations and may be at risk from some websites.
|
||||
Consequently, it does not keep any valuable data and has no facilities to view or
|
||||
edit office documents.
|
||||
|
||||
- **One offline qube for writing.** `work` is the qube used to edit documents – even
|
||||
MS office documents. It is based on an extended Fedora template containing additional
|
||||
software like LibreOffice, GIMP, Wine, and some Windows applications. It has no netVM
|
||||
and so the risk of an infected document contacting a hacker’s control server is minimized.
|
||||
|
||||
- **One qube for access to trusted servers.** `personal` is used to access only trusted
|
||||
websites like home banking, and the firewall rules for this qube restrict it to these
|
||||
locations. It is based on the same extended Fedora template. John uses this qube for
|
||||
access to his mail server, too, but does not process any documents received by mail
|
||||
in this qube. Any office documents from this qube are only opened in disposables in order
|
||||
to reduce the risk of infection.
|
||||
|
||||
- **One qube for preparing teaching material for his students.** `Windows` is the workhorse
|
||||
used to execute anything needed for teaching. It is based on a Windows 7 template with QWT
|
||||
installed as most of John’s students work with Windows PCs. In order to reduce the risks
|
||||
for such an AppVM, and possible risks caused by it, its internet access is limited, again
|
||||
by a firewall rule, to the servers providing material for teaching.
|
||||
|
||||
- **One qube for protected access to sensible websites.** `whonix` is just the standard
|
||||
AppVM `anon-whonix` based on the `whonix-ws` coming with the Qubes installation. It is
|
||||
used for all accesses over Tor and could as well be replaced by a disposable. John, who is
|
||||
engaged in a project for helping mentally disabled people, uses this qube to avoid tracking
|
||||
his access to the project’s server.
|
||||
|
||||
- **One offline qube for keeping the private PGP key.** `vault` is the key part of Split GPG,
|
||||
just as described in the Qubes documentation, keeping the private PGP key.
|
||||
|
||||
- **One offline qube for permanent data storage.** `storage` finally is a qube based on the
|
||||
standard Debian template and, having no applications and no network access, it is used
|
||||
explicitly and only for permanent data storage, and it is the only qube whose data is regarded
|
||||
as valuable and worth keeping. The Fedora-based qubes might even be configured as disposables, and,
|
||||
if you are willing to accept the rather slow start of Windows, even the qube `Windows` might be
|
||||
created as a disposable.
|
||||
|
||||
This is a rather simplistic design, intended to show that with a minimum effort a decent level
|
||||
of security can be reached, and it is a first implementation showing how John can compartmentalize
|
||||
his digital life, as described in the Qubes documentation. Once the templates are set up with
|
||||
the necessary software like LibreOffice and
|
||||
Split GPG is installed, setting up this structure takes only a few minutes, but it is much more
|
||||
secure than, for instance, a Windows 10 installation based on the available hardening studies,
|
||||
which are quite useless for a practical environment, especially for a user like John.
|
||||
|
||||
|
||||
## Conclusion
|
||||
|
||||
|
|
|
|||
|
|
@ -122,7 +122,7 @@ If you don't see anything that looks like your drive, run `sudo udevadm trigger
|
|||
|
||||
## Recovering From Premature Device Destruction
|
||||
|
||||
If the you fail to detach the device before it's destroyed in the sourceVM (e.g. by physically detaching the thumbdrive), [there will be problems](https://github.com/QubesOS/qubes-issues/issues/1082).
|
||||
If you fail to detach the device before it's destroyed in the sourceVM (e.g. by physically detaching the thumbdrive), [there will be problems](https://github.com/QubesOS/qubes-issues/issues/1082).
|
||||
|
||||
To recover from this error state, in dom0 run
|
||||
|
||||
|
|
|
|||
|
|
@ -284,7 +284,7 @@ Note the IP addresses you will need, they will be required in the next steps.
|
|||
|
||||
For the following example, we assume that the physical interface ens6 in sys-net is on the local network 192.168.x.y with the IP 192.168.x.n, and that the IP address of sys-firewall is 10.137.1.z.
|
||||
|
||||
In the sys-net VM's Terminal, the first step is to to define an ntables chain that will receive DNAT rules to relay the network traffic on a given port to the qube NetVM, we recommend to define a new chain for each destination qube to ease rules management:
|
||||
In the sys-net VM's Terminal, the first step is to define an ntables chain that will receive DNAT rules to relay the network traffic on a given port to the qube NetVM, we recommend to define a new chain for each destination qube to ease rules management:
|
||||
|
||||
```
|
||||
nft add chain qubes custom-dnat-qubeDEST '{ type nat hook prerouting priority filter +1 ; policy accept; }'
|
||||
|
|
|
|||
|
|
@ -140,10 +140,10 @@ work-email work-gpg allow
|
|||
|
||||
where `work-email` is the Thunderbird + Enigmail app qube and `work-gpg` contains your GPG keys.
|
||||
|
||||
You may also edit the qrexec policy file for Split GPG in order to tell Qubes your default gpg vm (qrexec prompts will appear with the gpg vm preselected as the target, instead of the user needing to type a name in manually). To do this, append `,default_target=<vmname>` to `ask` in `/etc/qubes-rpc/policy/qubes.Gpg`. For the examples given on this page:
|
||||
You may also edit the qrexec policy file for Split GPG in order to tell Qubes your default gpg vm (qrexec prompts will appear with the gpg vm preselected as the target, instead of the user needing to type a name in manually). To do this, append `default_target=<vmname>` to `ask` in `/etc/qubes-rpc/policy/qubes.Gpg`. For the examples given on this page:
|
||||
|
||||
```
|
||||
@anyvm @anyvm ask,default_target=work-gpg
|
||||
@anyvm @anyvm ask default_target=work-gpg
|
||||
```
|
||||
|
||||
Note that, because this makes it easier to accept Split GPG's qrexec authorization prompts, it may decrease security if the user is not careful in reviewing presented prompts. This may also be inadvisable if there are multiple app qubes with Split GPG set up.
|
||||
|
|
|
|||
|
|
@ -244,6 +244,7 @@ list of packages to be installed):
|
|||
if you want to use it as the `UpdateVM` (which is normally `sys-firewall`).
|
||||
- NetVM, such as the template for `sys-net`: `qubes-core-agent-networking`,
|
||||
`qubes-core-agent-network-manager`, `ntpd` (or other NTP Service).
|
||||
Wi-Fi also requires `wpasupplicant`, and (optionally) `gnome-keyring` for saving the Wi-Fi password.
|
||||
If your network devices need extra packages for a network VM, use the `lspci` command to identify the devices,
|
||||
then find the package that provides necessary firmware and install it. If you
|
||||
need utilities for debugging and analyzing network connections, install the
|
||||
|
|
|
|||
|
|
@ -26,7 +26,7 @@ Qubes Windows Tools (QWT) are a set of programs and drivers that provide integra
|
|||
- **Audio** - Audio support is available even without QWT installation if `qvm-features audio-model` is set as `ich6`
|
||||
|
||||
|
||||
**Note:** Due to the security problems described in [QSB-091](https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-091-2023.txt), installation of Qubes Windows Tools is currently blocked. Instead, a text file containing a warning is displayed. Currently, it is difficult to estimate the severity of the risks posed by the sources of the Xen drivers used in QWT possibly being compromised, so it was decided not to offer direct QWT installation until this problem could be treated properly. While Windows qubes are, in Qubes, generally not regarded as being very trustworthy, a possible compromise of the Xen drivers used in Qubes Windows Tools might create a risk for Xen or dom0 and thus be dangerous for Qubes itself. If you **understand** this risk and are **willing to take it**, you can still install the previous versions of Qubes Windows Tools, using the command
|
||||
**Note:** Due to the security problems described in [QSB-091](https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-091-2023.txt), installation of Qubes Windows Tools is currently blocked. Instead, a text file containing a warning is displayed. Currently, it is difficult to estimate the severity of the risks posed by the sources of the Xen drivers used in QWT possibly being compromised, so it was decided not to offer direct QWT installation until this problem could be treated properly. While Windows qubes are, in Qubes, generally not regarded as being very trustworthy, a possible compromise of the Xen drivers used in Qubes Windows Tools might create a risk for Xen or `dom0` and thus be dangerous for Qubes itself. This risk may be small or even non-existent, as stated in QSB-091. If you **understand** this risk and are **willing to take it**, you can still install the previous versions of Qubes Windows Tools, using the command
|
||||
|
||||
sudo qubes-dom0-update qubes-windows-tools-4.1.68
|
||||
|
||||
|
|
@ -34,9 +34,9 @@ for Qubes R4.1.2, or
|
|||
|
||||
sudo qubes-dom0-update qubes-windows-tools-4.1.69
|
||||
|
||||
for Qubes R4.2.0, respectively, instead of the command listed in step 1 of the installation described below. This will provide the .iso file to be presented as installation drive to the Windows qube in step 3 of the QWT installation.
|
||||
for Qubes R4.2.0, respectively, instead of the command listed in step 1 of the installation described below. This will provide the .iso file to be presented as an installation drive to the Windows qube in step 3 of the QWT installation.
|
||||
|
||||
If you prefer to download the corresponding .rpm files for manual QWT installation, these are still available from the repositories (version [4.1.68-1](https://yum.qubes-os.org/r4.1/current/dom0/fc32/rpm/qubes-windows-tools-4.1.68-1.noarch.rpm) for Qubes R4.1.2 and version [4.1.69-1](https://yum.qubes-os.org/r4.2/current/dom0/fc37/rpm/qubes-windows-tools-4.1.69-1.fc37.noarch.rpm) for Qubes R4.2.0).
|
||||
If you prefer to download the corresponding .rpm files for manual QWT installation, these are still available from the repositories (version [4.1.68-1](https://yum.qubes-os.org/r4.1/current/dom0/fc32/rpm/qubes-windows-tools-4.1.68-1.noarch.rpm) for Qubes R4.1.2 and version [4.1.69-1](https://yum.qubes-os.org/r4.2/current/dom0/fc37/rpm/qubes-windows-tools-4.1.69-1.fc37.noarch.rpm) for Qubes R4.2.0). After downloading, copy the file to `dom0` as described in [How to copy from dom0](https://www.qubes-os.org/doc/how-to-copy-from-dom0/#copying-to-dom0) and install it via `sudo dnf install /path/to/rpmfile`. Now you can proceed according to step 3 of the description below.
|
||||
|
||||
**Warning**: These older versions of Qubes Windows Tools will be replaced during the next dom0 update by the current dummy version 4.1.70-1. This can be inhibited by appending the line `exclude=qubes-windows-tools` to the file `/etc/dnf/dnf.conf` in dom0. But this will also stop any further QWT updates - so be sure to remove this line when - hopefully - a new functional version 4.1.71-1 of Qubes Windows Tools will be made available!!!
|
||||
|
||||
|
|
|
|||
|
|
@ -104,7 +104,7 @@ While using the `no-strict-reset` flag, do not require PCI device to be reset be
|
|||
qvm-pci attach --persistent --option permissive=true --option no-strict-reset=true sys-usb dom0:<BDF_OF_DEVICE>
|
||||
~~~
|
||||
|
||||
Be sure to replace `<BDF_OF_DEVICE>` with the BDF of your PCI device, which can be be obtained from running `qvm-pci`.
|
||||
Be sure to replace `<BDF_OF_DEVICE>` with the BDF of your PCI device, which can be obtained from running `qvm-pci`.
|
||||
|
||||
You can also configure strict reset directly from the Qubes interface by following these steps:
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue