Update the documentation (part 1)

Fill in the architecture section of the documentation

diff --git a/docs/_static b/docs/_static
new file mode 100644 (file)
index 0000000..e69de29

diff --git a/docs/architecture.rst b/docs/architecture.rst
new file mode 100644 (file)
index 0000000..e236d44
--- /dev/null
+++ b/docs/architecture.rst
@@ -0,0 +1,62 @@
+Architecture
+============
+
+snf-image is split in two components: The main program running on the Ganeti
+host, with full root privilege (*snf-image* previously *snf-image-host*), and a
+part running inside an unprivileged, helper VM (*snf-image-helper*).
+
+snf-image
+^^^^^^^^^
+
+This part implements the Ganeti OS interface. It extracts the Image onto the
+Ganeti-provided block device, using streaming block I/O (dd with oflag=direct),
+then passes control to snf-image-helper running inside a helper VM. The helper
+VM is created using KVM, runs as an unprivileged user, nobody by default.
+
+There is no restriction on the distribution running inside the helper VM, as
+long as it executes the snf-image-helper component automatically upon bootup.
+The snf-image-update-helper script is provided with snf-image to automate the
+creation of a helper VM image based on Debian Stable, using multistrap.
+
+The snf-image-helper component is spawned inside a specific hardware
+environment:
+
+ * The VM features a virtual floppy, containing an ext2 filesystem with all
+   parameters needed for image customization.
+ * The hard disk of the VM being deployed is accessible as the first virtio
+   hard disk.
+ * All kernel/console output is redirected to the first virtual serial console,
+   and eventually finds its way into the OS definition log files that Ganeti
+   maintains.
+ * The helper VM is expected to output "SUCCESS" to its second serial port if
+   image customization was successful inside the VM.
+ * In any other case, execution of the helper VM or snf-image-helper has
+   failed.
+ * The helper VM is expected to shutdown automatically once it is done. Its
+   execution is time-limited; if it has not terminated after a number of
+   seconds, configurable via /etc/default/snf-image, it is sent a SIGTERM
+   and/or a SIGKILL.
+
+KVM is currently a dependency for snf-image, meaning it is needed to spawn the
+helper VM. There is no restriction on the hypervisor used for the actual Ganeti
+instances. This is not a strict requirement; KVM could be replaced by qemu,
+doing full CPU virtualization without any kernel support for spawning the
+helper VM.
+
+snf-image-helper
+^^^^^^^^^^^^^^^^
+
+This part runs inside the helper VM and undertakes customization of the VM
+being deployed using a number of hooks, or tasks. The tasks run in an
+environment, specified by rules found in a virtual floppy, placed there by
+*snf-image*. *snf-image-helper* uses runparts to run tasks found under
+*/usr/lib/snf-image-helper/tasks* by default
+
+Graphical Representation
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+The architecture is presented below:
+
+.. image:: /images/arch.png
+
+

diff --git a/docs/images/arch.png b/docs/images/arch.png
new file mode 100644 (file)
index 0000000..58208a2
Binary files /dev/null and b/docs/images/arch.png differ

diff --git a/docs/images/logo.png b/docs/images/logo.png
new file mode 100644 (file)
index 0000000..5bf4d0d
Binary files /dev/null and b/docs/images/logo.png differ

diff --git a/docs/index.rst b/docs/index.rst
index 89e2197..89b26b3 100644 (file)
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -6,11 +6,45 @@
 Welcome to snf-image's documentation!
 =====================================
 
+.. image:: /images/logo.png
+
+snf-image is a `Ganeti <http://code.google.com/p/ganeti/>`_ OS definition,
+primary used by `Synnefo <http://www.synnefo.org/>`_. It is rewritten from
+scratch and allows Ganeti to launch instances from predefined or untrusted
+custom Images. The whole process of deploying an Image onto the block device,
+as provided by Ganeti, is done in complete isolation from the physical host,
+enhancing robustness and security.
+
+snf-image supports `KVM <http://www.linux-kvm.org/page/Main_Page>`_ and
+`Xen <http://www.xenproject.org/>`_ based ganeti clusters.
+
+There are also additional hooks that can be enabled at image deployment. They
+allow for:
+
+ * changing the password of root or arbitrary users
+ * injecting files at arbitrary locations inside the filesystem, e.g., SSH keys
+ * setting a custom hostname
+ * re-creating SSH host keys to ensure the image uses unique keys
+
+snf-image has been used successfully to deploy many major Linux distributions
+(Debian, Ubuntu/Kubuntu, CentOS, Fedora, OpenSUSE), Windows 2008 R2 & Windows
+Server 2012, as well as FreeBSD 9.1
+
+The snf-image Ganeti OS Definition is released under
+`GPLv2 <http://www.gnu.org/licenses/gpl-2.0.html>`_.
+
+
+
 Contents:
+^^^^^^^^^
 
 .. toctree::
    :maxdepth: 2
 
+   architecture
+   installation
+   usage
+
 Indices and tables
 ==================
 

diff --git a/docs/installation.rst b/docs/installation.rst
new file mode 100644 (file)
index 0000000..11e4437
--- /dev/null
+++ b/docs/installation.rst
@@ -0,0 +1,2 @@
+Installation
+============

diff --git a/docs/usage.rst b/docs/usage.rst
new file mode 100644 (file)
index 0000000..d4b9a15
--- /dev/null
+++ b/docs/usage.rst
@@ -0,0 +1,2 @@
+Usage
+=====