Git-Mirrors/qubes-doc
1
0
Fork 0
mirror of https://github.com/QubesOS/qubes-doc.git synced 2024-10-01 01:25:40 -04:00
Code Issues Packages Projects Releases Wiki Activity

replaced all github flavored code blocks with fenced kramdown code blocks

Browse Source
This commit is contained in:
Jeepler 2015-09-27 01:00:33 +02:00
parent df467baf1c
commit 39ef7373fd
58 changed files with 609 additions and 609 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

32
common-tasks/BackupEmergencyRestoreV2.md
View File

@ -15,7 +15,7 @@ The Qubes backup system has been designed with emergency disaster recovery in mi
1. Untar the main backup file.
```
~~~
[user@restore ~]$ tar -i -xvf qubes-backup-2013-12-26-123456
backup-header
backup-header.hmac
@ -31,17 +31,17 @@ The Qubes backup system has been designed with emergency disaster recovery in mi
vm1/whitelisted-appmenus.list.000.hmac
dom0-home/dom0user.000
dom0-home/dom0user.000.hmac
```
~~~
1. Verify the integrity of the `private.img` file which houses your data.
```
~~~
[user@restore ~]$ cd vm1/
[user@restore vm1]$ openssl dgst -sha512 -hmac "your_passphrase" private.img.000
HMAC-SHA512(private.img.000)= cf83e1357eefb8bdf1542850d66d8007d620e4050b5715dc83f4a921d36ce9ce47d0d13c5d85f2b0ff8318d2877eec2f63b931bd47417a81a538327af927da3e
[user@restore vm1]$ cat private.img.000.hmac
(stdin)= cf83e1357eefb8bdf1542850d66d8007d620e4050b5715dc83f4a921d36ce9ce47d0d13c5d85f2b0ff8318d2877eec2f63b931bd47417a81a538327af927da3e
```
~~~
**Note:** The hash values should match. If they do not match, then the backup file may have been tampered with, or there may have been a storage error.
@ -49,59 +49,59 @@ The Qubes backup system has been designed with emergency disaster recovery in mi
1. Decrypt the `private.img` file.
```
~~~
[user@restore vm1]$ openssl enc -d -pass pass:your_passphrase -aes-256-cbc -in private.img.000 -out private.img.dec.000
```
~~~
**Note:** For multi-part files, a loop can be used:
```
~~~
for f in private.img.*; do
openssl enc -d -pass pass:your_passphrase -aes-256-cbc -in $f -out
${f/.img/.img.dec}
done
```
~~~
**Note:** If your backup was encrypted with a cipher algorithm other than `aes-256-cbc`, you must substitute the correct cipher command. A complete list of supported cipher algorithms can be found with `openssl list-cipher-algorithms`.
1. Decompress the decrypted `private.img` file.
```
~~~
[user@restore vm1]$ zforce private.img.dec.*
[user@restore vm1]$ gunzip private.img.dec.000.gz
```
~~~
**Note:** If your backup was compressed with a program other than `gzip`, you must substitute the correct compression program.
1. Untar the decrypted and decompressed `private.img` file.
```
~~~
[user@restore vm1]$ tar -M -xvf private.img.dec.000
vm1/private.img
```
~~~
**Note:** For multi-part files, a script is required:
1. Create a `new-volume-script`:
```
~~~
#!/bin/sh
name=`expr $TAR_ARCHIVE : '\(.*\)\..*'`
suffix=`printf %03d $[ $TAR_VOLUME - 1 ]`
echo $name.$suffix >&$TAR_FD
```
~~~
2. `chmod +x new-volume-script`.
3. `tar --new-volume-script=./new-volume-script -xvf private.img.dec.000`. (The `--new-volume-script` option enables multi-volume untaring.)
1. Mount the private.img file and access your data.
```
~~~
[user@restore vm1]$ sudo mkdir /mnt/img
[user@restore vm1]$ sudo mount -o loop vm1/private.img /mnt/img/
[user@restore vm1]$ cat /mnt/img/home/user/your_data.txt
This data has been successfully recovered!
```
~~~
**Note:** You may wish to store a plain text copy of these instructions with your Qubes backups in the event that you fail to recall the above procedure while this web page is inaccessible. You may obtain a plaintext version of this file in Git repository housing all the documentation at:

12
common-tasks/CopyPaste.md
View File

@ -52,22 +52,22 @@ Clipboard automatic policy enforcement
The Qubes clipboard policy is configurable in:
```
~~~
/etc/qubes-rpc/policy/qubes.ClipboardPaste
```
~~~
You may wish to configure this policy in order to prevent user error. For example, if you are certain that you never wish to paste *into* your "vault" AppVM (and it is highly recommended that you do not), then you should edit the policy as follows:
```
~~~
$anyvm vault deny
$anyvm $anyvm ask
```
~~~
Shortcut Configuration
----------------------
The copy/paste shortcuts are configurable in:
```
~~~
/etc/qubes/guid.conf
```
~~~

8
common-tasks/CopyToDomZero.md
View File

@ -12,15 +12,15 @@ First, there should normally be few reasons for the user to want to copy files f
For this reason we intentionally do not provide a convenient tool for copying files between VMs and Dom0 (while we provide a tool for copying files between VMs). However, if you're determined to copy some files to Dom0 anyway, you can use the following method (run this command from Dom0's console):
```
~~~
qvm-run --pass-io <src_domain> 'cat /path/to/file_in_src_domain' > /path/to/file_name_in_dom0
```
~~~
BTW, you can use the same method to copy files from Dom0 to VMs:
```
~~~
cat /path/to/file_in_dom0 | qvm-run --pass-io <dst_domain> 'cat > /path/to/file_name_in_appvm'
```
~~~
### Copying logs from dom0

12
common-tasks/DisposableVms.md
View File

@ -38,9 +38,9 @@ Opening a file in a Disposable VM via command line (from AppVM)
Use the `qvm-open-in-dvm` command line (from your AppVM), e.g.:
```
~~~
[user@work-pub ~]$ qvm-open-in-dvm Downloads/apple-sandbox.pdf
```
~~~
The qvm-open-in-dvm will not exit until you close the application in the Disposable VM.
@ -49,9 +49,9 @@ Starting an arbitrary application in a disposable VM via command line (from Dom0
**Note:** Normally there should be no need for doing this -- this is just for Qubes hackers ;)
```
~~~
[joanna@dom0 ~]$ echo xterm | /usr/lib/qubes/qfile-daemon-dvm qubes.VMShell dom0 DEFAULT red
```
~~~
In fact the Disposable VM appmenu used for starting Firefox contains a very similar command to the above. Please note, however, that it generally makes little sense to start any other application other than a Web Browser this way...
@ -60,9 +60,9 @@ Starting an arbitrary program in a Disposable VM from an AppVM
Sometimes it might be useful to start an arbitrary program, such as e.g. terminal in an Disposable VM from an AppVM. This could be simply done this way:
```
~~~
[user@vault ~]$ qvm-run '$dispvm' xterm
```
~~~
Note the above command is issued in an AppVM, not in Dom0. The created Disposable VM can be normally accessed via other tools, such as e.g. `qvm-copy-to-vm`, using its 'dispX' name, as shown by the Qubes Manager or `qvm-ls` tools.

8
common-tasks/FullScreenMode.md
View File

