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