From 4197b5a67d514a81deff8081f401baa690bb04b2 Mon Sep 17 00:00:00 2001 From: Nikos Skalkotos Date: Mon, 14 Jan 2013 19:49:56 +0200 Subject: [PATCH] Update the documentation to reflect v0.2 --- docs/conf.py | 4 +- docs/install.rst | 6 +- docs/snapshots/select_media.png | Bin 0 -> 13184 bytes docs/usage.rst | 224 ++++++++++++++++++++++++--------------- 4 files changed, 139 insertions(+), 95 deletions(-) create mode 100644 docs/_static create mode 100644 docs/snapshots/select_media.png diff --git a/docs/_static b/docs/_static new file mode 100644 index 0000000..e69de29 diff --git a/docs/conf.py b/docs/conf.py index bd5c7f0..a78ba58 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -48,9 +48,9 @@ copyright = u'2012, GRNET' # built documents. # # The short X.Y version. -version = '0.1' +version = '0.2' # The full version, including alpha/beta/rc tags. -release = '0.1' +release = '0.2' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. diff --git a/docs/install.rst b/docs/install.rst index 7f15be9..357c5cf 100644 --- a/docs/install.rst +++ b/docs/install.rst @@ -89,11 +89,9 @@ In Ubuntu you can do this using: python-sendfile python-parted .. note:: - - If during the installation you get prompted to create/update a + If you are asked during the installation to create/update a "supermin appliance", choose "Yes". - Python Virtual Environment -------------------------- @@ -165,8 +163,6 @@ For ubuntu this can be done using: $ apt-get install git .. warning:: - Keep in mind that the bleeding edge version may be unstable or even unusable. - diff --git a/docs/snapshots/select_media.png b/docs/snapshots/select_media.png new file mode 100644 index 0000000000000000000000000000000000000000..8c0cd99e54d18da072c39b56c23dd2b8ea4b34e6 GIT binary patch literal 13184 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 ABLDyZ literal 0 HcmV?d00001 diff --git a/docs/usage.rst b/docs/usage.rst index d789268..b8f4ffb 100644 --- a/docs/usage.rst +++ b/docs/usage.rst @@ -2,9 +2,14 @@ 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 +Both expect the input media as first argument. The input media may be a local +file, a block device or *"/"* if you want to create an image out of the running +system (see `host bundling operation`_). + Non-interactive version ======================= @@ -13,58 +18,57 @@ snf-image-creator receives the following options: .. code-block:: console $ snf-image-creator --help - Usage: snf-image-creator [options] Options: - --version show program's version number and exit - -h, --help show this help message and exit - -o FILE, --outfile=FILE - dump image to FILE - -f, --force overwrite output files if they exist - -s, --silent silent mode, only output errors - -u FILENAME, --upload=FILENAME - upload the image to pithos with name FILENAME - -r IMAGENAME, --register=IMAGENAME - register the image with ~okeanos as IMAGENAME - -a ACCOUNT, --account=ACCOUNT - Use this ACCOUNT when uploading/registering images - [Default: None] - -m KEY=VALUE, --metadata=KEY=VALUE - Add custom KEY=VALUE metadata to the image - -t TOKEN, --token=TOKEN - Use this token when uploading/registering images - [Default: None] - --print-sysprep print the enabled and disabled system preparation - operations for this input media - --enable-sysprep=SYSPREP - run SYSPREP operation on the input media - --disable-sysprep=SYSPREP - prevent SYSPREP operation from running on the input - media - --no-sysprep don't perform system preparation - --no-shrink don't shrink any partition - - -Most input options are self-describing. If you want to save a local copy for -the image you create, you specify *-o* option. To upload the image to -*pithos+*, you specify valid credentials with *-a* and *-t* options and a -filename using *-u*. If you want to register the image with *~okeanos*, -in addition to *-u* specify a registration name using *-r*. + --version show program's version number and exit + -h, --help show this help message and exit + -o FILE, --outfile=FILE + dump image to FILE + -f, --force overwrite output files if they exist + -s, --silent output only errors + -u FILENAME, --upload=FILENAME + upload the image to pithos with name FILENAME + -r IMAGENAME, --register=IMAGENAME + register the image with ~okeanos as IMAGENAME + -a ACCOUNT, --account=ACCOUNT + use this ACCOUNT when uploading/registering images + [Default: None] + -m KEY=VALUE, --metadata=KEY=VALUE + add custom KEY=VALUE metadata to the image + -t TOKEN, --token=TOKEN + use this token when uploading/registering images + [Default: None] + --print-sysprep print the available enabled and disabled system + preparation operations for this input media + --enable-sysprep=SYSPREP + run SYSPREP operation on the input media + --disable-sysprep=SYSPREP + prevent SYSPREP operation from running on the input + media + --no-sysprep don't perform any system preparation operation + --no-shrink don't shrink the image + --tmpdir=DIR create large temporary image files under DIR + +Most input options are self-describing. If you want to save a local copy of +the image you create, provide a resulting filename using the *-o* option. To +upload the image to *pithos+*, provide valid credentials using *-a* and *-t* +and a filename using *-u*. If you also want to register the image with +*~okeanos*, in addition to *-u* provide a registration name using *-r*. By default snf-image-creator will perform a number of system preparation operations 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, the program will exit after outputing a +If *--print-sysprep* is defined, the program will exit after printing a list of enabled and disabled system preparation operation applicable to this media source. The user can enable or disable specific *syspreps* when creating -an image, using *-{enable,disable}-sysprep* options. You can specify those +an image, using *-{enable,disable}-sysprep* options. You may specify those 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: +debian system, we print the following output: .. _sysprep: @@ -126,8 +130,8 @@ debian system, we get the following output: cleaning up... -If we want the image to have all normal user accounts and all mail files -removed, we can create it specifying *--enable-sysprep* option like this: +If you want the image to have all normal user accounts and all mail files +removed, you should use *--enable-sysprep* option like this: .. code-block:: console @@ -140,18 +144,27 @@ Dialog-based version .. code-block:: console - $ Usage: snf-mkimage [options] [] + $ snf-mkimage --help + 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 + 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 + --tmpdir=DIR create large temporary image files under DIR If the input media is not specified in the command line, in the first dialog -box the user will be asked to specify it. After the input media is examined and -the program is initialized, the user will be given the choice to run -*snf-mkimage* in *wizard* or *expert* mode. +box the user will be asked to specify it: + +.. image:: /snapshots/select_media.png + +The user can select a file (regular or block device) or use the *Bundle Host* +button to create an image out of the running system (see +`Host bundling operation`_). + +After the input media is examined and the program is initialized, the user will +be given the choice to run *snf-mkimage* in *wizard* or *expert* mode. Wizard mode ----------- @@ -160,14 +173,16 @@ When *snf-mkimage* runs in *wizard* mode, the user is just asked to provide the following basic information: * Name: A short name for the image (ex. "Slackware") - * Description: An one-line description for the image (ex. "Slackware Linux 14.0 with KDE") + * Description: An one-line description for the image + (ex. "Slackware Linux 14.0 with KDE") * Account: An *~okeanos* account email * Token: A token corresponding to the account defined previously After confirming, the image will be extracted, uploaded to *pithos+* and -registered to *~okeanos*. The user will also be given the choice to keep a local -copy of it. For most users the functionality this mode provides should be -sufficient. +registered to *~okeanos*. The user will also be given the choice to keep a +local copy of it. + +For most users the functionality this mode provides should be sufficient. Expert mode ----------- @@ -187,13 +202,24 @@ In the *Customize* sub-menu the user can control: In the *Register* sub-menu the user can provide: * The credentials to login to *~okeanos* - * A pithos filename for the uploaded *diskdump* image + * 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 +By choosing the *Extract* menu entry, the user can dump the image to the local +file system. Finally, if the user selects *Reset*, the system will ignore all changes made so far and will start the image creation process again. +Host bundling operation +======================= + +As a new feature in *v0.2*, snf-image-creator can create images out of the host +system that runs the program. This is done either by specifying / as input +media or by using the *Bundle Host* button in the media selection dialog of +snf-mkimage. During this operation, the files of the disk are copied into a +temporary image file, which means that the file system that will host the +temporary image needs to have a lot of free space (see `the tmpdir option`_ +for more information). + Creating a new image ==================== @@ -222,28 +248,24 @@ 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 \ - -m 1000 -cdrom ubuntu-12.04.1-server-amd64.iso + -m 1G -cdrom ubuntu-12.04.1-server-amd64.iso -.. note:: +.. warning:: - 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. + During the installation, you will be asked about the partition scheme. Don't + use LVM partitions. They are not supported by snf-image-creator. -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 +You will be able to boot your installed OS and make any changes you want to it (e.g. install openssh-server) using the following command:: - $ sudo kvm -boot d -drive file=ubuntu_hd.raw,format=raw,cache=none,if=virtio + $ sudo kvm -m 1G -boot c -drive file=ubuntu_hd.raw,format=raw,cache=none,if=virtio -After you're done, become root, activate the virtual environment you have -installed snf-image-creator in, and use *snf-mkimage* to create and upload the +After you're done, you may use *snf-mkimage* as root to create and upload the image: .. code-block:: console $ sudo -s - $ source /path/to/snf-image-env/bin/activate $ snf-mkimage ubuntu_hd.raw In the first screen you will be asked to choose if you want to run the program @@ -257,7 +279,7 @@ confirm the provided data. .. image:: /snapshots/06_confirm.png -Choosing *YES* will create the image and upload it to your *~okeanos* account. +Choosing *YES* will create and upload the image to your *~okeanos* account. Some caveats on image creation ============================== @@ -273,26 +295,52 @@ 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. -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. - -Swap partitions ---------------- - -If you want your image to have a swap partition, 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. +Many popular linux distributions, like Ubuntu and Debian, will automatically +create a generic initial ramdisk file that contains many different modules, +including the VirtIO drivers. Others that target more experienced users, like +Slackware, won't do that [#f1]_. *snf-image-creator* cannot resolve this kind +of problems and it's left to the user to do so. Please refer to your +distribution's documentation for more information on this. You can always check +if a system can boot with para-virtualized disk controller by launching it with +kvm using the *if=virtio* option (take a look at the kvm command in the +`Creating a new image`_ section). + +Image partition schemes and shrinking +------------------------------------- + +When image shrinking is enabled, *snf-image-creator* will shrink the last +partition on the disk. If this is a swap partition, it will remove it, save +enough information to recreate it during image deployment and shrink the +partition that lays just before that. This will make the image smaller which +speeds up the deployment process. + +During image deployment, the last partition is enlarged to occupy the available +space in the VM's hard disk and a swap partition is added at the end if a SWAP +image property is present. + +Keep this in mind when creating images. It's always better to have your swap +partition placed as the last partition on the disk and have your largest +partition (*/* or */home*) just before that. + +The tmpdir option +----------------- + +*snf-image-creator* may create large temporary files when running: + + * During image shrinking, the input media snapshot file may reach the size of + the original media. + * When bundling the host system, the size of temporary image file may reach + the size of all disk files. + +The */tmp* directory is not a good place for hosting large files. In many systems +the contents of */tmp* are stored in volatile memory and the size they may occupy +is limited. By default, *snf-image-creator* will use a heuristic approach to +determine where to store large temporary files. It will examine the free space +under */var/tmp*, the user's home directory and */mnt* and will pick the one +with the most free space. The user may overwrite this behaviour and indicate a +directory using the *tmpdir* option. This option is present in both +*snf-image-creator* and *snf-mkimage*. .. rubric:: Footnotes -.. [#f1] https://wiki.archlinux.org/index.php/KVM#Paravirtualized_guests_.28virtio.29 +.. [#f1] http://mirrors.slackware.com/slackware/slackware-14.0/README.initrd -- 1.7.10.4