mirror of
https://github.com/QubesOS/qubes-doc.git
synced 2025-05-02 14:56:13 -04:00
replaced all github flavored code blocks with fenced kramdown code blocks
This commit is contained in:
Jeepler
parent
df467baf1c
commit
39ef7373fd
58 changed files with 609 additions and 609 deletions
|
|
@ -47,14 +47,14 @@ General typographic conventions
|
|||
|
||||
- Comments should be indent together with the code, e.g. like this:
|
||||
|
||||
```
|
||||
~~~
|
||||
for (...) {
|
||||
// The following code finds PGP private key matching the given public key in O(1)
|
||||
while (key_found) {
|
||||
(...)
|
||||
}
|
||||
}
|
||||
```
|
||||
~~~
|
||||
|
||||
File naming conventions
|
||||
-----------------------
|
||||
|
|
@ -87,29 +87,29 @@ General programming style guidelines
|
|||
- Use comments to explain non-trivial code fragments, or expected behavior of more complex functions, if it is not clear from their name.
|
||||
- Do **not** use comments for code fragments where it is immediately clear what the code does. E.g. avoid constructs like this:
|
||||
|
||||
```
|
||||
~~~
|
||||
// Return window id
|
||||
int get_window_id (...) {
|
||||
(...)
|
||||
return id;
|
||||
}
|
||||
```
|
||||
~~~
|
||||
|
||||
- Do **not** use comments to disable code fragments. In a production code there should really be no commented or disabled code fragments. If you really, really have a good reason to retain some fragment of unused code, use \#if or \#ifdef to disable it, e.g.:
|
||||
|
||||
```
|
||||
~~~
|
||||
#if 0
|
||||
(...) // Some unused code here
|
||||
#endif
|
||||
```
|
||||
~~~
|
||||
|
||||
... and preferably use some descriptive macro instead of just `0`, e.g.:
|
||||
|
||||
```
|
||||
~~~
|
||||
#if USE_OLD_WINDOW_TRAVERSING
|
||||
(...) // Some unused code here
|
||||
#endif
|
||||
```
|
||||
~~~
|
||||
|
||||
Not sure how to do similar thing in Python... Anyone?
|
||||
|
||||
|
|
@ -137,7 +137,7 @@ Security coding guidelines
|
|||
- Any input that comes from untrusted, or less trusted, or just differently-trusted, entity should always be considered as malicious and should always be sanitized and verified. So, if your software runs in Dom0 and processes some input from any of the VMs, this input should be considered to be malicious. Even if your software runs in a VM, and processes input from some other VM, you should also assume that the input is malicious and verify it.
|
||||
- Use `untrusted_` prefix for all variables that hold values read from untrusted party and which have not yet been verified to be decent, e.g.:
|
||||
|
||||
```
|
||||
~~~
|
||||
read_struct(untrusted_conf);
|
||||
/* sanitize start */
|
||||
if (untrusted_conf.width > MAX_WINDOW_WIDTH)
|
||||
|
|
@ -146,7 +146,7 @@ Security coding guidelines
|
|||
untrusted_conf.height = MAX_WINDOW_HEIGHT;
|
||||
width = untrusted_conf.width;
|
||||
height = untrusted_conf.height;
|
||||
```
|
||||
~~~
|
||||
|
||||
- Use another variables, without the `untrusted_` prefix to hold the sanitized values, as shown above.
|
||||
|
||||
|
|
|
|||
|
|
@ -21,15 +21,15 @@ this `QubesOS` github account.
|
|||
|
||||
To clone a repository:
|
||||
|
||||
```
|
||||
~~~
|
||||
git clone git://github.com/QubesOS/<repo_name>.git <repo_name>
|
||||
```
|
||||
~~~
|
||||
|
||||
e.g.:
|
||||
|
||||
```
|
||||
~~~
|
||||
git clone git://github.com/QubesOS/qubes-core-admin.git core-admin
|
||||
```
|
||||
~~~
|
||||
|
||||
## Sending a patch
|
||||
|
||||
|
|
|
|||
|
|
@ -23,17 +23,17 @@ Change the following variables GIT\_SUBDIR=marmarek DISTS\_VM=archlinux
|
|||
Get all required sources
|
||||
------------------------
|
||||
|
||||
```
|
||||
~~~
|
||||
make get-sources
|
||||
```
|
||||
~~~
|
||||
|
||||
Note that make get-sources sometimes fails because it didn't download packages that are not used by archlinux such as xfce or kde packages.
|
||||
|
||||
You can ignore the repositories that are failing by adding the following line to your builder.conf:
|
||||
|
||||
```
|
||||
~~~
|
||||
COMPONENTS:=$(filter-out desktop-linux-kde desktop-linux-xfce,$(COMPONENTS))
|
||||
```
|
||||
~~~
|
||||
|
||||
Just don't forget that you need to comment this line again if you want to build the whole Qubes-OS install CD.
|
||||
|
||||
|
|
@ -42,23 +42,23 @@ Make all required qubes components
|
|||
|
||||
The first use of the builder can take several hours depending on your bandwidth as it will install an archlinux chroot:
|
||||
|
||||
```
|
||||
~~~
|
||||
make vmm-xen-vm
|
||||
make core-vchan-xen-vm
|
||||
make linux-utils-vm
|
||||
make core-agent-linux-vm
|
||||
make gui-common-vm
|
||||
make gui-agent-linux-vm
|
||||
```
|
||||
~~~
|
||||
|
||||
Now build the template itself
|
||||
-----------------------------
|
||||
|
||||
This can take again several hours, especially the first time you built and archlinux template:
|
||||
|
||||
```
|
||||
~~~
|
||||
make linux-template-builder
|
||||
```
|
||||
~~~
|
||||
|
||||
Retrieve your template
|
||||
----------------------
|
||||
|
|
@ -75,30 +75,30 @@ Can't open file archlinux-2013.02.01-dual.iso
|
|||
|
||||
Archlinux ISO files are sometimes removed from mirrors. Check the last version available on the archlinux mirror (eg: [http://mir.archlinux.fr/iso/](http://mir.archlinux.fr/iso/)), and update qubes-src/linux-template-builder/scripts\_archlinux/00\_prepare.sh accordingly:
|
||||
|
||||
```
|
||||
~~~
|
||||
ISO_VERSION=2013.06.01
|
||||
```
|
||||
~~~
|
||||
|
||||
You will also need to download the signature matching this ISO version inside qubes-src/linux-template-builder/scripts\_archlinux/:
|
||||
|
||||
```
|
||||
~~~
|
||||
wget http://mir.archlinux.fr/iso/2013.06.01/archlinux-2013.06.01-dual.iso.sig
|
||||
```
|
||||
~~~
|
||||
|
||||
The nm-applet (network manager icon) fails to start when archlinux is defined as a template-vm:
|
||||
-----------------------------------------------------------------------------------------------
|
||||
|
||||
In fact /etc/dbus-1/system.d/org.freedesktop.NetworkManager.conf does not allow a standard user to run network manager clients. To allow this, one need to change inside \<policy context="default"\>:
|
||||
|
||||
```
|
||||
~~~
|
||||
<deny send_destination="org.freedesktop.NetworkManager"/>
|
||||
```
|
||||
~~~
|
||||
|
||||
to
|
||||
|
||||
```
|
||||
~~~
|
||||
<allow send_destination="org.freedesktop.NetworkManager"/>
|
||||
```
|
||||
~~~
|
||||
|
||||
DispVM, Yum proxy and most Qubes addons (thunderbird ...) have not been tested at all.
|
||||
--------------------------------------------------------------------------------------
|
||||
|
|
@ -111,26 +111,26 @@ This is apparently a bug in Archlinux between glibc and pulseaudio package 4.0-6
|
|||
Error when building the gui-agent-linux with pulsecore error
|
||||
------------------------------------------------------------
|
||||
|
||||
```
|
||||
~~~
|
||||
module-vchan-sink.c:62:34: fatal error: pulsecore/core-error.h: No such file or directory
|
||||
#include <pulsecore/core-error.h>
|
||||
```
|
||||
~~~
|
||||
|
||||
This error is because Archlinux update package too quickly. Probably, a new version of pulseaudio has been released, but the qubes team has not imported the new development headers yet.
|
||||
|
||||
You can create fake new headers just by copying the old headers:
|
||||
|
||||
```
|
||||
~~~
|
||||
cd qubes-builder/qubes-src/gui-agent-linux/pulse
|
||||
ls
|
||||
cp -r pulsecore-#lastversion pulsecore-#archlinuxversion
|
||||
```
|
||||
~~~
|
||||
|
||||
You can check the current archlinux pulseaudio version like this:
|
||||
|
||||
```
|
||||
~~~
|
||||
sudo chroot chroot-archlinux/ pacman -Qi pulseaudio
|
||||
```
|
||||
~~~
|
||||
|
||||
chroot-archlinux/dev/pts has not been unmounted
|
||||
-----------------------------------------------
|
||||
|
|
@ -154,15 +154,15 @@ The boot process fails without visible errors in the logs, but spawn a recovery
|
|||
|
||||
The problem is a new conflict between systemd and the old sysvinit style. To fix this, you can change the master xen template in dom0 to remove sysvinit remains: Edit **INSIDE DOM0** /usr/share/qubes/vm-template.conf, and change the variable 'extra' that contains the kernel variables: from:
|
||||
|
||||
```
|
||||
~~~
|
||||
extra="ro nomodeset 3 console=hvc0 rd_NO_PLYMOUTH {kernelopts}"
|
||||
```
|
||||
~~~
|
||||
|
||||
to:
|
||||
|
||||
```
|
||||
~~~
|
||||
extra="ro nomodeset console=hvc0 rd_NO_PLYMOUTH {kernelopts}"
|
||||
```
|
||||
~~~
|
||||
|
||||
Qubes-OS is now using different xenstore variable names, which makes to archlinux VM failing to boot
|
||||
----------------------------------------------------------------------------------------------------
|
||||
|
|
@ -171,15 +171,15 @@ Apply the following fix in the template to revert the variable name to the old Q
|
|||
|
||||
You can edit the template the following way:
|
||||
|
||||
```
|
||||
~~~
|
||||
sudo mkdir /mnt/vm
|
||||
sudo mount /var/lib/qubes/vm-templates/archlinux-x64/root.img /mnt/vm
|
||||
sudo chroot /mnt/vm
|
||||
```
|
||||
~~~
|
||||
|
||||
Then apply the fix:
|
||||
|
||||
```
|
||||
~~~
|
||||
sudo sed 's:qubes-keyboard:qubes_keyboard:g' -i /etc/X11/xinit/xinitrc.d/qubes-keymap.sh
|
||||
|
||||
sudo sed 's:qubes-netvm-domid:qubes_netvm_domid:g' -i /etc/NetworkManager/dispatcher.d/30-qubes-external-ip
|
||||
|
|
@ -212,19 +212,19 @@ sudo sed 's:qubes-vm-updateable:qubes_vm_updateable:g' -i /usr/lib/qubes/qubes_t
|
|||
|
||||
sudo sed 's:qubes-vm-type:qubes_vm_type:g' -i /usr/bin/qubes-session
|
||||
sudo sed 's:qubes-vm-updateable:qubes_vm_updateable:g' -i /usr/bin/qubes-session
|
||||
```
|
||||
~~~
|
||||
|
||||
Do not forgot to:
|
||||
|
||||
```
|
||||
~~~
|
||||
umount /mnt/vm
|
||||
```
|
||||
~~~
|
||||
|
||||
Installing the template in dom0 fails because of a missing dependency (qubes-core-dom0-linux)
|
||||
---------------------------------------------------------------------------------------------
|
||||
|
||||
Again you built a template based on a recent Qubes API which has not been released yet. So skip the dependency for now:
|
||||
|
||||
```
|
||||
~~~
|
||||
sudo rpm -U --nodeps yourpackage.rpm
|
||||
```
|
||||
~~~
|
||||
|
|
|
|||
|
|
@ -24,11 +24,11 @@ You need to install your OS inside a chroot that will be used to build all the r
|
|||
|
||||
The scripts you will be interested in will be inside the qubes-src/linux-template-builder project:
|
||||
|
||||
```
|
||||
~~~
|
||||
scripts_fedora
|
||||
scripts_archlinux
|
||||
scripts_yourOSname
|
||||
```
|
||||
~~~
|
||||
|
||||
### 00\_prepare.sh
|
||||
|
||||
|
|
@ -42,19 +42,19 @@ The goal of this script is to install a base environment of your target OS insid
|
|||
|
||||
Edit the builder.conf file to change the variable DISTS\_VM to your OS name (DISTS\_VM=your\_os\_name). The try to make the template to check that at least these to first scripts are working correctly:
|
||||
|
||||
```
|
||||
~~~
|
||||
make linux-template-builder
|
||||
```
|
||||
~~~
|
||||
|
||||
Qubes builder Makefiles
|
||||
-----------------------
|
||||
|
||||
Now you need to create Makefiles specific to your OS. You will find the required scripts directly inside qubes-builder:
|
||||
|
||||
```
|
||||
~~~
|
||||
prepare-chroot-yourOSname
|
||||
Makefile.yourOSname
|
||||
```
|
||||
~~~
|
||||
|
||||
### prepare-chroot-yourOSname
|
||||
|
||||
|
|
@ -103,11 +103,11 @@ Additional Installation scripts
|
|||
|
||||
Again you need to work on scripts inside the qubes-src/linux-template-builder project:
|
||||
|
||||
```
|
||||
~~~
|
||||
scripts_fedora
|
||||
scripts_archlinux
|
||||
scripts_yourOSname
|
||||
```
|
||||
~~~
|
||||
|
||||
### 02\_install\_groups.sh
|
||||
|
||||
|
|
|
|||
|
|
@ -22,10 +22,10 @@ The best way to write and contribute code is to create a git repo somewhere (e.g
|
|||
|
||||
**Example:**
|
||||
|
||||
```
|
||||
~~~
|
||||
$ cd qubes-builder/qubes-src/qubes-manager
|
||||
$ git remote add abel git@github.com:abeluck/qubes-manager.git
|
||||
```
|
||||
~~~
|
||||
|
||||
You can then proceed to easily develop in your own branches, pull in new commits from the dev branches, merge them, and eventually push to your own repo on github.
|
||||
|
||||
|
|
@ -37,55 +37,55 @@ When you are ready to submit your changes to Qubes to be merged, push your chang
|
|||
|
||||
In qubes-builder/qubes-src/kernel:
|
||||
|
||||
```
|
||||
~~~
|
||||
make prep
|
||||
```
|
||||
~~~
|
||||
|
||||
The resulting tree will be in kernel-\<VERSION\>/linux-\<VERSION\>:
|
||||
|
||||
```
|
||||
~~~
|
||||
ls -ltrd kernel*/linux*
|
||||
```
|
||||
~~~
|
||||
|
||||
```
|
||||
~~~
|
||||
drwxr-xr-x 23 user user 4096 Nov 5 09:50 kernel-3.4.18/linux-3.4.18
|
||||
drwxr-xr-x 6 user user 4096 Nov 21 20:48 kernel-3.4.18/linux-obj
|
||||
```
|
||||
~~~
|
||||
|
||||
#### Go to the kernel tree and update the version
|
||||
|
||||
In qubes-builder/qubes-src/kernel:
|
||||
|
||||
```
|
||||
~~~
|
||||
cd kernel-3.4.18/linux-3.4.18
|
||||
```
|
||||
~~~
|
||||
|
||||
#### Changing the config
|
||||
|
||||
In kernel-3.4.18/linux-3.4.18:
|
||||
|
||||
```
|
||||
~~~
|
||||
cp ../../config-pvops .config
|
||||
make oldconfig
|
||||
```
|
||||
~~~
|
||||
|
||||
Now change the configuration. For example, in kernel-3.4.18/linux-3.4.18:
|
||||
|
||||
```
|
||||
~~~
|
||||
make menuconfig
|
||||
```
|
||||
~~~
|
||||
|
||||
Copy the modified config back into the kernel tree:
|
||||
|
||||
```
|
||||
~~~
|
||||
cp .config ../../../config-pvops
|
||||
```
|
||||
~~~
|
||||
|
||||
#### Patching the code
|
||||
|
||||
TODO: describe the workflow for patching the code, below are some random notes, not working well
|
||||
|
||||
```
|
||||
~~~
|
||||
ln -s ../../patches.xen
|
||||
export QUILT_PATCHES=patches.xen
|
||||
export QUILT_REFRESH_ARGS="-p ab --no-timestamps --no-index"
|
||||
|
|
@ -101,7 +101,7 @@ quilt add drivers/usb/host/Kconfig drivers/usb/host/Makefile \
|
|||
quilt refresh
|
||||
cd ../..
|
||||
vi series-pvops.conf
|
||||
```
|
||||
~~~
|
||||
|
||||
#### Building RPMS
|
||||
|
||||
|
|
@ -113,20 +113,20 @@ You might want to take a moment here to review (git diff, git status), commit yo
|
|||
|
||||
To actually build RPMS, in qubes-src/kernel:
|
||||
|
||||
```
|
||||
~~~
|
||||
make rpms
|
||||
```
|
||||
~~~
|
||||
|
||||
RPMS will appear in qubes-src/kernel/rpm/x86\_64:
|
||||
|
||||
```
|
||||
~~~
|
||||
-rw-rw-r-- 1 user user 42996126 Nov 17 04:08 kernel-3.4.18-1debug20121116c.pvops.qubes.x86_64.rpm
|
||||
-rw-rw-r-- 1 user user 43001450 Nov 17 05:36 kernel-3.4.18-1debug20121117a.pvops.qubes.x86_64.rpm
|
||||
-rw-rw-r-- 1 user user 8940138 Nov 17 04:08 kernel-devel-3.4.18-1debug20121116c.pvops.qubes.x86_64.rpm
|
||||
-rw-rw-r-- 1 user user 8937818 Nov 17 05:36 kernel-devel-3.4.18-1debug20121117a.pvops.qubes.x86_64.rpm
|
||||
-rw-rw-r-- 1 user user 54490741 Nov 17 04:08 kernel-qubes-vm-3.4.18-1debug20121116c.pvops.qubes.x86_64.rpm
|
||||
-rw-rw-r-- 1 user user 54502117 Nov 17 05:37 kernel-qubes-vm-3.4.18-1debug20121117a.pvops.qubes.x86_64.rpm
|
||||
```
|
||||
~~~
|
||||
|
||||
### Useful [QubesBuilder](/doc/QubesBuilder/) commands
|
||||
|
||||
|
|
@ -148,7 +148,7 @@ You may also like to run your [test environment on separate machine](/doc/TestBe
|
|||
|
||||
TODO: edit this script to be more generic
|
||||
|
||||
```
|
||||
~~~
|
||||
#!/bin/sh
|
||||
|
||||
set -x
|
||||
|
|
@ -171,24 +171,24 @@ sudo cp misc/qubes-start.desktop /usr/share/qubes/
|
|||
sudo cp misc/block-snapshot /etc/xen/scripts/
|
||||
sudo cp aux-tools/qubes-dom0-updates.cron /etc/cron.daily/
|
||||
# FIXME(Abel Luck): I hope to
|
||||
```
|
||||
~~~
|
||||
|
||||
### Apply qvm-tools
|
||||
|
||||
TODO: make it more generic
|
||||
|
||||
```
|
||||
~~~
|
||||
#!/bin/sh
|
||||
|
||||
BAK=qvm-tools.bak$$
|
||||
mkdir -p $BAK
|
||||
cp -a /usr/bin/qvm-* /usr/bin/qubes-* $BAK/
|
||||
sudo cp qvm-tools/qvm-* qvm-tools/qubes-* /usr/bin/
|
||||
```
|
||||
~~~
|
||||
|
||||
### Copy from dom0 to an appvm
|
||||
|
||||
```
|
||||
~~~
|
||||
#/bin/sh
|
||||
#
|
||||
# usage ./cp-domain <vm_name> <file_to_copy>
|
||||
|
|
@ -199,4 +199,4 @@ fname=`basename $file`
|
|||
|
||||
qvm-run $domain 'mkdir /home/user/incoming/dom0 -p'
|
||||
cat $file| qvm-run --pass-io $domain "cat > /home/user/incoming/dom0/$fname"
|
||||
```
|
||||
~~~
|
||||
|
|
|
|||
|
|
@ -17,10 +17,10 @@ Build installer packages
|
|||
|
||||
Get [Qubes Installer repository](http://git.qubes-os.org/?p=smoku/installer) and build its packages:
|
||||
|
||||
```
|
||||
~~~
|
||||
cd installer
|
||||
make rpms
|
||||
```
|
||||
~~~
|
||||
|
||||
Packages will be in `rpm/noarch` and `rpm/x86_64`.
|
||||
|
||||
|
|
@ -29,57 +29,57 @@ Install Revisor
|
|||
|
||||
Next install the freshly built revisor and anaconda:
|
||||
|
||||
```
|
||||
~~~
|
||||
yum install rpm/noarch/revisor*.rpm
|
||||
yum install rpm/x86_64/anaconda*.rpm
|
||||
```
|
||||
~~~
|
||||
|
||||
Review configuration files
|
||||
--------------------------
|
||||
|
||||
All configuration files for Qubes Revisor are kept in the ```conf/``` directory:
|
||||
All configuration files for Qubes Revisor are kept in the ~~~conf/~~~ directory:
|
||||
|
||||
- ```conf/qubes-install.conf``` - Main Revisor configuration file. This configures Revisor to build Qubes Installation image based on Fedora 13. All other configuration files and working directories are pointed here.
|
||||
- ~~~conf/qubes-install.conf~~~ - Main Revisor configuration file. This configures Revisor to build Qubes Installation image based on Fedora 13. All other configuration files and working directories are pointed here.
|
||||
|
||||
- ```conf/qubes-x86_64.conf``` - This file describes all repositories needed to build Qubes for x86\_64 architecture.
|
||||
- ~~~conf/qubes-x86_64.conf~~~ - This file describes all repositories needed to build Qubes for x86\_64 architecture.
|
||||
|
||||
- ```conf/qubes-kickstart.cfg``` - Fedora Kickstart formatted file describing which packages should land in the ISO `/Packages` repository. This describes basically what will be available for installation. The packages list built using this file will be further filtered by the comps file.
|
||||
- ~~~conf/qubes-kickstart.cfg~~~ - Fedora Kickstart formatted file describing which packages should land in the ISO `/Packages` repository. This describes basically what will be available for installation. The packages list built using this file will be further filtered by the comps file.
|
||||
|
||||
- ```conf/comps-qubes.xml``` - Repository Comps file for ISO `/Packages` repository, describing packages and package groups of the installer repository. Package groups are used to select which of the packages are mandatory to install, which are optional and which are to be just available on the ISO but not installed by default (not used on Qubes).
|
||||
- ~~~conf/comps-qubes.xml~~~ - Repository Comps file for ISO `/Packages` repository, describing packages and package groups of the installer repository. Package groups are used to select which of the packages are mandatory to install, which are optional and which are to be just available on the ISO but not installed by default (not used on Qubes).
|
||||
|
||||
Create/Update local repository
|
||||
------------------------------
|
||||
|
||||
Revisor fetches all RPM packages from YUM repositories. We currently use 5 repositories:
|
||||
|
||||
- ```yum/installer``` (installer-related rpms)
|
||||
- ```yum/qubes-dom0``` (all the Qubes stuff)
|
||||
- ```yum/dom0-updates``` (for select 3rd party packages, e.g. Xorg)
|
||||
- ```yum/fedora13-repo``` (local fedora 13 repo, copy from DVD)
|
||||
- ~~~yum/installer~~~ (installer-related rpms)
|
||||
- ~~~yum/qubes-dom0~~~ (all the Qubes stuff)
|
||||
- ~~~yum/dom0-updates~~~ (for select 3rd party packages, e.g. Xorg)
|
||||
- ~~~yum/fedora13-repo~~~ (local fedora 13 repo, copy from DVD)
|
||||
- remote fedora repo for extra packages (usually deps for qubes-dom0)
|
||||
|
||||
You need to manually copy the Fedora 13 installation DVD contents (```Packages/``` and ```repodata/``` directories) into ```build/fedora13-repo```.
|
||||
You need to manually copy the Fedora 13 installation DVD contents (~~~Packages/~~~ and ~~~repodata/~~~ directories) into ~~~build/fedora13-repo~~~.
|
||||
|
||||
Also, you need to copy all the qubes dom0 rpms into ```build/yum/qubes-dom0/rpm``` and run the ```yum/update_repo.sh``` script afterwards.
|
||||
Also, you need to copy all the qubes dom0 rpms into ~~~build/yum/qubes-dom0/rpm~~~ and run the ~~~yum/update_repo.sh~~~ script afterwards.
|
||||
|
||||
In order to fill the ```build/yum/installer``` repo one can just use ```make update-repo```.
|
||||
In order to fill the ~~~build/yum/installer~~~ repo one can just use ~~~make update-repo~~~.
|
||||
|
||||
The ```build/yum/dom0-updates``` is to be used for select rpms that should also be used instead of those from the fedora (loacal and remote) repos.
|
||||
The ~~~build/yum/dom0-updates~~~ is to be used for select rpms that should also be used instead of those from the fedora (loacal and remote) repos.
|
||||
|
||||
Update your local repos:
|
||||
|
||||
```
|
||||
~~~
|
||||
make update-repo
|
||||
```
|
||||
~~~
|
||||
|
||||
Build ISO
|
||||
---------
|
||||
|
||||
Now you're finally ready to build the ISO image:
|
||||
|
||||
```
|
||||
~~~
|
||||
make iso
|
||||
```
|
||||
~~~
|
||||
|
||||
and wait...
|
||||
|
||||
|
|
|
|||
|
|
@ -13,9 +13,9 @@ The Qubes kde-dom0 project (see [Source Code](/doc/SourceCode/)) contains the so
|
|||
Getting the sources
|
||||
-------------------
|
||||
|
||||
```
|
||||
~~~
|
||||
git clone git://qubes-os.org/mainstream/kde-dom0.git kde-dom0
|
||||
```
|
||||
~~~
|
||||
|
||||
Building the packages
|
||||
---------------------
|
||||
|
|
@ -24,27 +24,27 @@ It's best to use Fedora 12 or 13 as a development system.
|
|||
|
||||
First, you should download and verify the original KDE sources (not part of the kde-dom0 repository):
|
||||
|
||||
```
|
||||
~~~
|
||||
make get-sources verify-sources
|
||||
```
|
||||
~~~
|
||||
|
||||
Now, check if you have all the required build dependencies:
|
||||
|
||||
```
|
||||
~~~
|
||||
make prep
|
||||
```
|
||||
~~~
|
||||
|
||||
Install any required packages that `make` might have complained about. Then you're ready to build the rpms (you might want to adjust the release of each rpm package by editing the `rel` variable at the beginning of each `.spec` file):
|
||||
|
||||
```
|
||||
~~~
|
||||
make rpms
|
||||
```
|
||||
~~~
|
||||
|
||||
**Note:** The `kdebase-*` packages build process requires corresponding `kdelibs-devel` package to be installed first. If your build system is based on Fedora 12/13, and if the `kdelibs-devel` package exist in Fedora repo that is based the same KDE software version (e.g. 4.4.3) as the KDE packages you're building (see the `version` file), than you should be able to use the Fedora package:
|
||||
|
||||
```
|
||||
~~~
|
||||
yum install kdelibs-devel-{version}
|
||||
```
|
||||
~~~
|
||||
|
||||
If not, then you should build your `kdelibs-devel` first (`cd kdelibs-devel && make rpms`), then install it on your build system, and then you can build all the rest (`make rpms`).
|
||||
|
||||
|
|
|
|||
|
|
@ -26,15 +26,15 @@ In order to use it one should use an rpm-based distro, like Fedora :) and should
|
|||
|
||||
Unusually one can install those packages by just issuing:
|
||||
|
||||
```
|
||||
~~~
|
||||
sudo yum install git createrepo rpm-build make wget rpmdevtools python-sh dialog rpm-sign
|
||||
```
|
||||
~~~
|
||||
|
||||
The build system creates build environments in chroots and so no other packages are needed on the host. All files created by the build system are contained within the qubes-builder directory. The full build requires some 25GB of free space, so keep that in mind when deciding where to place this directory.
|
||||
|
||||
The build system is configured via builder.conf file -- one should copy the attached builder.conf.default, and modify it as needed, e.g.:
|
||||
|
||||
```
|
||||
~~~
|
||||
cp builder.conf.default builder.conf
|
||||
# edit the builder.conf file and set the following variables:
|
||||
# (make sure to leave no spaces around '=' sign!)
|
||||
|
|
@ -44,23 +44,23 @@ NO_SIGN=1
|
|||
# and VMs is fc20 so if you want to build Qubes 2
|
||||
DIST_DOM0=fc20
|
||||
DISTS_VM=fc20
|
||||
```
|
||||
~~~
|
||||
|
||||
One additional useful requirement is that 'sudo root' work without any prompt, which is default on most distros (e.g. 'sudo bash' brings you the root shell without asking for any password). This is important as the builder needs to switch to root and then back to user several times during the build process.
|
||||
|
||||
Additionally, if building with signing enabled (so NO\_SIGN is not set), one must adjust \~/.rpmmacro file so that it point to the GPG key used for package signing, e.g.:
|
||||
|
||||
```
|
||||
~~~
|
||||
%_signature gpg
|
||||
%_gpg_path /home/user/.gnupg
|
||||
%_gpg_name AC1BF9B3 # <-- Key ID used for signing
|
||||
```
|
||||
~~~
|
||||
|
||||
It is also recommended to use an empty passphrase for the private key used for signing. Contrary to a popular belief, this doesn't affect your key or sources security -- if somebody compromised your system, then the game is over, whether you use additional passphrase for the key or not.
|
||||
|
||||
So, to build Qubes one would do:
|
||||
|
||||
```
|
||||
~~~
|
||||
# Import the Qubes master key
|
||||
gpg --recv-keys 0x36879494
|
||||
|
||||
|
|
@ -90,7 +90,7 @@ make qubes
|
|||
# ... and then to build the ISO
|
||||
|
||||
make iso
|
||||
```
|
||||
~~~
|
||||
|
||||
And this should produce a shiny new ISO.
|
||||
|
||||
|
|
@ -128,9 +128,9 @@ If you want to somehow modify sources, you can also do it, here are some basic s
|
|||
|
||||
> `get-sources` is already done, so continue with the next one. You can skip `sign-all` if you've disabled signing
|
||||
>
|
||||
> ```
|
||||
> ~~~
|
||||
> make xen core kernel gui addons docs template kde-dom0 installer qubes-manager dom0-updates
|
||||
> ```
|
||||
> ~~~
|
||||
|
||||
1. build iso installation image
|
||||
|
||||
|
|
@ -141,11 +141,11 @@ Code verification keys management
|
|||
|
||||
[QubesBuilder](/doc/QubesBuilder/) by default verifies signed tags on every downloaded code. Public keys used for that are stored in `keyrings/git`. By default Qubes developers' keys are imported automatically, but if you need some additional keys (for example your own), you can add them using:
|
||||
|
||||
```
|
||||
~~~
|
||||
GNUPGHOME=$PWD/keyrings/git gpg --import /path/to/key.asc
|
||||
GNUPGHOME=$PWD/keyrings/git gpg --edit-key ID_OF_JUST_IMPORTED_KEY
|
||||
# here use "trust" command to set key fully or ultimately trusted - only those keys are accepted by QubesBuilder
|
||||
```
|
||||
~~~
|
||||
|
||||
All Qubes developers' keys are signed by the Qubes Master Signing Key (which is set as ultimately trusted key), so are trusted automatically.
|
||||
|
||||
|
|
|
|||
|
|
@ -10,47 +10,47 @@ Building Qubes OS 3.0 ISO
|
|||
|
||||
Ensure your system is rpm-based and that you have necessary dependencies installed (see [QubesBuilder](/doc/QubesBuilder/) for more info):
|
||||
|
||||
```
|
||||
~~~
|
||||
sudo yum install git createrepo rpm-build make wget rpmdevtools pandoc
|
||||
```
|
||||
~~~
|
||||
|
||||
Get the necessary keys to verify the sources:
|
||||
|
||||
```
|
||||
~~~
|
||||
$ wget https://keys.qubes-os.org/keys/qubes-master-signing-key.asc
|
||||
$ gpg --import qubes-master-signing-key.asc
|
||||
$ gpg --edit-key 36879494
|
||||
# Verify fingerprint!, set trust to *ultimate*
|
||||
$ wget https://keys.qubes-os.org/keys/qubes-developers-keys.asc
|
||||
$ gpg --import qubes-developers-keys.asc
|
||||
```
|
||||
~~~
|
||||
|
||||
Note we do *not* relay above on the security of our server (keys.qubes-os.org) nor the connection (ssl, cert) -- we only rely on you getting the Qubes Master Signing Key fingerprint *somehow* and ensure they match!
|
||||
|
||||
Now lets bootstrap the builder. Unfortunately the builder cannot verify itself (the classic Chicken and Egg problem), so we need to verify the signature manually:
|
||||
|
||||
```
|
||||
~~~
|
||||
$ git clone git://github.com/QubesOS/qubes-builder.git
|
||||
$ cd qubes-builder
|
||||
$ git describe --exact-match HEAD
|
||||
<some tag>
|
||||
$ git tag -v <some tag>
|
||||
```
|
||||
~~~
|
||||
|
||||
Assuming the verification went fine, we're good to go with all the rest without ever thinking more about verifying digital signatures on all the rest of the components, as the builder will do that for us, for each component, every time we, even for all aux files (e.g. Xen or Linux kernel sources).
|
||||
|
||||
Let's configure the builder first (we can use one of the example configs, either for R2 or "master", which currently means pre-released R3):
|
||||
|
||||
```
|
||||
~~~
|
||||
cp example-configs/qubes-os-master.conf builder.conf
|
||||
```
|
||||
~~~
|
||||
|
||||
You can take a loot at the `builder.conf.default` for a description of all available options. Nevertheless, the default config should be enough for start:
|
||||
|
||||
```
|
||||
~~~
|
||||
$ make get-sources qubes
|
||||
$ make sign-all # this requires setting SIGN_KEY in the builder.conf, can be skipped for test builds.
|
||||
$ make iso
|
||||
```
|
||||
~~~
|
||||
|
||||
Enjoy your new ISO!
|
||||
|
|
|
|||
|
|
@ -115,7 +115,7 @@ compiled version to the right directory in the RPM file. I.e. adding `example.py
|
|||
### Editing \_\_init\_\_.py
|
||||
Add at the bottom of the file in the method `def load_tests` to the variable
|
||||
`modname` your test. I.e adding `example.py`.
|
||||
```python
|
||||
~~~python
|
||||
for modname in (
|
||||
'qubes.tests.basic',
|
||||
'qubes.tests.dom0_update',
|
||||
|
|
@ -126,4 +126,4 @@ Add at the bottom of the file in the method `def load_tests` to the variable
|
|||
'qubes.tests.regressions',
|
||||
'qubes.tests.example', # This is our newly added test
|
||||
):
|
||||
```
|
||||
~~~
|
||||
|
|
|
|||
|
|
@ -15,17 +15,17 @@ For the purpose of this document, `qubes-dev` is name of the domain used for pos
|
|||
Requirements
|
||||
------------
|
||||
|
||||
```
|
||||
~~~
|
||||
yum install gprof2dot graphviz
|
||||
git clone http://git.woju.eu/qubes/profiling.git
|
||||
```
|
||||
~~~
|
||||
|
||||
If you profile something on dom0, move `Upload.sh` from repository to dom0:
|
||||
|
||||
```
|
||||
~~~
|
||||
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.
|
||||
|
||||
|
|
@ -62,28 +62,28 @@ Remember to revert your changes to application afterwards.
|
|||
|
||||
If you are in dom0:
|
||||
|
||||
```
|
||||
~~~
|
||||
cd ~/profiling
|
||||
./Upload.sh
|
||||
```
|
||||
~~~
|
||||
|
||||
### Analyse
|
||||
|
||||
```
|
||||
~~~
|
||||
make
|
||||
```
|
||||
~~~
|
||||
|
||||
For every `${basename}.pstats` this will produce `${basename}.txt` and `${basename}.svg`. SVG contains call graph. Text file contains list of all functions sorted by cumulative execution time. You may also try `make all-png`.
|
||||
|
||||
```
|
||||
~~~
|
||||
make index.html
|
||||
```
|
||||
~~~
|
||||
|
||||
This creates `index.html` with all SVG graphics linked to TXT files. Ready for upload.
|
||||
|
||||
```
|
||||
~~~
|
||||
make REMOTE=example.com:public_html/qubes/profiling/ upload
|
||||
```
|
||||
~~~
|
||||
|
||||
Example
|
||||
-------
|
||||
|
|
|
|||
|
|
@ -57,9 +57,9 @@ Now configure your DHCP server so your testbench gets static IP and connect your
|
|||
|
||||
Install `openssh-server` on your testbench:
|
||||
|
||||
```
|
||||
~~~
|
||||
yum install openssh-server
|
||||
```
|
||||
~~~
|
||||
|
||||
Ensure that sudo works without password from your user account (it should by default).
|
||||
|
||||
|
|
@ -70,19 +70,19 @@ Development VM
|
|||
|
||||
Arrange firewall so you can reach the testbench from your `qubes-dev` VM. Generate SSH key in `qubes-dev`:
|
||||
|
||||
```
|
||||
~~~
|
||||
ssh-keygen -t ecdsa -b 521
|
||||
```
|
||||
~~~
|
||||
|
||||
Add the following section in `.ssh/config` in `qubes-dev`:
|
||||
|
||||
```
|
||||
~~~
|
||||
Host testbench
|
||||
# substitute username in testbench
|
||||
User user
|
||||
# substitute address of your testbench
|
||||
HostName 192.168.123.45
|
||||
```
|
||||
~~~
|
||||
|
||||
Then connect to your testbench and paste newly generated `id_ecdsa.pub` to `.ssh/authorized_keys` on testbench so you can log in without entering password every time.
|
||||
|
||||
|
|
|
|||
|
|
@ -46,7 +46,7 @@ Things get complicated if you need to perform kernel debugging or troubleshoot p
|
|||
- 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
|
||||
Waiting to reconnect...
|
||||
Connected to Windows 7 7601 x64 target at (Wed Mar 19 20:35:43.262 2014 (UTC + 1:00)), ptr64 TRUE
|
||||
|
|
@ -66,7 +66,7 @@ Things get complicated if you need to perform kernel debugging or troubleshoot p
|
|||
**************************************************************************
|
||||
Unable to read debugger data block header
|
||||
**************************************************************************
|
||||
```
|
||||
~~~
|
||||
|
||||
...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:
|
||||
|
||||
|
|
@ -193,7 +193,7 @@ Things get complicated if you need to perform kernel debugging or troubleshoot p
|
|||
|
||||
> 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
|
||||
|
|
@ -205,6 +205,6 @@ Things get complicated if you need to perform kernel debugging or troubleshoot p
|
|||
> Machine Name:
|
||||
> Kernel base = 0xfffff800`0261a000 PsLoadedModuleList = 0xfffff800`0285d6d0
|
||||
> System Uptime: not available
|
||||
> ```
|
||||
> ~~~
|
||||
|
||||
Happy debugging!
|
||||
|
|
|
|||
|
|
@ -100,7 +100,7 @@ Window manager hints and flags are described at [http://standards.freedesktop.or
|
|||
|
||||
Each message starts with the following header
|
||||
|
||||
```
|
||||
~~~
|
||||
struct msghdr {
|
||||
uint32_t type;
|
||||
uint32_t window;
|
||||
|
|
@ -111,7 +111,7 @@ struct msghdr {
|
|||
* whatever it wants! */
|
||||
uint32_t untrusted_len;
|
||||
};
|
||||
```
|
||||
~~~
|
||||
|
||||
The header is followed by message-specific data.
|
||||
|
||||
|
|
@ -183,12 +183,12 @@ Proper handling of the below messages is NOT security-critical.
|
|||
|
||||
Each message starts with the following header
|
||||
|
||||
```
|
||||
~~~
|
||||
struct msghdr {
|
||||
uint32_t type;
|
||||
uint32_t window;
|
||||
};
|
||||
```
|
||||
~~~
|
||||
|
||||
The header is followed by message-specific data.
|
||||
` KEYPRESS, BUTTON, MOTION, FOCUS ` messages pass information extracted from dom0 XEvent; see appropriate event documentation.
|
||||
|
|
|
|||
|
|
@ -31,7 +31,7 @@ Keeping Dom0 not connected to any network makes it hard, however, to provide upd
|
|||
|
||||
The update process is initiated by [qvm-dom0-update script](https://github.com/QubesOS/qubes-core-admin-linux/blob/release2/dom0-updates/qubes-dom0-update), running in Dom0.
|
||||
|
||||
Updates (\*.rpm files) are checked and downloaded by UpdateVM, which by default is the same as the firewall VM, but can be configured to be any other, network-connected VM. This is done by [qubes-download-dom0-updates.sh script](https://github.com/QubesOS/qubes-core-agent-linux/blob/release2/misc/qubes-download-dom0-updates.sh) (this script is executed using qrexec by the previously mentioned qvm-dom0-update). Note that we assume that this script might get compromised and might download a maliciously compromised downloads -- this is not a problem as Dom0 verifies digital signatures on updates later. The downloaded rpm files are placed in a ```/var/lib/qubes/dom0-updates``` directory on UpdateVM filesystem (again, they might get compromised while being kept there, still this isn't a problem). This directory is passed to yum using the ```--installroot=``` option.
|
||||
Updates (\*.rpm files) are checked and downloaded by UpdateVM, which by default is the same as the firewall VM, but can be configured to be any other, network-connected VM. This is done by [qubes-download-dom0-updates.sh script](https://github.com/QubesOS/qubes-core-agent-linux/blob/release2/misc/qubes-download-dom0-updates.sh) (this script is executed using qrexec by the previously mentioned qvm-dom0-update). Note that we assume that this script might get compromised and might download a maliciously compromised downloads -- this is not a problem as Dom0 verifies digital signatures on updates later. The downloaded rpm files are placed in a ~~~/var/lib/qubes/dom0-updates~~~ directory on UpdateVM filesystem (again, they might get compromised while being kept there, still this isn't a problem). This directory is passed to yum using the ~~~--installroot=~~~ option.
|
||||
|
||||
Once updates are downloaded, the update script that runs in UpdateVM requests an RPM service [qubes.ReceiveUpdates](https://github.com/QubesOS/qubes-core-admin-linux/blob/release2/dom0-updates/qubes.ReceiveUpdates) to be executed in Dom0. This service is implemented by [qubes-receive-updates script](https://github.com/QubesOS/qubes-core-admin-linux/blob/release2/dom0-updates/qubes-receive-updates) running in Dom0. The Dom0's qvm-dom0-update script (which originally initiated the whole update process) waits until qubes-receive-updates finished.
|
||||
|
||||
|
|
|
|||
|
|
@ -19,9 +19,9 @@ Typically, the first thing that a `qrexec-client` instance does is to send a req
|
|||
|
||||
E.g., to start a primitive shell in a VM type the following in Dom0 console:
|
||||
|
||||
```
|
||||
~~~
|
||||
[user@dom0 ~]$ /usr/lib/qubes/qrexec-client -d <vm name> user:bash
|
||||
```
|
||||
~~~
|
||||
|
||||
The string before first semicolon specifies what user to run the command as.
|
||||
|
||||
|
|
@ -65,9 +65,9 @@ In dom0, there is a bunch of files in `/etc/qubes-rpc/policy/` directory, whose
|
|||
|
||||
These files contain lines with the following format:
|
||||
|
||||
```
|
||||
~~~
|
||||
srcvm destvm (allow|deny|ask)[,user=user_to_run_as][,target=VM_to_redirect_to]
|
||||
```
|
||||
~~~
|
||||
|
||||
You can specify `srcvm` and `destvm` by name, or by one of `$anyvm`, `$dispvm`, `dom0` reserved keywords (note string `dom0` does not match the `$anyvm` pattern; all other names do). Only `$anyvm` keyword makes sense in the `srcvm` field (service calls from dom0 are currently always allowed, `$dispvm` means "new VM created for this particular request" - so it is never a source of request). Currently, there is no way to specify source VM by type, but this is planned for Qubes R3.
|
||||
|
||||
|
|
@ -80,9 +80,9 @@ Requesting VM-VM (and VM-Dom0) services execution
|
|||
|
||||
In a src VM, one should invoke the qrexec client via the following command:
|
||||
|
||||
```
|
||||
~~~
|
||||
/usr/lib/qubes/qrexec-client-vm <target vm name> <service name> <local program path> [local program arguments]`
|
||||
```
|
||||
~~~
|
||||
|
||||
Note that only stdin/stdout is passed between RPC server and client - notably, no cmdline argument are passed.
|
||||
|
||||
|
|
@ -103,9 +103,9 @@ Qubes RPC policy supports an "ask" action, that will prompt the user whether a g
|
|||
|
||||
In order to remove such authorization, issue this command from a Dom0 terminal (example below for qubes.Filecopy service):
|
||||
|
||||
```
|
||||
~~~
|
||||
sudo nano /etc/qubes-rpc/policy/qubes.Filecopy
|
||||
```
|
||||
~~~
|
||||
|
||||
and then remove any line(s) ending in "allow" (before the first \#\# comment) which are the "Yes to All" results.
|
||||
|
||||
|
|
@ -117,37 +117,37 @@ We will show the necessary files to create a simple RPC call that adds two integ
|
|||
|
||||
- Client code on source VM (`/usr/bin/our_test_add_client`)
|
||||
|
||||
```
|
||||
~~~
|
||||
#!/bin/sh
|
||||
echo $1 $2 # pass data to rpc server
|
||||
exec cat >&$SAVED_FD_1 # print result to the original stdout, not to the other rpc endpoint
|
||||
```
|
||||
~~~
|
||||
|
||||
- Server code on target VM (`/usr/bin/our_test_add_server`)
|
||||
|
||||
```
|
||||
~~~
|
||||
#!/bin/sh
|
||||
read arg1 arg2 # read from stdin, which is received from the rpc client
|
||||
echo $(($arg1+$arg2)) # print to stdout - so, pass to the rpc client
|
||||
```
|
||||
~~~
|
||||
|
||||
- Policy file in dom0 (`/etc/qubes-rpc/policy/test.Add`)
|
||||
|
||||
```
|
||||
~~~
|
||||
$anyvm $anyvm ask
|
||||
```
|
||||
~~~
|
||||
|
||||
- Server path definition on target VM (`/etc/qubes-rpc/test.Add`)
|
||||
|
||||
```
|
||||
~~~
|
||||
/usr/bin/our_test_add_server
|
||||
```
|
||||
~~~
|
||||
|
||||
- To test this service, run the following in the source VM:
|
||||
|
||||
```
|
||||
~~~
|
||||
/usr/lib/qubes/qrexec-client-vm <target VM> test.Add /usr/bin/our_test_add_client 1 2
|
||||
```
|
||||
~~~
|
||||
|
||||
and we should get "3" as answer, provided dom0 policy allows the call to pass through, which would happen after we click "Yes" in the popup that should appear after the invocation of this command. If we changed the policy from "ask" to "allow", then no popup should be presented, and the call will always be allowed.
|
||||
|
||||
|
|
|
|||
|
|
@ -87,37 +87,37 @@ We will show the necessary files to create rpc call that adds two integers on th
|
|||
|
||||
- rpc client code (*/usr/bin/our\_test\_add\_client*)
|
||||
|
||||
```
|
||||
~~~
|
||||
#!/bin/sh
|
||||
echo $1 $2 # pass data to rpc server
|
||||
exec cat >&$SAVED_FD_1 # print result to the original stdout, not to the other rpc endpoint
|
||||
```
|
||||
~~~
|
||||
|
||||
- rpc server code (*/usr/bin/our\_test\_add\_server*)
|
||||
|
||||
```
|
||||
~~~
|
||||
#!/bin/sh
|
||||
read arg1 arg2 # read from stdin, which is received from the rpc client
|
||||
echo $(($arg1+$arg2)) # print to stdout - so, pass to the rpc client
|
||||
```
|
||||
~~~
|
||||
|
||||
- policy file in dom0 (*/etc/qubes-rpc/policy/test.Add* )
|
||||
|
||||
```
|
||||
~~~
|
||||
$anyvm $anyvm ask
|
||||
```
|
||||
~~~
|
||||
|
||||
- server path definition ( */etc/qubes-rpc/test.Add*)
|
||||
|
||||
```
|
||||
~~~
|
||||
/usr/bin/our_test_add_server
|
||||
```
|
||||
~~~
|
||||
|
||||
- invoke rpc via
|
||||
|
||||
```
|
||||
~~~
|
||||
/usr/lib/qubes/qrexec-client-vm target_vm test.Add /usr/bin/our_test_add_client 1 2
|
||||
```
|
||||
~~~
|
||||
|
||||
and we should get "3" as answer, after dom0 allows it.
|
||||
|
||||
|
|
|
|||
|
|
@ -66,21 +66,21 @@ Qrexec protocol details
|
|||
|
||||
Qrexec protocol is message-based. All messages share a common header followed by an optional data packet.
|
||||
|
||||
```
|
||||
~~~
|
||||
/* uniform for all peers, data type depends on message type */
|
||||
struct msg_header {
|
||||
uint32_t type; /* message type */
|
||||
uint32_t len; /* data length */
|
||||
};
|
||||
```
|
||||
~~~
|
||||
|
||||
When two peers establish connection, the server sends `MSG_HELLO` followed by `peer_info` struct:
|
||||
|
||||
```
|
||||
~~~
|
||||
struct peer_info {
|
||||
uint32_t version; /* qrexec protocol version */
|
||||
};
|
||||
```
|
||||
~~~
|
||||
|
||||
The client then should reply with its own `MSG_HELLO` and `peer_info`. If protocol versions don't match, the connection is closed. TODO: fallback for backwards compatibility, don't do handshake in the same domain?.
|
||||
|
||||
|
|
@ -101,14 +101,14 @@ Details of all possible use cases and the messages involved are described below.
|
|||
- **dom0**: `qrexec-client` replies with `MSG_HELLO` header followed by `peer_info` to `qrexec-daemon`.
|
||||
- **dom0**: `qrexec-client` sends `MSG_EXEC_CMDLINE` header followed by `exec_params` to `qrexec-daemon`
|
||||
|
||||
```
|
||||
~~~
|
||||
/* variable size */
|
||||
struct exec_params {
|
||||
uint32_t connect_domain; /* target domain id */
|
||||
uint32_t connect_port; /* target vchan port for i/o exchange */
|
||||
char cmdline[0]; /* command line to execute, size = msg_header.len - sizeof(struct exec_params) */
|
||||
};
|
||||
```
|
||||
~~~
|
||||
|
||||
In this case, `connect_domain` and `connect_port` are set to 0.
|
||||
|
||||
|
|
@ -133,7 +133,7 @@ Details of all possible use cases and the messages involved are described below.
|
|||
- **domY**: `qrexec-client-vm` connects to `qrexec-agent` (via local socket/named pipe).
|
||||
- **domY**: `qrexec-client-vm` sends `trigger_service_params` data to `qrexec-agent` (without filling the `request_id` field):
|
||||
|
||||
```
|
||||
~~~
|
||||
struct trigger_service_params {
|
||||
char service_name[64];
|
||||
char target_domain[32];
|
||||
|
|
@ -143,7 +143,7 @@ Details of all possible use cases and the messages involved are described below.
|
|||
struct service_params {
|
||||
char ident[32];
|
||||
};
|
||||
```
|
||||
~~~
|
||||
|
||||
- **domY**: `qrexec-agent` allocates a locally-unique (for this domain) `request_id` (let's say `13`) and fills it in the `trigger_service_params` struct received from `qrexec-client-vm`.
|
||||
- **domY**: `qrexec-agent` sends `MSG_TRIGGER_SERVICE` header followed by `trigger_service_params` to `qrexec-daemon` in **dom0** via vchan.
|
||||
|
|
@ -159,14 +159,14 @@ Details of all possible use cases and the messages involved are described below.
|
|||
- **dom0**: `qrexec-client` replies with `MSG_HELLO` header followed by `peer_info` to **domX**'s`qrexec-daemon`.
|
||||
- **dom0**: `qrexec-client` sends `MSG_EXEC_CMDLINE` header followed by `exec_params` to **domX**'s`qrexec-daemon`
|
||||
|
||||
```
|
||||
~~~
|
||||
/* variable size */
|
||||
struct exec_params {
|
||||
uint32_t connect_domain; /* target domain id */
|
||||
uint32_t connect_port; /* target vchan port for i/o exchange */
|
||||
char cmdline[0]; /* command line to execute, size = msg_header.len - sizeof(struct exec_params) */
|
||||
};
|
||||
```
|
||||
~~~
|
||||
|
||||
In this case, `connect_domain` is set to id of **domY** (from the `-c` parameter) and `connect_port` is set to 0. `cmdline` field contains the RPC to execute, in this case `user:QUBESRPC qubes.SomeRpc domY`.
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue