+
+Host bundling operation
+=======================
+
+As a new feature in *v0.2*, snf-image-creator can create images out of the host
+system that runs the program. This is done either by specifying / as input
+media or by using the *Bundle Host* button in the media selection dialog of
+snf-mkimage. During this operation, the files of the disk are copied into a
+temporary image file, which means that the file system that will host the
+temporary image needs to have a lot of free space (see `large temporary files`_
+for more information).
+
+Creating a new image
+====================
+
+Suppose you want to create a new Ubuntu server image. Download the installation
+disk from the Internet:
+
+.. code-block:: console
+
+ $ wget http://ubuntureleases.tsl.gr/12.04.2/ubuntu-12.04.2-server-amd64.iso
+
+Verify that it has been downloaded correctly:
+
+.. code-block:: console
+
+ $ echo 'a8c667e871f48f3a662f3fbf1c3ddb17 ubuntu-12.04.2-server-amd64.iso' > check.md5
+ $ md5sum -c check.md5
+
+Create a 2G sparse file to host the new system:
+
+.. code-block:: console
+
+ $ truncate -s 2G ubuntu.raw
+
+And install the Ubuntu system on this file:
+
+.. code-block:: console
+
+ $ sudo kvm -boot d -drive file=ubuntu.raw,format=raw,cache=none,if=virtio \
+ -m 1G -cdrom ubuntu-12.04.2-server-amd64.iso
+
+.. warning::
+
+ During the installation, you will be asked about the partition scheme. Don't
+ use LVM partitions. They are not supported by snf-image-creator.
+
+You will be able to boot your installed OS and make any changes you want
+(e.g. install openssh-server) using the following command::
+
+ $ sudo kvm -m 1G -boot c -drive file=ubuntu.raw,format=raw,cache=none,if=virtio
+
+After you're done, you may use *snf-mkimage* as root to create and upload the
+image:
+
+.. code-block:: console
+
+ $ sudo -s
+ $ snf-mkimage ubuntu.raw
+
+In the first screen you will be asked to choose if you want to run the program
+in *Wizard* or *Expert* mode. Choose *Wizard*.
+
+.. image:: /snapshots/wizard.png
+
+Then you will be asked to select a cloud and provide a name, a description and
+a registration type (*private* or *public*). Finally, you'll be asked to
+confirm the provided data.
+
+.. image:: /snapshots/confirm.png
+
+Choosing *YES* will create and upload the image to your cloud account.
+
+Limitations
+===========
+
+Supported operating systems
+---------------------------
+
+*snf-image-creator* can only fully function on input media hosting *Linux*
+systems. The program will detect the needed metadata and you may use it to
+upload and register other *Unix* or *Windows* images, but you cannot use it to
+shrink them or perform system preparation operations.
+
+Logical Volumes
+---------------
+
+The program cannot work on LVM partitions [#f1]_. The input media may only
+contain primary or logical partitions.
+
+Para-virtualized drivers
+------------------------
+
+Most synnefo deployments uses the *VirtIO* framework. The disk I/O controller
+and the Ethernet cards on the VM instances are para-virtualized and need
+special *VirtIO* drivers. Those drivers are included in the Linux Kernel
+mainline since version 2.6.25 and are shipped with all the popular Linux
+distributions. The problem is that if the driver for the para-virtualized disk
+I/O controller is built as module, it needs to be preloaded using an initial
+ramdisk, otherwise the VM won't be able to boot.
+
+Many popular Linux distributions, like Ubuntu and Debian, will automatically
+create a generic initial ramdisk file that contains many different modules,
+including the VirtIO drivers. Others that target more experienced users, like
+Slackware, won't do that [#f2]_. *snf-image-creator* cannot resolve this kind
+of problems and it's left to the user to do so. Please refer to your
+distribution's documentation for more information on this. You can always check
+if a system can boot with para-virtualized disk controller by launching it with
+kvm using the *if=virtio* option (see the kvm command in the
+`Creating a new image`_ section).
+
+Some caveats on image creation
+==============================
+
+Image partition schemes and shrinking
+-------------------------------------
+
+When image shrinking is enabled, *snf-image-creator* will shrink the last
+partition on the disk. If this is a swap partition, it will remove it, save
+enough information to recreate it during image deployment and shrink the
+partition that lays just before that. This will make the image smaller which
+speeds up the deployment process.
+
+During image deployment, the last partition is enlarged to occupy the available
+space in the VM's hard disk and a swap partition is added at the end if a SWAP
+image property is present.
+
+Keep this in mind when creating images. It's always better to have your swap
+partition placed as the last partition on the disk and have your largest
+partition (*/* or */home*) just before that.
+
+Large temporary files
+---------------------
+
+*snf-image-creator* may create large temporary files when running:
+
+ * During image shrinking, the input media snapshot file may reach the size of
+ the original media.
+ * When bundling the host system, the temporary image file may became as large
+ as the rest of the disk files altogether.
+
+*/tmp* directory is not a good place for hosting large files. In many systems
+the contents of */tmp* are stored in volatile memory and the size they may occupy
+is limited. By default, *snf-image-creator* will use a heuristic approach to
+determine where to store large temporary files. It will examine the free space
+under */var/tmp*, the user's home directory and */mnt* and will pick the one
+with the most available space. The user may overwrite this behaviour and
+indicate a different directory using the *tmpdir* option. This option is
+supported by both *snf-image-creator* and *snf-mkimage*.
+
+.. rubric:: Footnotes
+
+.. [#f1] http://sourceware.org/lvm2/
+.. [#f2] http://mirrors.slackware.com/slackware/slackware-14.0/README.initrd