X-Git-Url: https://code.grnet.gr/git/snf-image-creator/blobdiff_plain/8c7d7b905ad862d03a9899c2eb347c6bf9a77193..fab154f00c00474d8baf495cf432dc6054f1bc7e:/docs/usage.rst diff --git a/docs/usage.rst b/docs/usage.rst index ce8c99d..c43fb29 100644 --- a/docs/usage.rst +++ b/docs/usage.rst @@ -31,9 +31,6 @@ snf-image-creator receives the following options: 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 @@ -48,13 +45,17 @@ snf-image-creator receives the following options: 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 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 valid credentials using *-a* and *-t* and a +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*. +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. By default, before extracting the image, snf-image-creator will perform a number of system preparation operations on the snapshot of the media and will @@ -175,8 +176,8 @@ 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 given above + * 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 @@ -201,9 +202,11 @@ In the *Customize* sub-menu the user can control: In the *Register* sub-menu the user can provide: - * The credentials to login to *~okeanos* + * The credentials (authentication token) to use when authenticating + to *~okeanos* * A *pithos+* filename for the uploaded *diskdump* image - * A name for the image to be registered to *~okeanos* with + * A name for the image to use when registering it with *~okeanos*, 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 @@ -217,7 +220,7 @@ 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`_ +temporary image needs to have a lot of free space (see `large temporary files`_ for more information). Creating a new image @@ -228,13 +231,13 @@ disk from the Internet: .. code-block:: console - $ wget http://ubuntureleases.tsl.gr/12.04.1/ubuntu-12.04.1-server-amd64.iso + $ wget http://ubuntureleases.tsl.gr/12.04.2/ubuntu-12.04.2-server-amd64.iso Verify that it has been downloaded correctly: .. code-block:: console - $ echo 'a8c667e871f48f3a662f3fbf1c3ddb17 ubuntu-12.04.1-server-amd64.iso' > check.md5 + $ echo 'a8c667e871f48f3a662f3fbf1c3ddb17 ubuntu-12.04.2-server-amd64.iso' > check.md5 $ md5sum -c check.md5 Create a 2G sparse file to host the new system: @@ -248,7 +251,7 @@ 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 1G -cdrom ubuntu-12.04.1-server-amd64.iso + -m 1G -cdrom ubuntu-12.04.2-server-amd64.iso .. warning:: @@ -271,18 +274,32 @@ image: 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/01_wizard.png +.. image:: /snapshots/wizard.png -Then you will be asked to provide a name, a description, an *~okeanos* account -and the token corresponding to this account. Finally, you'll be asked to -confirm the provided data. +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. -.. image:: /snapshots/06_confirm.png +.. image:: /snapshots/confirm.png Choosing *YES* will create and upload the image to your *~okeanos* account. -Some caveats on image creation -============================== +Limitations +=========== + +Supported operating systems +--------------------------- + +*snf-image-creator* can only fully function on input media hosting *Linux* +systems. The program will detect the needed metadata and you may use it to +upload and register other *Unix* or *Windows* images, but you cannot use it to +shrink them or perform system preparation operations. + +Logical Volumes +--------------- + +The program cannot work on LVM partitions [#f1]_. The input media may only +contain primary or logical partitions. Para-virtualized drivers ------------------------ @@ -298,13 +315,16 @@ 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, including the VirtIO drivers. Others that target more experienced users, like -Slackware, won't do that [#f1]_. *snf-image-creator* cannot resolve this kind +Slackware, won't do that [#f2]_. *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 (see the kvm command in the `Creating a new image`_ section). +Some caveats on image creation +============================== + Image partition schemes and shrinking ------------------------------------- @@ -322,8 +342,8 @@ 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 ------------------ +Large temporary files +--------------------- *snf-image-creator* may create large temporary files when running: @@ -343,4 +363,5 @@ supported by both *snf-image-creator* and *snf-mkimage*. .. rubric:: Footnotes -.. [#f1] http://mirrors.slackware.com/slackware/slackware-14.0/README.initrd +.. [#f1] http://sourceware.org/lvm2/ +.. [#f2] http://mirrors.slackware.com/slackware/slackware-14.0/README.initrd