From fa77d79a98c00b71221870f0ed7b6a6ca7b23f41 Mon Sep 17 00:00:00 2001 From: Nikos Skalkotos Date: Wed, 17 Oct 2012 17:36:48 +0300 Subject: [PATCH] Update snf-image-creator usage documentation Add missing sections --- docs/index.rst | 2 +- docs/install.rst | 10 ++-- docs/overview.rst | 18 +++--- docs/snapshots/main_menu.png | Bin 0 -> 18711 bytes docs/usage.rst | 131 +++++++++++++++++++++++++++++++++++------- 5 files changed, 125 insertions(+), 36 deletions(-) create mode 100644 docs/snapshots/main_menu.png 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 0000000000000000000000000000000000000000..536eec0296b12ec9e54327070c37155e427fbdf2 GIT binary patch literal 18711 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 literal 0 HcmV?d00001 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 -- 1.7.10.4