+ * snf-mkimage: A user-friendly dialog-based program
+
+Both expect the input media as first argument. The input media may be a local
+file, a block device or *"/"* if you want to create an image out of the running
+system (see `host bundling operation`_).
+
+Non-interactive version
+=======================
+
+snf-image-creator receives the following options:
+
+.. code-block:: console
+
+ $ snf-image-creator --help
+ Usage: snf-image-creator [options] <input_media>
+
+ Options:
+ --version show program's version number and exit
+ -h, --help show this help message and exit
+ -o FILE, --outfile=FILE
+ dump image to FILE
+ -f, --force overwrite output files if they exist
+ -s, --silent output only errors
+ -u FILENAME, --upload=FILENAME
+ upload the image to pithos with name FILENAME
+ -r IMAGENAME, --register=IMAGENAME
+ register the image with ~okeanos as IMAGENAME
+ -m KEY=VALUE, --metadata=KEY=VALUE
+ add custom KEY=VALUE metadata to the image
+ -t TOKEN, --token=TOKEN
+ use this token when uploading/registering images
+ [Default: None]
+ --print-sysprep print the available enabled and disabled system
+ preparation operations for this input media
+ --enable-sysprep=SYSPREP
+ run SYSPREP operation on the input media
+ --disable-sysprep=SYSPREP
+ prevent SYSPREP operation from running on the input
+ media
+ --no-sysprep don't perform any system preparation operation
+ --no-shrink don't shrink the image
+ --public register image with cyclades as public
+ --tmpdir=DIR create large temporary image files under DIR
+
+Most input options are self-describing. If you want to save a local copy of
+the image you create, provide a filename using the *-o* option. To upload the
+image to *pithos+*, provide a valid authentication token using *-t* and a
+filename using *-u*. If you also want to register the image with *~okeanos*, in
+addition to *-u* provide a registration name using *-r*. All images are
+registered as *private*. Only the user that registers the image can create
+VM's out of it. If you want the image to be visible by other user too, use the
+*--public* option.
+
+By default, before extracting the image, snf-image-creator will perform a
+number of system preparation operations on the snapshot of the media and will
+shrink the last partition found. Both actions can be disabled by specifying
+*--no-sysprep* and *--no-shrink* respectively.
+
+If *--print-sysprep* is defined, the program will exit after printing a
+list of enabled and disabled system preparation operation applicable to this
+input media. The user can enable or disable specific *syspreps*, using
+*-{enable,disable}-sysprep* options. The user may specify those options
+multiple times.
+
+Running *snf-image-creator* with *--print-sysprep* on a raw file that hosts a
+debian system, we print the following output:
+
+.. _sysprep:
+
+.. code-block:: console
+
+ $ snf-image-creator --print-sysprep debian_desktop.img
+
+ snf-image-creator 0.1
+ =====================
+ Examining source media `debian_desktop.img'... looks like an image file
+ Snapshotting media source... done
+ Enabling recovery proc
+ 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 you want the image to have all normal user accounts and all mail files
+removed, you should use *--enable-sysprep* option like this:
+
+.. code-block:: console
+
+ $ snf-image-creator --enable-sysprep cleanup-mail --enable-sysprep remove-user-accounts ...
+
+Dialog-based version
+====================
+
+*snf-mkimage* receives the following options:
+
+.. code-block:: console
+
+ $ snf-mkimage --help
+ Usage: snf-mkimage [options] [<input_media>]
+
+ Options:
+ --version show program's version number and exit
+ -h, --help show this help message and exit
+ -l FILE, --logfile=FILE
+ log all messages to FILE
+ --tmpdir=DIR create large temporary image files under DIR
+
+If the input media is not specified in the command line, in the first dialog
+box the user will be asked to specify it:
+
+.. image:: /snapshots/select_media.png
+
+The user can select a file (regular or block device) or use the *Bundle Host*
+button to create an image out of the running system (see
+`Host bundling operation`_).
+
+After the input media is examined and the program is initialized, the user will
+be given the choice to run *snf-mkimage* in *wizard* or *expert* mode.
+
+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 the image (ex. "Slackware")
+ * Description: An one-line description for the image
+ (ex. "Slackware Linux 14.0 with KDE")
+ * Registration Type: Private or Public
+ * Account: The authentication token for an *~okeanos* account
+
+After confirming, the image will be extracted, uploaded to *pithos+* and
+registered with *~okeanos*. The user will also be given the choice to keep a
+local copy of it.
+
+For most users the functionality this mode provides should be sufficient.
+
+Expert mode
+-----------
+
+Expert mode allows the user to have better control on the image creation
+process. The main menu can be seen in the picture below:
+
+.. image:: /snapshots/main_menu.png
+
+In the *Customize* sub-menu the user can control:
+
+ * The system preparation operations that will be applied on the media
+ * Whether the image will be shrunk or not
+ * The properties associated with the image
+ * The configuration tasks that will run during image deployment
+
+In the *Register* sub-menu the user can provide:
+
+ * The credentials (authentication token) to use when authenticating
+ to *~okeanos*
+ * A *pithos+* filename for the uploaded *diskdump* image
+ * A name for the image to use when registering it with *~okeanos*, as well as
+ the registration type (*private* or *public*)
+
+By choosing the *Extract* menu entry, the user can dump the image to the local
+file system. Finally, if the user selects *Reset*, the system will ignore
+all changes made so far and will start the image creation process again.
+
+Host bundling operation
+=======================
+
+As a new feature in *v0.2*, snf-image-creator can create images out of the host
+system that runs the program. This is done either by specifying / as input
+media or by using the *Bundle Host* button in the media selection dialog of
+snf-mkimage. During this operation, the files of the disk are copied into a
+temporary image file, which means that the file system that will host the
+temporary image needs to have a lot of free space (see `large temporary files`_
+for more information).