X-Git-Url: https://code.grnet.gr/git/snf-image-creator/blobdiff_plain/aa486e935452c7120582057caf9db0c77b88d68a..97d863ff7ce616ce9f595ba08a6460e0d08d2d3d:/docs/usage.rst diff --git a/docs/usage.rst b/docs/usage.rst index c43fb29..679b319 100644 --- a/docs/usage.rst +++ b/docs/usage.rst @@ -17,42 +17,50 @@ 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 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 - -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 - --public register image with cyclades as public - --tmpdir=DIR create large temporary image files under DIR + $ 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 output only errors + -u FILENAME, --upload=FILENAME + upload the image to the storage service with name FILENAME + -r IMAGENAME, --register=IMAGENAME + register the image with the compute service as IMAGENAME + -m KEY=VALUE, --metadata=KEY=VALUE + add custom KEY=VALUE metadata to the image + -t TOKEN, --token=TOKEN + use this authentication token when + uploading/registering images + -a URL, --authentication-url=URL + use this authentication URL when uploading/registering + images + -c CLOUD, --cloud=CLOUD + use this saved cloud account to authenticate against a + cloud when uploading/registering images + --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 any system preparation operation + --no-shrink don't shrink any partition + --public register image with the compute service as public + --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 filename using the *-o* option. To upload the -image to *pithos+*, provide a valid authentication token using *-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*. All images are +image to the storage service of a cloud, provide valid cloud API access info +(by either using a token and a URL with *-t* and *-a* respectively, or a cloud +name with *-c*) and a remote filename using *-u*. If you also want to register +the image with the compute service of the cloud, in addition to *-u* provide a +registration name using *-r*. All images are registered as *private*. Only the user that registers the image can create VM's out of it. If you want the image to be visible by other user too, use the *--public* option. @@ -75,61 +83,62 @@ debian system, we print the following output: .. code-block:: console - $ snf-image-creator --print-sysprep debian_desktop.img - - snf-image-creator 0.1 + $ snf-image-creator --print-sysprep ubuntu.raw + snf-image-creator 0.3 ===================== - Examining source media `debian_desktop.img'... looks like an image file - Snapshotting media source... done + Examining source media `ubuntu_hd.raw' ... 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 - + Launching helper VM (may take a while) ... done + Inspecting Operating System ... ubuntu + Mounting the media read-only ... done + Collecting image metadata ... done + Umounting the media ... done + Enabled system preparation operations: cleanup-cache: - Remove all regular files under /var/cache - + Remove all regular files under /var/cache + cleanup-log: - Empty all files under /var/log - + Empty all files under /var/log + cleanup-passwords: - Remove all passwords and lock all user accounts - + Remove all passwords and lock all user accounts + cleanup-tmp: - Remove all files under /tmp and /var/tmp - + Remove all files under /tmp and /var/tmp + cleanup-userdata: - Delete sensitive userdata - + Delete sensitive userdata + fix-acpid: - Replace acpid powerdown action scripts to immediately shutdown the - system without checking if a GUI is running. - + 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 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. - + 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. - + 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 all files under /var/mail and /var/spool/mail + remove-user-accounts: - Remove all user accounts with id greater than 1000 - - - cleaning up... + Remove all user accounts with id greater than 1000 + + + cleaning up ... If you want the image to have all normal user accounts and all mail files removed, you should use *--enable-sysprep* option like this: @@ -173,15 +182,15 @@ Wizard mode When *snf-mkimage* runs in *wizard* mode, the user is just asked to provide the following basic information: + * Cloud: The cloud account to use to upload and register the resulting image * Name: A short name for the image (ex. "Slackware") * Description: An one-line description for the image (ex. "Slackware Linux 14.0 with KDE") * Registration Type: Private or Public - * Account: The authentication token for an *~okeanos* account -After confirming, the image will be extracted, uploaded to *pithos+* and -registered with *~okeanos*. The user will also be given the choice to keep a -local copy of it. +After confirming, the image will be extracted, uploaded to the storage service +and registered with the compute service of the selected cloud. 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. @@ -202,11 +211,10 @@ In the *Customize* sub-menu the user can control: In the *Register* sub-menu the user can provide: - * The credentials (authentication token) to use when authenticating - to *~okeanos* - * A *pithos+* filename for the uploaded *diskdump* image - * A name for the image to use when registering it with *~okeanos*, as well as - the registration type (*private* or *public*) + * Which cloud account to use + * A filename for the uploaded *diskdump* image + * A name for the image to use when registering it with the storage service of + the cloud, as well as the registration type (*private* or *public*) 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 @@ -244,13 +252,13 @@ Create a 2G sparse file to host the new system: .. code-block:: console - $ truncate -s 2G ubuntu_hd.raw + $ truncate -s 2G ubuntu.raw 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 \ + $ sudo kvm -boot d -drive file=ubuntu.raw,format=raw,cache=none,if=virtio \ -m 1G -cdrom ubuntu-12.04.2-server-amd64.iso .. warning:: @@ -261,7 +269,7 @@ And install the Ubuntu system on this file: You will be able to boot your installed OS and make any changes you want (e.g. install openssh-server) using the following command:: - $ sudo kvm -m 1G -boot c -drive file=ubuntu_hd.raw,format=raw,cache=none,if=virtio + $ sudo kvm -m 1G -boot c -drive file=ubuntu.raw,format=raw,cache=none,if=virtio After you're done, you may use *snf-mkimage* as root to create and upload the image: @@ -269,20 +277,20 @@ image: .. code-block:: console $ sudo -s - $ snf-mkimage ubuntu_hd.raw + $ snf-mkimage ubuntu.raw In the first screen you will be asked to choose if you want to run the program in *Wizard* or *Expert* mode. Choose *Wizard*. .. image:: /snapshots/wizard.png -Then you will be asked to provide a name, a description, a registration type -(*private* or *public*) and the authentication token corresponding to your -*~okeanos* account. Finally, you'll be asked to confirm the provided data. +Then you will be asked to select a cloud and provide a name, a description and +a registration type (*private* or *public*). Finally, you'll be asked to +confirm the provided data. .. image:: /snapshots/confirm.png -Choosing *YES* will create and upload the image to your *~okeanos* account. +Choosing *YES* will create and upload the image to your cloud account. Limitations =========== @@ -304,13 +312,13 @@ contain primary or logical partitions. 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 won't be able to boot. +Most synnefo deployments 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 won't be able to boot. Many popular Linux distributions, like Ubuntu and Debian, will automatically create a generic initial ramdisk file that contains many different modules,