Add a manpage for InstallSystems.

Section: python

Priority: optional

Maintainer: Sébastien Luttringer <sebastien.luttringer@smartjog.com>

Build-Depends: python (>= 2.6), debhelper (>= 7), python-central (>= 0.6), cdbs (>= 0.4.50), python-setuptools

Build-Depends: python (>= 2.6), debhelper (>= 7), python-central (>= 0.6), cdbs (>= 0.4.50), python-setuptools, python-docutils

XS-Python-Version: >= 2.6

Standards-Version: 3.9.1

doc/is.1

==

is

==

--------------

InstallSystems

--------------

:Author: Sébastien Luttringer <sebastien.luttringer@smartjog.com>

:Manual section: 1

SYNOPSIS

========

is [options...] command [args...]

SUMMARY

=======

The InstallSystems is a systems deploy tool. It can easily setup hosts or VMs. This tool gives access to versionned images of systems and configuration scripts. It is a complete solution for mass deployment. It regroups tools for image making, repository management, and easy installing.

You can use InstallSystems with already existent repositories/images or you can make yours using the appropriate is command.

OPTIONS

=======

-h, --help

    show an help message and exit

-V, --version

    show installsystems version

-v {0,1,2}, --verbosity {0,1,2}

    show InstallSystems version

-d, --debug

    enable debug mode

-q, --quiet

    enable quiet mode

-c *CONFIG*, --config *CONFIG*

    define path to configuration file

-R *REPO_CONFIG*, --repo-config *REPO_CONFIG*

    define path to repositories configuration file

-s *REPO*, --repo-search *REPO*

    search for images inside those repositories

-f *REPO_FILTER*, --repo-filter *REPO_FILTER*

    filter repositories by name

-r *REPO_PATH*, --repo-path *REPO_PATH*

    define *REPO_PATH* as a temporary repository

-T *SECONDS*, --repo-timeout *SECONDS*

    set repositories access timeout to *SECONDS*

--no-cache

    do not use persistent database caching

--no-sync

    do not sync repository database cache

--no-color

    do not display color output

--nice NICE

    set the *NICE* value for the process

--ionice-class {none,rt,be,idle}

    ionice class of the process (default: none)

--ionice-level IONICE_LEVEL

    set the *IONICE_LEVEL* for the process

COMMANDS

========

Please note that you can display specific help messages for all of

these commands by using the --help argument after the command name.

add [-h] [-p] *repository* *image*...

    Add a local *image* to a local *repository*.

    -p, --preserve

        do not remove *image* after adding it to the *repository*

build [-h] [-c] [-C] [-f] [-p] [-s] [*path*]...

    Check and build the InstallSystems source image in *path* (by default, in the current directory).

    -c, --no-check

        do not check scripts compilation

    -C, --chdir

        build image inside source image directory, not in the current one

    -f, --force

        overwrite existing images

    -p, --payload

        overwrite existing payloads

    -s, --no-script

        do not run build scripts

cat [-h] path|[repository/]\ *image*\ [:version] *file*...

    Display one *file* (or more) from *image*. Globbing is allowed for files matching.

changelog [-h] [-v]  path|[repository/]\ *image*\ [:version]...

    Display the last changelog entry for one *image* (or more).

    -v, --all-version

        display the whole changelog

check [-h] *repository*

    Check a local *repository* for missing, unreferenced and corrupted files.

chroot [-h] [-m] [-s *SHELL*\ ] *path*

    Chroot inside *path*. This is especially usefull to update system images. This mounts filesystems (/proc, /sys, /dev, /dev/pts, /dev/shm), modify a few config files (resolv.conf, mtab) and finally executes a shell in your chroot (default: /bin/bash)

    -m, --no-mount

        disable mounting of /{proc,dev,sys}

    -s *SHELL*\ , --shell *SHELL*

        shell to call inside the chroot

clean [-h] [-f] *repository*...

    Clean-up one local *repository* (or more). This will remove files that are no longer referenced in the repository database.

    -f, --force

        do not prompt before cleaning

copy [-h] [-f] *image*... *repository*

    Copy one *image* (or more) to another local **repository**.

     -f, --force

         overwrite existing images whithout prompting

del [-h] [-f] [-p] *image*...

    Delete one *image* (or more) from its repository.

    -f, --force

        delete images whithout prompting

    -p, --preserve

        do not remove payloads from the repository

diff [-h] *object* *object*

    Show diff between two repositories or images.

extract [-h] [-f] [-g] [-p] *image* *path*

    Extract an InstallSystems *image* into *path*.

    -f, --force

        overwrite existing destination

    -g, --gen-description

        generate a description file from metadata

    -p, --payload

        extract payloads

