X-Git-Url: https://code.grnet.gr/git/snf-image-creator/blobdiff_plain/6ca928ac8e5d26fe49b22ed3b7406d240193b9ad..c8025360fc1500322d6e3c6eed06c5752bf2d264:/docs/usage.rst

diff --git a/docs/usage.rst b/docs/usage.rst
index 32e09dd..dbeec58 100644
--- a/docs/usage.rst
+++ b/docs/usage.rst
@@ -2,8 +2,139 @@ Usage
 =====
 
 snf-image-creator comes in 2 variants:
- * snf-mkimage: A user-friendly dialog-based program
  * snf-image-creator: A non-interactive command line program
+ * snf-mkimage: A user-friendly dialog-based program
+
+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          silent mode, only output errors
+  -u FILENAME, --upload=FILENAME
+                        upload the image to pithos with name FILENAME
+  -r IMAGENAME, --register=IMAGENAME
+                        register the image with ~okeanos as IMAGENAME
+  -a ACCOUNT, --account=ACCOUNT
+                        Use this ACCOUNT when uploading/registering images
+                        [Default: None]
+  -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 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 system preparation
+  --no-shrink           don't shrink any partition
+
+
+Most input options are self-describing. If you want to save a local copy for
+the image, you need to specify *-o* option. In order to upload the image to
+pithos, you need to specify valid credentials with *-a* and *-t* options and a
+filename using *-u* option. To also register the image with ~okeanos, specify a
+name using the *-r* option.
+
+By default snf-image-creator will run a number of system preparation tasks on
+the snapshot of the media and will shrink the last partition found, before
+extracting the image. Both can be disabled by specifying *--no-sysprep* and
+*--no-shrink* respectively.
+
+If *--print-sysprep* is defined, then snf-image-creator will not create an
+image at all. It will only run the OS detection part and will output the system
+preparation tasks that would and would not run on the image. This behavior is,
+convenient because it allows you to see the available system preparation tasks
+that you can enable or disable with *-{enable,disable}-sysprep* options when
+you create a new image.
+
+Running *snf-image-creator* with *--print-sysprep* on a raw file that hosts a
+debian system, I get the following output:
+
+.. 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 image... 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 I want your images to also have all normal user accounts and all mail files
+removed, you can create it specifying the *--enable-sysprep* option like this:
+
+.. code-block:: console
+
+   $ snf-image-creator --enable-sysprep cleanup-mail,remove-user-accounts ...
+
+Dialog-based version
+--------------------
+
 
 Creating a new image
 --------------------
@@ -49,3 +180,4 @@ confirm the provided data.
 .. image:: /snapshots/06_confirm.png
 
 Choosing *YES* will create the image and upload it to your ~okeanos account.
+