From: Nikos Skalkotos Date: Wed, 18 Sep 2013 13:43:11 +0000 (+0300) Subject: Add documentation for progressr monitor interface X-Git-Tag: 0.10~1^2~2^2~1 X-Git-Url: https://code.grnet.gr/git/snf-image/commitdiff_plain/7f904d2980d968cfdb8bde9aa0c6e59af411ade8 Add documentation for progressr monitor interface Also fix various typos --- diff --git a/docs/advanced.rst b/docs/advanced.rst index 7cde1ee..1ee6220 100644 --- a/docs/advanced.rst +++ b/docs/advanced.rst @@ -1,2 +1,96 @@ Advanced Topics =============== + +Progress Monitoring Interface +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +*snf-image* has an embedded mechanism for transmitting progress messages during +an image deployment. A user may specify an external executable by overwriting +the *PROGRESS_MONITOR* variable under ``/etc/default/snf-image`` and +*snf-image* will redirect the progress messages to the standard input of this +program. In this section we will describe the format and the fields of the +progress messages. + +The progress messages are json strings with standardized fields. All messages +have a **type** field whose value is a string and a **timestamp** field whose +value is a floating point number referring to a time encoded as the number of +seconds elapsed since the epoch. The rest of the field depend on the specific +type. + +image-info +++++++++++ + +This message type is used to display random progress information. It has an +extra *messages* field whose value is a list of strings. A valid ``image-info`` +message looks like this: + +``{"messages": ["Starting image copy..."], "type": "image-info", "timestamp": 1378914866.209169}`` + +image-error ++++++++++++ + +This message type is used to display a fatal error that occurred during image +deployment. It may either have an extra *messages* field to display the error +message or an *stderr* field to display the last lines of the standard error +output stream of the OS creation script. Valid ``image-error`` messages look +like this: + +``{"messages": ["Image customization failed."], "type": "image-error", "timestamp": 1379507045.924449}`` + +image-copy-progress ++++++++++++++++++++ + +One of the tasks *snf-image* has to accomplish is to copy the image file into +the VM's hard disk before configuring it. Messages of type +``image-copy-progress`` are used to display the progress of this task. The extra +fields this message type has is *position*, *total* and *progress*. The +*position* field is used to display the number of bytes written to the hard +disk. The *total* field indicates the overall size (in bytes) of the image, and +finally the *progress* field indicates the percent of the accomplished work. +Messages of this type look like this: + +``{"position": 335547996, "total": 474398720, "type": "image-copy-progress", "timestamp": 1378914869.312985, "progress": 70.73}`` + +image-helper +++++++++++++ + +This is a family of messages that are created when *snf-image-helper* runs. +Each message of this type has a *subtype* field. + +task-start +---------- + +Messages with *subtype* ``task-start`` indicate that *snf-image-helper* +started running a :ref:`configuration task ` on the +image. Messages of this type have an extra *task* field whose value is the +name of the task *snf-image-helper* started, and look like this: + +``{"subtype": "task-start", "task": "FixPartitionTable", "type": "image-helper", "timestamp": 1379507040.456931}`` + +task-stop +--------- + +Messages with *subtype* ``task-stop`` are produced every time a configuration +task successfully exits. As with the ``task-start`` messages, the *task* field +is present: + +``{"subtype": "task-end", "task": "FixPartitionTable", "type": "image-helper", "timestamp": 1379507041.357184}`` + +warning +------- + +This messages are produced to display a warning. The actual warning message +itself is present in the *messages* field: + +``{"subtype": "warning", "type": "image-helper", "messages": [" No swap partition defined"], "timestamp": 1379075807.71704}`` + +error +----- + +The last ``image-helper`` message that may occur is the ``error`` message. As +with the ``image-error`` messages, either a *messages* field that hosts the +actual error message or a *stderr* field that hosts the last 10 lines of the +standard error output stream of *snf-image-helper*. Valid *error* messages look +like this: + +``{"subtype": "error", "type": "image-helper", "messages": ["The image contains a(n) msdos partition table. For FreeBSD images only GUID Partition Tables are supported."], "timestamp": 1379507910.799365}`` diff --git a/docs/architecture.rst b/docs/architecture.rst index 34d261e..391fdd0 100644 --- a/docs/architecture.rst +++ b/docs/architecture.rst @@ -59,6 +59,8 @@ The architecture is presented below: .. image:: /images/arch.png +.. _image-configuration-tasks: + Image Configuration Tasks ^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/docs/usage.rst b/docs/usage.rst index b2c3687..876a1e6 100644 --- a/docs/usage.rst +++ b/docs/usage.rst @@ -34,21 +34,21 @@ extdump and ntfsdump image formats ++++++++++++++++++++++++++++++++++ Those two formats are dumps (raw copies using dd) of partitions hosting Linux -systems on ext{2,3,4} and Windows systems on ntfs filesystems respectively. +systems on ext{2,3,4} and Windows systems on ntfs file systems respectively. Partitions hosting a Windows or Linux system that are suitable for dumping should have the following properties: - * Be the first partition in the filesystem + * Be the first partition in the file system * The OS they host should not depend on any other partitions * Start at sector 2048 - * Have a bootloader installed in the boot sector of the partition (not MBR) + * Have a boot loader installed in the boot sector of the partition (not MBR) * Have the root device in */etc/fstab* specified in a persistent way, using UUID or LABEL (for extdump only) Known Issues ------------ - * For linux systems, having grub installed in the partition is fragile and + * For Linux systems, having grub installed in the partition is fragile and things can go wrong when resizing the partitions, especially when shrinking. * More complicated partition schemes are not supported. @@ -62,7 +62,7 @@ This design decision has the following benefits: * Swap partitions are supported * The system may use multiple partitions: - * dedicated partitions for /boot, /home etc in linux + * dedicated partitions for /boot, /home etc in Linux * system and boot partition in Windows * There are no restrictions on starting sectors of partitions @@ -82,7 +82,7 @@ Image IDs & Storage back-ends *snf-image* can use images that are stored in a variety of different back-ends. The back-end to be used is determined by the value passed by the *img_id* OS -parameter. The following backends are supported: +parameter. The following back-ends are supported: * **Local back-end**: The local back-end is used to retrieve images that are stored in the ganeti @@ -205,7 +205,7 @@ Personality OS Parameter This parameter is an extension of the Server Personality notation proposed by the OpenStack Compute API v1.1 and defines a list of files to be injected into -the image filesystem. +the image file system. Format ++++++ @@ -248,6 +248,9 @@ their permissions are ``-rw-r--r--`` [#]_ .. [#] The first mode is in octal representation and the second in decimal. + +.. _sample-images: + Sample Images ^^^^^^^^^^^^^ @@ -304,3 +307,24 @@ that have been tested with snf-image and provided here for testing purposes: [`diskdump `_] [`md5sum `_] [`metadata `_] + +Sample Usage +^^^^^^^^^^^^ + +Download an Image ++++++++++++++++++ + +Download a :ref:`Sample Image ` and store it under IMAGE_DIR. +Make sure you also have its corresponding metadata file. + +Spawn a diskdump image +++++++++++++++++++++++ + +If you want to deploy an image of type diskdump, you need to provide the +corresponding *img_properties* as described in the +:ref:`Image Format` section. If using a diskdump found in the +:ref:`sample-images` list, use the *img_properties* described in the image's +metadata file. For example: + +``gnt-instance add -o snf-image+default --os-parameters img_passwd=SamplePassw0rd,img_format=diskdump,img_id=debian_base-6.0-7-x86_64,img_properties='{"OSFAMILY":"linux"\,"ROOT_PARTITION":"1"}' -t plain --disk=0:size=10G --no-name-check --no-ip-check --no-nics test1`` +