@ -30,19 +30,19 @@ If you want to enable full screen mode for select VMs, you can do that by creati
**Note:** There should be only one `VM: {}` block in the file (or you will [get into problems](https://groups.google.com/d/msg/qubes-users/-Yf9yNvTsVI/xXsEm8y2lrYJ))
```
~~~
VM: {
personal: {
allow_fullscreen = true;
};
};
```
~~~
The string 'personal' above is exemplary and should be replaced by the actual name of the VM for which you want to enable this functionality.
One can also enable this functionality for all the VMs globally in the same file, by modifying the 'global' section:
```
~~~
global: {
# default values
allow_fullscreen = true;
@ -51,6 +51,6 @@ global: {
#secure_paste_sequence = "Ctrl-Shift-v";
#windows_count_limit = 500;
};
```
~~~
Be sure to restart the VM(s) after modifying this file, for the changes to take effect.

24
common-tasks/SoftwareUpdateDom0.md
View File

@ -35,15 +35,15 @@ Of course, command line tools are still available for accomplishing various upda
1. To check and install updates for dom0 software:
```
~~~
$ sudo qubes-dom0-update
```
~~~
1. To install additional packages in dom0 (usually not recommended):
```
~~~
$ sudo qubes-dom0-update anti-evil-maid
```
~~~
You may also pass the `--enablerepo=` option in order to enable optional repositories (see yum configuration in dom0). However, this is only for advanced users who really understand what they are doing.
@ -51,30 +51,30 @@ Of course, command line tools are still available for accomplishing various upda
1. Download an older version of the package:
```
~~~
sudo qubes-dom0-update package-version
```
~~~
Yum will say that there is no update, but the package will nonetheless be downloaded to dom0.
1. Downgrade the packge:
```
~~~
sudo yum downgrade package-version
```
~~~
### Kernel Upgrade ###
Install newer kernel. The following example installs kernel 3.19 and was tested on Qubes R3 RC1.
```
~~~
sudo qubes-dom0-update kernel-3.19*
```
~~~
Rebuild grub config.
```
~~~
sudo grub2-mkconfig -o /boot/grub2/grub.cfg
```
~~~
Reboot required.

16
common-tasks/SoftwareUpdateVM.md
View File

@ -72,9 +72,9 @@ Sometime it might be convenient to have a VM that has its own filesystem, where
In order to create a standalone VM you can use a command line like this (from console in Dom0):
```
~~~
qvm-create <vmname> --standalone --label <label>
```
~~~
... or click appropriate options in the Qubes Manager's Create VM window.
@ -85,9 +85,9 @@ It's also possible to have more than one template VM in the system. E.g. one cou
When you create a new domain you can choose which template this VM should be based on. If you use command line, you should use the `--template` switch:
```
~~~
qvm-create <vmname> --template <templatename> --label <label>
```
~~~
Temporarily allowing networking for software installation
---------------------------------------------------------
@ -111,15 +111,15 @@ The proxy is running in selected VMs (by default all the NetVMs (1)) and interce
1. Updates proxy: It is running as "qubes-yum-proxy" service. Startup script of this service setup firewall rule to intercept proxy traffic:
```
~~~
iptables -t nat -A PR-QBS-SERVICES -d 10.137.255.254/32 -i vif+ -p tcp -m tcp --dport 8082 -j REDIRECT
```
~~~
1. VM using the proxy service Startup script (qubes-misc-post service) configure yum using /etc/yum.conf.d/qubes-proxy.conf file. It can either contain
```
~~~
proxy=http://10.137.255.254:8082/
```
~~~
line, or be empty. Note that this file is specifically included from main yum.conf, yum does not support real conf.d configuration style...

44
configuration/AssigningDevices.md
View File

@ -10,21 +10,21 @@ Assigning Devices to VMs
In order to assign a whole PCI(e) device to a VM, one should use `qvm-pci` tool. E.g.
```
~~~
lspci
```
~~~
Find the BDF address of the device you want to assign, and then:
```
~~~
qvm-pci -a <vmname> <bdf>
```
~~~
E.g. assuming 00:1a.0 is a BDF of the device I want to assign to the "personal" domain:
```
~~~
qvm-pci -a personal 00:1a.0
```
~~~
Note that one can only assign full PCI or PCI Express devices. This means one cannot assign single USB devices -- only the whole USB controller with whatever USB devices connected to it. This limit is imposed by PC and VT-d architecture.
@ -40,33 +40,33 @@ Finding the right USB controller
If you want assign certain USB device to a VM (by attaching a whole USB controller), you need to figure out which PCI device is the right controller. First check to which USB bus the device is connected:
```
~~~
lsusb
```
~~~
For example I want assign a broadband modem to the netvm. In lsusb output it can be listed as something like this (in this case device isn't fully identified):
```
~~~
Bus 003 Device 003: ID 413c:818d Dell Computer Corp.
```
~~~
The device is connected to the USB bus \#3. Then check which other devices are connected to the same bus - all of them will be assigned to the same VM. Now is the time to find right USB controller:
```
~~~
readlink /sys/bus/usb/devices/usb3
```
~~~
This should output something like:
```
~~~
../../../devices/pci-0/pci0000:00/0000:00:1a.0/usb3
```
~~~
Now you see BDF address in the path (right before final usb3). Strip leading "0000:" and pass the rest to qvm-pci tool:
```
~~~
qvm-pci -a netvm 00:1a.0
```
~~~
Possible issues
---------------
@ -75,11 +75,11 @@ Possible issues
VMs with assigned PCI devices in Qubes have allocated a small buffer for DMA operations (called swiotlb). By default it is 2MB, but some devices need a larger buffer. To change this allocation, edit VM's kernel parameters (this is expressed in 512B chunks):
```
~~~
# qvm-prefs netvm |grep kernelopts
kernelopts : iommu=soft swiotlb=2048 (default)
# qvm-prefs -s netvm kernelopts "iommu=soft swiotlb=4096"
```
~~~
This is [known to be needed](https://groups.google.com/group/qubes-devel/browse_thread/thread/631c4a3a9d1186e3) for Realtek RTL8111DL Gigabit Ethernet Controller.
@ -87,7 +87,7 @@ This is [known to be needed](https://groups.google.com/group/qubes-devel/browse_
Sometimes PCI arbitrator is too strict. There is a way to enable permissive mode for it. Create `/etc/systemd/system/qubes-pre-netvm.service`:
```
~~~
[Unit]
Description=Netvm fixup
Before=qubes-netvm.service
@ -99,7 +99,7 @@ RemainAfterExit=yes
[Install]
WantedBy=multi-user.target
```
~~~
Then enable it with `systemctl enable qubes-pre-netvm.service`
@ -118,11 +118,11 @@ or
1. Go to the sysfs (`/sys/bus/pci`), find the right device, detach it from the pciback driver and attach back to the original driver. Replace `<BDF>` with your device, for example `00:1c.2`:
```
~~~
echo 0000:<BDF> > /sys/bus/pci/drivers/pciback/unbind
MODALIAS=`cat /sys/bus/pci/devices/0000:<BDF>/modalias`
MOD=`modprobe -R $MODALIAS | head -n 1`
echo <BDF> > /sys/bus/pci/drivers/$MOD/bind
```
~~~

8
configuration/ConfigFiles.md
View File

@ -14,11 +14,11 @@ Those files are placed in /rw, which survives VM restart, so can be used to cust
- `/rw/config/rc.local` - script run at VM startup. Good place to change some service settings, replace config files with its copy stored in /rw/config etc. Example usage:
```
~~~
# Store bluetooth keys in /rw to keep them across VM restarts
rm -rf /var/lib/bluetooth
ln -s /rw/config/var-lib-bluetooth /var/lib/bluetooth
```
~~~
- `/rw/config/qubes-ip-change-hook` - script run in NetVM after external IP change (or connection to the network)
- `/rw/config/qubes-firewall-user-script` - script run in ProxyVM after firewall update. Good place to write own custom firewall rules
@ -31,7 +31,7 @@ GUI and audio configuration in dom0
GUI configuration file `/etc/qubes/guid.conf` in one of few not managed by qubes-prefs nor Qubes Manager tool. Sample config (included in default installation):
```
~~~
# Sample configuration file for Qubes GUI daemon
# For syntax go http://www.hyperrealm.com/libconfig/libconfig_manual.html
@ -55,7 +55,7 @@ VM: {
#allow_fullscreen = true;
};
};
```
~~~
Currently supported settings:

12
configuration/DiskTRIM.md
View File

@ -11,23 +11,23 @@ To enable TRIM in dom0 you need:
1. Get your LUKS device UUID:
```
~~~
ls /dev/mapper/luks-*
```
~~~
2. Add entry to `/etc/crypttab` (replace luks-\<UUID\> with the device name and the \<UUID\> with UUID alone):
```
~~~
luks-<UUID> UUID=<UUID> none allow-discards
```
~~~
3. Add `rd.luks.allow-discards=1` to kernel cmdline (`/etc/default/grub`, GRUB\_CMDLINE\_LINUX line)
4. Rebuild grub config (`grub2-mkconfig -o /boot/grub2/grub.cfg`)
5. Rebuild initrd **in hostonly mode**:
```
~~~
dracut -H -f
```
~~~
6. Add "discard" option to `/etc/fstab` for root device
7. Reboot the system, verify that allow-discards is really enabled (`dmsetup table`)

12
configuration/ExternalAudio.md
View File

@ -22,16 +22,16 @@ First you need to identify an user VM dedicated to audio and [assign a device](/
In a terminal of the template from which you user VM depends, install pavucontrol with:
```
~~~
sudo yum install pavucontrol
```
~~~
Close the template and start or restart your user VM, insert your external audio device, open a terminal and prepare pulseaudio to use it with:
```
~~~
sudo chmod a+rw /dev/snd/*
pactl load-module module-udev-detect
```
~~~
Start the audio application that is going to use the external audio device.
@ -39,8 +39,8 @@ Launch pavucontrol, for example using "run command in VM" of Qubes Manager and s
If you detach your external audio device, then want to insert it again, or change it with another one, you need to repeat the previous commands in terminal, adding an other line at the beginning:
```
~~~
pactl unload-module module-udev-detect
sudo chmod a+rw /dev/snd/*
pactl load-module module-udev-detect
```
~~~

4
configuration/ExternalDeviceMountPoint.md
View File

@ -7,8 +7,8 @@ redirect_from: /wiki/ExternalDeviceMountPoint/
All external storage devices connected to an AppVM using the Fedora template can be found under
```
~~~
/run/media/user/
```
~~~
...of that AppVM's filesystem.

12
configuration/Fetchmail.md
View File

@ -24,7 +24,7 @@ Assuming you have more than one account (safe assumption these days), you need t
In TemplateVM create `/etc/systemd/system/fetchmail@.service`:
```
~~~
[Unit]
Description=Mail Retrieval Agent
After=network.target
@ -34,11 +34,11 @@ Requires=postfix.service
User=user
ExecStart=/bin/fetchmail -f /usr/local/etc/fetchmail/%I.rc -d 60 -i /usr/local/etc/fetchmail/.%I.fetchids --pidfile /usr/local/etc/fetchmail/.%I.pid
RestartSec=1
```
~~~
Then shutdown TemplateVM, start AppVM and create directory `/usr/local/etc/fetchmail`. In it, create one `.rc` file for each instance of fetchmail, ie. `personal1.rc` and `personal2.rc`. Sample configuration file:
```
~~~
set syslog
set no bouncemail
#set daemon 600
@ -57,13 +57,13 @@ user woju pass supersecret
idle
# vim: ft=fetchmail
```
~~~
Then `chown -R user:user /usr/local/etc/fetchmail` and `chmod 600 /usr/local/etc/fetchmail/*.rc`. **This is important**, fetchmail will refuse to run with wrong permissions on its rc-file.
Next, add this to `/rw/config/rc.local`:
```
~~~
#!/bin/sh
for rc in /usr/local/etc/fetchmail/*.rc; do
@ -71,6 +71,6 @@ for rc in /usr/local/etc/fetchmail/*.rc; do
instance=${instance##*/}
echo systemctl --no-block start fetchmail@${instance}
done
```
~~~
Now reboot your AppVM and you are done.

12
configuration/Mutt.md
View File

@ -33,7 +33,7 @@ Mutt generally works out of the box. This configuration guide discusses only Qub
First, paste this to `/etc/Muttrc.local` in TemplateVM:
```
~~~
# specify your key or override in ~/.mutt/muttrc in AppVM
set pgp_sign_as="0xDEADBEEF"
@ -105,11 +105,11 @@ send-hook "~A" set pgp_autoinline=no crypt_autoencrypt=no
send-hook "~t @invisiblethingslab\.com" set crypt_autoencrypt=yes
# vim:ft=muttrc
```
~~~
Then shutdown your TemplateVM. Next open your AppVM, create file `/home/user/.mutt/muttrc` and adjust for your needs:
```
~~~
#
# accounts
#
@ -134,14 +134,14 @@ subscribe (qubes-(users|devel)|othergroup)@googlegroups\.com
fcc-save-hook qubes-users@googlegroups\.com =list/qubes-users/
fcc-save-hook qubes-devel@googlegroups\.com =list/qubes-devel/
fcc-save-hook othergroup@googlegroups\.com =list/othergroup/
```
~~~
You may also create `/home/user/.signature`:
```
~~~
regards,
Wojciech Porczyk
```
~~~
Some additional useful settings
-------------------------------

32
configuration/NetworkBridgeSupport.md
View File

@ -22,20 +22,20 @@ Qubes manager patch (Qubes R2B2)
The following patches can be applied to the Qubes Manager GUI in order to add an option to easily bridge a VM. Use it at your own risk. If the patch breaks the Qubes Manager, you can try to restore the qubes packages:
```
~~~
# qubes-dom-update qubes-core-dom0 qubes-manager
# yum reinstall qubes-core-dom0
# yum reinstall qubes-manager
```
~~~
First, retrieve the attachment of this Wifi article in dom0. Then apply the three patches the following way after installing the patch tool :
```
~~~
# qubes-dom0-update patch
# patch /usr/lib64/python2.7/site-package/qubes/qubes.py < qubes.py-bridge.diff
# patch /usr/lib64/python2.7/site-package/qubesmanager/settings.py < settings.py-bridge.diff
# patch /usr/lib64/python2.7/site-package/qubesmanager/ui_settingsdlg.py < ui_settingsdlg.py-bridge.diff
```
~~~
Finally restart the qubes manager GUI.
@ -50,7 +50,7 @@ Modify manually the Template you use for your NetVM (not the NetVM itself). This
- Starting from the line -A POSTROUTING -j MASQUERADE that you need to comment :
```
~~~
# Bridge support
# Comment the following line
#-A POSTROUTING -j MASQUERADE
@ -59,26 +59,26 @@ Modify manually the Template you use for your NetVM (not the NetVM itself). This
# Allow redirection of bridge packets (optional as POSTROUTING default is ACCEPT)
#-A POSTROUTING -o bridge+ -j ACCEPT
# End Bridge support
```
~~~
- Starting from the line -A FORWARD -i vif+ -j ACCEPT:
```
~~~
-A FORWARD -i vif+ -o vif+ -j DROP
-A FORWARD -i vif+ -j ACCEPT
# Bridge Support
-A FORWARD -i bridge+ -j ACCEPT
# End Bridge Support
-A FORWARD -j DROP
```
~~~
Ensure that the IP addresses used by default in qubes are in the form 10.137.1.\* or 10.137.2.\* by running ifconfig. Of course, this setup won't work with IPv6.
Now you need to restart the NetVM and FirewallVM or only iptables in both VMs if you prefer:
```
~~~
# systemctl restart iptables
```
~~~
Create a Bridge inside the NetVM
--------------------------------
@ -96,7 +96,7 @@ The bridge edition GUI is somehow buggy as it does not remember all the paramete
- Bridge-DHCP
```
~~~
[connection]
id=Bridge-DHCP
uuid=fd68198b-313a-47cb-9155-52e95cdc67f3
@ -113,13 +113,13 @@ The bridge edition GUI is somehow buggy as it does not remember all the paramete
[bridge]
interface-name=bridge0
stp=false
```
~~~
Note: Do not forget to put stp=false if you bridge only eth0 because sending BPDUs could make your admins angry :)
- bridge0-eth0
```
~~~
[802-3-ethernet]
duplex=full
mac-address=88:AE:1D:AE:30:31
@ -132,12 +132,12 @@ Note: Do not forget to put stp=false if you bridge only eth0 because sending BPD
timestamp=1363601650
master=fd68198b-313a-47cb-9155-52e95cdc67f3
slave-type=bridge
```
~~~
If you do not manager to start your bridge, you can start it manually from a NetVM terminal:
```
~~~
$ nmcli con up id bridge0-eth0
```
~~~
Now that the bridge is ready, the bridged AppVM can be started...

36
configuration/Postfix.md
View File

@ -22,9 +22,9 @@ Configuration
In TemplateVM open `/etc/aliases` and add line:
```
~~~
root: user
```
~~~
and run `newaliases`.
@ -36,7 +36,7 @@ Now shutdown TemplateVM, start AppVM. Create directory `/usr/local/etc/postfix`
Postfix keeps its lookup tables in bdb hash databases. They need to be compiled from source files. Postfix admins like to keep track of them by means of `/usr/local/etc/postfix/Makefile`:
```
~~~
all: $(addsuffix .db,$(shell sed -n -e '/^[^#].*hash:\/etc\/postfix/s:.*/::p' main.cf))
newaliases
clean:
@ -45,13 +45,13 @@ clean:
%.db: %
/usr/sbin/postmap hash:$<
```
~~~
### Postfix main configuration
`/usr/local/etc/postfix/main.cf` (`/etc/postfix` is intentional, don't correct it):
```
~~~
mydestination = $myhostname, $myhostname.$mydomain, $myhostname.localdomain, localhost, localhost.$mydomain, localhost.localdomain, $mydomain, localdomain
mynetworks_style = host
@ -84,36 +84,36 @@ sendmail_path = /usr/sbin/sendmail
newaliases_path = /usr/bin/newaliases
mailq_path = /usr/bin/mailq
alias_maps = hash:/etc/aliases
```
~~~
### Lookup tables
`/usr/local/etc/postfix/generic` (put there your primary address):
```
~~~
@localhost your.mail@example.com
```
~~~
`/usr/local/etc/postfix/sender_relay`. This is important file. Put there all your SMTP servers. Pay attention to port (smtp/submission). Square brackets have their special meaning, they are almost certainly needed. For more info consult Postfix manual.
```
~~~
your.mail@exmaple.com [mail.example.com]:submission
your.other@mail.com [smtp.mail.com]:smtp
```
~~~
`/usr/local/etc/postfix/saslpass`. Here you put passwords to abovementioned servers. It depends on provider if you need to put whole email as username or just the part before `@`.
```
~~~
[mail.example.com]:submission your.mail:y0urP4ssw0rd
[smtp.mail.com]:smtp your.other@mail.com:supers3cret
```
~~~
`/usr/local/etc/postfix/sender_access`. I use it to nullroute known spam domains. If you do not need it, comment respective line in `main.cf`.
```
~~~
spamdomain1.com DISCARD
spamdomain2.com DISCARD
```
~~~
Now run `make` in `/usr/local/etc/postfix`. It will hopefully compile four abovementioned lookup tables (`generic.db`, `sender_relay.db`, `saslpass.db` and `sender_access`).
@ -121,7 +121,7 @@ Now run `make` in `/usr/local/etc/postfix`. It will hopefully compile four above
Don't start postfix or fetchmail yet, first create `/home/user/.procmailrc`:
```
~~~
MAILDIR = "${HOME}/.maildir"
ORGMAIL = "${MAILDIR}/"
DEFAULT = "${MAILDIR}/"
@ -133,18 +133,18 @@ list/qubes-users/
:0
* ^List-Id:.*qubes-devel\.googlegroups\.com
list/qubes-devel/
```
~~~
Run
---
Open `/rw/config/rc.local` and add those two lines (before fetchmail lines, if you have them):
```
~~~
#!/bin/sh
mount --bind /usr/local/etc/postfix /etc/postfix
systemctl --no-block start postfix
```
~~~
Reboot your AppVM and you are done.

32
configuration/ResizeDiskImage.md
View File

@ -17,17 +17,17 @@ There are several disk images which can be easily extended.
To grow the private disk image of a AppVM beyond this limit [qubes-grow-private](/doc/Dom0Tools/QvmGrowPrivate/) can be used:
```
~~~
qvm-grow-private <vm-name> <size>
```
~~~
Note: Size is the target size (i.e. 4096MB or 16GB, ...), not the size to add to the existing disk.
Note2: If once the VM is started, the disk is has not been increased, you can issue in the VM's terminal:
```
~~~
sudo resize2fs /dev/xvdb
```
~~~
### Shrinking private disk image (Linux VM)
@ -40,14 +40,14 @@ The basic idea is to:
Ext4 does not support online shrinking, so can't be done as convenient as image grown. Note that we don't want to touch the VM filesystem directly in dom0 for security reasons. First you need to start VM without `/rw` mounted. One of the possibility is to interrupt its normal startup by adding `rd.break` kernel option:
```
~~~
qvm-prefs -s <vm-name> kernelopts rd.break
qvm-start --no-guid <vm-name>
```
~~~
And wait for qrexec connect timeout (or simply press Ctrl-C). Then you can connect to VM console and shrink the filesystem:
```
~~~
sudo xl console <vm-name>
# you should get dracut emergency shell here
mount --bind /dev /sysroot/dev
@ -59,19 +59,19 @@ umount /proc
exit
umount /sysroot/dev
poweroff
```
~~~
Now you can resize the image:
```
~~~
truncate -s <new-desired-size> /var/lib/qubes/appvms/<vm-name>/private.img
```
~~~
**It is critical to use the same (or bigger for some safety margin) size in truncate call compared to resize2fs call. Otherwise you will loose your data!** Then reset kernel options back to default:
```
~~~
qvm-prefs -s <vm-name> kernelopts default
```
~~~
Done.
@ -97,12 +97,12 @@ First, stop/shutdown the HVM.
Then, from a Dom0 terminal (in KDE: System Tools -\> Terminal Emulator) do the following:
```
~~~
cd /var/lib/qubes/appvms/<yourHVM>/
ls -lh root.img (<--verify current size of disk image)
truncate -s 30GB root.img
ls -lh root.img (<--verify new size of disk image)
```
~~~
The partition table and file-system must be adjusted after this change:
@ -117,9 +117,9 @@ No reboot required.
#### FreeBSD
```
~~~
gpart recover ada0
sysctl kern.geom.debugflags=0x10
gpart resize -i index ada0
zpool online -e poolname ada0
```
~~~

8
configuration/ResizeRootDiskImage.md
View File

@ -16,14 +16,14 @@ template between reboots didn't exceed 10G).
Replace the size and the path (name) of the template as wished and run your
modified command:
```
~~~
truncate -s 20G /var/lib/qubes/vm-templates/fedora-21/root.img
```
~~~
Then start your template or standalone VM and run:
```
~~~
sudo resize2fs /dev/mapper/dmroot
```
~~~
after that shutdown the template.

8
configuration/Rxvt.md
View File

@ -20,7 +20,7 @@ Xresources
In TemplateVM create file `/etc/X11/Xresources.urxvt` and paste config below. `!`-lines are comments and may be left out. `#`-lines are directives to CPP (C preprocessor) and are neccessary. This shouldn't go to `/etc/X11/Xresources`, because that file is not preprocessed by default.
```
~~~
! CGA colour palette
!*color0: #000000
@ -123,15 +123,15 @@ URxvt.insecure: False
! some termcap-aware software sometimes throw '$TERM too long'
!URxvt.termName: rxvt-256color
```
~~~
Then create script to automatically merge those to xrdb. File `/etc/X11/xinit/xinitrc.d/urxvt.sh`:
```
~~~
#!/bin/sh
[ -r /etc/X11/Xresources.urxvt ] && xrdb -merge /etc/X11/Xresources.urxvt
```
~~~
Shortcuts
---------

56
configuration/ZFS.md
View File

@ -20,14 +20,14 @@ Install DKMS style packages for Fedora <sup>(defunct\\ in\\ 0.6.2\\ due\\ to\\ s
Fetch and install repository for DKMS style packages for your Dom0 Fedora version [http://zfsonlinux.org/fedora.html](http://zfsonlinux.org/fedora.html):
```
~~~
disp1# wget http://archive.zfsonlinux.org/fedora/zfs-release-1-1$(rpm -E %dist).noarch.rpm
dom0# qvm-run --pass-io disp1 'cat /home/user/zfs-release-1-1.fc18.noarch.rpm' > /home/user/zfs-release-1-1.fc18.noarch.rpm
dom0# sudo yum localinstall /home/user/zfs-release-1-1.fc18.noarch.rpm
dom0# sudo sed -i 's/$releasever/18/g' /etc/yum.repo.d/zfs.repo
dom0# sudo qubes-dom0-update @development-tools
dom0# sudo qubes-dom0-update zfs
```
~~~
Install DKMS style packages from git-repository
-----------------------------------------------
@ -38,57 +38,57 @@ Build and install your DKMS or KMOD packages as described in [http://zfsonlinux.
Checkout repositories for SPL and ZFS:
```
~~~
mkdir ~/repositories && cd ~/repositories
git clone https://github.com/zfsonlinux/spl.git
git clone https://github.com/zfsonlinux/zfs.git
```
~~~
Revert changes in SPL repository due to this bug: [https://github.com/zfsonlinux/spl/issues/284](https://github.com/zfsonlinux/spl/issues/284)
```
~~~
cd ~/repositories/spl
git config --global user.email "user@example.com"
git config --global user.name "user"
git revert e3c4d44886a8564e84aa697477b0e37211d634cd
```
~~~
### Installation steps in Dom0
Copy repositories over to Dom0:
```
~~~
mkdir ~/repositories
qvm-run --pass-io disp1 'tar -cf - -C ~/repositories/ {spl,zfs}' | tar -xpf - -C ~/repositories/
```
~~~
Installing build requirements for SPL and ZFS DKMS modules:
```
~~~
sudo qubes-dom0-update dkms kernel-devel zlib-devel libuuid-devel libblkid-devel lsscsi bc autoconf automake binutils bison flex gcc gcc-c++ gdb gettext libtool make pkgconfig redhat-rpm-config rpm-build strace
```
~~~
Configure and build SPL DKMS packages:
```
~~~
cd ~/repositories/spl
./autogen.sh
./configure --with-config=user
make rpm-utils rpm-dkms
```
~~~
Configure and build ZFS DKMS packages:
```
~~~
cd ~/repositories/zfs
./autogen.sh
./configure --with-config=user
make rpm-utils rpm-dkms
```
~~~
Install SPL and ZFS packages (i.e. version 0.6.2):
```
~~~
sudo yum localinstall \
~/repositories/spl/spl-0.6.2-1.qbs2.x86_64.rpm \
~/repositories/spl/spl-dkms-0.6.2-1.qbs2.noarch.rpm \
@ -96,7 +96,7 @@ sudo yum localinstall \
~/repositories/zfs/zfs-dkms-0.6.2-1.qbs2.noarch.rpm \
~/repositories/zfs/zfs-dracut-0.6.2-1.qbs2.x86_64.rpm \
~/repositories/zfs/zfs-test-0.6.2-1.qbs2.x86_64.rpm
```
~~~
Configure ZFS
=============
@ -106,13 +106,13 @@ Automatically load modules
/etc/sysconfig/modules/zfs.modules
```
~~~
#!/bin/sh
for module in spl zfs; do
modprobe ${module} >/dev/null 2>&1
done
```
~~~
Make this file executable.
@ -123,9 +123,9 @@ Tame the memory-eating dragon (i.e. 512 Mb zfs\_arc\_max):
/etc/modprobe.d/zfs.conf
```
~~~
options zfs zfs_arc_max=536870912
```
~~~
Setup a zpool with ZFS datasets
-------------------------------
@ -138,7 +138,7 @@ Beware: VMs on a ZFS dataset aren't working, if your ZFS installation deserts yo
So keep netvm, firewallvm and your templates on your root file-system (preferably on a SSD).
```
~~~
zpool create -m none -o ashift=12 -O atime=off -O compression=lz4 qubes mirror /dev/mapper/<cryptname1> /dev/mapper/<cryptname2>
zfs create -p qubes/appvms
zfs create -m /var/lib/qubes/backup-zfs qubes/backup
@ -146,7 +146,7 @@ zfs create -m /var/lib/qubes/appvms/banking qubes/appvms/banking
zfs create -m /var/lib/qubes/appvms/personal qubes/appvms/personal
zfs create -m /var/lib/qubes/appvms/untrusted qubes/appvms/untrusted
zfs create -m /var/lib/qubes/appvms/work qubes/appvms/work
```
~~~
Have fun with zpool and zfs.
@ -161,28 +161,28 @@ You're depending on an huge amount of code for this file system, keep this in mi
Encrypt underlying devices
--------------------------
```
~~~
dom0# cryptsetup -c aes-xts-plain64 luksFormat <device1>
dom0# cryptsetup luksOpen <device1> <cryptname1>
```
~~~
With the use of cryptsetup a keyfile can be specified to decrypt devices.
```
~~~
dom0# head -c 256 /dev/random > /root/keyfile1
dom0# chmod 0400 /root/keyfile1
dom0# cryptsetup luksAddKey <device1> /root/keyfile1
```
~~~
Decrypt devices on boot
-----------------------
Add your devices to /etc/crypttab.
```
~~~
<cryptname1> <device1> <keyfile1>
<cryptname2> <device2> none
```
~~~
Specifying a keyfile is especially useful, if ZFS should be ready during boot.

20
developers/CodingStyle.md
View File

@ -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.

8
developers/SourceCode.md
View File

@ -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

68
developers/building/BuildingArchlinuxTemplate.md
View File

@ -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
```
~~~

16
developers/building/BuildingNonFedoraTemplate.md
View File

@ -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

56
developers/building/DevelopmentWorkflow.md
View File

@ -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"
```
~~~

42
developers/building/InstallationIsoBuilding.md
View File

@ -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...

20
developers/building/KdeDom0.md
View File

@ -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`).

24
developers/building/QubesBuilder.md
View File

@ -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.

20
developers/building/QubesR3Building.md
View File

@ -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!

4
developers/debugging/AutomatedTests.md
View File

@ -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
):
```
~~~

24
developers/debugging/Profiling.md
View File

@ -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
-------

12
developers/debugging/TestBench.md
View File

@ -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.

8
developers/debugging/WindowsDebugging.md
View File

@ -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!

8
developers/fundamentals/GUIdocs.md
View File

@ -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.

2
developers/services/Dom0SecureUpdates.md
View File

@ -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.

36
developers/services/Qrexec.md
View File

@ -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.

20
developers/services/Qrexec3.md
View File

@ -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.

20
developers/services/Qrexec3Implementation.md
View File

@ -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`.

12
installing/UpgradeToR2.md
View File

@ -33,9 +33,9 @@ Note that dom0 in R2 is based on Fedora 20, in contrast to Fedora 18 in previous
1. Install all the updates for Dom0:
```
~~~
sudo qubes-dom0-update
```
~~~
After this step you should have `qubes-release-2-5` in your Dom0. Important: if you happen to have `qubes-release-2-6*` then you should downgrade to `qubes-release-2-5`! The `qubes-release-2-6*` packages have been uploaded to the testing repos and were kept there for a few hours, until we realized they bring incorrect repo definitions and so we removed them and also have changed the update procedure a bit (simplifying it).
@ -43,18 +43,18 @@ After this step you should have `qubes-release-2-5` in your Dom0. Important: if
Note: be sure that the VM used as a update-downloading-vm (by default its the firewallvm based on the default template) has been updated to the latest qubes packages, specifically `qubes-core-vm-2.1.33` or later. This doesn't imply that the VM must already be upgraded to fc20 -- for Dom0 upgrade we could still use an fc18-based VM (updatevm) it is only important to install the latest Qubes packages there.
```
~~~
sudo qubes-dom0-update qubes-dom0-dist-upgrade
sudo qubes-dom0-update
```
~~~
1. If above step completed successfully you should have `qubes-release-2-9` or later. If not, repeat above step with additional `--clean` option.
4a. If you chose not to upgrade your fc18 templates, but instead to download our new fc20-based template you should now be able to do that by simply typing:
```
~~~
sudo qubes-dom0-update qubes-template-fedora-20-x64
```
~~~
1. Reboot the system.

20
installing/UpgradeToR2B1.md
View File

@ -22,26 +22,26 @@ By default, in Qubes R1, there is only one Template VM, however users are free t
1. Open terminal in the template VM (or standalone VM). E.g. use the Qubes Manager's right-click menu and choose Run Command in VM and type `gnome-terminal` there.
2. Install `qubes-upgrade-vm` package (this package brings in R2 repo definitions and R2 keys)
```
~~~
sudo yum install qubes-upgrade-vm
```
~~~
3. Proceed with normal update in the template (this should bring in also the R2 packages for the VMs):
```
~~~
sudo yum update
```
~~~
The installer (yum) will prompt to accept the new Qubes R2 signing key:
```
~~~
Importing GPG key 0x0A40E458:
Userid : "Qubes OS Release 2 Signing Key"
Fingerprint: 3f01 def4 9719 158e f862 66f8 0c73 b9d4 0a40 e458
Package : qubes-upgrade-vm-1.0-1.fc17.x86_64 (@qubes-vm-current)
From : /etc/pki/rpm-gpg/RPM-GPG-KEY-upgrade-qubes-2-primary
Is this ok [y/N]:
```
~~~
If you see (as is the case on the "screenshot" above) that the new key was imported from a local filesystem (`/etc/pki/rpm-gpg/...`) you can safely accept the key, without checking its fingerprint. This is because there were only two ways for such a key to make it to your Template VM's filesystem:
@ -58,17 +58,17 @@ Be sure to do steps described in this section after *all* your template and stan
1. Open terminal in Dom0. E.g. Start-\>System Settings-\>Konsole.
2. Upgrade the `qubes-release` package to the latest version which brings in new repo definitions and R2 signing keys:
```
~~~
sudo qubes-dom0-update qubes-release
```
~~~
This should install `qubes-release-1-6` in your Dom0.
3. Install R2 packages:
```
~~~
sudo qubes-dom0-update --releasever=2
```
~~~
4. Reboot your system. Please note that if you use Anti Evil Maid, then it won't be able to unseal the passphrase this time, because the Xen, kernel, and initramfs binaries have changed. Once the system boots up again, you could reseal your Anti Evil Maid's passphrase to the new configuration. Please consult Anti Evil Maid documentation for explanation on how to do that.

32
installing/UpgradeToR2B2.md
View File

@ -20,26 +20,26 @@ By default, in Qubes R1, there is only one Template VM, however users are free t
1. Open terminal in the template VM (or standalone VM). E.g. use the Qubes Manager's right-click menu and choose Run Command in VM and type `gnome-terminal` there.
2. Install `qubes-upgrade-vm` package (this package brings in R2 repo definitions and R2 keys)
```
~~~
sudo yum install qubes-upgrade-vm
```
~~~
3. Proceed with normal update in the template (this should bring in also the R2 packages for the VMs):
```
~~~
sudo yum update
```
~~~
The installer (yum) will prompt to accept the new Qubes R2 signing key:
```
~~~
Importing GPG key 0x0A40E458:
Userid : "Qubes OS Release 2 Signing Key"
Fingerprint: 3f01 def4 9719 158e f862 66f8 0c73 b9d4 0a40 e458
Package : qubes-upgrade-vm-1.0-1.fc17.x86_64 (@qubes-vm-current)
From : /etc/pki/rpm-gpg/RPM-GPG-KEY-upgrade-qubes-2-primary
Is this ok [y/N]:
```
~~~
If you see (as is the case on the "screenshot" above) that the new key was imported from a local filesystem (`/etc/pki/rpm-gpg/...`) you can safely accept the key, without checking its fingerprint. This is because there were only two ways for such a key to make it to your Template VM's filesystem:
@ -53,13 +53,13 @@ Installing new template
Qubes R2 Beta2 brings new fedora-18-x64 template (based on Fedora 18). You can install it from Qubes installation DVD. Insert installation DVD into your drive and issue following commmands:
```
~~~
$ sudo -s
# mkdir -p /mnt/cdrom
# mount /dev/cdrom /mnt/cdrom # you can also use ISO image instead of /dev/cdrom; then add -o loop option
# yum install /mnt/cdrom/Packages/q/qubes-template-fedora-18-x64*rpm
# umount /mnt/cdrom
```
~~~
If you already have fedora-17-x64, you can also upgrade it to fedora-18-x64 following [standard Fedora upgrade procedure](http://fedoraproject.org/wiki/Upgrading_Fedora_using_yum) (only "yum" method will work in Qubes VM).
@ -71,31 +71,31 @@ Be sure to do steps described in this section after *all* your template and stan
1. Open terminal in Dom0. E.g. Start-\>System Settings-\>Konsole.
2. Upgrade the `qubes-release` package to the latest version which brings in new repo definitions and R2 signing keys:
```
~~~
sudo qubes-dom0-update qubes-release
```
~~~
This should install `qubes-release-1-6` in your Dom0.
3. Install R2 upgrade package:
```
~~~
sudo qubes-dom0-update --releasever=1 qubes-dist-upgrade
```
~~~
4. Start upgrade process:
```
~~~
sudo qubes-dist-upgrade
```
~~~
5. Follow instructions on screen, first stage of upgrade should end up with reboot request.
6. Reboot your system, ensure that you choose "Qubes Upgrade" boot option.
7. When system starts up, login and start start
```
~~~
sudo qubes-dist-upgrade
```
~~~
again. This will start second stage of upgrade, here most packages will be upgraded, so this will take a while.

24
installing/UpgradeToR2B3.md
View File

@ -24,21 +24,21 @@ It is critical to complete this step **before** proceeding to dom0 upgrade. Othe
1. Open terminal in the template VM (or standalone VM). E.g. use the Qubes Manager's right-click menu and choose Run Command in VM and type `gnome-terminal` there.
2. Proceed with normal update in the template:
```
~~~
sudo yum update
```
~~~
3. Ensure that you've got qubes-core-vm package version 2.1.13-3.fc18:
```
~~~
rpm -q qubes-core-vm
```
~~~
4. Update the system to R2 beta3 packages:
```
~~~
sudo yum --enablerepo=qubes-vm-r2b3-current update
```
~~~
5. **Do not** shutdown the VM.
@ -50,24 +50,24 @@ Be sure to do steps described in this section after *all* your template and stan
1. Open terminal in Dom0. E.g. Start-\>System Settings-\>Konsole.
2. Upgrade the `qubes-release` package to the latest version which brings in new repo definitions and R2 signing keys:
```
~~~
sudo qubes-dom0-update qubes-release
```
~~~
This should install `qubes-release-2-3.1` in your Dom0.
3. Upgrade dom0 to R2 beta3:
```
~~~
sudo qubes-dom0-update --enablerepo=qubes-dom0-r2b3-current
```
~~~
4. If above step completed successfully you should have qubes-core-dom0 at least 2.1.34. If not, repeat above step with additional `--clean` option.
5. Now is the time to shutdown all the VMs:
```
~~~
qvm-shutdown --all --wait
```
~~~
6. Reboot the system.

24
managing-os/FedoraTemplateUpgrade18.md
View File

@ -17,32 +17,32 @@ Upgrading Fedora 18 to Fedora 20
Commands to run in dom0 console (you can do the same from Qubes Manager):
```
~~~
qvm-clone fedora-18-x64 fedora-20-x64
qvm-run -a fedora-20-x64 gnome-terminal
```
~~~
Commands to run in new fedora-20-x64 template:
```
~~~
sudo yum --releasever=20 distro-sync
poweroff
```
~~~
If you have installed a lot of software in your template, it may happen that you don't have enough disk space for upgrade. Yum will tell you this just after confirming the operation (before it change anything to your system). In that case you need to provide some "external" place for yum cache (uses about 2GB during upgrade). For example attach virtual disk stored in some file. Prepare the file in dom0:
```
~~~
truncate -s 5GB /var/tmp/template-upgrade-cache.img
qvm-block -A fedora-20-x64 dom0:/var/tmp/template-upgrade-cache.img
```
~~~
Then use it in template:
```
~~~
sudo mkfs.ext4 /dev/xvdi
sudo mount /dev/xvdi /mnt/removable
sudo yum --releasever=20 --setopt=cachedir=/mnt/removable distro-sync
```
~~~
After upgrade is finished, you can remove /var/tmp/template-upgrade-cache.img file.
@ -55,17 +55,17 @@ fstrim, nor "discard" mount option do not work on template root fs, so when some
You can compact root.img in the "old way", you'll need about 15GB (template's max size + really used space there) in dom0 for this operation: Start the template, fill all the free space with zeros, for example with:
```
~~~
dd if=/dev/zero of=/var/tmp/zero
(wait for "No space left on device" error)
rm -f /var/tmp/zero
```
~~~
Then shutdown template and all VMs based on it. Go into template directory in dom0 (/var/lib/qubes/vm-templates/fedora-20-x64 or so) and issue:
```
~~~
cp --sparse=always root.img root.img.new
mv root.img.new root.img
```
~~~
Done.

60
managing-os/HvmCreate.md
View File

@ -20,23 +20,23 @@ Creating an HVM domain
First, lets create a new HVM domain (use the --hvm switch to qvm-create, or choose HVM type in the Qubes Manager VM creation dialog box):
```
~~~
qvm-create win7 --hvm --label green
```
~~~
(Of course, the name of the domain ("win7"), as well as it's label ("green"), are just exemplary).
Now, we need to install an OS inside this VM, this can done by attaching an installation ISO upon starting the VM (this currently can be done only from command line, but in the future we surely will added an option to do this also from the manager):
```
~~~
qvm-start win7 --cdrom=/usr/local/iso/win7_en.iso
```
~~~
The command above assumes the installation ISO was somehow transferred to Dom0, e.g. copied using `dd` command from an installation CDROM. If one wishes to use the actual physical media without copying it first to a file, then one can just pass `/dev/cdrom` as an argument to `--cdrom`:
```
~~~
qvm-start win7 --cdrom=/dev/cdrom
```
~~~
Now, the VM will start booting from the attached CDROM device, which in the example above just happens to be the Windows 7 installation disk. Depending on the OS that is being installed in the VM, one might be required to start the VM several times (as is the case e.g. with Windows 7 installation), because whenever the installer wants to "reboot the system", it actually shutdowns the VM (and Qubes won't automatically start it), so several invocations of qvm-start command (as shown above) might be needed.
@ -47,16 +47,16 @@ Using Installation ISOs located in other VMs
Sometimes one wants to download the installation ISO from the Web and use it for HVM creation. However, for security reasons, networking is disabled for Qubes Dom0, which makes it not possible to download an ISO within Dom0. Also Qubes do not provide any (easy to use) mechanisms for copying files between AppVMs and Dom0, and generally tries to discourage such actions. So, it would be inconvenient to require that the installation ISO for an HVM domain be always located in Dom0. And the good news is that this is indeed not required -- one can use the following syntax when specifying the location of /usr/local/iso/win7\_en.iso the installation ISO:
```
~~~
--cdrom=[appvm]:[/path/to/iso/within/appvm]
```
~~~
Assuming e.g. the an installation ISO named `ubuntu-12.10-desktop-i386.iso` has been downloaded in `work-web` AppVM, and located within `/home/user/Downloads` directory within this AppVM, one can immediately create a new HVM and use this ISO as an installation media with the following command (issued in Dom0, of course):
```
~~~
qvm-create --hvm ubuntu --label red
qvm-start ubuntu --cdrom=work-web:/home/user/Downloads/ubuntu-12.10-desktop-i386.iso
```
~~~
Of course the AppVM where the ISO is kept must also be running for this to work (this VM is now serving the ISO and acting as a disk backend).
@ -93,7 +93,7 @@ Just like normal AppVMs, the HVM domains can also be cloned, either using a comm
The cloned VM will get identical root and private image, and essentially will be identical to the original VM, except that it will get a different MAC address for the networking interface:
```
~~~
[joanna@dom0 ~]$ qvm-prefs win7
name : win7
label : green
@ -145,21 +145,21 @@ qrexec_installed : False
qrexec timeout : 60
drive : None
timezone : localtime
```
~~~
Note how the MAC addresses differ between those two, otherwise identical VMs. Of course, the IP addresses, assigned by Qubes, will also be different, to allow networking to function properly:
```
~~~
[joanna@dom0 ~]$ qvm-ls -n
/.../
win7-copy | | Halted | Yes | | *firewallvm | green | 10.137.2.3 | n/a | 10.137.2.1 |
win7 | | Halted | Yes | | *firewallvm | green | 10.137.2.7 | n/a | 10.137.2.1 |
/.../
```
~~~
If, for any reason, one would like to make sure that the two VMs have the same MAC address, one can use qvm-prefs to set a fixed MAC address for the VM:
```
~~~
[joanna@dom0 ~]$ qvm-prefs win7-copy -s mac 00:16:3E:5E:6C:05
[joanna@dom0 ~]$ qvm-prefs win7-copy
name : win7-copy
@ -184,7 +184,7 @@ qrexec_installed : False
qrexec timeout : 60
drive : None
timezone : localtime
```
~~~
Please note that as of now Qubes does not support shared templates for HVM domains. This means that HVM domains cloned this way will have two separate copies of the whole filesystems. This has consequences in taking much more disk space compared to standard AppVMs that share the root fs with the Template VM. Another consequence is that it's probably not legal to clone a proprietary OS, such as Windows this way, unless your license specifically allows for that (even though Windows Activation won't complain when one sets identical MAC address for the cloned VMs, it's doubtful practice at best).
@ -211,22 +211,22 @@ Qubes Windows Support Tools are not open source and are distributed under a comm
Because the Windows Support Tools are not licensed under a GPL license they are not distributed with Qubes installation ISO. Instead, one can download them when needed using the standard Qubes command for installing software in Dom0:
```
~~~
sudo qubes-dom0-update qubes-windows-tools
```
~~~
This should install `qubes-windows-tools-*.rpm` in your system, a package that brings an ISO with Windows Support Tools:
```
~~~
[joanna@dom0 ~]$ rpm -ql qubes-windows-tools-1-201211301354.noarch
/usr/lib/qubes/qubes-windows-tools-201211301354.iso
```
~~~
Now, in order to install the tools in a Windows VM one should start the VM with the ISO attached:
```
~~~
qvm-start lab-win7 --cdrom=/usr/lib/qubes/qubes-windows-tools-201211301354.iso
```
~~~
Once the Windows VM boots, a CDROM should appear in the 'My Computer' menu (typically as `D:`) with a setup program in its main directory:
@ -242,25 +242,25 @@ After successful installation, the Windows VM must be shut down.
Additionally, once should inform Qubes that tools have been installed in this VM by setting the `qrexec_installed` flag in the VM's properties -- this can be done using the `qvm-prefs` command in Dom0, e.g.:
```
~~~
qvm-prefs lab-win7 -s qrexec_installed true
```
~~~
Also, by default Qubes assumes that the default user in the Windows VM is named `user` -- if one has chosen a different user during Windows installation, Qubes should be informed about this by setting the `default_user` property for the VM, e.g.:
```
~~~
qvm-prefs lab-win7 -s default_user joanna
```
~~~
If everything went fine (please remember about the need to reboot the Windows VM after installation of the tools), one can run some simple tests to see if qrexec service runs fine with this VM, e.g.:
```
~~~
qvm-run lab-win7 calc
```
~~~
... or something more fancy (a "networkless" telnet to Windows ;):
```
~~~
[joanna@dom0 ~]$ qvm-run lab-win7 -p cmd.exe
Microsoft Windows [Version 6.1.7601]
Copyright (c) 2009 Microsoft Corporation. All rights reserved.
@ -283,7 +283,7 @@ dir c:\
C:\Windows\system32>exit
exit
```
~~~
Another things to check are if clipboard copy/paste and file copy works fine with this VM. If it doesn't, then perhaps one more VM reboot is necessary (seriously, hey this is Windows!).

12
managing-os/LinuxHVMTips.md
View File

@ -20,24 +20,24 @@ To achieve it (all commands run as root):
1. Generate XOrg configuratio (if you don't have it):
```
~~~
X -configure :1 && mv ~/xorg.conf.new /etc/X11/xorg.conf
```
~~~
2. Add HorizSync line to Monitor section, it should look something like:
```
~~~
Section "Monitor"
Identifier "Monitor0"
VendorName "Monitor Vendor"
ModelName "Monitor Model"
HorizSync 30.0 - 60.0
EndSection
```
~~~
3. Change driver to "vesa" in Device section:
```
~~~
Section "Device"
# (...)
Identifier "Card0"
@ -46,7 +46,7 @@ To achieve it (all commands run as root):
BoardName "Unknown Board"
BusID "PCI:0:2:0"
EndSection
```
~~~
Now you should get at least 1280x1024 and be able to choose other modes.

20
managing-os/Templates/FedoraMinimal.md
View File

@ -17,25 +17,25 @@ Install
It can be installed via the following command:
```
~~~
[user@dom0 ~]$ sudo qubes-dom0-update qubes-template-fedora-21-minimal
```
~~~
Usage
-----
It is a good idea to clone the original template, and make any changes in the new clone instead:
```
~~~
[user@dom0 ~]$ qvm-clone fedora-21-minimal <your new template name>
```
~~~
The sudo package is not installed by default, so let's install it:
```
~~~
[user@F21-Minimal ~]$ su -
[user@F21-Minimal ~]$ yum install sudo
```
~~~
The rsyslog logging service is not installed by default. All logging is now being handled by the systemd journal. Users requiring the rsyslog service should install it manually.
@ -45,15 +45,15 @@ To access the journald log, use the `journalctl` command.
If you want to use this template to for standard NetVMs you should install some more packeges:
```
~~~
[user@F21-Minimal ~]$ sudo yum install NetworkManager NetworkManager-wifi network-manager-applet wireless-tools dbus-x11 dejavu-sans-fonts tar tinyproxy
```
~~~
And maybe some more optional but useful packages as well:
```
~~~
[user@F21-Minimal ~]$ sudo yum install pciutils vim-minimal less tcpdump telnet psmisc nmap nmap-ncat gnome-keyring
```
~~~
If your network device needs some firmware then you should also install the corresponding packages as well. The `lspci; yum search firmware` command will help to choose the right one :)

4
managing-os/UninstallingWindowsTools2.md
View File

@ -61,7 +61,7 @@ The uninstall script
Save it as a .BAT file in the HVM and run in Safe Mode.
```
~~~
@echo off
:: This batch file uninstalls Qubes Tools for Windows version 2.x
@ -120,4 +120,4 @@ FOR /F "delims=. tokens=1" %%I IN ('DIR /B "%SYSTEMROOT%\INF\OEM*.INF"') DO (
echo.
echo Cleanup finished. Please manually uninstall Qubes Video and Xen devices from the Device Manager.
```
~~~

32
managing-os/WindowsAppVms.md
View File

@ -32,17 +32,17 @@ Installing Qubes support tools in Windows 7 VMs
First, make sure that `qubes-windows-tools` is installed in your system:
```
~~~
sudo qubes-dom0-update qubes-windows-tools
```
~~~
This package brings the ISO with Qubes Windows Tools that is passed to the VM when `--install-windows-tools` is specified for the `qvm-start` command. Please note that even though the Qubes Windows Tools are proprietary, none of this software ever runs in Dom0 or any other part of the system except for the Windows AppVM in which it is to be installed.
To install the Qubes Windows support tools in a Windows VM one should start the VM passing the additional option `--install-windows-tools`:
```
~~~
qvm-start lab-win7 --install-windows-tools
```
~~~
Once the Windows VM boots, a CDROM should appear in the 'My Computer' menu (typically as `D:`) with a setup program in its main directory.
@ -54,30 +54,30 @@ After successful installation, the Windows VM must be shut down and started agai
Qubes (R2 Beta 3 and later releases) will automatically detect the tools has been installed in the VM and will set appropriate properties for the VM, such as `qrexec_installed`, `guiagent_installed`, and `default_user`. This can be verified (but is not required) using qvm-prefs command:
```
~~~
qvm-prefs <your-appvm-name>
```
~~~
Using Windows AppVMs in seamless mode (Qubes R2 Beta 3 and later)
-----------------------------------------------------------------
Once you start a Windows-based AppVM with Qubes Tools installed, you can easily start individual applications from the VM (note the `-a` switch used here, which will auto-start the VM if it is not running):
```
~~~
qvm-run -a my-win7-appvm explorer.exe
```
~~~
![windows-seamless-4.png](/attachment/wiki/WindowsAppVms/windows-seamless-4.png) ![windows-seamless-1.png](/attachment/wiki/WindowsAppVms/windows-seamless-1.png)
Also, the inter-VM services work as usual -- e.g. to request opening a document or URL in the Windows AppVM from another VM:
```
~~~
[user@work ~]$ qvm-open-in-vm work-win7 roadmap.pptx
```
~~~
```
~~~
[user@work ~]$ qvm-open-in-vm work-win7 http://www.invisiblethingslab.com
```
~~~
... just like in case of Linux AppVMs. Of course all those operations are governed by central policy engine running in Dom0 -- if the policy
@ -97,9 +97,9 @@ Using template-based Windows AppVMs (Qubes R2 Beta 3 and later)
Qubes allows HVM VMs to share a common root filesystem from a select Template VM, just like it is done for Linux AppVMs. This mode is not limited to Windows AppVMs, and can be used for any HVM (e.g. FreeBSD running in a HVM). In order to create a HVM TemplateVM one can use the following command:
```
~~~
qvm-create --hvm-template win7-x64-template -l green
```
~~~
... and install Windows OS (or other OS) into this template the same way as you would install it into a normal HVM -- please see [this page](/doc/HvmCreate/) instructions. However, it would make lots of sense to store the `C:\Users` directory on the 2nd disk which is automatically exposed by Qubes to all HVMs. This 2nd disk is backed by the `private.img` file in the AppVMs' and is not reset upon AppVMs reboot, so the user's directories and profiles would survive the AppVMs reboot, unlike the "root" filesystem which will be reverted to the "golden image" from the Template VM automatically. To facilitate such separation of user profiles, Qubes Windows Tools provide an option to automatically move `C:\Users` directory to the 2nd disk backed by `private.img`. It's a selectable feature of the installer, enabled by default. If that feature is selected during installation, completion of the process requires two reboots:
@ -110,6 +110,6 @@ It also makes sense to disable Automatic Updates for all the Windows-based AppVM
Once the template has been created and installed it is easy to create AppVMs based on:
```
~~~
qvm-create --hvm <new windows appvm name> --template <name of template vm> --label <label color>
```
~~~

4
reference/QubesService.md
View File

@ -12,11 +12,11 @@ Under the hood enabled service in VM is signaled by file in /var/run/qubes-servi
1. Disable old service: `systemctl disable <service name>`
2. Create `/etc/systemd/system/<service name>.service` file containing:
```
~~~
.include /lib/systemd/system/<service name>.service
[Unit]
ConditionPathExists=/var/run/qubes-service/<service name>
```
~~~
3. Enable new service: `systemctl enable <service name>`.

8
releases/1.0/release-notes.md
View File

@ -20,10 +20,10 @@ Known issues
- On systems with more than 8GB of RAM there is problem with Disposable VM. To fix it, limit maximum memory allocation for DispVM to 3GB
```
~~~
qvm-prefs -s fedora-17-x64-dvm maxmem 3072
qvm-create-default-dvm --default-template --default-script
```
~~~
- On some systems the KDE Window Manager might freeze upon resuming from S3 sleep when compositing is enabled (and the only method to log in to the system if this happens is to switch to a text console, enter your user's password, kill the kwin process, go back to the Xorg console, log in, and start a new instance of kwin using Konsole application :) If you experience such problems, make sure to disable compositing before putting the system into sleep by pressing Alt-Ctrl-F12 (and then enabling it back once you log in after resume) -- this way you should never see this problem again.
@ -48,7 +48,7 @@ If you're already running Qubes 1.0-rc1, you don't need to reinstall, it's just
If you have Qubes Beta 3 currently installed on your system, you must reinstall from scratch, as we offer no direct upgrade option in the installer (sorry). However, we do offer tools for smooth migration of your AppVMs. In order to do that, please backup your AppVMs using the `qvm-backup` tool [as usual](/doc/BackupRestore/). Then, after you install Qubes 1.0 rc1, you can restore them using `qvm-backup-restore` tool. However, because we have changed the default template in RC1, you should tell qvm-back-restore about that by passing `--replace-template` option:
```
~~~
qvm-backup-restore <backup_dir> --replace-template=fedora-15-x64:fedora-17-x64
```
~~~

4
security/AntiEvilMaid.md
View File

@ -18,9 +18,9 @@ Installing
In Dom0 install anti-evil-maid:
```
~~~
sudo qubes-dom0-update anti-evil-maid
```
~~~
More information regarding configuration in the [README](https://github.com/QubesOS/qubes-antievilmaid/blob/master/README) file.

56
security/QubesFirewall.md
View File

@ -34,15 +34,15 @@ Reconnecting AppVMs after a NetVM reboot
Normally Qubes doesn't let the user to stop a NetVM if there are other AppVMs running which use it as their own NetVM. But in case the NetVM stops for whatever reason (e.g. it crashes, or the user forces its shutdown via qvm-kill via terminal in the netvm), then there is an easy way to restore the connection to the netvm by issuing:
```
~~~
qvm-prefs <appvm> -s netvm <netvm>
```
~~~
Normally AppVMs do not connect directly to the actual NetVM which has networking devices, but rather to the default FirewallVM first, and in most cases it would be the NetVM that would crash, e.g. in response to S3 sleep/restore or other issues with WiFi drivers. In that case it is necessary to just issue the above command once, for the FirewallVM (this assumes default VM-nameing used by the default Qubes installation):
```
~~~
qvm-prefs firewallvm -s netvm netvm
```
~~~
Enabling networking between two AppVMs
--------------------------------------
@ -56,18 +56,18 @@ In order to allow networking between AppVM A and B follow those steps:
- Start both AppVMs, and also open a terminal in the firewall VM
- In the firewall VM's terminal enter the following iptables rule:
```
~~~
sudo iptables -I FORWARD 2 -s <IP address of A> -d <IP address of B> -j ACCEPT
```
~~~
- Now you should be able to reach the AppVM B from A -- test it using e.g. ping issues from AppVM A. Note however, that this doesn't allow you to reach A from B -- for this you would need another rule, with A and B addresses swapped.
- If everything works as expected, then the above iptables rule(s) should be written into firewall VM's `qubes_firewall_user_script` script which is run on every firewall update. This is necessary, because Qubes orders every firewall VM to update all the rules whenever new VM is started in the system. If we didn't enter our rules into this "hook" script, then shortly our custom rules would disappear and inter-VM networking would stop working. Here's an example how to update the script (note that, by default, there is no script file present, so we likely will be creating it, unless we had some other custom rules defines earlier in this firewallvm):
```
~~~
[user@firewallvm ~]$ sudo bash
[root@firewallvm user]# echo "iptables -I FORWARD 2 -s 10.137.2.25 -d 10.137.2.6 -j ACCEPT" >> /rw/config/qubes_firewall_user_script
[root@firewallvm user]# chmod +x /rw/config/qubes_firewall_user_script
```
~~~
Port forwarding to an AppVM from the outside world
--------------------------------------------------
@ -90,15 +90,15 @@ In NetVM terminal, take note of the interface name and IPAddress on which you wa
Still in NetVM terminal, code the appropriate natting firewall rule to intercept traffic on the inbound interface for the service and nat the destination IP address to the one of the firewallVM for the traffic to be routed there:
```
~~~
iptables -t nat -A PREROUTING -i eth0 -p tcp --dport 443 -d 192.168.0.10 -j DNAT --to-destination 10.137.1.x
```
~~~
Code the appropriate new filtering firewall rule to allow new connections for the service:
```
~~~
iptables -I FORWARD 2 -i eth0 -d 10.137.1.x -p tcp --dport 443 -m conntrack --ctstate NEW -j ACCEPT
```
~~~
Note: If you want to expose the service on multiple interfaces, repeat the steps described in part 1 for each interface.
@ -114,23 +114,23 @@ In order to ensure your set-up survive a reboot we need in the NetVM to:
Store these commands in ` /rw/config/rc.local `:
```
~~~
sudo nano /rw/config/rc.local
```
~~~
```
~~~
#!/bin/sh
/sbin/iptables -t nat -A PREROUTING -i eth0 -p tcp --dport 443 -d 192.168.0.10 -j DNAT --to-destination 10.137.1.x
/sbin/iptables -I FORWARD 2 -s 192.168.0.0/24 -d 10.137.1.x -p tcp --dport 443 -m conntrack --ctstate NEW -j ACCEPT
```
~~~
Make this file executable:
```
~~~
sudo chmod +x /rw/config/rc.local
```
~~~
**2. Allow packets to be routed from the firewallVM to the appVM**
@ -140,15 +140,15 @@ In FirewallVM Terminal, take note of the IPAddress for interface eth0 using the
Still in FirewallVM terminal, code the appropriate natting firewall rule to intercept traffic on the inbound interface for the service and nat the destination IP address to the one of the AppVM for the traffic to be routed there:
```
~~~
iptables -t nat -A PREROUTING -i eth0 -p tcp --dport 443 -d 10.137.1.x -j DNAT --to-destination 10.137.2.y
```
~~~
Code the appropriate new filtering firewall rule to allow new connections for the service:
```
~~~
iptables -I FORWARD 2 -i eth0 -s 192.168.0.0/24 -d 10.137.2.y -p tcp --dport 443 -m conntrack --ctstate NEW -j ACCEPT
```
~~~
> Note: If you do not wish to limit the IP addresses connecting to the service, remove the ` -s 192.168.0.1/24 `
@ -158,28 +158,28 @@ This time in order to ensure your set-up survive a reboot we need in the firewal
Store these commands in ` /rw/config/qubes_firewall_user_script `:
```
~~~
#!/bin/sh
/sbin/iptables -t nat -A PREROUTING -i eth0 -p tcp --dport 443 -d 10.137.1.x -j DNAT --to-destination 10.137.2.y
/sbin/iptables -I FORWARD 4 -i eth0 -s 192.168.0.0/24 -d 10.137.2.y -p tcp --dport 443 -m conntrack --ctstate NEW -j ACCEPT
```
~~~
And again make this file executable:
```
~~~
sudo chmod +x /rw/config/qubes_firewall_user_script
```
~~~
**3. Allow packets into the AppVM to reach the service**
Here no routing is required, only filtering. Proceed in the same way as above but store the filtering rule in the `/rw/config/rc.local` script.
```
~~~
#!/bin/sh
/sbin/iptables -I INPUT 5 -p tcp --dport 443 -m conntrack --ctstate NEW -j ACCEPT
```
~~~
This time testing should allow connectivity to the service.

24
security/SecurityGuidelines.md
View File

@ -29,17 +29,17 @@ Download Verification
Standard program installation
```
~~~
sudo yum install <program>
```
~~~
on template terminal already accomplishes verification, for fedora and qubes repositories.
If you install new repositories, they might have gpgcheck disabled. [Check the config files](http://docs.fedoraproject.org/en-US/Fedora/12/html/Deployment_Guide/sec-Configuring_Yum_and_Yum_Repositories.html) and be sure to check that
```
~~~
gpgcheck=1
```
~~~
Plus, also make sure you **safely import their signing keys**. This may require you check from multiple sources that the signing key is always the same.
@ -66,9 +66,9 @@ Enabling and Verifying VT-d/IOMMU
In **Dom0** terminal, run:
```
~~~
qubes-hcl-report <userVM>
```
~~~
where \<userVM\> is the name of the VM within which the report will be written (but the report will also be displayed in the Dom0 terminal). If it displays that VT-d is active, you should be able to assign **PCIe devices to a HVM** and **enjoy DMA protection** for your driver domains, so you successfully passed this step.
@ -79,15 +79,15 @@ Updating Software
To keep your system regularly updated against security related bugs and get new features, run in Dom0:
```
~~~
sudo qubes-dom0-update
```
~~~
and run in templates and standalone VM
```
~~~
sudo yum update
```
~~~
or use the equivalent items in Qubes Manager, which displays an icon when an update is available.
@ -145,9 +145,9 @@ An **USBVM** operates like a dedicated temporary parking area, used just to prev
5. Click OK. Restart the AppVM. (Restarting may not even be required.)
6. Set the VM to start automatically at Boot using the VM Manager, (under VM Settings), or **In dom0 terminal**, run
```
~~~
qvm-prefs -s usbvm autostart true
```
~~~
This will cause your new **USBVM** to automatically start when the system starts up. So that in case you forgot to start it and then accidentally plugged a USB stick (or your colleague at work did it while you were at lunch), **it won't compromise the Dom0**.

4
security/SecurityPage.md
View File

@ -21,9 +21,9 @@ Qubes Security Team
The Qubes Security Team can be contacted via email using the following address:
```
~~~
security at qubes-os dot org
```
~~~
Qubes Security Team GPG Key
---------------------------

32
troubleshooting/InstallNvidiaDriver.md
View File

@ -17,19 +17,19 @@ There are rpm packages with all necessary software on rpmfusion. The only packag
You will need any Fedora 18 system to download and build packages. You can use Qubes AppVM for it, but it isn't necessary. To download packages from rpmfusion - add this repository to your yum configuration (instructions are on their website). Then download packages using yumdownloader:
```
~~~
yumdownloader --resolve xorg-x11-drv-nvidia
yumdownloader --source nvidia-kmod
```
~~~
###Build kernel package
You will need at least kernel-devel (matching your Qubes dom0 kernel), rpmbuild tool and kmodtool, and then you can use it to build package:
```
~~~
yum install kernel-devel rpm-build kmodtool
rpmbuild --nodeps -D "kernels `uname -r`" --rebuild nvidia-kmod-260.19.36-1.fc13.3.src.rpm
```
~~~
In above command replace `uname -r` with kernel version from your Qubes dom0. If everything went right, you have now complete packages with nvidia drivers for Qubes system. Transfer them to dom0 (eg using USB stick) and install (using standard "yum install /path/to/file").
@ -37,15 +37,15 @@ Then you need to disable nouveau (normally it is done by install scripts from nv
Edit /etc/default/grub:
```
~~~
GRUB_CMDLINE_LINUX="quiet rhgb nouveau.modeset=0 rd.driver.blacklist=nouveau video=vesa:off"
```
~~~
Regenerate grub configuration:
```
~~~
grub2-mkconfig -o /boot/grub2/grub.cfg
```
~~~
Reboot.
@ -65,9 +65,9 @@ See [this page](/doc/CopyToDomZero/) for instructions on how to transfer files t
Install libraries, Xorg driver, configuration utilities. This can by done by nvidia-installer:
```
~~~
./NVIDIA-Linux-x86_64-260.19.44.run --ui=none --no-x-check --keep --no-nouveau-check --no-kernel-module
```
~~~
###Kernel module
@ -85,21 +85,21 @@ This installation must be done manually, because nvidia-installer refused to ins
If all the files are not there correct the errors manually. To build kernel module, enter *NVIDIA-Linux-x86\_64-260.19.44/kernel* directory and execute:
```
~~~
make
IGNORE_XEN_PRESENCE=1 CC="gcc -DNV_VMAP_4_PRESENT -DNV_SIGNAL_STRUCT_RLIM" make -f Makefile.kbuild
mv /lib/modules/2.6.34.1-12.xenlinux.qubes.x86_64/kernel/drivers/video/nvidia.ko /lib/modules/2.6.34.1-12.xenlinux.qubes.x86_64/extra/
```
~~~
Ignore any errors while inserting nvidia.ko (at the end of make phase).
###Disable nouveau:
```
~~~
cat /etc/modprobe.d/nouveau-disable.conf
# blacklist isn't enough...
install nouveau /bin/true
```
~~~
Add *rdblacklist=nouveau* option to /boot/grub/menu.lst (at the end of line containing *vmlinuz*).
@ -107,11 +107,11 @@ Add *rdblacklist=nouveau* option to /boot/grub/menu.lst (at the end of line cont
After all, you should configure Xorg to use nvidia driver. You can use *nvidia-xconfig* or do it manually:
```
~~~
X -configure
mv /root/xorg.conf.new /etc/X11/xorg.conf
# replace Driver in Device section by "nvidia"
```
~~~

24
troubleshooting/NvidiaTroubleshooting.md
View File

@ -22,15 +22,15 @@ Assuming your X Window System works fine now when you booted from the "failsafe"
1. Switch to runlevel 3 (this should kill your X server):
```
~~~
init 3
```
~~~
1. Run X-autoconfiguration:
```
~~~
Xorg -configure
```
~~~
This should generate a file `xorg.conf.new` in the `/root` directory.
@ -40,29 +40,29 @@ In most cases you can ignore any warning or error messages displayed by the X se
- Uncomment the ShadowFB option, so that you should now have something like this:
```
~~~
Option "ShadowFB" # [<bool>]
```
~~~
- Change the driver name to `nouveau` (you will probably have `nv` written there):
```
~~~
Driver "nouveau"
```
~~~
Save the modification, exit the editor.
1. Move the file to `/etc/X11` and rename it as `xorg.conf`:
```
~~~
mv /root/xorg.conf.new /etc/X11/xorg.conf
```
~~~
1. Verify that X will work with those new settings:
```
~~~
xinit
```
~~~
If you see a terminal window in the top left corner, it means you most likely succeeded, even if your keyboard or mouse do not work now (don't worry about them).

20
troubleshooting/OutOfmemory.md
View File

@ -9,18 +9,18 @@ VMs specially templates use disk space. Also default private storage max size is
So it is a good practice to regularly check disk space usage with command
```
~~~
df
```
~~~
in dom0 terminal.
A system in out of space condition should be able to boot, but may be unable to load a desktop manager. In this case it is possible to login to dom0 terminal with Alt + Ctrl + F2. To recover disk space it may be possible to delete files in a userVM connecting to the userVM terminal:
```
~~~
qvm-start <VMname>
sudo xl console <VMname>
```
~~~
If this does not work, check the size of /var/lib/qubes/qubes.xml. If it is zero, you'll need to use one of the file backup (stored in /var/lib/qubes/backup), hopefully you have the current data there. Find the most recent one and place in /var/lib/qubes/qubes.xml instead of the empty file.
@ -28,25 +28,25 @@ In any case you'll need some disk space to start the VM. Check "df" output if yo
1. Clean yum cache:
```
~~~
sudo yum clean all
```
~~~
1. Delete .img files of a less important VM, that can be found in
/var/lib/qubes/appvms/. Then, when the system is working again, cleanup the rest with:
```
~~~
qvm-remove <VMname>
```
~~~
With this method you lose one VM data, but it'll more securely work.
1. Decrease filesystem safety margin (5% by default):
```
~~~
sudo tune2fs -m 4 /dev/mapper/vg_dom0-lv_root
```
~~~
1. Remove some unneeded files in dom0 home (if you have one, most likely no).

6
troubleshooting/SonyVaioTinkering.md
View File

@ -30,7 +30,7 @@ On a side note, we should notice that allowing anybody to reflash the BIOS is re
Getting the touchpad working during installation
------------------------------------------------
In order to get the touchpad working during installation you should pass the **```i8042.nopnp=1```** option to the kernel before the installer starts.
In order to get the touchpad working during installation you should pass the **~~~i8042.nopnp=1~~~** option to the kernel before the installer starts.
\<screenshot\>
@ -39,12 +39,12 @@ Applying other fixes
There are a few more fixes needed for Sony Vaio Z, and we have prepared a special package that you can install in Dom0 that applies them all. After the installation is complete, open console in Dom0 and do the following:
```
~~~
$ sudo bash
# qvm-dom0-networking up
# yum install qubes-core-dom0-vaio-fixes
# reboot
```
~~~
This script takes care about the following: