From: Nikos Skalkotos Date: Mon, 16 Sep 2013 10:22:48 +0000 (+0300) Subject: Update the documentation (part 1) X-Git-Tag: 0.10~1^2~2^2~5 X-Git-Url: https://code.grnet.gr/git/snf-image/commitdiff_plain/0416bac5632be698186934f47be44a9569f14014?ds=sidebyside 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 index 0000000..e69de29 diff --git a/docs/architecture.rst b/docs/architecture.rst new file mode 100644 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 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 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 --- 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 `_ OS definition, +primary used by `Synnefo `_. 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 `_ and +`Xen `_ 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 `_. + + + Contents: +^^^^^^^^^ .. toctree:: :maxdepth: 2 + architecture + installation + usage + Indices and tables ================== diff --git a/docs/installation.rst b/docs/installation.rst new file mode 100644 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 index 0000000..d4b9a15 --- /dev/null +++ b/docs/usage.rst @@ -0,0 +1,2 @@ +Usage +=====