usage.rst

Usage

snf-image-creator comes in 2 variants:

• snf-mkimage: A non-interactive command line program
• snf-image-creator: 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-mkimage receives the following options:

# 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
  -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 the cloud with name FILENAME
  -r IMAGENAME, --register=IMAGENAME
                        register the image with a cloud as IMAGENAME
  -m KEY=VALUE, --metadata=KEY=VALUE
                        add custom KEY=VALUE metadata to the image
  -t TOKEN, --token=TOKEN
                        use this authentication token when
                        uploading/registering images
  -a URL, --authentication-url=URL
                        use this authentication URL when uploading/registering
                        images
  -c CLOUD, --cloud=CLOUD
                        use this saved cloud account to authenticate against a
                        cloud when uploading/registering images
  --print-syspreps      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
  --install-virtio=DIR  install VirtIO drivers hosted under DIR (Windows only)
  --print-sysprep-params
                        print the defined system preparation parameters for
                        this input media
  --sysprep-param=SYSPREP_PARAMS
                        add KEY=VALUE system preparation parameter
  --no-sysprep          don't perform any system preparation operation
  --public              register image with the cloud as public
  --allow-unsupported   proceed with the image creation even if the media is
                        not supported
  --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 the storage service of a cloud, provide valid cloud API access info (by either using a token and a URL with -t and -a respectively, or a cloud name with -c) and a remote filename using -u. If you also want to register the image with the compute service of the cloud, 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-mkimage 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-mkimage with --print-sysprep on a raw file that hosts an Ubuntu system, will print the following output:

# snf-mkimage --print-syspreps ubuntu.raw

snf-image-creator 0.7
===========================
Examining source media `ubuntu.raw' ... looks like an image file
Snapshotting media source ... done
Enabling recovery proc
Launching helper VM (may take a while) ... done
Inspecting Operating System ... ubuntu
Collecting image metadata ... done

Running OS inspection:
Checking if the media contains logical volumes (LVM)... no

Enabled system preparation operations:
    cleanup-tmp:
        Remove all files under /tmp and /var/tmp

    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.

    cleanup-cache:
        Remove all regular files under /var/cache

    cleanup-userdata:
        Delete sensitive user data

    cleanup-passwords:
        Remove all passwords and lock all user accounts

    cleanup-log:
        Empty all files under /var/log

    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.

    use-persistent-block-device-names:
        Scan fstab & grub configuration files and replace all non-persistent
        device references with UUIDs.

    fix-acpid:
        Replace acpid powerdown action scripts to immediately shutdown the
        system without checking if a GUI is running.

    shrink:
        Shrink the last file system and update the partition table

Disabled system preparation operations:
    remove-user-accounts:
        Remove all user accounts with id greater than 1000

    cleanup-mail:
        Remove all files under /var/mail and /var/spool/mail


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:

$ snf-mkimage --enable-sysprep cleanup-mail --enable-sysprep remove-user-accounts ...

Sysprep parameters are parameters used by some sysprep tasks. In most cases you don't need to change their value. You can see the available sysprep parameters and the default values they have by using the --print-sysprep-params option. You can update their values by using the --sysprep-param option.

If the media is a Windows image, you can install or update its VirtIO drivers by using the --install-virtio option. With this option you can point to a directory that hosts a set of extracted Windows VirtIO drivers.

Dialog-based version

snf-image-creator receives the following options: