X-Git-Url: https://code.grnet.gr/git/snf-image-creator/blobdiff_plain/b28209d949da5c3289c8188a7947112551594266..1e72da952348c62a3d96b6c97f23e54da03dd9e0:/docs/usage.rst

diff --git a/docs/usage.rst b/docs/usage.rst
index 3e4acf3..2199116 100644
--- a/docs/usage.rst
+++ b/docs/usage.rst
@@ -66,6 +66,8 @@ options multiple times to enable or disable multiple *syspreps*.
 Running *snf-image-creator* with *--print-sysprep* on a raw file that hosts a
 debian system, we get the following output:
 
+.. _sysprep:
+
 .. code-block:: console
 
    $ snf-image-creator --print-sysprep debian_desktop.img
@@ -191,3 +193,106 @@ In the *Register* sub-menu the user can provide:
 By choosing the *Extract* menu entry the user can dump the image to the local
 file system and finally, if the user selects *Reset*, the system will ignore
 all changes made so far and will start the image creation process again.
+
+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.1/ubuntu-12.04.1-server-amd64.iso
+
+Verify that it has been downloaded correctly:
+
+.. code-block:: console
+
+   $ echo 'a8c667e871f48f3a662f3fbf1c3ddb17  ubuntu-12.04.1-server-amd64.iso' > check.md5
+   $ md5sum -c check.md5
+
+Create a 2G sparce file to host the new system:
+
+.. code-block:: console
+
+   $ truncate -s 2G ubuntu_hd.raw
+
+And install the Ubuntu system on this file:
+
+.. code-block:: console
+
+   $ sudo kvm -boot d -drive file=ubuntu_hd.raw,format=raw,cache=none,if=virtio \
+     -m 1000 -cdrom ubuntu-12.04.1-server-amd64.iso
+
+.. note::
+
+   During the installation, you will be asked about the partition scheme. Since
+   snf-image-creator does not support LVM partitions, you are advised to create
+   regular partitions.
+
+When the installation is complete, you can close the QEMU window. You
+will be able to boot your installed OS and make any changes you want to it
+(e.g. install openssh-server) using the following command::
+
+   $ sudo kvm -m 1000 -drive file=linuxmint.raw,format=raw,cache=none,if=virtio
+
+After you're done, become root, activate the virtual environment you have
+installed snf-image-creator in, and use *snf-mkimage* to create and upload the
+image:
+
+.. code-block:: console
+
+   $ sudo -s
+   $ source /path/to/snf-image-env/bin/activate
+   $ snf-mkimage ubuntu_hd.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/01_wizard.png
+
+Then you will be asked to provide a name, a description, an *~okeanos* account
+and the token corresponding to this account. After that you will be asked to
+confirm the provided data.
+
+.. image:: /snapshots/06_confirm.png
+
+Choosing *YES* will create the image and upload it to your *~okeanos* account.
+
+Some caveats on image creation
+==============================
+
+Para-virtualized drivers
+------------------------
+
+*~Okeanos* 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 will not be able to boot.
+
+In the image creation demonstration above, we initially installed the Ubuntu
+system on a hard disk (*ubuntu_hd.raw*) that was connected on a
+para-virtualized interface (pay attention to the *if=virtio* option of the kvm
+line). Ubuntu and Debian create a generic initial ramdisk file that contains
+many different modules, including the VirtIO drivers. In many distros this is
+not the case. In Arch Linux for example, the user needs to manually add
+*virtio_blk* and *virtio_pci* drivers in */etc/mkinitcpio.conf* and rebuild the
+initial ramdisk [#f1]_ to make the virtio drivers get preloaded during boot.
+For now, *snf-image-creator* cannot resolve this kind of problems and it's left
+to the user to do it.
+
+Swap partitions
+---------------
+
+If you want your image to have a swap partitions, make sure this is the last
+partition on the disk. If snf-image-creator detects a swap partition in the end
+of the input media, it will remove the partition when shrinking and will save
+enough information to be able to recreate it during image deployment. This will
+make the image smaller and will speed up the deployment process.
+
+.. rubric:: Footnotes
+
+.. [#f1] https://wiki.archlinux.org/index.php/KVM#Paravirtualized_guests_.28virtio.29