KVMSurf Files

KVMSurf
=======

Create a Debian Live based Linux distribution optimized for Internet surfing within a virtual machine.

License: GPLv3
Web: http://www.henrici.biz/projects/kvmsurf.html


Important note
~~~~~~~~~~~~~~
These scripts are provided on a "works for me" basis only. Use at your own risk.
The scripts are tested on Debian Wheezy and Debian Mint (May 2013); KVM was used as virtualization host. For your environment, some adaptations might be required. However, I hope you find these scripts useful.


Building a KVMSurf image from source
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Note: This is only necessary if you did not download a prebuild iso image file.

Install Debian Live Build on your Debian system
  aptitude install live-build

Optionally: Adjust the makefile to your needs. 

Run "make" to build the image.

Run "make install" to copy the generated image to the "/home/vm/" diretory (or another one if specified as such).


Running the generated image
~~~~~~~~~~~~~~~~~~~~~~~~~~~
There are two options for running the system:
1) Use the disk image iso file as virtual CDROM drive und use it as a normal Debian Live boot image.
2) Use the disk image iso as a harddisk image and boot via "Direct Kernel Boot" offered by KVM/LibVirt. The correct kernel parameters (see below) need to be provided for direct kernel boot to work properly. However, it is the fastest and thus recommended way for booting if you are an advanced user.

It is important that you choose "qxl" as graphics adapter for your virtual hardware. There are no other X graphics drivers included in KVMSurf by default.


Kernel Boot Parameters
~~~~~~~~~~~~~~~~~~~~~~
Example for kernel boot parameters
  root=/dev/vda boot=live config hostname=kvmsurf1 locales=de_DE.UTF-8 mount=//192.168.1.10/kvmsurf,/home/server,user=kvmsurf,password=mypassword,nobrl,uid=1000,exec

Explanation
  "root=/dev/vda"
    Drive for root file system. This parameter is needed for direct kernel boot. "vda" is for a KVM VirtIO device, "sda" for a SCSI device.
  "boot=live config"
    Request Debian Live scripts to run for doing some configuration tasks on boot time.
  "hostname=kvmsurf1"
    Overrides the default hostname.
  "locales=de_DE.UTF-8"
    Overrides the default locale.
  "keyboard-layouts=de"
    Overrides the keyboard layout.
  "mount=//192.168.1.70/kvmsurf,/home/server,user=kvmsurf,password=mypassword,nobrl,uid=1000,exec
    Mounts a CIFS network share. The mount directory is created in case it does not exist. At the end, arbitrary mount parameter can be listed comma-separatedly.
    "nobrl" ("no byte range locking") is needed if you want to place a Firefox/Iceweasel profile folder on the share.
    If you use "/home/server" as mount directory AND specify the "exec" mount option AND have an executable file "onboot.sh" in the root of the mounted share, the latter script is executed on boot. This makes runtime customizations simple.  


Make targets for building from source
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
make
make all
  Shortcut for "make clean" followed by "make build"

make clean
  Cleans some files from the previous build process (standard Debian Live Build cleansing)

make veryclean
  In addition to "make clean", delete all temporary directories exept the cache directory

make totallyclean
  In addition to "make veryclean", delete the cache directory

make install
  Install the generated images in the destination directory

make uninstall
  Delete the generated images in the destination directory