Commit 7f904d29 authored by Nikos Skalkotos's avatar Nikos Skalkotos
Browse files

Add documentation for progressr monitor interface

Also fix various typos
parent 48b98a80
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 <image-configuration-tasks>` 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}``
......@@ -59,6 +59,8 @@ The architecture is presented below:
.. image:: /images/arch.png
.. _image-configuration-tasks:
Image Configuration Tasks
^^^^^^^^^^^^^^^^^^^^^^^^^
......
......@@ -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 <http://cdn.synnefo.org/freebsd-9.1-x86_64.diskdump>`_]
[`md5sum <http://cdn.synnefo.org/freebsd-9.1-x86_64.diskdump.md5sum>`_]
[`metadata <http://cdn.synnefo.org/freebsd-9.1-x86_64.diskdump.meta>`_]
Sample Usage
^^^^^^^^^^^^
Download an Image
+++++++++++++++++
Download a :ref:`Sample Image <sample-images>` 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<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``
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment