mirror of
https://github.com/QubesOS/qubes-doc.git
synced 2025-06-21 21:24:28 -04:00
Markdown formatting fixes
- mark all code blocks with ``` - unify empty lines between sections - adjust list syntax (no space before dash) - adjust headers to use Atx-style syntax - remove trailing spaces
This commit is contained in:
Maya
Marek Marczykowski-Górecki
parent
2bde7d07e0
commit
67a92614aa
148 changed files with 4025 additions and 3639 deletions
|
|
@ -7,14 +7,12 @@ redirect_from:
|
|||
- /doc/AutomatedTests/
|
||||
---
|
||||
|
||||
Automated Tests
|
||||
===============
|
||||
# Automated Tests
|
||||
|
||||
Unit and Integration Tests
|
||||
--------------------------
|
||||
## Unit and Integration Tests
|
||||
|
||||
Starting with Qubes R3 we use [python unittest][unittest] to perform automatic tests of Qubes OS.
|
||||
Despite the name, we use it for both [unit tests](https://en.wikipedia.org/wiki/Unit_tests) and [integration tests](https://en.wikipedia.org/wiki/Integration_tests).
|
||||
Starting with Qubes R3 we use [python unittest][unittest] to perform automatic tests of Qubes OS.
|
||||
Despite the name, we use it for both [unit tests](https://en.wikipedia.org/wiki/Unit_tests) and [integration tests](https://en.wikipedia.org/wiki/Integration_tests).
|
||||
The main purpose is, of course, to deliver much more stable releases.
|
||||
|
||||
The integration tests must be run in dom0, but some unit tests can run inside a VM as well.
|
||||
|
|
@ -46,6 +44,7 @@ Our test runner runs mostly the same as the standard one, but it has some nice a
|
|||
|
||||
You can use `python3 -m qubes.tests.run -h` to get usage information:
|
||||
|
||||
```
|
||||
[user@dom0 ~]$ python3 -m qubes.tests.run -h
|
||||
usage: run.py [-h] [--verbose] [--quiet] [--list] [--failfast] [--no-failfast]
|
||||
[--do-not-clean] [--do-clean] [--loglevel LEVEL]
|
||||
|
|
@ -83,9 +82,11 @@ You can use `python3 -m qubes.tests.run -h` to get usage information:
|
|||
When running only specific tests, write their names like in log, in format:
|
||||
MODULE+"/"+CLASS+"/"+FUNCTION. MODULE should omit initial "qubes.tests.".
|
||||
Example: basic/TC_00_Basic/test_000_create
|
||||
```
|
||||
|
||||
For instance, to run only the tests for the fedora-21 template, you can use the `-l` option, then filter the list:
|
||||
|
||||
```
|
||||
[user@dom0 ~]$ python3 -m qubes.tests.run -l | grep fedora-21
|
||||
network/VmNetworking_fedora-21/test_000_simple_networking
|
||||
network/VmNetworking_fedora-21/test_010_simple_proxyvm
|
||||
|
|
@ -108,6 +109,7 @@ For instance, to run only the tests for the fedora-21 template, you can use the
|
|||
vm_qrexec_gui/TC_20_DispVM_fedora-21/test_020_gui_app
|
||||
vm_qrexec_gui/TC_20_DispVM_fedora-21/test_030_edit_file
|
||||
[user@dom0 ~]$ sudo -E python3 -m qubes.tests.run -v `python3 -m qubes.tests.run -l | grep fedora-21`
|
||||
```
|
||||
|
||||
Example test run:
|
||||
|
||||
|
|
@ -115,11 +117,12 @@ Example test run:
|
|||
|
||||
Tests are also compatible with nose2 test runner, so you can use this instead:
|
||||
|
||||
```bash
|
||||
sudo systemctl stop qubesd; sudo -E nose2 -v --plugin nose2.plugins.loader.loadtests qubes.tests; sudo systemctl start qubesd
|
||||
```
|
||||
|
||||
This may be especially useful together with various nose2 plugins to store tests results (for example `nose2.plugins.junitxml`), to ease presenting results. This is what we use on [OpenQA].
|
||||
|
||||
|
||||
### Unit testing inside a VM
|
||||
|
||||
Many unit tests will also work inside a VM. However all of the tests requiring a dedicated VM to be run (mostly the integration tests) will be skipped.
|
||||
|
|
@ -132,6 +135,7 @@ its dependency [qubes-core-qrexec](https://github.com/QubesOS/qubes-core-qrexec)
|
|||
The below example however will assume that you set up a build environment as described in the [Qubes Builder documentation](/doc/qubes-builder/).
|
||||
|
||||
Assuming you cloned the `qubes-builder` repository to your home directory inside a fedora VM, you can use the following commands to run the unit tests:
|
||||
|
||||
```{.bash}
|
||||
cd ~
|
||||
sudo dnf install python3-pip lvm2 python35 python3-virtualenv
|
||||
|
|
@ -158,16 +162,17 @@ the current stable branch.
|
|||
|
||||
Test runs can be altered using environment variables:
|
||||
|
||||
- `DEFAULT_LVM_POOL` - LVM thin pool to use for tests, in `VolumeGroup/ThinPool` format
|
||||
- `QUBES_TEST_PCIDEV` - PCI device to be used in PCI passthrough tests (for example sound card)
|
||||
- `QUBES_TEST_TEMPLATES` - space separated list of templates to run tests on; if not set, all installed templates are tested
|
||||
- `QUBES_TEST_LOAD_ALL` - load all tests (including tests for all templates) when relevant test modules are imported; this needs to be set for test runners not supporting [load_tests protocol](https://docs.python.org/3/library/unittest.html#load-tests-protocol)
|
||||
- `DEFAULT_LVM_POOL` - LVM thin pool to use for tests, in `VolumeGroup/ThinPool` format
|
||||
- `QUBES_TEST_PCIDEV` - PCI device to be used in PCI passthrough tests (for example sound card)
|
||||
- `QUBES_TEST_TEMPLATES` - space separated list of templates to run tests on; if not set, all installed templates are tested
|
||||
- `QUBES_TEST_LOAD_ALL` - load all tests (including tests for all templates) when relevant test modules are imported; this needs to be set for test runners not supporting [load_tests protocol](https://docs.python.org/3/library/unittest.html#load-tests-protocol)
|
||||
|
||||
### Adding a new test to core-admin
|
||||
|
||||
After adding a new unit test to [core-admin/qubes/tests](https://github.com/QubesOS/qubes-core-admin/tree/master/qubes/tests) you'll have to include it in [core-admin/qubes/tests/\_\_init\_\_.py](https://github.com/QubesOS/qubes-core-admin/tree/master/qubes/tests/__init__.py)
|
||||
|
||||
|
||||
#### Editing `__init__.py`
|
||||
|
||||
You'll also need to add your test at the bottom of the `__init__.py` file, in the method `def load_tests`, in the for loop with `modname`.
|
||||
Again, given the hypothetical `example.py` test:
|
||||
|
||||
|
|
@ -213,7 +218,7 @@ class SomeTestCase(unittest.TestCase):
|
|||
# first test that actually use event loop will try to dereference (already
|
||||
# destroyed) objects, resulting in SEGV
|
||||
self.loop = quamash.QEventLoop(self.qtapp)
|
||||
|
||||
|
||||
def tearDown(self):
|
||||
[...]
|
||||
# process any pending events before destroying the object
|
||||
|
|
@ -237,11 +242,10 @@ class SomeTestCase(unittest.TestCase):
|
|||
gc.collect()
|
||||
~~~
|
||||
|
||||
## Installation Tests with openQA
|
||||
|
||||
Installation Tests with openQA
|
||||
------------------------------
|
||||
**URL:** <https://openqa.qubes-os.org/>
|
||||
|
||||
**URL:** <https://openqa.qubes-os.org/>
|
||||
**Tests:** <https://github.com/marmarek/openqa-tests-qubesos>
|
||||
|
||||
Manually testing the installation of Qubes OS is a time-consuming process.
|
||||
|
|
@ -258,4 +262,3 @@ Thanks to an anonymous donor, our openQA system is hosted in a datacenter on har
|
|||
|
||||
[unittest]: https://docs.python.org/3/library/unittest.html
|
||||
[OpenQA]: http://open.qa/
|
||||
|
||||
|
|
|
|||
|
|
@ -6,8 +6,8 @@ permalink: /doc/mount-lvm-image/
|
|||
|
||||
# How to mount LVM image
|
||||
|
||||
You want to read your LVM image (e.g., there is a problem where you can't start any VMs except dom0).
|
||||
|
||||
You want to read your LVM image (e.g., there is a problem where you can't start any VMs except dom0).
|
||||
|
||||
1: make the image available for qubesdb.
|
||||
From dom0 terminal:
|
||||
|
||||
|
|
@ -25,7 +25,8 @@ From dom0 terminal:
|
|||
|
||||
3: Attach the device to your newly created disp VM
|
||||
|
||||
From the GUI, or from the command line:
|
||||
From the GUI, or from the command line:
|
||||
|
||||
```bash
|
||||
[user@dom0]$ qvm-block attach NEWLY_CREATED_DISPVM dom0:$dev
|
||||
```
|
||||
|
|
@ -37,15 +38,19 @@ From the GUI, or from the command line:
|
|||
```
|
||||
|
||||
5: Umount and kill the VM
|
||||
```
|
||||
|
||||
```bash
|
||||
[user@dispXXXX]$ umount /mnt/
|
||||
```
|
||||
|
||||
6: Remove the image from qubesdb
|
||||
```
|
||||
|
||||
```bash
|
||||
[user@dom0]$ qubesdb-rm /qubes-block-devices/$dev/
|
||||
```
|
||||
|
||||
# References
|
||||
|
||||
https://github.com/QubesOS/qubes-issues/issues/4687#issuecomment-451626625
|
||||
Please consult this issue's [comment].
|
||||
|
||||
[comment]: https://github.com/QubesOS/qubes-issues/issues/4687#issuecomment-451626625
|
||||
|
|
|
|||
|
|
@ -8,15 +8,13 @@ redirect_from:
|
|||
- /wiki/Profiling/
|
||||
---
|
||||
|
||||
Profiling
|
||||
=========
|
||||
# Profiling
|
||||
|
||||
This is a python profiling primer.
|
||||
|
||||
For the purpose of this document, `qubes-dev` is name of the domain used for postprocessing profiling stats.
|
||||
|
||||
Requirements
|
||||
------------
|
||||
## Requirements
|
||||
|
||||
~~~
|
||||
yum install gprof2dot graphviz
|
||||
|
|
@ -30,10 +28,9 @@ mkdir -p ~/profiling
|
|||
qvm-run -p qubes-dev 'cat ~/profiling/Upload.sh' > ~/profiling/Upload.sh
|
||||
~~~
|
||||
|
||||
- WARNING: this will obviously be running third-party code which is not signed by ITL nor Fedora. You have been warned.
|
||||
- WARNING: this will obviously be running third-party code which is not signed by ITL nor Fedora. You have been warned.
|
||||
|
||||
Workflow
|
||||
--------
|
||||
## Workflow
|
||||
|
||||
### Identify function responsible for some slow action
|
||||
|
||||
|
|
@ -43,17 +40,21 @@ You have to select the area in which you suspect less than optimal performance.
|
|||
|
||||
Replace
|
||||
|
||||
```python
|
||||
def foo(self, bar):
|
||||
# function content
|
||||
```
|
||||
|
||||
with
|
||||
|
||||
```python
|
||||
def foo(self, *args, **kwargs):
|
||||
profile.runctx('self.real_foo(*args, **kwargs)', globals(), locals(),
|
||||
time.strftime('/home/user/profiling/foo-%Y%m%d-%H%M%S.pstats'))
|
||||
|
||||
def real_foo(self, bar):
|
||||
# function content
|
||||
```
|
||||
|
||||
### Run application
|
||||
|
||||
|
|
@ -88,8 +89,7 @@ This creates `index.html` with all SVG graphics linked to TXT files, ready for u
|
|||
make REMOTE=example.com:public_html/qubes/profiling/ upload
|
||||
~~~
|
||||
|
||||
Example
|
||||
-------
|
||||
## Example
|
||||
|
||||
This example is from `qubes-manager` (`qubesmanager/main.py`).
|
||||
|
||||
|
|
|
|||
|
|
@ -8,20 +8,19 @@ redirect_from:
|
|||
- /wiki/TestBench/
|
||||
---
|
||||
|
||||
Test bench for Dom0
|
||||
===================
|
||||
# Test bench for Dom0
|
||||
|
||||
This guide shows how to set up simple test bench that automatically test your code you're about to push. It is written especially for `core3` branch of `core-admin.git` repo, but some ideas are universal.
|
||||
|
||||
We will set up a spare machine (bare metal, not a virtual) that will be hosting our experimental Dom0. We will communicate with it via Ethernet and SSH. This tutorial assumes you are familiar with [QubesBuilder](/doc/qubes-builder/) and you have it set up and running flawlessly.
|
||||
|
||||
Setting up the machine
|
||||
----------------------
|
||||
## Setting up the machine
|
||||
|
||||
First, do a clean install from ISO you built or grabbed elsewhere.
|
||||
|
||||
You have to fix network, because it is intentionally broken. This script should reenable your network card without depending on anything else.
|
||||
|
||||
```bash
|
||||
#!/bin/sh
|
||||
|
||||
# adjust this for your NIC (run lspci)
|
||||
|
|
@ -53,6 +52,7 @@ You have to fix network, because it is intentionally broken. This script should
|
|||
pcibind ${BDF} e1000e
|
||||
|
||||
dhclient
|
||||
```
|
||||
|
||||
TODO: describe how to run this at every startup
|
||||
|
||||
|
|
@ -66,8 +66,7 @@ yum install openssh-server
|
|||
|
||||
Ensure that sudo works without password from your user account (it should by default).
|
||||
|
||||
Development VM
|
||||
--------------
|
||||
## Development VM
|
||||
|
||||
### SSH
|
||||
|
||||
|
|
@ -95,12 +94,15 @@ This step is optional, but very helpful. Put these scripts somewhere in your `${
|
|||
|
||||
`qtb-runtests`:
|
||||
|
||||
```bash
|
||||
#!/bin/sh
|
||||
|
||||
ssh testbench python -m qubes.tests.run
|
||||
```
|
||||
|
||||
`qtb-install`:
|
||||
|
||||
```bash
|
||||
#!/bin/sh
|
||||
|
||||
TMPDIR=/tmp/qtb-rpms
|
||||
|
|
@ -119,9 +121,11 @@ This step is optional, but very helpful. Put these scripts somewhere in your `${
|
|||
ssh testbench sudo rpm -i --replacepkgs --replacefiles "${TMPDIR}/$(basename ${1})"
|
||||
shift
|
||||
done
|
||||
```
|
||||
|
||||
`qtb-iterate`:
|
||||
|
||||
```bash
|
||||
#!/bin/sh
|
||||
|
||||
set -e
|
||||
|
|
@ -136,6 +140,7 @@ This step is optional, but very helpful. Put these scripts somewhere in your `${
|
|||
make core-admin
|
||||
qtb-install qubes-src/core-admin/rpm/x86_64/qubes-core-dom0-*.rpm
|
||||
qtb-runtests
|
||||
```
|
||||
|
||||
### Hooking git
|
||||
|
||||
|
|
@ -143,14 +148,18 @@ I (woju) have those two git hooks. They ensure tests are passing (or are marked
|
|||
|
||||
`core-admin/.git/hooks/pre-commit`: (you may retain also the default hook, here omitted for readability)
|
||||
|
||||
```bash
|
||||
#!/bin/sh
|
||||
|
||||
set -e
|
||||
|
||||
python -c "import sys, qubes.tests.run; sys.exit(not qubes.tests.run.main())"
|
||||
```
|
||||
|
||||
`core-admin/.git/hooks/pre-push`:
|
||||
|
||||
```bash
|
||||
#!/bin/sh
|
||||
|
||||
exec qtb-iterate
|
||||
```
|
||||
|
|
|
|||
|
|
@ -9,45 +9,43 @@ redirect_from:
|
|||
- /wiki/SystemDoc/VMInterface/
|
||||
---
|
||||
|
||||
VM Configuration Interface
|
||||
==========================
|
||||
# VM Configuration Interface
|
||||
|
||||
Qubes VM have some settings set by dom0 based on VM settings. There are multiple configuration channels, which includes:
|
||||
|
||||
- QubesDB
|
||||
- XenStore (in Qubes 2, data the same as in QubesDB, keys without leading `/`)
|
||||
- Qubes RPC (called at VM startup, or when configuration changed)
|
||||
- GUI protocol
|
||||
- QubesDB
|
||||
- XenStore (in Qubes 2, data the same as in QubesDB, keys without leading `/`)
|
||||
- Qubes RPC (called at VM startup, or when configuration changed)
|
||||
- GUI protocol
|
||||
|
||||
QubesDB
|
||||
--------------------
|
||||
## QubesDB
|
||||
|
||||
### Keys exposed by dom0 to VM ###
|
||||
### Keys exposed by dom0 to VM
|
||||
|
||||
- `/qubes-vm-type` - VM type, the same as `type` field in `qvm-prefs`. One of `AppVM`, `ProxyVM`, `NetVM`, `TemplateVM`, `HVM`, `TemplateHVM`
|
||||
- `/qubes-vm-updatable` - flag whether VM is updatable (whether changes in root.img will survive VM restart). One of `True`, `False`
|
||||
- `/qubes-vm-persistence` - what data do persist between VM restarts:
|
||||
- `full` - all disks
|
||||
- `rw-only` - only `/rw` disk
|
||||
- `none` - none
|
||||
- `/qubes-timezone - name of timezone based on dom0 timezone. For example `Europe/Warsaw`
|
||||
- `/qubes-keyboard` (deprecated in R4.1) - keyboard layout based on dom0 layout. Its syntax is suitable for `xkbcomp` command (after expanding escape sequences like `\n` or `\t`). This is meant only as some default value, VM can ignore this option and choose its own keyboard layout (this is what keyboard setting from Qubes Manager does). This entry is created as part of gui-daemon initialization (so not available when gui-daemon disabled, or not started yet).
|
||||
- `/keyboard-layout` - keyboard layout based on GuiVM layout. Its syntax can be `layout+variant+options`, `layout+variant`, `layout++options` or simply `layout`. For example, `fr+oss`, `pl++compose:caps` or `fr`. This is meant only as some default value, VM can ignore this option and choose its own keyboard layout (this is what keyboard setting from Qubes Manager does).
|
||||
- `/qubes-debug-mode` - flag whether VM has debug mode enabled (qvm-prefs setting). One of `1`, `0`
|
||||
- `/qubes-service/SERVICE_NAME` - subtree for VM services controlled from dom0 (using the `qvm-service` command or Qubes Manager). One of `1`, `0`. Note that not every service will be listed here, if entry is missing, it means "use VM default". A list of currently supported services is in the `qvm-service` man page.
|
||||
- `/qubes-netmask` - network mask (only when VM has netvm set); currently hardcoded "255.255.255.0"
|
||||
- `/qubes-ip - IP address for this VM (only when VM has netvm set)
|
||||
- `/qubes-gateway` - default gateway IP (only when VM has netvm set); VM should add host route to this address directly via eth0 (or whatever default interface name is)
|
||||
- `/qubes-primary-dns` - primary DNS address (only when VM has netvm set)
|
||||
- `/qubes-secondary-dns` - secondary DNS address (only when VM has netvm set)
|
||||
- `/qubes-netvm-gateway` - same as `qubes-gateway` in connected VMs (only when VM serves as network backend - ProxyVM and NetVM)
|
||||
- `/qubes-netvm-netmask` - same as `qubes-netmask` in connected VMs (only when VM serves as network backend - ProxyVM and NetVM)
|
||||
- `/qubes-netvm-network` - network address (only when VM serves as network backend - ProxyVM and NetVM); can be also calculated from qubes-netvm-gateway and qubes-netvm-netmask
|
||||
- `/qubes-netvm-primary-dns` - same as `qubes-primary-dns` in connected VMs (only when VM serves as network backend - ProxyVM and NetVM); traffic sent to this IP on port 53 should be redirected to primary DNS server
|
||||
- `/qubes-netvm-secondary-dns` - same as `qubes-secondary-dns` in connected VMs (only when VM serves as network backend - ProxyVM and NetVM); traffic sent to this IP on port 53 should be redirected to secondary DNS server
|
||||
- `/guivm-windows-prefix` - title prefix for any window not originating from another qube. This means windows of applications running in GuiVM itself
|
||||
- `/qubes-vm-type` - VM type, the same as `type` field in `qvm-prefs`. One of `AppVM`, `ProxyVM`, `NetVM`, `TemplateVM`, `HVM`, `TemplateHVM`
|
||||
- `/qubes-vm-updatable` - flag whether VM is updatable (whether changes in root.img will survive VM restart). One of `True`, `False`
|
||||
- `/qubes-vm-persistence` - what data do persist between VM restarts:
|
||||
- `full` - all disks
|
||||
- `rw-only` - only `/rw` disk
|
||||
- `none` - none
|
||||
- `/qubes-timezone - name of timezone based on dom0 timezone. For example `Europe/Warsaw`
|
||||
- `/qubes-keyboard` (deprecated in R4.1) - keyboard layout based on dom0 layout. Its syntax is suitable for `xkbcomp` command (after expanding escape sequences like `\n` or `\t`). This is meant only as some default value, VM can ignore this option and choose its own keyboard layout (this is what keyboard setting from Qubes Manager does). This entry is created as part of gui-daemon initialization (so not available when gui-daemon disabled, or not started yet).
|
||||
- `/keyboard-layout` - keyboard layout based on GuiVM layout. Its syntax can be `layout+variant+options`, `layout+variant`, `layout++options` or simply `layout`. For example, `fr+oss`, `pl++compose:caps` or `fr`. This is meant only as some default value, VM can ignore this option and choose its own keyboard layout (this is what keyboard setting from Qubes Manager does).
|
||||
- `/qubes-debug-mode` - flag whether VM has debug mode enabled (qvm-prefs setting). One of `1`, `0`
|
||||
- `/qubes-service/SERVICE_NAME` - subtree for VM services controlled from dom0 (using the `qvm-service` command or Qubes Manager). One of `1`, `0`. Note that not every service will be listed here, if entry is missing, it means "use VM default". A list of currently supported services is in the `qvm-service` man page.
|
||||
- `/qubes-netmask` - network mask (only when VM has netvm set); currently hardcoded "255.255.255.0"
|
||||
- `/qubes-ip - IP address for this VM (only when VM has netvm set)
|
||||
- `/qubes-gateway` - default gateway IP (only when VM has netvm set); VM should add host route to this address directly via eth0 (or whatever default interface name is)
|
||||
- `/qubes-primary-dns` - primary DNS address (only when VM has netvm set)
|
||||
- `/qubes-secondary-dns` - secondary DNS address (only when VM has netvm set)
|
||||
- `/qubes-netvm-gateway` - same as `qubes-gateway` in connected VMs (only when VM serves as network backend - ProxyVM and NetVM)
|
||||
- `/qubes-netvm-netmask` - same as `qubes-netmask` in connected VMs (only when VM serves as network backend - ProxyVM and NetVM)
|
||||
- `/qubes-netvm-network` - network address (only when VM serves as network backend - ProxyVM and NetVM); can be also calculated from qubes-netvm-gateway and qubes-netvm-netmask
|
||||
- `/qubes-netvm-primary-dns` - same as `qubes-primary-dns` in connected VMs (only when VM serves as network backend - ProxyVM and NetVM); traffic sent to this IP on port 53 should be redirected to primary DNS server
|
||||
- `/qubes-netvm-secondary-dns` - same as `qubes-secondary-dns` in connected VMs (only when VM serves as network backend - ProxyVM and NetVM); traffic sent to this IP on port 53 should be redirected to secondary DNS server
|
||||
- `/guivm-windows-prefix` - title prefix for any window not originating from another qube. This means windows of applications running in GuiVM itself
|
||||
|
||||
#### Firewall rules in 3.x ####
|
||||
#### Firewall rules in 3.x
|
||||
|
||||
QubesDB is also used to configure firewall in ProxyVMs. Rules are stored in
|
||||
separate key for each target VM. Entries:
|
||||
|
|
@ -63,7 +61,7 @@ VM after applying rules may signal some error, writing a message to
|
|||
`/qubes-iptables-error` key. This does not exclude any other way of
|
||||
communicating problems - like a popup.
|
||||
|
||||
#### Firewall rules in 4.x ####
|
||||
#### Firewall rules in 4.x
|
||||
|
||||
QubesDB is also used to configure firewall in ProxyVMs. Each rule is stored as
|
||||
a separate entry, grouped on target VM:
|
||||
|
|
@ -85,19 +83,19 @@ Each rule is a single QubesDB entry, consisting of pairs `key=value` separated
|
|||
by space. QubesDB enforces limit on a single entry length - 3072 bytes.
|
||||
Possible options for a single rule:
|
||||
|
||||
- `action`, values: `accept`, `drop`; this is present in every rule
|
||||
- `dst4`, value: destination IPv4 address with a mask; for example: `192.168.0.0/24`
|
||||
- `dst6`, value: destination IPv6 address with a mask; for example: `2000::/3`
|
||||
- `dsthost`, value: DNS hostname of destination host
|
||||
- `proto`, values: `tcp`, `udp`, `icmp`
|
||||
- `specialtarget`, value: One of predefined target, currently defined values:
|
||||
- `dns` - such option should match DNS traffic to default DNS server (but
|
||||
- `action`, values: `accept`, `drop`; this is present in every rule
|
||||
- `dst4`, value: destination IPv4 address with a mask; for example: `192.168.0.0/24`
|
||||
- `dst6`, value: destination IPv6 address with a mask; for example: `2000::/3`
|
||||
- `dsthost`, value: DNS hostname of destination host
|
||||
- `proto`, values: `tcp`, `udp`, `icmp`
|
||||
- `specialtarget`, value: One of predefined target, currently defined values:
|
||||
- `dns` - such option should match DNS traffic to default DNS server (but
|
||||
not any DNS server), on both TCP and UDP
|
||||
- `dstports`, value: destination ports range separated with `-`, valid only
|
||||
- `dstports`, value: destination ports range separated with `-`, valid only
|
||||
together with `proto=tcp` or `proto=udp`; for example `1-1024`, `80-80`
|
||||
- `icmptype`, value: numeric (decimal) icmp message type, for example `8` for
|
||||
- `icmptype`, value: numeric (decimal) icmp message type, for example `8` for
|
||||
echo request, valid only together with `proto=icmp`
|
||||
- `dpi`, value: Deep Packet Inspection protocol (like: HTTP, SSL, SMB, SSH, SMTP) or the default 'NO' as no DPI, only packet filtering
|
||||
- `dpi`, value: Deep Packet Inspection protocol (like: HTTP, SSL, SMB, SSH, SMTP) or the default 'NO' as no DPI, only packet filtering
|
||||
|
||||
Options must appear in the rule in the order listed above. Duplicated options
|
||||
are forbidden.
|
||||
|
|
@ -117,48 +115,46 @@ Example valid rules:
|
|||
- `action=drop proto=tcp specialtarget=dns` - drop DNS queries sent using TCP
|
||||
- `action=drop`
|
||||
|
||||
### Keys set by VM for passing info to dom0 ###
|
||||
### Keys set by VM for passing info to dom0
|
||||
|
||||
- `memory/meminfo` (**xenstore**) - used memory (updated by qubes-meminfo-writer), input information for qmemman;
|
||||
- Qubes 3.x format: 6 lines (EOL encoded as `\n`), each in format "FIELD: VALUE kB"; fields: `MemTotal`, `MemFree`, `Buffers`, `Cached`, `SwapTotal`, `SwapFree`; meaning the same as in `/proc/meminfo` in Linux.
|
||||
- Qubes 4.0+ format: used memory size in the VM, in kbytes
|
||||
- `/qubes-block-devices` - list of block devices exposed by this VM, each device (subdirectory) should be named in a way that VM can attach the device based on it. Each should contain these entries:
|
||||
- `desc` - device description (ASCII text)
|
||||
- `size` - device size in bytes
|
||||
- `mode` - default connection mode; `r` for read-only, `w` for read-write
|
||||
- `/qubes-usb-devices` - list of USB devices exposed by this VM, each device (subdirectory) should contain:
|
||||
- `desc` - device description (ASCII text)
|
||||
- `usb-ver` - USB version (1, 2 or 3)
|
||||
- `memory/meminfo` (**xenstore**) - used memory (updated by qubes-meminfo-writer), input information for qmemman;
|
||||
- Qubes 3.x format: 6 lines (EOL encoded as `\n`), each in format "FIELD: VALUE kB"; fields: `MemTotal`, `MemFree`, `Buffers`, `Cached`, `SwapTotal`, `SwapFree`; meaning the same as in `/proc/meminfo` in Linux.
|
||||
- Qubes 4.0+ format: used memory size in the VM, in kbytes
|
||||
- `/qubes-block-devices` - list of block devices exposed by this VM, each device (subdirectory) should be named in a way that VM can attach the device based on it. Each should contain these entries:
|
||||
- `desc` - device description (ASCII text)
|
||||
- `size` - device size in bytes
|
||||
- `mode` - default connection mode; `r` for read-only, `w` for read-write
|
||||
- `/qubes-usb-devices` - list of USB devices exposed by this VM, each device (subdirectory) should contain:
|
||||
- `desc` - device description (ASCII text)
|
||||
- `usb-ver` - USB version (1, 2 or 3)
|
||||
|
||||
Qubes RPC
|
||||
---------
|
||||
## Qubes RPC
|
||||
|
||||
Services called by dom0 to provide some VM configuration:
|
||||
|
||||
- `qubes.SetMonitorLayout` - provide list of monitors, one per line. Each line contains four numbers: `width height X Y width_mm height_mm` (physical dimensions - `width_mm` and `height_mm` - are optional)
|
||||
- `qubes.WaitForSession` - called to wait for full VM startup
|
||||
- `qubes.GetAppmenus` - receive appmenus from given VM (template); TODO: describe format here
|
||||
- `qubes.GetImageRGBA` - receive image/application icon. Protocol:
|
||||
- `qubes.SetMonitorLayout` - provide list of monitors, one per line. Each line contains four numbers: `width height X Y width_mm height_mm` (physical dimensions - `width_mm` and `height_mm` - are optional)
|
||||
- `qubes.WaitForSession` - called to wait for full VM startup
|
||||
- `qubes.GetAppmenus` - receive appmenus from given VM (template); TODO: describe format here
|
||||
- `qubes.GetImageRGBA` - receive image/application icon. Protocol:
|
||||
|
||||
1. Caller sends name of requested icon. This can be one of:
|
||||
* `xdgicon:NAME` - search for NAME in standard icons theme
|
||||
* `-` - get icon data from stdin (the caller), can be prefixed with format name, for example `png:-`
|
||||
* file name
|
||||
2. The service responds with image dimensions: width and height as
|
||||
1. Caller sends name of requested icon. This can be one of:
|
||||
* `xdgicon:NAME` - search for NAME in standard icons theme
|
||||
* `-` - get icon data from stdin (the caller), can be prefixed with format name, for example `png:-`
|
||||
* file name
|
||||
2. The service responds with image dimensions: width and height as
|
||||
decimal numbers, separated with space and with EOL marker at the and; then
|
||||
image data in RGBA format (32 bits per pixel)
|
||||
- `qubes.SetDateTime` - set VM time, called periodically by dom0 (can be
|
||||
- `qubes.SetDateTime` - set VM time, called periodically by dom0 (can be
|
||||
triggered manually from dom0 by calling `qvm-sync-clock`). The service
|
||||
receives one line at stdin - time in format of `date -u -Iseconds`, for
|
||||
example `2015-07-31T16:10:43+0000`.
|
||||
- `qubes.SetGuiMode` - called in HVM to switch between fullscreen and seamless
|
||||
- `qubes.SetGuiMode` - called in HVM to switch between fullscreen and seamless
|
||||
GUI mode. The service receives a single word on stdin - either `FULLSCREEN`
|
||||
or `SEAMLESS`
|
||||
- `qubes.ResizeDisk` - called to inform that underlying disk was resized.
|
||||
- `qubes.ResizeDisk` - called to inform that underlying disk was resized.
|
||||
Name of disk image is passed on standard input (`root`, `private`, `volatile`,
|
||||
or other). This is used starting with Qubes 4.0.
|
||||
|
||||
|
||||
Other Qrexec services installed by default:
|
||||
|
||||
- `qubes.Backup` - store Qubes backup. The service receives location chosen by
|
||||
|
|
@ -193,19 +189,19 @@ Other Qrexec services installed by default:
|
|||
can send icon for the same window multiple times to replace previous one (for
|
||||
example for animated icons)
|
||||
- `qubes.VMShell` - call any command in the VM; the command(s) is passed one per line
|
||||
- `qubes.VMShell+WaitForSession` waits for full VM startup first
|
||||
- `qubes.VMShell+WaitForSession` waits for full VM startup first
|
||||
- `qubes.VMExec` - call any command in the VM, without using shell, the command
|
||||
needs to be passed as argument and encoded as follows:
|
||||
- the executable name and arguments are separated by `+`
|
||||
- everything except alphanumeric characters, `.` and `_` needs to be
|
||||
- the executable name and arguments are separated by `+`
|
||||
- everything except alphanumeric characters, `.` and `_` needs to be
|
||||
escaped
|
||||
- bytes are escaped as `-HH` (where `HH` is hex code, capital letters only)
|
||||
- `-` itself can be escaped as `--`
|
||||
- example: to run `ls -a /home/user`, use
|
||||
- bytes are escaped as `-HH` (where `HH` is hex code, capital letters only)
|
||||
- `-` itself can be escaped as `--`
|
||||
- example: to run `ls -a /home/user`, use
|
||||
`qubes.VMExec+ls+--a+-2Fhome-2Fuser`
|
||||
- `qubes.VMExecGUI` - a variant of `qubes.VMExec` that waits for full VM
|
||||
startup first
|
||||
|
||||
|
||||
Services called in GuiVM:
|
||||
|
||||
- `policy.Ask`, `policy.Notify` - confirmation prompt and notifications for
|
||||
|
|
@ -224,7 +220,6 @@ abstraction. This will change in the future. Those tools are:
|
|||
|
||||
Additionally, automatic tests extensively run various commands directly in VMs. We do not plan to change that.
|
||||
|
||||
GUI protocol
|
||||
------------
|
||||
## GUI protocol
|
||||
|
||||
GUI initialization includes passing the whole screen dimensions from dom0 to VM. This will most likely be overwritten by qubes.SetMonitorLayout Qubes RPC call.
|
||||
|
|
|
|||
|
|
@ -8,8 +8,7 @@ redirect_from:
|
|||
- /wiki/WindowsDebugging/
|
||||
---
|
||||
|
||||
Debugging Windows HVMs
|
||||
======================
|
||||
# Debugging Windows HVMs
|
||||
|
||||
Debugging Windows code can be tricky in a virtualized environment. The guide below assumes Xen hypervisor and Windows 7 VMs.
|
||||
|
||||
|
|
@ -17,22 +16,25 @@ User-mode debugging is usually straightforward if it can be done on one machine.
|
|||
|
||||
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.
|
||||
|
||||
- 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:
|
||||
- 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:
|
||||
|
||||
```bash
|
||||
#!/bin/sh
|
||||
|
||||
id1=$(xl domid "$1-dm")
|
||||
tty1=$(xenstore-read /local/domain/${id1}/device/console/3/tty)
|
||||
echo $tty1
|
||||
```
|
||||
|
||||
Pass it a running VM name and it will output the corresponding pty name.
|
||||
Pass it a running VM name and it will output the corresponding pty name.
|
||||
|
||||
- To connect both ptys you can use [socat](http://www.dest-unreach.org/socat/) like that:
|
||||
- To connect both ptys you can use [socat](http://www.dest-unreach.org/socat/) like that:
|
||||
|
||||
```bash
|
||||
#!/bin/sh
|
||||
|
||||
id1=$(xl domid "$1-dm")
|
||||
|
|
@ -40,14 +42,15 @@ Things get complicated if you need to perform kernel debugging or troubleshoot p
|
|||
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
|
||||
```
|
||||
|
||||
...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.
|
||||
...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.
|
||||
|
||||
- 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%28v=vs.85%29.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:
|
||||
- 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](http://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:
|
||||
|
||||
~~~
|
||||
Opened \\.\com1
|
||||
|
|
@ -55,7 +58,7 @@ Things get complicated if you need to perform kernel debugging or troubleshoot p
|
|||
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*http://msdl.microsoft.com/download/symbols
|
||||
Executable search path is:
|
||||
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.
|
||||
|
|
@ -73,6 +76,7 @@ Things get complicated if you need to perform kernel debugging or troubleshoot p
|
|||
|
||||
...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>
|
||||
|
|
@ -85,11 +89,11 @@ Things get complicated if you need to perform kernel debugging or troubleshoot p
|
|||
{
|
||||
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);
|
||||
|
|
@ -112,13 +116,13 @@ Things get complicated if you need to perform kernel debugging or troubleshoot p
|
|||
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)
|
||||
{
|
||||
|
|
@ -182,6 +186,7 @@ Things get complicated if you need to perform kernel debugging or troubleshoot p
|
|||
close(fd2);
|
||||
return 0;
|
||||
}
|
||||
```
|
||||
|
||||
> This utility is a unidirectional relay so you need to run two instances to get duplex communication, like:
|
||||
>
|
||||
|
|
@ -202,7 +207,7 @@ Things get complicated if you need to perform kernel debugging or troubleshoot p
|
|||
> 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*http://msdl.microsoft.com/download/symbols
|
||||
> Executable search path is:
|
||||
> 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:
|
||||
|
|
@ -214,7 +219,7 @@ Things get complicated if you need to perform kernel debugging or troubleshoot p
|
|||
|
||||
There are two main issues to be adopted to get all things to work in the R4.0.
|
||||
|
||||
## Add a virtual serial port ##
|
||||
## 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.
|
||||
|
||||
|
|
@ -228,15 +233,17 @@ $ 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 ##
|
||||
## Connect two consoles
|
||||
|
||||
Run the following script:
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue