Skip to content
Snippets Groups Projects
Commit 1e72da95 authored by Alex Pyrgiotis's avatar Alex Pyrgiotis
Browse files

Restore original image creation example 

Also, add a warning about LVM, the need for openssh-server, memmory
parameter for KVM and md5sum for the dowloaded iso.
parent 9de17202
No related branches found
No related tags found
No related merge requests found
Hide whitespace changes
Inline Side-by-side
Showing
with 68 additions and 274 deletions
docs/usage.rst
+ 68
− 274
View file @ 1e72da95
...@@ -194,311 +194,105 @@ By choosing the *Extract* menu entry the user can dump the image to the local ...@@ -194,311 +194,105 @@ 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 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. all changes made so far and will start the image creation process again.
Usage example Creating a new image
============= ====================
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 <https://okeanos.grnet.gr/support/user-guide/cyclades-how-do-
i-connect-to-a-vm/#windows-linux-host-to-linux-guest-graphical>`_.
For our guest OS, we will choose, Linux Mint, which is the most hyped Linux Suppose you want to create a new Ubuntu server image. Download the installation
OS according to Distrowatch. A new version has just been released, so disk from the Internet:
this seems like a fine choice. ::
Warning: The installation might take a long time (~1 hour) and a bit of .. code-block:: console
lagginess due to nested virtualization is to be expected.
Fire up your terminal, go to your home directory and type the following to $ wget http://ubuntureleases.tsl.gr/12.04.1/ubuntu-12.04.1-server-amd64.iso
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:
Verify that it has been downloaded correctly. If the following command .. code-block:: console
prints "OK". then you are good to go::
$ echo 'b370ac59d1ac6362f1662cfcc22a489c linuxmint-14-mate-dvd-64bit.iso' > check.md5 $ echo 'a8c667e871f48f3a662f3fbf1c3ddb17 ubuntu-12.04.1-server-amd64.iso' > check.md5
$ md5sum -c check.md5 $ md5sum -c check.md5
Allocate a few gigs of space to create a sparse file:: Create a 2G sparce file to host the new system:
$ truncate -s 7G linuxmint.raw
Use `kvm` to boot the Live CD:: .. code-block:: console
$ 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: $ truncate -s 2G ubuntu_hd.raw
-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 And install the Ubuntu system on this file:
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| .. code-block:: console
Choose "Install Linux Mint". The installation process should be pretty $ sudo kvm -boot d -drive file=ubuntu_hd.raw,format=raw,cache=none,if=virtio \
straightforward. Just keep two things in mind: -m 1000 -cdrom ubuntu-12.04.1-server-amd64.iso
* The username you choose will also be used later on, when you create a VM .. note::
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| 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.
After the installation is complete, you can close the QEMU window. You 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 will be able to boot your installed OS and make any changes you want to it
using the following command:: (e.g. install openssh-server) 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 <https://wiki.archlinux.org/index.php/KVM#Paravirtualized_
guests_.28virtio.29>`_ 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 $ sudo kvm -m 1000 -drive file=linuxmint.raw,format=raw,cache=none,if=virtio
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 After you're done, become root, activate the virtual environment you have
provided to them. So, any changes they apply do not affect the OS installed snf-image-creator in, and use *snf-mkimage* to create and upload the
installed on the original media.* image:
Let's see both tools in action. We will use them to create an image of the .. code-block:: console
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| $ sudo -s
$ source /path/to/snf-image-env/bin/activate
$ snf-mkimage ubuntu_hd.raw
Alternatively, if you want to create a VM from another user's custom In the first screen you will be asked to choose if you want to run the program
image, you can go to the "Public Images" section. in *Wizard* or *Expert* mode. Choose *Wizard*.
.. |qemu-live| image:: /snapshots/qemu-live.png .. image:: /snapshots/01_wizard.png
.. |qemu-partition| image:: /snapshots/qemu-partition.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.
.. |mkimage-wizard| image:: /snapshots/mkimage-wizard.png .. image:: /snapshots/06_confirm.png
.. |mkimage1| image:: /snapshots/mkimage1.png Choosing *YES* will create the image and upload it to your *~okeanos* account.
.. |mkimage2| image:: /snapshots/mkimage2.png Some caveats on image creation
==============================
.. |mkimage3| image:: /snapshots/mkimage3.png Para-virtualized drivers
------------------------
.. |mkimage4| image:: /snapshots/mkimage4.png *~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.
.. |mkimage-fin| image:: /snapshots/mkimage-fin.png 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.
.. |mkimage-results| image:: /snapshots/mkimage-results.png Swap partitions
---------------
.. |image-creator| image:: /snapshots/image-creator.png 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.
.. |custom-vm| image:: /snapshots/custom-vm.png .. rubric:: Footnotes
.. [#f1] https://wiki.archlinux.org/index.php/KVM#Paravirtualized_guests_.28virtio.29
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment