Git-Mirrors/qubes-doc
1
0
Fork 0
mirror of https://github.com/QubesOS/qubes-doc.git synced 2025-08-19 03:38:08 -04:00
Code Issues Projects Releases Packages Wiki Activity

Merge remote-tracking branch 'upstream/master'

Browse source 
Conflicts:
	managing-os/kali.md
This commit is contained in:
Lorenzo 2017-01-12 10:49:18 +00:00
commit b3c9713842
144 changed files with 4526 additions and 1297 deletions
Download patch file Download diff file Expand all files Collapse all files

115
managing-os/hvm.md
View file

@ -15,20 +15,20 @@ Creating and using HVM (fully virtualized) domains
What are HVM domains?
---------------------
HVM domains (Hardware VM), in contrast to PV domains (Paravirtualized domains), allow to create domains based on any OS, if one only has its installation ISO. E.g. this allows to have Windows-based VMs in Qubes.
HVM domains (Hardware VM), in contrast to PV domains (Paravirtualized domains), allow one to create domains based on any OS for which one has an installation ISO. For example, this allows one to have Windows-based VMs in Qubes.
Interested readers might want to check [this article](http://theinvisiblethings.blogspot.com/2012/03/windows-support-coming-to-qubes.html) to learn why it took so long for Qubes OS to support HVM domains (Qubes 1 only supported Linuxed-based PV domains).
Interested readers might want to check [this article](http://theinvisiblethings.blogspot.com/2012/03/windows-support-coming-to-qubes.html) to learn why it took so long for Qubes OS to support HVM domains (Qubes 1 only supported Linux based PV domains).
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):
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).
(The name of the domain ("win7") as well as it's label ("green") are just exemplary of course).
If you receive an error like this one, then you must first enable VT-x in your BIOS:
@ -36,72 +36,141 @@ If you receive an error like this one, then you must first enable VT-x in your B
libvirt.libvirtError: invalid argument: could not find capabilities for arch=x86_64
~~~
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):
Now we need to install an OS inside this VM. This can done by attaching an installation ISO to and starting the VM (this can currently only be done from command line, but in the future we will surely add 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`:
The above command assumes the installation ISO was transferred to Dom0 (copied using `dd` command from an installation CDROM for example). 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.
Next the VM will start booting from the attached CDROM device (which in the example above just happens to be a 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 with Windows 7 installations), because whenever the installer wants to "reboot the system" it actually shutdowns the VM and Qubes won't automatically start it. Several invocations of qvm-start command (as shown above) might be needed.
[![r2b1-win7-installing.png](/attachment/wiki/HvmCreate/r2b1-win7-installing.png)](/attachment/wiki/HvmCreate/r2b1-win7-installing.png)
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:
Sometimes one wants to download the installation ISO from the Web and use it for HVM creation. For security reasons, networking is disabled for Qubes Dom0, which makes it impossible to download an ISO within Dom0. Qubes also does not provide any easy to use mechanisms for copying files between AppVMs and Dom0 and generally tries to discourage such actions. Due to these factors it would be inconvenient to require that the installation ISO for an HVM domain be always located in Dom0. The good news, however, is that this is indeed not required. One can use the following syntax when specifying the location of an installation ISO (such as the Windows 7 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):
Assuming that an installation ISO named `ubuntu-12.10-desktop-i386.iso` has been downloaded in `work-web` AppVM and is located within the `/home/user/Downloads` directory within this AppVM, one can immediately create a new HVM using this ISO as an installation media with the following command issued in Dom0:
~~~
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).
The AppVM where the ISO is kept must be running for this to work as this VM is now serving the ISO and acting as a disk backend.
![r2b1-installing-ubuntu-1.png](/attachment/wiki/HvmCreate/r2b1-installing-ubuntu-1.png)
Converting VirtualBox VM to HVM
-------------------------------
Microsoft provides [free 90 day evaluation VirtualBox VMs for browser testing](https://developer.microsoft.com/en-us/microsoft-edge/tools/vms/).
About 60 GB of disk space is required for conversion, use external harddrive if needed. Final root.img size is 40 GB.
In Debian AppVM, install qemu-utils and unzip:
~~~
sudo apt install qemu-utils unzip
~~~
Unzip VirtualBox zip file:
~~~
unzip *.zip
~~~
Extract OVA tar archive:
~~~
tar -xvf *.ova
~~~
Convert vmdk to raw:
~~~
qemu-img convert -O raw *.vmdk win10.raw
~~~
Create new HVM in Dom0, with amount of RAM in MB you wish:
~~~
qvm-create --hvm win10 --label red --mem=4096
~~~
Copy file to Dom0:
~~~
qvm-run --pass-io untrusted 'cat "/media/user/externalhd/win10.raw"' > /var/lib/qubes/appvms/win10/root.img
~~~
Start win10 VM:
~~~
qvm-start win10
~~~
**Optional ways to get more information**
Filetype of OVA file:
~~~
file *.ova
~~~
List files of OVA tar archive:
~~~
tar -tf *.ova
~~~
List filetypes supported by qemu-img:
~~~
qemu-img -h | tail -n1
~~~
Setting up networking for HVM domains
-------------------------------------
Just like standard (paravirtualized) AppVMs, the HVM domains got fixed IP addresses centrally assigned by Qubes. Normally Qubes agent scripts, running within each AppVM, are responsible for setting up networking within the VM according the configuration created by Qubes. Such centrally managed networking infrastructure allows for [advanced networking configuration](http://theinvisiblethings.blogspot.com/2011/09/playing-with-qubes-networking-for-fun.html).
Just like standard paravirtualized AppVMs, the HVM domains get fixed IP addresses centrally assigned by Qubes. Normally Qubes agent scripts running within each AppVM are responsible for setting up networking within the VM according the configuration created by Qubes. Such centrally managed networking infrastructure allows for [advanced networking configuration](http://theinvisiblethings.blogspot.com/2011/09/playing-with-qubes-networking-for-fun.html).
However, a generic HVM domain, e.g. a standard Windows or Ubuntu installation, has (at least initially) no Qubes agent scripts running inside it, and thus requires manual networking configuration, so that it match the values assigned by Qubes for this domain.
A generic HVM domain such as a standard Windows or Ubuntu installation, however, has no Qubes agent scripts running inside it initially and thus requires manual networking configuration so that it match the values assigned by Qubes for this domain.
Even though we do have a small DHCP server (that runs inside HVM untrusted stub domain) to make the manual network configuration not necessary for many VMs, this won't work for most modern Linux distributions which contain Xen networking PV drivers built in (but not Qubes tools) and which bypass the stub-domain networking (their net frontends connect directly to the net backend in the netvm), and so our DHCP server is not useful.
Even though we do have a small DHCP server that runs inside HVM untrusted stub domain to make the manual network configuration not necessary for many VMs, this won't work for most modern Linux distributions which contain Xen networking PV drivers (but not Qubes tools) built in which bypass the stub-domain networking (their net frontends connect directly to the net backend in the netvm). In this instance our DHCP server is not useful.
In order to manually configure networking in a VM, one should first find out the IP/netmask/gateway assigned to the particular VM by Qubes. This can be seen e.g. in the Qubes Manager in the VM's properties:
![r2b1-manager-networking-config.png](/attachment/wiki/HvmCreate/r2b1-manager-networking-config.png)
Alternatively, one can use `qvm-ls -n` command to obtain the same information.
Alternatively, one can use `qvm-ls -n` command to obtain the same information. One should configure the networking within the HVM according to those settings (IP/netmask/gateway). One should set DNS addresses to the same IP as gateway.
Now, one should configure the networking within the HVM according to those settings (IP/netmask/gateway). Only IPv4 networking is currently supported in Qubes. Set DNS address to the same IP as gateway.
Only IPv4 networking is currently supported in Qubes.
**Note:** If one plans on installing Qubes Tools for Windows guests (see below) it is 'not' necessary to configure networking manually as described in this section, because the tools will take care of setting the networking automatically for such Windows domains.
Using Template-based HVM domains
--------------------------------
TODO (Coming in Qubes R2 beta 3).
Please see our dedicated page on [installing and using Windows-based AppVMs](/doc/windows-appvms/).
Cloning HVM domains
-------------------
Just like normal AppVMs, the HVM domains can also be cloned, either using a command-line `qvm-clone` command, or via manager's 'Clone VM' option in the right-click menu.
Just like normal AppVMs, the HVM domains can also be cloned either using a command-line `qvm-clone` command or via manager's 'Clone VM' option in the right-click menu.
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:
The cloned VM will get identical root and private image and will essentially be an identical of the original VM except that it will get a different MAC address for the networking interface:
~~~
[joanna@dom0 ~]$ qvm-prefs win7
@ -157,7 +226,7 @@ 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:
Note how the MAC addresses differ between those two otherwise identical VMs. The IP addresses assigned by Qubes will also be different of course to allow networking to function properly:
~~~
[joanna@dom0 ~]$ qvm-ls -n
@ -167,7 +236,7 @@ Note how the MAC addresses differ between those two, otherwise identical VMs. Of
/.../
~~~
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:
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
@ -196,10 +265,6 @@ 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).
In the near future we plan on introducing shared template also for HVM domains, hopefully solving the problems described above.
Installing Qubes support tools in Windows 7 VMs
-----------------------------------------------
@ -210,7 +275,7 @@ Assigning PCI devices to HVM domains
HVM domains (including Windows VMs) can be [assigned PCI devices](/doc/assigning-devices/) just like normal AppVMs. E.g. one can assign one of the USB controllers to the Windows VM and should be able to use various devices that require Windows software, such as phones, electronic devices that are configured via FTDI, etc.
Once problem, however, at the moment, is that after the whole system gets suspend into S3 sleep, and subsequently resumed, such attached devices stop working and should be restarted within the VM. Under Windows this can be achieved by opening the Device Manager, selecting the actual device, such as a USB controller, and then first 'Disabling', and then 'Enabling' the device again. This is illustrated on the screenshot below:
One problem at the moment however, is that after the whole system gets suspended into S3 sleep and subsequently resumed, some attached devices may stop working and should be restarted within the VM. This can be achieved under a Windows HVM by opening the Device Manager, selecting the actual device (such as a USB controller), 'Disabling' the device, and then 'Enabling' the device again. This is illustrated on the screenshot below:
[![r2b1-win7-usb-disable.png](/attachment/wiki/HvmCreate/r2b1-win7-usb-disable.png)](/attachment/wiki/HvmCreate/r2b1-win7-usb-disable.png)

39
managing-os/linux-hvm-tips.md
View file

@ -11,6 +11,45 @@ redirect_from:
Tips for Linux in HVM domain
============================
How to fix bootup kernel error
-------------------------------
This concerns the following:
BUG: soft lockup - CPU#0 stuck for 23s! [systemd-udevd:244]
This has been tested with Qubes `R3.2-RC3`. Note that the issue may be related
to the `bochs_drm` video driver. To fix this:
1. Edit the file `/etc/default/grub`.
2. Find the line which starts:
~~~
GRUB_CMDLINE_LINUX=
~~~
3. Remove this text from that line:
~~~
rhgb
~~~
4. Add this text to that line:
~~~
modprobe.blacklist=bochs_drm
~~~
5. Run this command:
~~~
grub2-mkconfig --output=/boot/grub2/grub.cfg
~~~
The HVM should no longer display the error if it's related to the `bochs_drm`
kernel driver.
Screen resolution
-----------------

30
managing-os/pentesting.md Normal file
View file

@ -0,0 +1,30 @@
---
layout: doc
title: Penetration Testing
permalink: /doc/pentesting/
---
**Legal notice:**
The usage of penetration testing tools outside your own laboratory environment requires the permission of the organization you attack. Penetration testing without such a permission can have legal consequences.
To avoid such legal conflicts please refer to the [EC-Council: Code of Ethics](https://www.eccouncil.org/Support/code-of-ethics).
Penetration Testing
===================
"A penetration test, informally pen test, is an attack on a computer system that looks for security weaknesses, potentially gaining access to the computer's features and data." (source [Penetration test](https://en.wikipedia.org/wiki/Penetration_test)).
Penetration Testing Distributions
---------------------------------
The following install instructions explain how to setup a penetration testing distribution within Qubes OS.
- [BlackArch](/doc/pentesting/blackarch/)
- [Kali](/doc/pentesting/kali/)
- [PenTester Framework (PTF)](/doc/pentesting/ptf/)
Using Qubes OS to host a "hacking" laboratory
---------------------------------------------
Qubes OS is a hypervisor based operating system. Qubes OS can host various operating systems such as Linux, Unix or Windows and run them in parallel. Qubes OS can therefor be used to host your own "hacking" laboratory.

96
managing-os/pentesting/blackarch.md Normal file
View file

@ -0,0 +1,96 @@
---
layout: doc
title: How to Create a BlackArch VM
permalink: /doc/pentesting/blackarch/
redirect_from:
- /doc/blackarch/
---
**General Remainder:**
- The installation scripts and provided tools may have bugs, be vulnerable to Man in the Middle (MitM) attacks or other vulnerabilities.
- Adding additional repositories or tools for installing software extends your trust to those tool provider.
Please keep in mind that using such a VM or VM's based on the template for security and privacy critical tasks is not recommended.
How to Create a BlackArch VM
============================
[BlackArch](http://www.blackarch.org) Linux is an [Arch Linux](http://www.archlinux.org/)-based distribution for penetration testers and security researchers. The repository contains [1434](http://www.blackarch.org/tools.html) tools.
- List of [tools](http://www.blackarch.org/tools.html)
- [Installation Instructions](http://www.blackarch.org/downloads.html)
Create ArchLinux Based BlackArch Template
-----------------------------------------
1. Create ArchlLinux Template
- Follow the [Archlinux Template instructions](/doc/templates/archlinux/)
2. Update Template
sudo pacman -Syyu
3. Clone template
1. Via Qubes VM Manager
2. Via command line
qvm-clone archlinux blackarch
4. Install BlackArch repository
$ curl -O https://blackarch.org/strap.sh
# The SHA1 sum should match: 86eb4efb68918dbfdd1e22862a48fda20a8145ff
$ sha1sum strap.sh
# Set execute bit
$ chmod +x strap.sh
# Run strap.sh
$ sudo ./strap.sh
5. Install tools
- install all tools
sudo pacman -S blackarch
- or by category:
# list available categories
pacman -Sg | grep blackarch
# install category
sudo pacman -S blackarch-<category>
# example
sudo pacman -S blackarch-forensic
- or specific tool
# Search for tool
pacman -Ss <tool-name>
# Install tool
sudo pacman -S <tool-name>
# Example
pacman -Ss burpsuite
sudo pacman -S burpsuite
6. Create a AppVMs based on the `blackarch` template
- (Optional) Attach necessary devices
Alternative Options to BlackArch
--------------------------------
- [Kali](/doc/pentesting/kali/)
- [PenTester Framework (PTF)](/doc/pentesting/ptf/)
- [Pentesting](/doc/pentesting/)

202
managing-os/pentesting/kali.md Normal file
View file

@ -0,0 +1,202 @@
---
layout: doc
title: How to create a Kali Linux VM
permalink: /doc/pentesting/kali/
redirect_from:
- /doc/kali/
---
**General Remainder:**
- The installation scripts and provided tools may have bugs, be vulnerable to Man in the Middle (MitM) attacks or other vulnerabilities.
- Adding additional repositories or tools for installing software extends your trust to those tool provider.
Please keep in mind that using such a VM or VM's based on the template for security and privacy critical tasks is not recommended.
How to Create a Kali Linux VM
=============================
This guide is being created to give guidance on ways in which you could create a [Kali Linux](https://www.kali.org/) penetration testing VM (Qube) in Qubes OS.
Kali Linux is the most widely used penetration testing Linux distribution.
There are multiple ways to create a Kali Linux VM. One way is to create a HVM and use the offical ISO to install the system or convert a [Virtual Image](https://www.offensive-security.com/kali-linux-vmware-virtualbox-image-download/). Another way is to clone the Qubes OS Debian image and turn it into a Kali Linux distribution.
Kali Linux HVM
--------------
1. Download the Kali installation DVD
2. Create a new HVM
3. Start the HVM with attached CD/DVD
qvm-start <hvm-name> --cdrom <vm-name>:/home/user/Downloads/<iso-name>.iso
Create Debian Based Kali Template
---------------------------------
1. *(Optional)* Install `debian-8` template (if not already installed)
2. Update your `debian-8` template
sudo apt-get update
sudo apt-get dist-upgrade
3. Clone `debian-8` template (two options)
1. Via Qubes VM Manager
![Clone Debian Template](/attachment/wiki/Kali/clone-kali.png)
2. Via command line
qvm-clone debian-8 kali
4. Start and upgrade the `kali` Template from Debian 8 to Debian 9
sudo sed -i 's/jessie/stretch/g' /etc/apt/sources.list
sudo sed -i 's/jessie/stretch/g' /etc/apt/sources.list.d/qubes-r3.list
sudo apt-get update
sudo apt-get dist-upgrade
sudo apt-get autoremove
**Note:** From now on there are two possible ways either doing everything manually or automatically with [Katoolin](https://github.com/LionSec/katoolin).
Katoolin is a script (written in Python) which helps you to install Kali tools.
5. *manually* - Add Kali Linux repositories
1. Add Kali Linux repositories to `/etc/apt/sources.list`
deb http://http.kali.org/kali kali-rolling main contrib non-free
deb http://repo.kali.org/kali kali-bleeding-edge main
2. Add kali signing key
- The signing key can be found here [Download Kali Linux Images Securely](https://www.kali.org/downloads/)
sudo apt-key adv --keyserver hkp://keys.gnupg.net --recv-keys 7D8D0BF6
sudo apt-get update
6. *katoolin* - Install Katoolin and add Kali Linux repositories
1. Install Katoolin
sudo apt-get install git
git clone https://github.com/LionSec/katoolin.git
sudo cp katoolin/katoolin.py /usr/bin/katoolin
sudo chmod +x /usr/bin/katoolin
rm -rf katoolin
2. Add Kali Linux repositories
- start katoolin
sudo katoolin
- select 'Add Kali repositories & Update'
1) Add Kali repositories & Update
2) View Categories
3) Install classicmenu indicator
4) Install Kali menu
5) Help
kat > 1
![Add Kali repositories and Update menu](/attachment/wiki/Kali/katoolin-add-update-repo-menu.png)
- select 'Add kali linux repositories'
1) Add kali linux repositories
2) Update
3) Remove all kali linux repositories
4) View the contents of sources.list file
What do you want to do ?> 1
![Add Kali repositories](/attachment/wiki/Kali/katoolin-add-repos-menu.png)
- update Kali repositories
1) Add kali linux repositories
2) Update
3) Remove all kali linux repositories
4) View the contents of sources.list file
What do you want to do ?> 2
- quit katoolin by pressing `CRTL` + `c` keys
What do you want to do ?> ^CShutdown requested...Goodbye...
7. Cleanup and update `kali` template
sudo apt-get dist-upgrade
sudo apt-get autoremove
8. Shutdown and trim `kali` template
- Shutdown `kali` template
sudo shutdown -h now
- In `dom0` console:
qvm-trim-template kali
9. Start image
10. *manually* - Install tools
**Warning:** `kali-linux` and `kali-linux-full` does currently not work properly. Please use `Katoolin` or `PTF`.
1. List available packages
sudo apt-cache search kali-linux
2. Select and install tools
- install base system
sudo apt-get install kali-linux
- or install all tools
sudo apt-get install kali-linux-full
- or select specific (example):
sudo apt-get install kali-linux-top10 kali-linux-web
11. *katoolin* - Install tools
1. View Categories
- start katoolin
sudo katoolin
- select `2) View Categories`
2. Select the categories/tools you want to install
- For more information on how to use Katoolin see [How to Auto Install All Kali Linux Tools Using “Katoolin” on Debian/Ubuntu](http://www.tecmint.com/install-kali-linux-tools-using-katoolin-on-ubuntu-debian/)
- **Note:** The `all` option does not work for `Information Gathering`, `Web Apps`, `Forensic Tools`, `Reverse Engineering` and `Extra`.
12. Create a AppVMs based on the `kali` template
- (Optional) Attach necessary devices
Alternative Options to Kali
---------------------------
- [BlackArch](/doc/pentesting/blackarch/)
- [PenTester Framework (PTF)](/doc/pentesting/ptf/)
- [Pentesting](/doc/pentesting/)

121
managing-os/pentesting/ptf.md Normal file
View file

@ -0,0 +1,121 @@
---
layout: doc
title: How to create Penetration Testers Framework (PTF) VM
permalink: /doc/pentesting/ptf/
redirect_from:
- /doc/ptf/
---
**General Remainder:**
- The installation scripts and provided tools may have bugs, be vulnerable to Man in the Middle (MitM) attacks or other vulnerabilities.
- Adding additional repositories or tools for installing software extends your trust to those tool provider.
Please keep in mind that using such a VM or VM's based on the template for security and privacy critical tasks is not recommended.
How to create Penetration Testers Framework (PTF) VM
====================================================
"The PenTesters Framework (PTF) is a Python script designed for Debian/Ubuntu/ArchLinux based distributions to create a similar and familiar distribution for Penetration Testing.
PTF attempts to install all of your penetration testing tools (latest and greatest), compile them, build them, and make it so that you can install/update your distribution on any machine." (source [PTF Readme](https://github.com/trustedsec/ptf/blob/master/README.md))
**Note** PTF works on Debian testing as well as on Debian 8. PTF itself works with Debian 8, but the software tools will have missing dependencies. Metasploit for examples requires a newer Ruby version than Debian 8 has in the repositories. Therefor the best way to install PTF is by upgrading a Debian 8 into Debian testing with additional Kali repositories. Instead of installing the tools from Kali, PTF will install and update the newest tools.
Create Debian Based Penetration Testers Framework (PTF) Template
----------------------------------------------------------------
1. Create PTF template
1. Follow [Create Debian Based Kali Template](/doc/pentesting/kali/) till step 7.
2. (Optional) Rename the cloned template to `ptf`
2. Download PTF
sudo apt-get install git
cd /opt
sudo git clone https://github.com/trustedsec/ptf.git
- (Optional) Configure PTF
1. Go to configuration directory
cd /opt/ptf/config
2. Edit the configuration file
for example by using vim:
sudo vim ptf.config
the configuration options are described in the `ptf.config` file
3. Install PTF
cd /opt/ptf
sudo ./ptf
**Note:** the config file has to be in the same directory as the executable. It is not
possible to do sudo ptf/ptf
PTF will put itself into `/usr/local/bin/ptf`. You can use `ptf` from now on.
4. Install/Update modules (tools)
1. Start PTF
sudo ptf
![PTF start banner](/attachment/wiki/PTF/ptf-banner.png)
2. Show available modules (tools)
ptf> show modules
3. Install/Update modules (all/)
- Install/Update all tools
ptf> use modules/install_update_all
- or by category Install/Update
ptf> use modules/code-audit/install_update_all
- or individually (example Metasploit)
1. Search for module
ptf> search metasploit
[*] Search results below:
modules/exploitation/metasploit
2. Use module
ptf> use modules/exploitation/metasploit
ptf:(modules/exploitation/metasploit)>
3. Install module
ptf:(modules/exploitation/metasploit)>install
4. Run Metasploit
ptf:(modules/exploitation/metasploit)>exit
ptf> quit
[*] Exiting PTF - the easy pentest platform creation framework.
sudo msfconsole
5. Create a AppVMs based on the `ptf` template
- (Optional) Attach necessary devices
Alternative Options to PTF
--------------------------
- [BlackArch](/doc/pentesting/blackarch/)
- [Kali](/doc/pentesting/kali/)
- [Pentesting](/doc/pentesting/)

39
managing-os/reinstall-template.md
View file

@ -9,12 +9,39 @@ redirect_from:
How to Reinstall a TemplateVM
=============================
If you suspect your [TemplateVM] is broken, misconfigured, or compromised,
or if you wish to do a clean reinstall in order to upgrade to a new version, you
can reinstall any TemplateVM from the Qubes repository. In what follows, the
phrase "target TemplateVM" refers to whichever TemplateVM you want to reinsatll.
If you want to reinstall more than one TemplateVM, repeat these instructions for
each one.
If you suspect your [TemplateVM] is broken, misconfigured, or compromised, you
can reinstall any TemplateVM that was installed from the Qubes repository.
Starting in Qubes 3.1, the process is greatly simplified.
First, copy any files that you wish to keep from the TemplateVM's `/home` and
`/rw` folders to a safe storage location. Then, in a dom0 terminal, run:
$ sudo qubes-dom0-update --action=reinstall qubes-template-package-name
Replace `qubes-template-package-name` with the name of the *package* of the
template you wish to reinstall. For example, use `qubes-template-fedora-24` if
you wish to reinstall the `fedora-24` template. Only one template can be
reinstalled at a time.
**Reminder:** If you're trying to reinstall a template that is not in an enabled
repo, you must enable that repo. For example:
$ sudo qubes-dom0-update --enablerepo=qubes-templates-community --action=reinstall qubes-template-whonix-ws
**Note:** VMs that are using the reinstalled template will not be affected until they are
restarted.
Manual Reinstallation Method
----------------------------
If you're using Qubes 3.0 or older, you should use the manual reinstallation
method. You can also use this method on later Qubes versions if, for any reason,
you want to reinstall a template manually.
In what follows, the term "target TemplateVM" refers to whichever TemplateVM you
want to reinstall. If you want to reinstall more than one TemplateVM, repeat
these instructions for each one.
1. (Optional) Clone the existing target TemplateVM.

21
managing-os/templates.md
View file

@ -17,7 +17,7 @@ TemplateBasedVMs is installed. The default template is based on Fedora,
but there are additional templates based on other Linux distributions. There
are also templates available with or without certain software preinstalled. The
concept of TemplateVMs is initially described
[here](/doc/getting-started/#appvms-domains-and-templatevms). The technical
[here](/getting-started/#appvms-qubes-and-templatevms). The technical
details of this implementation are described in the developer documentation
[here](/doc/template-implementation/).
@ -85,14 +85,25 @@ Important Notes
update a template from dom0 (and thereby lose any user modifications in the
existing template), you must first uninstall the existing template from dom0:
$ sudo yum remove qubes-template-fedora-23
$ sudo yum remove qubes-template-fedora-24
* Standalone VMs using Template VMs as a basis can be created easily. These
VMs receive a *copy* of the operating system and do not get automatically
updated when Template VMs are updated--they must be updated individually.
* Template VMs can occupy more space on the dom0 filesystem than necessary
because they cannot employ automatic TRIM/discard on the root fs. The
`qvm-trim-template` command in dom0 is used to recover this unused space.
Conversely, the root filesystems in Standalone VMs *can* employ
TRIM/discard on the root fs using normal tools and configuration options.
* On XFCE based Dom0, a manual action may be required to remove the "Start Menu"
sub-menu of the removed TemplateVM. For example, to remove a dangling sub-menu
for a removed "fedora-21" template, open a Dom0 Terminal and type:
for a removed "fedora-24" template, open a Dom0 Terminal and type:
$ sudo rm ~/.local/share/applications/fedora-21-*
$ sudo rm ~/.local/share/applications/fedora-24-*
Just make sure there are no other TemplateVMs whose names start with "fedora-21"
Just make sure there are no other TemplateVMs whose names start with "fedora-24"
or else their menu items will be removed too.

64
managing-os/templates/archlinux.md
View file

@ -23,7 +23,7 @@ Main maintainer of this template is [Olivier Médoc](mailto:o_medoc@yahoo.fr).
## Instructions ##
<br>
**These are the instructions for Qubes 3.1. They will take you step by step thru the entire process start to finish**
**These are the instructions for Qubes 3.2. They will take you step by step through the entire process start to finish**
*Note: Currently there are no binary packages and it must be compiled from source using the instructions below.*
@ -80,15 +80,17 @@ Main maintainer of this template is [Olivier Médoc](mailto:o_medoc@yahoo.fr).
* python-sh
* dailog
* dialog
* rpm-sign
* gnupg
<br>
* The tools can usually be installed all together with the following terminal command string:
* **$ sudo dnf install git createrepo rpm-build make wget rpmdevtools python-sh dialog rpm-sign**
* **$ sudo dnf install git createrepo rpm-build make wget rpmdevtools python-sh dialog rpm-sign gnupg**
<br>
<br>
![arch-template-04](/attachment/wiki/ArchlinuxTemplate/arch-template-04.png)
@ -98,19 +100,19 @@ Main maintainer of this template is [Olivier Médoc](mailto:o_medoc@yahoo.fr).
##### **4: Installing the "Qubes Automated Build System":** #####
* To get the most current build system its best to use marmarek's git repository.
* Download the latest stable qubes-builder repository:
* $ **git clone https://github.com/marmarek/qubes-builder.git**
* $ **git clone https://github.com/QubesOS/qubes-builder.git**
<br>
<br>
![arch-template-05](/attachment/wiki/ArchlinuxTemplate/arch-template-05.png)
<br>
<br>
* You will now have the Qubes Builder System environment installed in the directory below:
* **/home/user/qubes-builder**
<br>
* You will now have the Qubes Builder System environment installed in the directory below:
* **/home/user/qubes-builder/**
<br>
<br>
@ -120,11 +122,11 @@ Main maintainer of this template is [Olivier Médoc](mailto:o_medoc@yahoo.fr).
*In the future this should not be needed once a change is made to the 'setup' script.*
* Edit the '**qubes-os-r3.1.conf**' which is found in **/home/user/qubes-builder/example-configs** Use the text editor of your choice.
* Edit the '**qubes-os-r3.2.conf**' which is found in **/home/user/qubes-builder/example-configs** Use the text editor of your choice.
* **$ cd /home/user/qubes-builder/example-config/**
* **$ nano -W qubes-os-r3.1.conf** or **$ gedit qubes-os-r3.1.conf** or etc….
* **$ nano -W qubes-os-r3.2.conf** or **$ gedit qubes-os-r3.2.conf** or etc….
<br>
<br>
![arch-template-06](/attachment/wiki/ArchlinuxTemplate/arch-template-06.png)
@ -172,7 +174,7 @@ Main maintainer of this template is [Olivier Médoc](mailto:o_medoc@yahoo.fr).
* This screen will give you the choice of which Qubes Release to build the template for.
* Select '**Qubes Release 3.1**'
* Select '**Qubes Release 3.2**'
* Select '**OK**' Press '**Enter**'
<br>
<br>
@ -185,6 +187,9 @@ Main maintainer of this template is [Olivier Médoc](mailto:o_medoc@yahoo.fr).
* Select 'QubesOS/qubes- Stable - Default Repo'
* Select '**OK**' Press '**Enter**'
<br>
<br>
![arch-template-12](/attachment/wiki/ArchlinuxTemplate/arch-template-12.png)
<br>
<br>
* Screen "**Build Template Only?**"
@ -192,7 +197,7 @@ Main maintainer of this template is [Olivier Médoc](mailto:o_medoc@yahoo.fr).
* Select '**Yes**' Press '**Enter**'
<br>
<br>
![arch-template-12](/attachment/wiki/ArchlinuxTemplate/arch-template-12.png)
![arch-template-12](/attachment/wiki/ArchlinuxTemplate/arch-template-12a.png)
<br>
<br>
@ -200,9 +205,9 @@ Main maintainer of this template is [Olivier Médoc](mailto:o_medoc@yahoo.fr).
* Deselect '**Fedora**'
* Deselect '**mgnt_salt**'
* Deselect '**mgmt_salt**'
* Select '**archlinux**'
* Select '**builder-archlinux**'
* Select '**OK**' Press **Enter**
<br>
@ -213,10 +218,18 @@ Main maintainer of this template is [Olivier Médoc](mailto:o_medoc@yahoo.fr).
* Screen '**Get sources**' wants to download additional packages needed for the choosen plugin/s.
* Select '**No**' Press '**Enter**'
* Select '**Yes**' Press '**Enter**'
<br>
<br>
![arch-template-14](/attachment/wiki/ArchlinuxTemplate/arch-template-14.png)
<br>
<br>
* Then wait for download to finish and press '**OK**'
<br>
<br>
![arch-template-14](/attachment/wiki/ArchlinuxTemplate/arch-template-15.png)
<br>
<br>
* Screen '**Template Distribution Selection**' allows you to choose the actual template/s you wish to build.
@ -237,19 +250,6 @@ Main maintainer of this template is [Olivier Médoc](mailto:o_medoc@yahoo.fr).
<br>
![arch-template-17](/attachment/wiki/ArchlinuxTemplate/arch-template-17.png)
<br>
<br>
* Archlinux builder is not(yet?) in official Qubes release branch, so it has to be downloaded from different repository.
* Open file builder.conf with your favourite text editor and find section **"O V E R R I D E B R A N C H"** (single space
between letters) and add:
* **GIT_URL_builder_archlinux = $(GIT_BASEURL)/marmarek/qubes-builder-archlinux.git**
<br>
<br>
![arch-template-17](/attachment/wiki/ArchlinuxTemplate/arch-template-17a.png)
<br>
<br>
<br>
##### **7: Install all the dependencies:** #####
@ -388,7 +388,7 @@ Please check out:
[XYNE's (dev) Powerpill](http://xyne.archlinux.ca/projects/powerpill/)
**Important Note:** Until Powerpill is configured you will have to open network access to the template to get the initial packages etc downloaded. You can use the "allow full access for" a given time period in the FW settings of the template in the VMM or open up the various services thru the same window. Remember to change it back if you choose the later route. Actions needing network access will be noted with (needs network access)
**Important Note:** Until Powerpill is configured you will have to open network access to the template to get the initial packages etc downloaded. You can use the "allow full access for" a given time period in the FW settings of the template in the VMM or open up the various services through the same window. Remember to change it back if you choose the later route. Actions needing network access will be noted with (needs network access)
<br>
<br>
@ -676,9 +676,9 @@ Note: For info on Reflector and its configs: [Reflector](https://wiki.archlinux.
* There May also be a similar issue of dependencies with Xorg.
* Upgrade Relfector functionality to allow its use thru the QUPS
* Upgrade Relfector functionality to allow its use through the QUPS
* Pacman functionality changes and allows it to be directly configured to work thru QUPS.
* Pacman functionality changes and allows it to be directly configured to work through QUPS.
<br>
@ -694,6 +694,6 @@ Note: For info on Reflector and its configs: [Reflector](https://wiki.archlinux.
* [How can I contribute to the Qubes Project?](/doc/contributing/)
* [Guidelines for Documentation Contributors](doc/doc-guidelines/)
* [Guidelines for Documentation Contributors](/doc/doc-guidelines/)
<br>

9
managing-os/templates/debian.md
View file

@ -34,14 +34,10 @@ Debian 7 (wheezy) - old stable:
[user@dom0 ~]$ sudo qubes-dom0-update qubes-template-debian-7
(The download will take a while, and there will be no progress indicator.)
Debian 8 (jessie) - stable:
[user@dom0 ~]$ sudo qubes-dom0-update qubes-template-debian-8
(The download will take a while, and there will be no progress indicator.)
Debian 9 (stretch) - testing:
A prebuilt template is not yet available, but there are two options for
@ -59,3 +55,8 @@ Known issues
------------
If you want to help in improving the template, feel free to [contribute](/wiki/ContributingHowto).
More information
----------------
* [Debian wiki](https://wiki.debian.org/Qubes)

17
managing-os/debian-template-upgrade-8.md → managing-os/templates/debian/upgrade-8-to-9.md
View file

@ -1,8 +1,9 @@
---
layout: doc
title: Upgrading the Debian 8 Template
permalink: /doc/debian-template-upgrade-8/
title: Upgrading the Debian 8 Template to Debian 9
permalink: /doc/template/debian/upgrade-8-to-9/
redirect_from:
- /doc/debian-template-upgrade-8/
- /en/doc/debian-template-upgrade-8/
- /doc/DebianTemplateUpgrade8/
- /wiki/DebianTemplateUpgrade8/
@ -13,8 +14,10 @@ Upgrading the Debian 8 Template
Disclaimer: Debian 9 (Stretch) is marked testing for a reason. You may notice stability problems when using it.
Summary: Upgrading the Standard Debian 8 Template to Debian 9
-------------------------------------------------------------
Please note that if you installed packages from one of the testing repositories you must make sure that the repository is enabled in `/etc/apt/sources.list.d/qubes-r3.list` before attempting the upgrade. Otherwise, your upgrade will [break](https://github.com/QubesOS/qubes-issues/issues/2418).
Summary: Upgrading a Debian 8 Template to Debian 9
--------------------------------------------------
[user@dom0 ~]$ qvm-clone debian-8 debian-9
[user@dom0 ~]$ qvm-run -a debian-9 gnome-terminal
@ -78,7 +81,7 @@ any template based on the standard Debian 8 template.
Compacting the Upgraded Template
================================
--------------------------------
Neither `fstrim` nor the `discard` mount option works on the TemplateVM's root
filesystem, so when a file is removed in the template, space is not freed in
@ -110,7 +113,7 @@ TemplateVM's max size + the actually used space there) free space in dom0.
[user@dom0 ~]$ mv root.img.new root.img
Additional Information
======================
----------------------
It should be noted that Debian 9 (Stretch) is currently marked testing and
should be treat as such. For projects that need absolute stability, upgrading
@ -124,4 +127,4 @@ Relevant Mailing List Discussions
---------------------------------
* [Stretch Template Installation](https://groups.google.com/forum/#!topicsearchin/qubes-devel/debian$20stretch/qubes-devel/4rdayBF_UTc)
* [Stretch availability in 3.2](https://groups.google.com/forum/#!topicsearchin/qubes-devel/debian$20stretch/qubes-devel/cekPfBqQMOI)
* [Fixing sound in Debian Stretch](https://groups.google.com/forum/#!topic/qubes-users/JddCE54GFiU)
* [Fixing sound in Debian Stretch](https://groups.google.com/forum/#!topic/qubes-users/JddCE54GFiU)

115
managing-os/templates/fedora-minimal.md
View file

@ -12,71 +12,64 @@ redirect_from:
Fedora - minimal
================
The template weighs only about 300MB and has most of the stuff cut off, except for minimal X and xterm. It is really just a barebone and not even usable in this form - but you can customize it to meet your needs. You can find some usage examples in the section below.
The template only weighs about 300 MB and has only the most vital packages installed, including a minimal X and xterm installation.
The minimal template, however, can be easily extended to fit your requirements. The sections below contain the instructions on duplicating the template and provide some examples for commonly desired use cases.
Installation
------------
The Fedora minimal template can be installed with the following command:
Install
~~~
[user@dom0 ~]$ sudo qubes-dom0-update qubes-template-fedora-24-minimal
~~~
The download may take a while depending on your connection speed.
Duplication and first steps
---------------------------
It is higly recommended to clone the original template, and make any changes in the clone instead of the original template. The following command clones the template. Replace `your-new-clone` with your desired name.
~~~
[user@dom0 ~]$ qvm-clone fedora-24-minimal your-new-clone
~~~
You must start the template in order to customize it.
A recommended first step is to install the `sudo` package, which is not installed by default in the minimal template:
~~~
[user@your-new-clone ~]$ su -
[user@your-new-clone ~]$ dnf install sudo
~~~
Customization
-------------
Customizing the template for specific use cases normally only requires installing additional packages.
The following table provides an overview of which packages are needed for which purpose.
As expected, the required packages are to be installed in the running template with the following command. Replace "packages` with a space-delimited list of packages to be installed.
~~~
[user@your-new-clone ~]$ sudo dnf install packages
~~~
Use case | Description | Required steps
--- | --- | ---
**Standard utilities** | If you need the commonly used utilities | Install the following packages: `pciutils` `vim-minimal` `less` `psmisc` `gnome-keyring`
**FirewallVM** | You can use the minimal template as a [FirewallVM](/doc/firewall/), such as the basis template for `sys-firewall` | No extra packages are needed for the template to work as a firewall.
**NetVM** | You can use this template as the basis for a NetVM such as `sys-net` | Install the following packages: `NetworkManager` `NetworkManager-wifi` `network-manager-applet` `wireless-tools` `dbus-x11 dejavu-sans-fonts` `tinyproxy` `notification-daemon` `gnome-keyring`.
**NetVM (extra firmware)** | If your network devices need extra packages for the template to work as a network VM | Use the `lspci` command to identify the devices, then run `dnf search firmware` (replace `firmware` with the appropriate device identifier) to find the needed packages and then install them.
**Network utilities** | If you need utilities for debugging and analyzing network connections | Install the following packages: `tcpdump` `telnet` `nmap` `nmap-ncat`
**USB** | If you want USB input forwarding to use this template as the basis for a [USB](/doc/usb/) qube such as `sys-usb` | Install `qubes-input-proxy-sender`
**VPN** | You can use this template as basis for a [VPN](/doc/vpn/) qube | Use the `dnf search "NetworkManager VPN plugin"` command to look up the VPN packages you need, based on the VPN technology you'll be using, and install them. Some GNOME related packages may be needed as well. After creation of a machine based on this template, follow the [VPN howto](/doc/vpn/#set-up-a-proxyvm-as-a-vpn-gateway-using-networkmanager) to configure it.
Logging
-------
It can be installed via the following command:
The `rsyslog` logging service is not installed by default, as all logging is instead being handled by the `systemd` journal.
Users requiring the `rsyslog` service should install it manually.
~~~
[user@dom0 ~]$ sudo qubes-dom0-update qubes-template-fedora-23-minimal
~~~
To access the `journald` log, use the `journalctl` command.
Download will take a while and there will be no progress indicator.
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-23-minimal <your new template name>
~~~
The sudo package is not installed by default, so let's install it:
~~~
[user@F23-Minimal ~]$ su -
[user@F23-Minimal ~]$ dnf 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.
To access the journald log, use the `journalctl` command.
### as a NetVM
If you want to use this template to for standard NetVMs you should install some more packeges:
~~~
[user@F21-Minimal ~]$ sudo dnf install NetworkManager NetworkManager-wifi network-manager-applet wireless-tools dbus-x11 dejavu-sans-fonts tinyproxy
~~~
And maybe some more optional but useful packages as well:
~~~
[user@F21-Minimal ~]$ sudo dnf 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` and `dnf search firmware` command will help to choose the right one :)
### as a ProxyVM
If you want to use this template as a ProxyVM you may want to install even more packages
#### Firewall
This template is now ready to use for a standard firewall VM.
#### VPN
The needed packages depend on the VPN technology. The `dnf search "NetworkManager VPN plugin"` command may help you to choose the right one. You should also install the corresponding GNOME related packages as well.
[More details about setting up a VPN Gateway](/wiki/VPN#ProxyVM)
#### TOR
[UserDoc/TorVM](/wiki/UserDoc/TorVM)

11
managing-os/templates/fedora.md Normal file
View file

@ -0,0 +1,11 @@
---
layout: doc
title: The Fedora TemplateVM
permalink: /doc/templates/fedora/
---
The Fedora TemplateVM
=====================
The Fedora TemplateVM is the default TemplateVM in Qubes OS.

9
managing-os/fedora-template-upgrade-18.md → managing-os/templates/fedora/upgrade-18-to-20.md
View file

@ -1,14 +1,15 @@
---
layout: doc
title: Upgrading the Fedora 18 Temlpate
permalink: /doc/fedora-template-upgrade-18/
title: Upgrading the Fedora 18 Template to Fedora 20
permalink: /doc/template/fedora/upgrade-18-to-20/
redirect_from:
- /doc/fedora-template-upgrade-18/
- /en/doc/fedora-template-upgrade-18/
- /doc/FedoraTemplateUpgrade18/
- /wiki/FedoraTemplateUpgrade/
---
Upgrading the Fedora 18 Temlpate
Upgrading the Fedora 18 Template
================================
(**Note:** There is a [newer version of this page for upgrading from Fedora 20 to Fedora 21](/doc/fedora-template-upgrade-20/).)
@ -50,7 +51,7 @@ sudo yum --releasever=20 --setopt=cachedir=/mnt/removable distro-sync
After upgrade is finished, you can remove /var/tmp/template-upgrade-cache.img file.
Compacting templates root.img
=============================
-----------------------------
fstrim, nor "discard" mount option do not work on template root fs, so when some file is removed in the template, space isn't freed in dom0. This means that template will use about twice a space that is really need after upgrade.

11
managing-os/fedora-template-upgrade-20.md → managing-os/templates/fedora/upgrade-20-to-21.md
View file

@ -1,8 +1,9 @@
---
layout: doc
title: Upgrading the Fedora 20 Template
permalink: /doc/fedora-template-upgrade-20/
title: Upgrading the Fedora 20 Template to Fedora 21
permalink: /doc/template/fedora/upgrade-20-to-21/
redirect_from:
- /doc/fedora-template-upgrade-20/
- /en/doc/fedora-template-upgrade-20/
- /doc/FedoraTemplateUpgrade20/
- /wiki/FedoraTemplateUpgrade20/
@ -157,7 +158,7 @@ minimal template) is the same as the procedure for the standard template above,
Compacting the Upgraded Template
================================
--------------------------------
Neither `fstrim` nor the `discard` mount option works on the TemplateVM's root
filesystem, so when a file is removed in the template, space is not freed in
@ -190,7 +191,7 @@ TemplateVM's max size + the actually used space there) free space in dom0.
Additional Information
======================
----------------------
As mentioned above, you may encounter the following `yum` error:
@ -219,6 +220,6 @@ list which also apply to TemplateVM management and migration in general:
* [Jason M](https://groups.google.com/d/msg/qubes-users/mCXkxlACILQ/5PxDfI-RKAsJ)
Known issues with Fedora 21
===========================
---------------------------
* [The "Update VM" command in Qubes Manager does not work](https://github.com/QubesOS/qubes-issues/issues/982).

13
managing-os/fedora-template-upgrade-21.md → managing-os/templates/fedora/upgrade-21-to-23.md
View file

@ -1,8 +1,9 @@
---
layout: doc
title: Upgrading the Fedora 21 Template
permalink: /doc/fedora-template-upgrade-21/
title: Upgrading the Fedora 21 Template to Fedora 23
permalink: /doc/template/fedora/upgrade-21-to-23/
redirect_from:
- /doc/fedora-template-upgrade-21/
- /en/doc/fedora-template-upgrade-21/
- /doc/FedoraTemplateUpgrade21/
- /wiki/FedoraTemplateUpgrade21/
@ -140,7 +141,7 @@ minimal template) is the same as the procedure for the standard template above,
Compacting the Upgraded Template
================================
--------------------------------
Neither `fstrim` nor the `discard` mount option works on the TemplateVM's root
filesystem, so when a file is removed in the template, space is not freed in
@ -173,7 +174,7 @@ TemplateVM's max size + the actually used space there) free space in dom0.
Additional Information
======================
----------------------
As mentioned above, you may encounter the following `yum` error:
@ -202,13 +203,13 @@ list which also apply to TemplateVM management and migration in general:
* [Jason M](https://groups.google.com/d/msg/qubes-users/mCXkxlACILQ/5PxDfI-RKAsJ)
Upgrading to Fedora 22
======================
----------------------
You may choose to upgrade to Fedora 22 instead of Fedora 23. In that case,
simply replace version "23" with "22" in all above commands.
Known issues with Fedora 23
===========================
---------------------------
* [Graphical update tools (using PackageKit) does not work](https://github.com/QubesOS/qubes-issues/issues/982).
* [Dnf (new Fedora package manager) needs a lot of time to process repository metadata](https://bugzilla.redhat.com/show_bug.cgi?id=1227014), you may want to use `yum-deprecated` for now

238
managing-os/templates/fedora/upgrade-23-to-24.md Normal file
View file

@ -0,0 +1,238 @@
---
layout: doc
title: Upgrading the Fedora 23 Template to Fedora 24
permalink: /doc/template/fedora/upgrade-23-to-24/
redirect_from:
- /doc/fedora-template-upgrade-23/
- /en/doc/fedora-template-upgrade-23/
- /doc/FedoraTemplateUpgrade23/
- /wiki/FedoraTemplateUpgrade23/
---
Upgrading the Fedora 23 Template
================================
Summary: Upgrading the Standard Fedora 23 Template to Fedora 24
---------------------------------------------------------------
**Note:** The prompt on each line indicates where each command should be entered
(`@dom0` or `@fedora-24`).
[user@dom0 ~]$ qvm-clone fedora-23 fedora-24
[user@dom0 ~]$ truncate -s 5GB /var/tmp/template-upgrade-cache.img
[user@dom0 ~]$ qvm-run -a fedora-24 gnome-terminal
[user@dom0 ~]$ qvm-block -A fedora-24 dom0:/var/tmp/template-upgrade-cache.img
[user@fedora-24 ~]$ sudo mkfs.ext4 /dev/xvdi
[user@fedora-24 ~]$ sudo mount /dev/xvdi /mnt/removable
[user@fedora-24 ~]$ sudo dnf clean all
[user@fedora-24 ~]$ sudo dnf --releasever=24 --setopt=cachedir=/mnt/removable distro-sync
(Shut down TemplateVM by any normal means.)
[user@dom0 ~]$ rm /var/tmp/template-upgrade-cache.img
[user@dom0 ~]$ qvm-trim-template fedora-24
(Optional cleanup: Switch everything over to the new template and delete the old
one. See instructions below for details.)
Detailed: Upgrading the Standard Fedora 23 Template to Fedora 24
----------------------------------------------------------------
These instructions will show you how to upgrade the standard Fedora 23
TemplateVM to Fedora 24. The same general procedure may be used to upgrade any
template based on the standard Fedora 23 template.
**Note:** The command-line prompt on each line indicates where each command
should be entered (`@dom0` or `@fedora-24`).
1. Ensure the existing template is not running.
[user@dom0 ~]$ qvm-shutdown fedora-23
2. Clone the existing template and start a terminal in the new template.
[user@dom0 ~]$ qvm-clone fedora-23 fedora-24
[user@dom0 ~]$ qvm-run -a fedora-24 gnome-terminal
3. Attempt the upgrade process in the new template.
[user@fedora-24 ~]$ sudo dnf clean all
[user@fedora-24 ~]$ sudo dnf --releasever=24 distro-sync
**Note:** `dnf` might ask you to approve importing a new package signing
key. For example, you might see a prompt like this one:
warning: /var/cache/dnf/fedora-d02ca361e1b58501/packages/python2-babel-2.3.4-1.fc24.noarch.rpm: Header V3 RSA/SHA256 Signature, key ID 81b46521: NOKEY
Importing GPG key 0x81B46521:
Userid : "Fedora (24) <fedora-24-primary@fedoraproject.org>"
Fingerprint: 5048 BDBB A5E7 76E5 47B0 9CCC 73BD E983 81B4 6521
From : /etc/pki/rpm-gpg/RPM-GPG-KEY-fedora-24-x86_64
Is this ok [y/N]:
This key was already checked when it was installed (notice that the "From"
line refers to a location on your local disk), so you can safely say yes to
this prompt.
**Note:** If you encounter no errors, proceed to step 4. If you do encounter
errors, see the next two points first.
* If `dnf` reports that you do not have enough free disk space to proceed
with the upgrade process, create an empty file in dom0 to use as a cache
and attach it to the template as a virtual disk.
[user@dom0 ~]$ truncate -s 5GB /var/tmp/template-upgrade-cache.img
[user@dom0 ~]$ qvm-block -A fedora-24 dom0:/var/tmp/template-upgrade-cache.img
Then reattempt the upgrade process, but this time use the virtual disk
as a cache.
[user@fedora-24 ~]$ sudo mkfs.ext4 /dev/xvdi
[user@fedora-24 ~]$ sudo mount /dev/xvdi /mnt/removable
[user@fedora-24 ~]$ sudo dnf clean all
[user@fedora-24 ~]$ sudo dnf --releasever=24 --setopt=cachedir=/mnt/removable distro-sync
If this attempt is successful, proceed to step 4.
* `dnf` may complain:
At least X MB more space needed on the / filesystem.
In this case, one option is to [resize the TemplateVM's disk
image][resize-disk-image] before reattempting the upgrade process.
(See [Additional Information] below for other options.)
4. Shut down the new TemplateVM (from the command-line or Qubes VM Manager).
[user@dom0 ~]$ qvm-shutdown fedora-24
5. Remove the cache file, if you created one.
[user@dom0 ~]$ rm /var/tmp/template-upgrade-cache.img
6. Trim the new template (see [Compacting the Upgraded Template] for details
and other options).
[user@dom0 ~]$ qvm-trim-template fedora-24
7. (Recommended) Switch everything that was set to the old template to the new
template, e.g.:
1. Make the new template the default template:
Qubes Manager --> Global settings --> Default template
2. Base AppVMs on the new template. In Qubes Manager, for each VM that is
currently based on `fedora-23` that you would like to base on
`fedora-24`, enter its VM settings and change the Template selection:
Qubes Manager --> (Select a VM) --> VM settings --> Template
3. Base the [DispVM] template on the new template.
If you have set the new template as your default template:
[user@dom0 ~]$ qvm-create-default-dvm --default-template
Otherwise:
[user@dom0 ~]$ qvm-create-default-dvm fedora-24
8. (Optional) Remove the old template. (Make sure to type `fedora-23`, not
`fedora-24`.)
[user@dom0 ~]$ sudo dnf remove qubes-template-fedora-23
Summary: Upgrading the Minimal Fedora 23 Template to Fedora 24
--------------------------------------------------------------
**Note:** The prompt on each line indicates where each command should be entered
(`@dom0` or `@fedora-24`).
[user@dom0 ~]$ qvm-clone fedora-23-minimal fedora-24-minimal
[user@dom0 ~]$ qvm-run -a fedora-24-minimal xterm
[user@fedora-24-minimal ~]$ su -
[root@fedora-24-minimal ~]# dnf clean all
[user@fedora-24-minimal ~]# dnf --releasever=24 distro-sync
(Shut down TemplateVM by any normal means.)
[user@dom0 ~]$ qvm-trim-template fedora-24-minimal
(If you encounter insufficient space issues, you may need to use the methods
described for the standard template above.)
Differences Between the Standard and Minimal Upgrade Procedures
---------------------------------------------------------------
The procedure for upgrading the minimal template (or any template based on the
minimal template) is the same as the procedure for the standard template above,
**with the following exceptions**:
1. `gnome-terminal` is not installed by default. Unless you've installed it
(or another terminal emulator), use `xterm`. (Of course, you can also use
`xterm` for the standard template, if you prefer.)
2. `sudo` is not installed by default. Unless you've installed it, use `su` as
demonstrated above. (Of course, you can also use `su` for the standard
template, if you prefer.)
Compacting the Upgraded Template
--------------------------------
Neither `fstrim` nor the `discard` mount option works on the TemplateVM's root
filesystem, so when a file is removed in the template, space is not freed in
dom0. This means that the template will use about twice as much space as is
really necessary after upgrading.
You can use the `qvm-trim-template` tool:
[user@dom0 ~]$ qvm-trim-template fedora-24
Upgrading StandaloneVMs
-----------------------
The procedure for upgrading a StandaloneVM from Fedora 23 to Fedora 24 is the
same as for a TemplateVM, except that `qvm-trim-template` does not work on
StandaloneVMs. Instead, you should run the following command inside the
StandaloneVM in order to compact it:
$ sudo fstrim -v -a
Additional Information
----------------------
As mentioned above, you may encounter the following `dnf` error:
At least X MB more space needed on the / filesystem.
In this case, you have several options:
1. [Increase the TemplateVM's disk image size][resize-disk-image].
This is the solution mentioned in the main instructions above.
2. Delete files in order to free up space. One way to do this is by
uninstalling packages. You may then reinstalling them again after you
finish the upgrade process, if desired). However, you may end up having to
increase the disk image size anyway (see previous option).
3. Increase the `root.img` size with `qvm-grow-root`.
4. Do the upgrade in parts, e.g., by using package groups. (First upgrade
`@core` packages, then the rest.)
5. Do not perform an in-place upgrade. Instead, simply download and install a
new template package, then redo all desired template modifications.
With regard to the last option, here are some useful messages from the
mailing list which also apply to TemplateVM management and migration in
general:
* [Marek](https://groups.google.com/d/msg/qubes-users/mCXkxlACILQ/dS1jbLRP9n8J)
* [Jason M](https://groups.google.com/d/msg/qubes-users/mCXkxlACILQ/5PxDfI-RKAsJ)
[resize-disk-image]: /doc/resize-disk-image/
[Additional Information]: #additional-information
[Compacting the Upgraded Template]: #compacting-the-upgraded-template
[DispVM]: /doc/dispvm/

18
managing-os/templates/ubuntu.md
View file

@ -12,10 +12,10 @@ redirect_from:
Ubuntu template(s)
==================
If you like to use Ubuntu Linux distribution in your AppVMs, you can build and
install one of available Ubuntu templates. Those template currently are not
If you would like to use Ubuntu Linux distribution in your AppVMs, you can build and
install one of the available Ubuntu templates. These templates are currently not
available in ready to use binary packages, because Canonical does not allow
to redistribute a modified Ubuntu. The redistribution is not allowed by their
redistribution of a modified Ubuntu. The redistribution is not allowed by their
[Intellectual property rights policy](http://www.ubuntu.com/legal/terms-and-policies/intellectual-property-policy).
@ -30,15 +30,9 @@ To quickly prepare the builder configuration, you can use `setup` script
available in the repository - it will interactively ask you which templates you
want to build.
Known issues
------------
Ubuntu 14.4 LTS (Trusty) can be built with little effort.
Building an Ubuntu 14.4 LTS template can be difficult ([see](https://groups.google.com/forum/#!topic/qubes-users/w0uZNr8nno8)).
A workaround is creating an ubuntu HVM A and use X over ssh from a second vm B ([see](https://groups.google.com/forum/#!topic/qubes-users/-wkG7E55PUI)).
To do this you have to enable networking between A and B, or set B as netvm of A.
If B supports copy and paste or seamless mode so does (indirectly) A. (you will be missing some features. e.g.: send file to vm A)
Doing this reduces the security of A to the security of B!
This is no problem, if B's only purpose is providing X over ssh only for vm A.
----------
If you want to help in improving the template, feel free to
[contribute](/wiki/ContributingHowto).
[contribute](/doc/contributing/).

2
managing-os/uninstalling-windows-tools-2.md → managing-os/windows/uninstalling-windows-tools-2.md
View file

@ -60,7 +60,7 @@ If you need network access to copy the uninstall script to the HVM, use *Safe Mo
The uninstall script
====================
--------------------
Save it as a .BAT file in the HVM and run in Safe Mode.

22
managing-os/windows-appvms.md → managing-os/windows/windows-appvms.md
View file

@ -51,6 +51,14 @@ sudo qubes-dom0-update --enablerepo=qubes-dom0-current-testing qubes-windows-too
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 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.
Before proceeding with the installation we need to disable Windows mechanism that allows only signed drivers to be installed, because currently (beta releases) the drivers we provide as part of the Windows Tools are not digitally signed with a publicly recognizable certificate. To do that:
- Start command prompt as Administrator, i.e. right click on the Command Prompt icon and choose "Run as administrator"
- In the command prompt type `bcdedit /set testsigning on`
- Reboot your Windows VM
In the future this step will not be necessary anymore, because we will sign our drivers with a publicly verifiable certificate. However, it should be noted that even now, the fact that those drivers are not digitally signed, this doesn't affect security of the Windows VM in 'any' way. This is because the actual installation ISO (the `qubes-windows-tools-*.iso` file) is distributed as a signed RPM package and its signature is verified by the `qubes-dom0-update` utility once it's being installed in Dom0. The only downside of those drivers not being signed is the inconvenience to the user that he or she must disable the signature enforcement policy before installing the tools.
To install the Qubes Windows Tools in a Windows VM one should start the VM passing the additional option `--install-windows-tools`:
~~~
@ -59,9 +67,7 @@ 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.
Before proceeding with the installation we need to disable Windows mechanism that allows only signed drivers to be installed, because currently (beta releases) the drivers we provide as part of the Windows Tools are not digitally signed with a publicly recognizable certificate. How to do that is explained in the `README` file also located on the installation CDROM. In the future this step will not be necessary anymore, because we will sign our drivers with a publicly verifiable certificate. However, it should be noted that even now, the fact that those drivers are not digitally signed, this doesn't affect security of the Windows VM in 'any' way. This is because the actual installation ISO (the `qubes-windows-tools-*.iso` file) is distributed as a signed RPM package and its signature is verified by the `qubes-dom0-update` utility once it's being installed in Dom0. The only downside of those drivers not being signed is the inconvenience to the user that he or she must disable the signature enforcement policy before installing the tools.
After successful installation, the Windows VM must be shut down and started again.
After successful installation, the Windows VM must be shut down and started again, possibly a couple of times (see [this page](/doc/windows-tools-3/) for detailed configuration options).
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:
@ -69,7 +75,7 @@ Qubes (R2 Beta 3 and later releases) will automatically detect the tools has bee
qvm-prefs <your-appvm-name>
~~~
NOTE: it is recommended to increase the default value of `qrexec_timeout` property from 60 (seconds) to, for example, 300. During one of the first reboots after Windows Tools installation Windows user profiles are moved onto the private VM's virtual disk (private.img) and this operation can take some time. Moving profiles is performed in an early boot phase when qrexec is not yet running, so timeout may occur with the default value. To change the property use this command in dom0:
NOTE: it is recommended to increase the default value of Windows VM's `qrexec_timeout` property from 60 (seconds) to, for example, 300. During one of the first reboots after Windows Tools installation Windows user profiles are moved onto the private VM's virtual disk (private.img) and this operation can take some time. Moving profiles is performed in an early boot phase when qrexec is not yet running, so timeout may occur with the default value. To change the property use this command in dom0:
~~~
qvm-prefs -s <vm-name> qrexec_timeout 300
@ -104,10 +110,10 @@ To simulate CTRL-ALT-DELETE in the HVM (SAS, Secure Attention Sequence), press C
![windows-seamless-7.png](/attachment/wiki/WindowsAppVms/windows-seamless-7.png)
Forcing Windows AppVM into full desktop mode
--------------------------------------------
Changing between seamless and full desktop mode
-----------------------------------------------
You can switch between seamless and "full desktop" mode for Windows HVMs in their settings in Qubes Manager.
You can switch between seamless and "full desktop" mode for Windows HVMs in their settings in Qubes Manager. The latter is the default.
Using template-based Windows AppVMs (Qubes R2 Beta 3 and later)
---------------------------------------------------------------
@ -123,7 +129,7 @@ qvm-create --hvm-template win7-x64-template -l green
- The private disk is initialized and formatted on the first reboot after tools installation. It can't be done **during** the installation because Xen mass storage drivers are not yet active.
- User profiles are moved to the private disk on the next reboot after the private disk is initialized. Reboot is required because the "mover utility" runs very early in the boot process so OS can't yet lock any files in there. This can take some time depending on the profiles' size and because the GUI agent is not yet active dom0/Qubes Manager may complain that the AppVM failed to boot. That's a false alarm (you can increase AppVM's default boot timeout using `qvm-prefs`), the VM should appear "green" in Qubes Manager shortly after.
It also makes sense to disable Automatic Updates for all the Windows-based AppVMs -- of course this should be done in the Template VM, not in individual AppVMs, because the system-wide setting are stored in the root filesystem (which holds the system-wide registry hives).
It also makes sense to disable Automatic Updates for all the template-based AppVMs -- of course this should be done in the Template VM, not in individual AppVMs, because the system-wide setting are stored in the root filesystem (which holds the system-wide registry hives). Then, periodically check for updates in the Template VM and the changes will be carried over to any child AppVMs.
Once the template has been created and installed it is easy to create AppVMs based on:

0
managing-os/windows-tools-2.md → managing-os/windows/windows-tools-2.md
View file

13
managing-os/windows-tools-3.md → managing-os/windows/windows-tools-3.md
View file

@ -32,16 +32,17 @@ Qubes Windows Tools (QWT for short) contain several components than can be enabl
**In testing VMs only** it's probably a good idea to install a VNC server before installing QWT. If something goes very wrong with the Qubes gui agent, a VNC server should still allow access to the OS.
**NOTE**: Xen PV disk drivers are not installed by default. This is because they seem to cause severe problems, including disk image/files corruption in Qubes HVMs. We're investigating this. *However*, the problem doesn't always occur in tests -- disk drivers often work *if they are installed separately after the main portion of QWT is up and running*. **Do this at your own risk** of course, but we welcome reports of success/failure in any case. With disk PV drivers absent `qvm-block` will not work for the VM, but you can still use standard Qubes inter-VM file copying mechanisms.
**NOTE**: Xen PV disk drivers are not installed by default. This is because they seem to cause problems (BSOD). We're working with upstream devs to fix this. *However*, the BSOD seems to only occur after the first boot and everything works fine after that. **Enable the drivers at your own risk** of course, but we welcome reports of success/failure in any case (backup your VM first!). With disk PV drivers absent `qvm-block` will not work for the VM, but you can still use standard Qubes inter-VM file copying mechanisms.
Verbose installation
--------------------
Xen PV driver components may display a message box asking for reboot during installation -- it's safe to ignore them and defer the reboot.
If the install process fails you can retry it using the command line below to get a detailed installation log (and send that to us):
Installation logs
-----------------
`msiexec /i path-to-qubes-tools.msi /lv path-to-log-file.txt`
If the install process fails or something goes wrong during it, include the installation logs in your bug report. They are created in the `%TEMP%` directory, by default `<user profile>\AppData\Local\Temp`. There are two text files, one small and one big, with names starting with `Qubes_Windows_Tools`.
Uninstalling QWT 3.x is **not recommended**. It will most likely make the OS non-bootable because drivers for Xen storage devices will be uninstalled. This will be fixed in the future.
Uninstalling QWT is supported from version 3.2.1. Uninstalling previous versions is **not recommended**.
After uninstalling you need to manually enable the DHCP Client Windows service, or set IP settings yourself to restore network access.
Configuration
-------------