From: Alex Pyrgiotis Date: Thu, 13 Dec 2012 11:34:34 +0000 (+0200) Subject: Update usage section with an example X-Git-Tag: v0.2~9^2~4 X-Git-Url: https://code.grnet.gr/git/snf-image-creator/commitdiff_plain/9de17202577f52d05e5512531b9edb8177ac0ac8 Update usage section with an example The example has been copied from okeanos-guides. However, some of the example's steps have been ommited (e.g. the installation of snf-image-creator). Also, the focus has been shifted from ~okeanos to a run-of-the-mill synnefo deployment. --- diff --git a/docs/snapshots/custom-vm.png b/docs/snapshots/custom-vm.png new file mode 100644 index 0000000..d55f616 Binary files /dev/null and b/docs/snapshots/custom-vm.png differ diff --git a/docs/snapshots/image-creator.png b/docs/snapshots/image-creator.png new file mode 100644 index 0000000..63cbe9b Binary files /dev/null and b/docs/snapshots/image-creator.png differ diff --git a/docs/snapshots/mkimage-fin.png b/docs/snapshots/mkimage-fin.png new file mode 100644 index 0000000..10bca5b Binary files /dev/null and b/docs/snapshots/mkimage-fin.png differ diff --git a/docs/snapshots/mkimage-results.png b/docs/snapshots/mkimage-results.png new file mode 100644 index 0000000..637523e Binary files /dev/null and b/docs/snapshots/mkimage-results.png differ diff --git a/docs/snapshots/mkimage-wizard.png b/docs/snapshots/mkimage-wizard.png new file mode 100644 index 0000000..ec22eed Binary files /dev/null and b/docs/snapshots/mkimage-wizard.png differ diff --git a/docs/snapshots/mkimage1.png b/docs/snapshots/mkimage1.png new file mode 100644 index 0000000..083eef1 Binary files /dev/null and b/docs/snapshots/mkimage1.png differ diff --git a/docs/snapshots/mkimage2.png b/docs/snapshots/mkimage2.png new file mode 100644 index 0000000..5fea5fd Binary files /dev/null and b/docs/snapshots/mkimage2.png differ diff --git a/docs/snapshots/mkimage3.png b/docs/snapshots/mkimage3.png new file mode 100644 index 0000000..b87f06c Binary files /dev/null and b/docs/snapshots/mkimage3.png differ diff --git a/docs/snapshots/mkimage4.png b/docs/snapshots/mkimage4.png new file mode 100644 index 0000000..a9b34a0 Binary files /dev/null and b/docs/snapshots/mkimage4.png differ diff --git a/docs/snapshots/qemu-live.png b/docs/snapshots/qemu-live.png new file mode 100644 index 0000000..57a6c92 Binary files /dev/null and b/docs/snapshots/qemu-live.png differ diff --git a/docs/snapshots/qemu-partition.png b/docs/snapshots/qemu-partition.png new file mode 100644 index 0000000..1080570 Binary files /dev/null and b/docs/snapshots/qemu-partition.png differ diff --git a/docs/usage.rst b/docs/usage.rst index 3e4acf3..90cf460 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,312 @@ 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. + +Usage example +============= + +Supposing you have snf-image-creator installed on a machine (hereafter referred +to as your **host machine**), you can follow the next steps to upload and +register an image of an OS of your preference (hereafter referred to as your +**guest OS**) to your synnefo deployment. + + * `Step 1: Install the guest OS`_ + * `Step 2: Create and upload an image of the guest OS`_ + * `Step 3: Create your VM`_ + + +Step 1: Install the guest OS +----------------------------- + +The guest OS has to be installed on a media such as a block device or a regular +raw file, that can be **accessible** by your host machine. + +But why is accessible empasized? Well, because you don't need to do the +installation of the guest OS on your host machine. You can just as well install +it on a raw file, upload it on Pithos+, download it on your host machine and +use it for Step 2. + +*Note: If you have a guest OS already installed, you may want to skip the +next step. However, be sure to check out the* `Caveats`_ *section, where +some requirements about the guest OS are presented.* + +Installation example +"""""""""""""""""""" + +To simplify things a bit, we will install the guest OS on the host machine +where snf-image-creator is installed. We will assume that the host machine is +an Ubuntu 12.04 ~okeanos VM, built with max specifications (4 CPUs, 2GB of +ram, 40GB of disk space at the time of writing this). + +*Note: Since the installation of the guest OS will take place on your host +VM, you must be able to connect to it graphically. This is covered by our* +`connection guide `_. + +For our guest OS, we will choose, Linux Mint, which is the most hyped Linux +OS according to Distrowatch. A new version has just been released, so +this seems like a fine choice. :: + + Warning: The installation might take a long time (~1 hour) and a bit of + lagginess due to nested virtualization is to be expected. + +Fire up your terminal, go to your home directory and type the following to +download the Linux Mint live cd:: + + $ wget http://ftp.ntua.gr/pub/linux/linuxmint//stable/14/linuxmint-14-mate-dvd-64 bit.iso + +Verify that it has been downloaded correctly. If the following command +prints "OK". then you are good to go:: + + $ echo 'b370ac59d1ac6362f1662cfcc22a489c linuxmint-14-mate-dvd-64bit.iso' > check.md5 + $ md5sum -c check.md5 + +Allocate a few gigs of space to create a sparse file:: + + $ truncate -s 7G linuxmint.raw + +Use `kvm` to boot the Live CD:: + + $ sudo kvm -m 1200 -smp 4 -boot d -drive \ + file=linuxmint.raw,format=raw,cache=none,if=virtio \ + -cdrom linuxmint-14-mate-dvd-64bit.iso + + At a glance, let's see what the above options do: + -m 1200: Use 1200MB of RAM for the guest OS. You should + allocate as much as possible + -smp 4: Simulate an SMP system with 4 CPUs for the + guest OS to use. + -boot d: Place cdrom first in the boot order + file=opensuse.raw Use this raw file as the "hard disk" for the + installation + if=virtio: Inform the OS that it should preload the + VirtIO drivers (more on that on `Caveats`_ + section) + -cdrom linuxmint-14-mate-dvd-64bit.iso: + "Insert" Linux Mint's live cd in the cdrom + drive + +Wait a few seconds and then a new screen with the Linux Mint logo should +appear. You don't have to press any key since it will boot automatically to +Linux Mint's live desktop after a few minutes. + +|qemu-live| + +Choose "Install Linux Mint". The installation process should be pretty +straightforward. Just keep two things in mind: + +* The username you choose will also be used later on, when you create a VM + from this OS image. The password, however, will be removed and you will + be given a new one. +* The installed OS must have no more than one primary partition and + optionally a swap partition. You can read more in the `Caveats`_ + section below. You don't have to worry about it in this installation + however, since the default option takes care of that. + + |qemu-partition| + +After 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 +using the following command:: + + $ sudo kvm -m 1200 -smp 4 -boot d -drive \ + file=linuxmint.raw,format=raw,cache=none,if=virtio + +At the very least, you should install OpenSSH server to connect to your VM +properly. You can install OpenSSH server using the following command:: + + $ sudo apt-get install openssh-server + +Bear in mind that once the OS image has been uploaded to your synnefo +deployment, you will not be able to make changes to it. Since you can only +apply changes to your raw file, you are advised to do so now and then proceed +to Step 2. + +Caveats +""""""" +This is a list of restrictions you must have in mind while installing the +guest OS: + +**Partitions** + +The installation must consist of no more than one primary partition. It +can have a swap partition though, which should ideally - but not +necessarily - be located at the end of the media. In this case, the +uploaded image will be much smaller and the VM deployment process much +faster. + +**VirtIO drivers** + +Depending on your synnefo-deployment, you may need to use para-virtualized +drivers for your storage and network needs. + +~okeanos uses the VirtIO framework which is essential for the ~okeanos VMs +to work properly since their disk I/O controller and Ethernet cards are +para-virtualized. + +Fortunately, you will not need to deal with the installation of VirtIO drivers +directly, since they are included in Linux kernel since version 2.6.25 and +shipped with all the modern Linux distributions. However, if the VirtIO drivers +are built as a module (and most modern OSes do so), they need to be preloaded +using an initial ramdisk (initramfs), otherwise the VM you create from this OS +image will not be able to boot. + +Debian derivatives will create an initial ramdisk with VirtIO included if +they are connected during the installation on a para-virtualized interface +(the "if=virtio" option in the Linux Mint example). + +In many other distros though, 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 to make the +virtio drivers get preloaded during boot. You can read more in the `Arch +Linux wiki `_ on how to do it. + +For now, snf-image-creator cannot resolve this kind of problems and it's +left to the user to do it. + +Step 2: Create and upload an image of the guest OS +-------------------------------------------------- + +This is the step on which we use snf-image-creator. There are actually two +variants of snf-image-creator, `snf-image-creator`_ and `snf-mkimage`_, both +achieving the same results but suited for different needs. Their scope is +documented at the start of the `Usage`_ section of this document. + +*Note: Both tools take a snapshot of the installed OS on the media +provided to them. So, any changes they apply do not affect the OS +installed on the original media.* + +Let's see both tools in action. We will use them to create an image of the +Linux Mint 14 OS we installed in Step 2. + +snf-mkimage +""""""""""" + +In order to use snf-mkimage, simply type:: + + $ sudo snf-mkimage linuxmint.raw + +snf-mkimage will initially check if the media is indeed a single disk +partition or a raw file representing a hard disk. Then, it will use +heuristics to understand which OS has been installed on the media. After +that, you will be asked which mode you prefer. + +|mkimage-wizard| + +* Wizard mode is intuitive and consists of 4 simple steps. +* Expert mode has an abundance of options but requires a bit of knowledge + of the inner workings of Cyclades from your part. You can learn more on the + `Expert Mode`_ section of snf-mkimage. + +For our tutorial, we will use Wizard mode. So, choose "Wizard" and then provide +a name for the image. + +|mkimage1| + +This name will appear on Pithos+ and on the Public Images section of Cyclades. + +Then, provide a description for the image. + +|mkimage2| + +This will appear under the chosen image name on the Public Images section of +cyclades. + +Next, add your account e-mail + +|mkimage3| + +... your account token... + +|mkimage4| + +...and you're done! A list operations will appear on your console. + +|mkimage-results| + +We will briefly comment on the above output. + +* **Sysprep:** Operations from 1/9 to 9/9 are part of the system + preparation operations and are best explained in the snf-image-creator's + `sysprep`_ section. +* **Shrinking:** When shrinking the image, we check if a swap partition + exists at the end of the media. If this is the case, it will be removed + and re-inserted upon the deployment process of the VM. Alternatively, if + the swap partition lies at the start of the media, it will be left + untouched. On both cases, the primary partition will be shrunken as much + as possible. On this example, we can see that the final size is 3.5GB, + whereas the orginal size was 7GB. This means that the image was reduced + by half, a pretty impressive feat. +* **MD5SUM:** The md5sum of the image is used later on to verify that the + image has been uploaded successfully. +* **Uploading:** Everytime you upload an OS image, every block is hashed, + checked against existing blocks in Pithos+ and finally uploaded, if no + other block has the same hash. + + *Consider this example: You have just uploaded a Gentoo Linux image but + had forgotten to install a necessary package. In this case, you would + probably edit the OS in the raw file and then use snf-mkimage to upload + the new image. However, since there is an almost identical image already + uploaded on Pithos+, you can just as well upload only the blocks that + differentiate those two images. This is both time and space efficient.* + +Finally, after the image has been uploaded successfully, you will be asked +whether you want to save a local copy of the **shrunken** image. This is +just a copy of the diskdump that has been uploaded to Pithos+ and, in case +you are confused, the original OS installed on the media (linuxmint.raw in +our example) remains intact. + +snf-image-creator +""""""""""""""""" + +snf-image-creator is the command-line equivalent of snf-mkimage. All the +info provided in the steps above are given now as options, which makes it +ideal for scripting purposes. The full set of options can be found in the +`Usage section <#non-interactive-version>`_ of snf-image-creator's +documentation. + +This tool is most commonly used with the following set of options:: + + $ sudo snf-image-creator linuxmint.raw -a user@email.com \ + -t hUudl4DEIlomlnvWnv7Rlw== -u linuxmint.diskdump -r "Linux Mint 14 Nadia" + +As you can see, these options are exactly what snf-mkimage's steps +translate to. You can also see that the output is nearly identical: + +|image-creator| + +Step 3: Create your VM +---------------------- + +Creating a VM out of an uploaded custom image is a fairly simple task. +Just select "New Machine", go to "My Images" section and select your +image. + +|custom-vm| + +Alternatively, if you want to create a VM from another user's custom +image, you can go to the "Public Images" section. + +.. |qemu-live| image:: /snapshots/qemu-live.png + +.. |qemu-partition| image:: /snapshots/qemu-partition.png + +.. |mkimage-wizard| image:: /snapshots/mkimage-wizard.png + +.. |mkimage1| image:: /snapshots/mkimage1.png + +.. |mkimage2| image:: /snapshots/mkimage2.png + +.. |mkimage3| image:: /snapshots/mkimage3.png + +.. |mkimage4| image:: /snapshots/mkimage4.png + +.. |mkimage-fin| image:: /snapshots/mkimage-fin.png + +.. |mkimage-results| image:: /snapshots/mkimage-results.png + +.. |image-creator| image:: /snapshots/image-creator.png + +.. |custom-vm| image:: /snapshots/custom-vm.png +