get [-h] [-f] [-I] [-p] *image*...

Download a remote InstallSystem *image* in current directory.

    -f, --force

        overwrite existing destination

    -I, --no-image

        do not get the image (should be combined with -p)

    -p, --payload

        also get payloads

help [-h]

    Show help.

info [-h] [-c] [-j] [-v] *image*...

    Display info about one *image* (or more).

    -c, --changelog

        display *image* changelog

    -j, --json

        output is formated in json

    -v, --verbose

        verbose output

init [-h] *repository*...

    Create one empty *repository* (or more).

install [--dry-run] *image*

    Install *image*. Each *image* may have specific options. Typically, each one will display a list of available options when using the **--help** argument. In case of trouble during the install you should contact the author of the image. You can find this info in its description file.

    --dry-run

        do not execute setup scripts

list [-h] [-A] [-d] [-D] [-j] [-l] [-m] [-s] [-u] [image...]

    List available images. By default, it displays the image name and its repository, ordered by repositories/images/version.

    -A, --author

        display image author

    -d, --date

        display image date

    -D, --description

        display image description

    -j, --json

        output is formated in json

    -l, --long

        long display

    -m, --md5

        display image md5

    -s, --size

        display image size

    -u, --url

        display image url

move [-h] [-f] *image*... *repository*

    Move one *image* (or more) to another *repository*.

    -f, --force

        move *image* without confirmation

new [-h] [-f] *path*

    Create a new source image in *path*. It creates the base directories (parser, setup, payload) and a description template. Moreover this command creates samples files for setup, parser and changelog. It also set executable rights on scripts.

    -f, --force

        overwrite existing source image

payload [-h] [-j] [-i] [md5_pattern]...

    List available payloads matching *md5_pattern* (Default: match everything)

    -j, --json

        output is formated in json

    -i, --images

        list images using payload

prepare_chroot [-h] [-m] *path*

    Prepare to chroot in *path*.

    -m, --no-mount

        disable mounting of /{proc,dev,sys}

repo [-h] [-j] [-l|-r] [-o|-O] [-s] [-u] [--purge] [repository]...

    List available repositories. By defaut, only names are displayed.

    -j, --json

        output is formated in json

    -l, --local

        list local repositoriez (filter)

    -r, --remote

        list remote repositories (filter)

    -o, --online

        list online repositories (filter)

    -O, --offline

        list offline repositories (filter)

    -s, --state

        display repository state (online/offline/local/remote)

    -u, --url

        display repository url

    --purge

        remove cache databases

search [-h] *pattern*

    Search *pattern* in repositories.

unprepare_chroot [-h] [-m] *path*

    Remove preparation of a chroot in *path*.

    -m, --no-umount

        disable unmouting of /{proc,dev,sys}

version [-h]

    Print InstallSystems version.

EXAMPLES

========

Setup a real host and then reboot it.

    is install debian-smartjog -n bobby.seblu.net --disks /dev/sda --reboot

Create of a new image named foobar.

    is new foobar

Build the cdn-fw image

    is build ./images/cdn-fw

IMAGES

======

InstallSystems use two kind of images:

**source image**

     Each image available in repositories has to be build. The image before building is called a source image. In a source image, there are three directories and two files. Each images make the distinction between scripts and chroot.

    build/

        Scripts to customize the build process for the image.

    parser/

        Scripts adding specific options for the image are in this directory.

    setup/

        The scripts with logical steps of the install are in this directory.

    payload/

        The payload directory embeds one or more rootfs for the image.

    description

        It defines the author, the date and the version of the image.

    changelog

        The changelog file lists modifications of the image.

**packaged image**

    Built images are called packaged images. They are versionned, gunzipped and ready to deploy. Like source images, package images still make the difference between scripts and chroot. But it doesn't make difference between parser scripts and setup scripts. In fact you will have at least two tarballs:

    image_name.isimage

        This tarball contains parser/, setup/, description and changelog.

    image_name.isdata

        This tarball contains one rootfs from payload/

REPOSITORIES

============

InstallSystems manages images with repositories.

An InstallSystems repository use a SQLite3 database (db), a last file (last version of images) and Md5s of images. The repos are reachable by HTTP, FTP and SSH. This allows you to easily access images.

Also, please note that you can only modify local repositories.

import os

import sys

import installsystems

import subprocess

# Build manpage

subprocess.call(['rst2man', 'doc/is.1.rst', 'doc/is.1'])

# Retrieval of version