From: Nikos Skalkotos Date: Wed, 17 Oct 2012 14:36:48 +0000 (+0300) Subject: Update snf-image-creator usage documentation X-Git-Tag: v0.1~14 X-Git-Url: https://code.grnet.gr/git/snf-image-creator/commitdiff_plain/fa77d79a98c00b71221870f0ed7b6a6ca7b23f41 Update snf-image-creator usage documentation Add missing sections --- diff --git a/docs/index.rst b/docs/index.rst index 356d405..a27ad0f 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -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 `_ diff --git a/docs/install.rst b/docs/install.rst index 9b7a9ab..7cb9cb9 100644 --- a/docs/install.rst +++ b/docs/install.rst @@ -1,5 +1,5 @@ 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: diff --git a/docs/overview.rst b/docs/overview.rst index d823afe..55f0e15 100644 --- a/docs/overview.rst +++ b/docs/overview.rst @@ -1,5 +1,5 @@ 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 `_. Image Format ------------- +============ The images the program creates are in diskdump format. This is the recommended format for `snf-image `_, the Ganeti diff --git a/docs/snapshots/main_menu.png b/docs/snapshots/main_menu.png new file mode 100644 index 0000000..536eec0 Binary files /dev/null and b/docs/snapshots/main_menu.png differ diff --git a/docs/usage.rst b/docs/usage.rst index dbeec58..a7c371e 100644 --- a/docs/usage.rst +++ b/docs/usage.rst @@ -1,12 +1,12 @@ 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] [] + + 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