README.rst

   1 ======================
   2  User Guide of **mic**
   3 ======================
   4
   5 Overview
   6 ========
   7 The tool `mic` is used to create and manipulate images for Linux distributions.
   8 It's composed of three subcommand: create, convert, chroot. Subcommand `create`
   9 is used to create images with different types, including fs image, loop image,
  10 live CD image, live USB image, raw image, etc. For each image type, there is a
  11 corresponding subcommand. (Details in the following sections)
  12
  13 It supports native running in many mainstream Linux distributions, including:
  14
  15   * Fedora (13 and above)
  16   * openSUSE (11.3 and above)
  17   * Ubuntu (10.04 and above)
  18   * Debian (5.0 and above)
  19   * MeeGo
  20
  21 Installation
  22 ============
  23
  24 Repositories
  25 ------------
  26 So far we support `mic` binary rpms/debs for many popular Linux distributions,
  27 please see the following list. And you can get the corresponding repository on
  28 `<http://download.meego.com/live/devel:/tools:/building/>`_, if there is no
  29 your distribution in the list, please install the tool `mic` from source.
  30
  31   * Debian 5.0
  32   * Fedora 13
  33   * Fedora 14
  34   * Fedora 15
  35   * openSUSE 11.3
  36   * openSUSE 11.4
  37   * Ubuntu 10.04
  38   * Ubuntu 10.10
  39
  40 *Tips*: Debian 6.0 can use the repository of Debian 5.0.
  41
  42 Binary Installation
  43 -------------------
  44
  45 Fedora Installation
  46 ~~~~~~~~~~~~~~~~~~~
  47 1. Add devel:tools:building repo
  48
  49 >>> sudo cat <<REPO > /etc/yum.repos.d/devel-tools-building.repo
  50 >>> [devel-tools-building]
  51 >>> name=Tools for Fedora
  52 >>> baseurl=http://download.meego.com/live/devel:/tools:/building/Fedora_<VERSION>
  53 >>> enabled=1
  54 >>> gpgcheck =1
  55 >>> gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-meego
  56 >>> REPO
  57
  58 Also you can take the repo file on devel:tools:building as example. For example,
  59 Fedora 13 can use:
  60 `<http://download.meego.com/live/devel:/tools:/building/Fedora_13/devel:tools:building.repo>`_.
  61
  62 2. Update repolist
  63
  64 >>> sudo yum update
  65
  66 3. Install mic
  67
  68 >>> sudo yum install mic
  69
  70 openSUSE Installation
  71 ~~~~~~~~~~~~~~~~~~~~~
  72 1. Add devel:tools:building repo
  73
  74 >>> sudo zypper addrepo http:/download.meego.com/live/devel:/tools:/building/openSUSE_<VERSION>/ devel-tools-building
  75
  76 2. Update repolist
  77
  78 >>> sudo zypper refresh
  79
  80 3. Update libzypp
  81
  82 >>> sudo zypper update libzypp
  83
  84 4. Install mic
  85
  86 >>> sudo zypper install mic
  87
  88 Ubuntu/Debian Installation
  89 ~~~~~~~~~~~~~~~~~~~~~~~~~~
  90 1. Append repo source
  91
  92 >>> sudo cat <<REPO >> /etc/apt-sources.list
  93 >>> deb http://download.meego.com/live/devel:/tools:/building/<Ubuntu/Debian>_<VERSION>/ /
  94 >>> REPO
  95
  96 2. Update repolist
  97
  98 >>> sudo apt-get update
  99
 100 3. Install mic
 101
 102 >>> sudo apt-get install mic
 103
 104 Source Installation
 105 -------------------
 106 First, get the source of mic (`<TBD>`_). Then unpack the tar ball, and use make
 107 to process the installation.
 108
 109 1. unpack
 110
 111 >>> tar xzvf mic.tar.gz
 112
 113 2. Build
 114
 115 >>> cd micng
 116 >>> make clean
 117 >>> make
 118
 119 3. Install
 120
 121 >>> sudo make install
 122
 123 Configuration file
 124 ==================
 125 A global configure file for mic is provided as `/etc/mic/mic.conf`, where you
 126 can specify the program options statically.
 127 Below is a sample file which is presented in the source:
 128
 129 >>> cat /etc/mic/mic.conf
 130 >>> [common]
 131 >>> ; general settings
 132 >>>
 133 >>> [create]
 134 >>> ; settings for create subcommand
 135 >>> tmpdir= /var/tmp/mic
 136 >>> cachedir= /var/tmp/mic/cache
 137 >>> outdir= .
 138 >>> pkgmgr = zypp
 139 >>>
 140 >>> ; proxy = http://proxy.yourcompany.com:8080/
 141 >>> ; no_proxy = localhost,127.0.0.0/8,.yourcompany.com
 142 >>>
 143 >>> [convert]
 144 >>> ; settings for convert subcommand
 145 >>>
 146 >>> [chroot]
 147 >>> ; settings for chroot subcommand
 148
 149 For the further development, there are four sections on mic.conf, and [common]
 150 is for general setting, [create], [convert], and [chroot] are prepared for the
 151 options of mic subcommands: create, convert, and chroot.
 152
 153 While you only need set [create] section properly for practice, since other
 154 section would be not effective currently.
 155
 156 +---------+-------------------------------------------------------------------+
 157 | Option  | Usage                                                             |
 158 +=========+===================================================================+
 159 | tmpdir  | temporary directory used to put _instroot and others              |
 160 +---------+-------------------------------------------------------------------+
 161 | cachedir| directory where cached repos will reside also downloaded packages |
 162 +---------+-------------------------------------------------------------------+
 163 | outdir  | where your images will reside once they are created               |
 164 +---------+-------------------------------------------------------------------+
 165 | pkgmgr  | default backend package manager, including yum/zypp               |
 166 +---------+-------------------------------------------------------------------+
 167 | arch    | default repo architecture, like i586, armv7l                      |
 168 +---------+-------------------------------------------------------------------+
 169
 170 Usages
 171 ======
 172 It's recommended to use `--help` or `help <subcmd>` to get the help message, for
 173 the tool is more or less self-documented.
 174
 175 Running 'mic create'
 176 --------------------
 177 Subcommand *create* is used for creating images. To create an image, you should
 178 give the sub-sub commands which presents the image type you want, and also you
 179 should provide an argument which presents the kickstart file for using, such
 180 as:
 181
 182 >>> sudo mic create fs test.ks
 183
 184 The supported image types can be listed using `mic create --help`::
 185
 186   fs             create fs image
 187   livecd         create livecd image
 188   liveusb        create liveusb image
 189   loop           create loop image
 190   raw            create raw image
 191
 192 For each image type, you can get their own options by `--help` option, like
 193 `mic cr fs --help`. Meanwhile, there are some common options that can be used
 194 by all image types, see following table:
 195
 196 +------------------+----------------------------------------------------------+
 197 | Option           | Usage                                                    |
 198 +==================+==========================================================+
 199 | -o/--outdir      | specify directory where the images reside                |
 200 +------------------+----------------------------------------------------------+
 201 | -a/--arch        | specify repo architecture, like i586, armv7l, etc        |
 202 +------------------+----------------------------------------------------------+
 203 | -c/--config      | specify the custom configure file for mic                |
 204 +------------------+----------------------------------------------------------+
 205 | --release        | generate release package: image, ks, pkg-list, MANIFEST  |
 206 +------------------+----------------------------------------------------------+
 207 | --logfile        | specify log file to record the output                    |
 208 +------------------+----------------------------------------------------------+
 209 | --local-pkgs-path| directory where local packages can be used when creating |
 210 +------------------+----------------------------------------------------------+
 211 | --pkgmgr         | specify backend package manager                          |
 212 +------------------+----------------------------------------------------------+
 213
 214 *Tips*: the common options can be normally put before sub-sub command, but also
 215 can be after them, such as:
 216
 217 >>> sudo mic cr --outdir output fs test.ks
 218
 219 or
 220
 221 >>> sudo mic cr fs test.ks --outdir output
 222
 223 Running 'mic chroot'
 224 --------------------
 225 Subcommand *chroot* is used to chroot an image file. Given an image file, you
 226 can use `mic chroot` to chroot inside the image, and then you can do some
 227 modification to the image. After you logout, the image file will keep your
 228 changes. It's a convenient way to hack your image file.
 229
 230 Sample command could be like this:
 231
 232 >>> sudo mic chroot test.img
 233
 234 Running 'mic convert'
 235 ---------------------
 236 Subcommand *convert* is used for converting an image to another one with
 237 different image type. Using `convert`, you can get your needed image type
 238 comfortably. So far converting livecd to liveusb and liveusb to livecd is
 239 supported.
 240
 241 Sample command is given as following:
 242
 243 >>> sudo mic convert test.iso liveusb
 244
 245 Debug/Verbose Output
 246 --------------------
 247 When you encounter some errors, and you want to know more about it, please use
 248 debug/verbose output to get more details in the process by adding `-d/-v`. And
 249 it's recommended to add `-d/--debug` or `-v/--verbose` like as following:
 250
 251 >>> sudo mic -d cr fs test.ks