X-Git-Url: https://code.grnet.gr/git/snf-image-creator/blobdiff_plain/f0b21d376243f5ceb5594c4f0951721043d3a210..1e72da952348c62a3d96b6c97f23e54da03dd9e0:/docs/usage.rst diff --git a/docs/usage.rst b/docs/usage.rst index 32e09dd..2199116 100644 --- a/docs/usage.rst +++ b/docs/usage.rst @@ -1,35 +1,244 @@ Usage -===== +^^^^^ snf-image-creator comes in 2 variants: - * snf-mkimage: A user-friendly dialog-based program * 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: + +.. 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*. + +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 +list of enabled and disabled system preparation operation appliable 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 +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: + +.. _sysprep: + +.. code-block:: console + + $ snf-image-creator --print-sysprep debian_desktop.img + + snf-image-creator 0.1 + ===================== + Examining source media `debian_desktop.img'... looks like an image file + Snapshotting media source... done + Enabling recovery proc + Launching helper VM... done + Inspecting Operating System... found a(n) debian system + Mounting the media read-only... done + + Enabled system preparation operations: + cleanup-cache: + Remove all regular files under /var/cache + + cleanup-log: + Empty all files under /var/log + + cleanup-passwords: + Remove all passwords and lock all user accounts + + cleanup-tmp: + Remove all files under /tmp and /var/tmp + + cleanup-userdata: + Delete sensitive userdata + + fix-acpid: + Replace acpid powerdown action scripts to immediately shutdown the + system without checking if a GUI is running. + + remove-persistent-net-rules: + Remove udev rules that will keep network interface names persistent + after hardware changes and reboots. Those rules will be created again + the next time the image runs. + + remove-swap-entry: + Remove swap entry from /etc/fstab. If swap is the last partition + then the partition will be removed when shrinking is performed. If the + swap partition is not the last partition in the disk or if you are not + going to shrink the image you should probably disable this. + + use-persistent-block-device-names: + Scan fstab & grub configuration files and replace all non-persistent + device references with UUIDs. + + Disabled system preparation operations: + cleanup-mail: + Remove all files under /var/mail and /var/spool/mail + + remove-user-accounts: + Remove all user accounts with id greater than 1000 + + + 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: + +.. code-block:: console + + $ snf-image-creator --enable-sysprep cleanup-mail --enable-sysprep 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, 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. + +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 the image (ex. "Slackware") + * 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. + +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* sub-menu the user can control: + + * The system preparation operations that will be applied on the media + * Whether the image will be shrunk or not + * The properties associated with the image + * The configuration tasks that will run during image deployment + +In the *Register* sub-menu 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 $ wget http://ubuntureleases.tsl.gr/12.04.1/ubuntu-12.04.1-server-amd64.iso +Verify that it has been downloaded correctly: + +.. code-block:: console + + $ echo 'a8c667e871f48f3a662f3fbf1c3ddb17 ubuntu-12.04.1-server-amd64.iso' > check.md5 + $ md5sum -c check.md5 + Create a 2G sparce file to host the new system: .. code-block:: console $ 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 + -m 1000 -cdrom ubuntu-12.04.1-server-amd64.iso + +.. note:: + + 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. + +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 +(e.g. install openssh-server) using the following command:: + + $ sudo kvm -m 1000 -drive file=linuxmint.raw,format=raw,cache=none,if=virtio -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 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 +image: .. code-block:: console @@ -38,14 +247,52 @@ 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 -Then you will be asked to provide a name, a description, an ~okeanos account +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. .. image:: /snapshots/06_confirm.png -Choosing *YES* will create the image and upload it to your ~okeanos account. +Choosing *YES* will create the image and upload it to your *~okeanos* account. + +Some caveats on image creation +============================== + +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 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 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. + +.. rubric:: Footnotes + +.. [#f1] https://wiki.archlinux.org/index.php/KVM#Paravirtualized_guests_.28virtio.29