diff --git a/.gitignore b/.gitignore
index a2049825c33d5fc7bb842a120e027576140870c8..79bebe7f0dcd9e46467eb60a393e984f01e48743 100644
--- a/.gitignore
+++ b/.gitignore
@@ -2,3 +2,4 @@
build/
dist/
*.egg-info
+docs/_build
diff --git a/docs/install.rst b/docs/install.rst
index 5428e7e87bd4874ff92da8e0e1c31e49254c9df6..f9592ccc7eab027a418b45a1b97a16688dcf3355 100644
--- a/docs/install.rst
+++ b/docs/install.rst
@@ -2,7 +2,7 @@ Installation
^^^^^^^^^^^^
This guide describes how to install snf-image-creator on an Ubuntu 12.04 LTS
-system. It it highly recommended to have virtualization capable hardware.
+system. It is highly recommended to have virtualization capable hardware.
snf-image-creator will work on processors that do not support virtualization
but it will be extremely slow.
@@ -21,21 +21,102 @@ snf-image-creator depends on the following programs:
* progress [http://pypi.python.org/pypi/progress]
* Python interface to sendfile [http://pypi.python.org/pypi/pysendfile]
-The first four programs (python2, setuptools, libguestfs and Python Dialog)
-need to be installed manually by the user. In an Ubuntu 12.04 LTS system this
-can be archived by installing packages provided by the distribution, using the
-following command:
+The above dependencies are resolved differently, depending on the installation
+method you choose.
+
+There are two installation methods. The first uses official packages whereas
+the second installs snf-image-creator and its dependencies from source. Both
+methods are presented below.
+
+Install snf-image-creator using official packages
+=================================================
+
+This method of installing snf-image-creator has all the advantages of Ubuntu's
+APT installation:
+
+* Automatic resolution of dependencies
+* Simple installation of consequent updates
+
+In order to proceed with the installation, you must first add GRNET's dev repo
+to your sources. You can use the following commands:
+
+.. code-block:: console
+
+ $ cd /etc/apt/sources.list.d
+ $ echo "deb http://apt.dev.grnet.gr precise main" | \
+ sudo tee -a apt.dev.grnet.gr.list
+ $ echo "deb-src http://apt.dev.grnet.gr precise main" | \
+ sudo tee -a apt.dev.grnet.gr.list
+
+You will also need to import the repo's GPG key. You can use the ``curl`` tool
+for this.
+
+.. code-block:: console
+
+ $ sudo apt-get install curl
+
+Use the following command to import the GPG key:
+
+.. code-block:: console
+
+ $ sudo curl https://dev.grnet.gr/files/apt-grnetdev.pub | sudo apt-key add -
+
+You can verify that the repo has been added successfully if snf-image-creator
+exists as a package. First do an update of your sources:
+
+.. code-block:: console
+
+ $ sudo apt-get update
+
+then check if snf-image-creator exists with the following command:
+
+.. code-block:: console
+
+ $ apt-cache showpkg snf-image-creator
+
+If GRNET's dev repo has been added successfully, you can install
+snf-image-creator, along with its dependencies, with the following command:
+
+.. code-block:: console
+
+ $ sudo apt-get install snf-image-creator
+
+The installation might take a while. Please note that at some point during the
+installation you will be prompted to create/update a "supermin appliance". This
+is a setting regarding libguestfs and you can safely choose "Yes".
+
+Install snf-image-creator from source
+=====================================
+
+This method provides you with the cutting edge of snf-image-creator, which
+gives you access to all the latest features. Keep in mind, however,
+that you may experience instability issues.
+
+The first four dependencies (python2, setuptools, Python-Dialog, and
+libguestfs) need to be installed manually by the user. In an Ubuntu 12.04 LTS
+system this can be achieved by installing packages provided by the
+distribution, using the following command:
.. code-block:: console
$ apt-get install python-setuptools python-guestfs python-dialog
The rest of the dependencies will be automatically resolved by setuptools.
+Note that at some point during the installation, you will be prompted to
+create/update a "supermin appliance". This is a setting regarding libguestfs
+and you can safely choose "Yes".
+
+In order to download the source files, git needs to be installed. You can do
+so with the following command:
+
+.. code-block:: console
+
+ $ apt-get install git
Python Virtual Environment
-==========================
+--------------------------
-Since snf-image-creator and the rest of it's dependencies won't be installed
+Since snf-image-creator and the rest of its dependencies won't be installed
using packages, it's better to work in an isolated python virtual environment
(virtualenv). Installing the Virtual Python Environment builder in Ubuntu can
be accomplished using the following command:
@@ -62,39 +143,59 @@ You can later deactivate it using the following command:
$ deactivate
+snf-common Installation
+-----------------------
+
+Install snf-common from source, by cloning it's repository:
+
+.. code-block:: console
+
+ $ cd ~
+ $ git clone https://code.grnet.gr/git/synnefo
+ $ cd synnefo/snf-common
+ $ python setup.py build
+
+Then, make sure you are within the activated virtual environment before you
+execute:
+
+.. code-block:: console
+
+ $ python setup.py install
kamaki Installation
-===================
+-------------------
Install kamaki from source, by cloning it's repository:
.. code-block:: console
+ $ cd ~
$ git clone https://code.grnet.gr/git/kamaki
$ cd kamaki
- $ ./setup build
+ $ ./setup.py build
-Then, make sure you are within the activated virtual environment before you
+As above, make sure you are within the activated virtual environment before you
execute:
.. code-block:: console
- $ ./setup install
+ $ ./setup.py install
snf-image-creator Installation
-==============================
+------------------------------
Install snf-image-creator the same way:
.. code-block:: console
+ $ cd ~
$ git clone https://code.grnet.gr/git/snf-image-creator
+ $ git checkout stable-0.1
$ cd snf-image-creator
- $ ./setup build
+ $ ./setup.py build
And from within the virtual environment execute:
.. code-block:: console
- $ ./setup install
-
+ $ ./setup.py install
diff --git a/docs/overview.rst b/docs/overview.rst
index da72b8694f2584db4460afaefcf338703aa25c09..e375086077989c2a33396083439f84304ffc13d8 100644
--- a/docs/overview.rst
+++ b/docs/overview.rst
@@ -1,7 +1,7 @@
Overview
^^^^^^^^
-snf-image-creator is a simple command-line tools for creating OS images. The
+snf-image-creator is a simple command-line tool for creating OS images. The
original media from which the image is created, can be a block device or a
regular file that represents a hard disk. Given a media file, snf-image-creator
will create a snapshot for it and will run a number of system preparation
diff --git a/docs/snapshots/custom-vm.png b/docs/snapshots/custom-vm.png
new file mode 100644
index 0000000000000000000000000000000000000000..d55f616ae1a4fd1ffcde2f40e0d96b77fcc774e3
Binary files /dev/null and b/docs/snapshots/custom-vm.png differ
diff --git a/docs/snapshots/image-creator.png b/docs/snapshots/image-creator.png
new file mode 100644
index 0000000000000000000000000000000000000000..63cbe9bc9b2312d96d68ec961c8dc3380da17f3a
Binary files /dev/null and b/docs/snapshots/image-creator.png differ
diff --git a/docs/snapshots/mkimage-fin.png b/docs/snapshots/mkimage-fin.png
new file mode 100644
index 0000000000000000000000000000000000000000..10bca5b5e6ff56609e412d704e668966a283b916
Binary files /dev/null and b/docs/snapshots/mkimage-fin.png differ
diff --git a/docs/snapshots/mkimage-results.png b/docs/snapshots/mkimage-results.png
new file mode 100644
index 0000000000000000000000000000000000000000..637523e89dba714552ec9d50317d168a95b2423d
Binary files /dev/null and b/docs/snapshots/mkimage-results.png differ
diff --git a/docs/snapshots/mkimage-wizard.png b/docs/snapshots/mkimage-wizard.png
new file mode 100644
index 0000000000000000000000000000000000000000..ec22eeda075407824731a2fbe69e0e0cdcafe812
Binary files /dev/null and b/docs/snapshots/mkimage-wizard.png differ
diff --git a/docs/snapshots/mkimage1.png b/docs/snapshots/mkimage1.png
new file mode 100644
index 0000000000000000000000000000000000000000..083eef1d317fe2be75d757db142ae81abe283cf0
Binary files /dev/null and b/docs/snapshots/mkimage1.png differ
diff --git a/docs/snapshots/mkimage2.png b/docs/snapshots/mkimage2.png
new file mode 100644
index 0000000000000000000000000000000000000000..5fea5fd51da0d9487fb28f72a61b6a265761e6b0
Binary files /dev/null and b/docs/snapshots/mkimage2.png differ
diff --git a/docs/snapshots/mkimage3.png b/docs/snapshots/mkimage3.png
new file mode 100644
index 0000000000000000000000000000000000000000..b87f06c0b60be3e61822b8c817c2a7618c38ebb3
Binary files /dev/null and b/docs/snapshots/mkimage3.png differ
diff --git a/docs/snapshots/mkimage4.png b/docs/snapshots/mkimage4.png
new file mode 100644
index 0000000000000000000000000000000000000000..a9b34a001d096def4cf3bde4cf387abaa88f08d8
Binary files /dev/null and b/docs/snapshots/mkimage4.png differ
diff --git a/docs/snapshots/qemu-live.png b/docs/snapshots/qemu-live.png
new file mode 100644
index 0000000000000000000000000000000000000000..57a6c92bcf0ee97e9619e8b33c6b41e63056da21
Binary files /dev/null and b/docs/snapshots/qemu-live.png differ
diff --git a/docs/snapshots/qemu-partition.png b/docs/snapshots/qemu-partition.png
new file mode 100644
index 0000000000000000000000000000000000000000..1080570eef8592b5aeeb5b0c8ccdcb3e84b46afd
Binary files /dev/null and b/docs/snapshots/qemu-partition.png differ
diff --git a/docs/usage.rst b/docs/usage.rst
index 70cafb6426fc8c11a618a3c54c0f1d33f76d3d83..219911620b3760e8758244f8babf2158a1b53e3d 100644
--- a/docs/usage.rst
+++ b/docs/usage.rst
@@ -66,6 +66,8 @@ options multiple times to enable or disable multiple *syspreps*.
Running *snf-image-creator* with *--print-sysprep* on a raw file that hosts a
debian system, we get the following output:
+.. _sysprep:
+
.. code-block:: console
$ snf-image-creator --print-sysprep debian_desktop.img
@@ -78,50 +80,50 @@ debian system, we get the following output:
Launching helper VM... done
Inspecting Operating System... found a(n) debian system
Mounting the media read-only... done
-
+
Enabled system preparation operations:
cleanup-cache:
Remove all regular files under /var/cache
-
+
cleanup-log:
Empty all files under /var/log
-
+
cleanup-passwords:
Remove all passwords and lock all user accounts
-
+
cleanup-tmp:
Remove all files under /tmp and /var/tmp
-
+
cleanup-userdata:
Delete sensitive userdata
-
+
fix-acpid:
Replace acpid powerdown action scripts to immediately shutdown the
system without checking if a GUI is running.
-
+
remove-persistent-net-rules:
Remove udev rules that will keep network interface names persistent
after hardware changes and reboots. Those rules will be created again
the next time the image runs.
-
+
remove-swap-entry:
Remove swap entry from /etc/fstab. If swap is the last partition
then the partition will be removed when shrinking is performed. If the
swap partition is not the last partition in the disk or if you are not
going to shrink the image you should probably disable this.
-
+
use-persistent-block-device-names:
Scan fstab & grub configuration files and replace all non-persistent
device references with UUIDs.
-
+
Disabled system preparation operations:
cleanup-mail:
Remove all files under /var/mail and /var/spool/mail
-
+
remove-user-accounts:
Remove all user accounts with id greater than 1000
-
-
+
+
cleaning up...
If we want the image to have all normal user accounts and all mail files
@@ -157,7 +159,7 @@ Wizard mode
When *snf-mkimage* runs in *wizard* mode, the user is just asked to provide the
following basic information:
- * Name: A short name for image (ex. "Slackware")
+ * 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 defined previously
@@ -202,6 +204,13 @@ disk from the Internet:
$ wget http://ubuntureleases.tsl.gr/12.04.1/ubuntu-12.04.1-server-amd64.iso
+Verify that it has been downloaded correctly:
+
+.. code-block:: console
+
+ $ echo 'a8c667e871f48f3a662f3fbf1c3ddb17 ubuntu-12.04.1-server-amd64.iso' > check.md5
+ $ md5sum -c check.md5
+
Create a 2G sparce file to host the new system:
.. code-block:: console
@@ -213,11 +222,23 @@ 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 \
- -cdrom ubuntu-12.04.1-server-amd64.iso
+ -m 1000 -cdrom ubuntu-12.04.1-server-amd64.iso
+
+.. note::
+
+ During the installation, you will be asked about the partition scheme. Since
+ snf-image-creator does not support LVM partitions, you are advised to create
+ regular partitions.
+
+When the installation is complete, you can close the QEMU window. You
+will be able to boot your installed OS and make any changes you want to it
+(e.g. install openssh-server) using the following command::
+
+ $ sudo kvm -m 1000 -drive file=linuxmint.raw,format=raw,cache=none,if=virtio
-After the installation finishes, become root, activate the virtual environment
-you have installed snf-image-creator in, and use *snf-mkimage* to create and
-upload the image:
+After you're done, become root, activate the virtual environment you have
+installed snf-image-creator in, and use *snf-mkimage* to create and upload the
+image:
.. code-block:: console