Commit fa77d79a authored by Nikos Skalkotos's avatar Nikos Skalkotos
Browse files

Update snf-image-creator usage documentation

Add missing sections
parent c8025360
......@@ -4,7 +4,7 @@
contain the root `toctree` directive.
Welcome to snf-image-creator's documentation!
=============================================
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
snf-image-creator is an image creation tool for `Synnefo <https://code.grnet.gr/projects/synnefo>`_
......
Installation
============
^^^^^^^^^^^^
This guide describes how to install snf-image-creator on an Ubuntu 12.04 LTS
system. It it highly recommended to have virtualization capable hardware.
......@@ -7,7 +7,7 @@ snf-image-creator can work on processors that do not support virtualization but
it will be extremely slow.
Dependencies
------------
============
snf-image-creator depends on the following programs:
......@@ -33,7 +33,7 @@ the following command:
The rest of the dependencies will be resolved by setuptools.
Python Virtual Environment
--------------------------
==========================
Since snf-image-creator and the rest of it's dependencies won't be installed
using packages provided by the distribution it's better to work in an isolated
......@@ -64,7 +64,7 @@ You can later deactivate it using the following command:
kamaki Installation
-------------------
===================
Install kamaki from source, by cloning it's repository:
......@@ -82,7 +82,7 @@ execute:
$ ./setup install
snf-image-creator Installation
------------------------------
==============================
Install snf-image-creator the same way:
......
Overview
========
^^^^^^^^
snf-image-creator is a simple command-line tools for creating OS images. The
original media from which the image is created, can be a block device or a
......@@ -8,18 +8,18 @@ will create a snapshot for it and will run a number of image preparation task
on the snapshot, before the image is created.
Snapshotting
------------
============
snf-image-creator works on snapshots of the original media. Any changes made by
the program do not affect the original media.
Preparation
-----------
===========
Some of the image preparation tasks that run on each image are OS specific.
snf-image-creator will use heuristics to detect the OS of the image and
determine which tasks should run on it. The main purpose of running those tasks
is to:
Some of the image preparation operations that run on each image are OS
specific. snf-image-creator will use heuristics to detect the OS of the image
and determine which operations should run on it. The main purpose of running
them is to:
* Shrink the image
* Clear out sensitive user data (passwords, ssh keys, history files, etc.)
......@@ -27,13 +27,13 @@ is to:
names, remove persistent net rules, etc.)
Creation
--------
========
The program can either dump the image file locally or directly upload it to
pithos and register it with `okeanos <http://www.okeanos.grnet.gr>`_.
Image Format
------------
============
The images the program creates are in diskdump format. This is the recommended
format for `snf-image <https://code.grnet.gr/projects/snf-image>`_, the Ganeti
......
Usage
=====
^^^^^
snf-image-creator comes in 2 variants:
* snf-image-creator: A non-interactive command line program
* snf-mkimage: A user-friendly dialog-based program
Non-interactive version
-----------------------
=======================
snf-image-creator receives the following options:
......@@ -52,20 +52,19 @@ pithos, you need to specify valid credentials with *-a* and *-t* options and a
filename using *-u* option. To also register the image with ~okeanos, specify a
name using the *-r* option.
By default snf-image-creator will run a number of system preparation tasks on
the snapshot of the media and will shrink the last partition found, before
extracting the image. Both can be disabled by specifying *--no-sysprep* and
*--no-shrink* respectively.
By default snf-image-creator will run a number of system preparation
preparations on the snapshot of the media and will shrink the last partition
found, before extracting the image. Both can be disabled by specifying
*--no-sysprep* and *--no-shrink* respectively.
If *--print-sysprep* is defined, then snf-image-creator will not create an
image at all. It will only run the OS detection part and will output the system
preparation tasks that would and would not run on the image. This behavior is,
convenient because it allows you to see the available system preparation tasks
that you can enable or disable with *-{enable,disable}-sysprep* options when
you create a new image.
If *--print-sysprep* is defined, then snf-image-creator will only run the OS
detection part and will output the system preparation operation that would and
would not run during image creation. This behavior is, convenient because it
allows you to see the available system preparation tasks that you can enable or
disable with *-{enable,disable}-sysprep* options when you create a new image.
Running *snf-image-creator* with *--print-sysprep* on a raw file that hosts a
debian system, I get the following output:
debian system, we get the following output:
.. code-block:: console
......@@ -133,14 +132,68 @@ removed, you can create it specifying the *--enable-sysprep* option like this:
$ snf-image-creator --enable-sysprep cleanup-mail,remove-user-accounts ...
Dialog-based version
--------------------
====================
*snf-mkimage* receives the following options:
.. code-block:: console
$ Usage: snf-mkimage [options] [<input_media>]
Options:
--version show program's version number and exit
-h, --help show this help message and exit
-l FILE, --logfile=FILE
log all messages to FILE
If the input media is not specified in the command line, then the user will be
asked to specify it in the first dialog box. After the input media is examined
and the program is initialized, the user is given the choice to run
*snf-mkimage* in *wizard* or *expert* mode.
Wizard mode
-----------
When *snf-mkimage* runs in *wizard* mode, the user is just asked to provide the
following basic information:
* Name: A short name for image (ex. "Slackware")
* Description: An one line description for the image (ex. "Slackware Linux 14.0 with KDE")
* Account: An ~okeanos account e-mail
* Token: A token corresponding to the account defined previously
For most users the functionality this mode provides should be sufficient.
Expert mode
-----------
Expert mode allows the user to have better control on the image creation
process. In the picture below the main menu can be seen:
.. image:: /snapshots/main_menu.png
In the *Customize* submenu the user can control:
* The system preparation operations that will run during the image creation process
* Whether the image will be shrunk or not
* The properties associated with the image
* Which configuration tasks will run during image deployment
In the *Register* submenu the user can provide:
* The credentials to login to ~okeanos
* A pithos filename for the uploaded diskdump image
* A name for the image to be registered to ~okeanos with
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:
Suppose you want to create a new Ubuntu server image. Download the installation
disk from the Internet:
.. code-block:: console
......@@ -152,15 +205,16 @@ Create a 2G sparce file to host the new system:
$ truncate -s 2G ubuntu_hd.raw
And install the ubuntu system on this file:
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 \
-cdrom ubuntu-12.04.1-server-amd64.iso
After this, become root, activate the virtual environment you have installed
snf-image-creator in, and use *snf-mkimage* to create and upload the image:
After the installation finishes, 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
......@@ -169,7 +223,7 @@ snf-image-creator in, and use *snf-mkimage* to create and upload the image:
$ snf-mkimage ubuntu_hd.raw
In the first screen you will be asked to choose if you want to run the program
in *Wizand* or *Expert* mode. Choose *Wizard*.
in *Wizard* or *Expert* mode. Choose *Wizard*.
.. image:: /snapshots/01_wizard.png
......@@ -181,3 +235,38 @@ confirm the provided data.
Choosing *YES* will create the image and upload it to your ~okeanos account.
Things you need to pay attention on when creating images
========================================================
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 those drivers are built as modules, they need 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 a hard disk (ubuntu_hd.raw) that was para-virtualized (pay
attention on the *if=virtio* option of the kvm line). The Ubuntu installer
detected that the disk was paravirtualized and made sure the appropriate
drivers will be preloaded each time the system boots. 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 then
rebuild the initial ramdisk [#f1]_ to make the virtio drivers get preloaded
during boot.
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 during shrinking and will save
enough information to be able to recreate it during image deployment. This will
make your image smaller and will speed up the deployment process.
.. rubric:: Footnotes
.. [#f1] https://wiki.archlinux.org/index.php/KVM#Paravirtualized_guests_.28virtio.29
Markdown is supported
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