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=0
  59   > REPO
  60
  61 Also you can take the repo file on devel:tools:building as example. For example,
  62 Fedora 13 can use:
  63 `<http://download.meego.com/live/devel:/tools:/building/Fedora_13/devel:tools:building.repo>`_.
  64
  65 2. Update repolist:
  66 ::
  67
  68   $ sudo yum makecache
  69
  70 3. Install mic:
  71 ::
  72
  73   $ sudo yum install mic
  74
  75 openSUSE Installation
  76 ~~~~~~~~~~~~~~~~~~~~~
  77 1. Add devel:tools:building repo:
  78 ::
  79
  80   $ sudo zypper addrepo http:/download.meego.com/live/devel:/tools:/building/openSUSE_<VERSION>/ devel-tools-building
  81
  82 2. Update repolist:
  83 ::
  84
  85   $ sudo zypper refresh
  86
  87 3. Update libzypp:
  88 ::
  89
  90   $ sudo zypper update libzypp
  91
  92 4. Install mic:
  93 ::
  94
  95   $ sudo zypper install mic
  96
  97 Ubuntu/Debian Installation
  98 ~~~~~~~~~~~~~~~~~~~~~~~~~~
  99 1. Append repo source:
 100 ::
 101
 102   $ sudo cat <<REPO >> /etc/apt-sources.list
 103   > deb http://download.meego.com/live/devel:/tools:/building/<Ubuntu/Debian>_<VERSION>/ /
 104   > REPO
 105
 106 *Tips*: for Ubuntu 10.10, you should use xUbuntu_10.10 to replace <Ubuntu/Debian>_<VERSIN>.
 107
 108 2. Update repolist:
 109 ::
 110
 111   $ sudo apt-get update
 112
 113 3. Install mic:
 114 ::
 115
 116   $ sudo apt-get install mic
 117
 118 Source Installation
 119 -------------------
 120 First, get the source of mic (`<TBD>`_). Then unpack the tar ball, and use make
 121 to process the installation.
 122
 123 1. Unpack:
 124 ::
 125
 126   $ tar xzvf mic.tar.gz
 127
 128 2. Build:
 129 ::
 130
 131   $ cd micng
 132   $ make clean
 133   $ make
 134
 135 3. Install:
 136 ::
 137
 138   $ sudo make install
 139
 140 Configuration file
 141 ==================
 142 The configure file for mic can be provided as `/etc/mic/mic.conf`, where you
 143 can specify the global settings.
 144 The blow is the content of one sample file: ::
 145
 146   [common]
 147   ; general settings
 148
 149   [create]
 150   ; settings for create subcommand
 151   tmpdir= /var/tmp/mic
 152   cachedir= /var/tmp/mic/cache
 153   outdir= .
 154   pkgmgr = zypp
 155
 156   ; proxy = http://proxy.yourcompany.com:8080/
 157   ; no_proxy = localhost,127.0.0.0/8,.yourcompany.com
 158
 159   [convert]
 160   ; settings for convert subcommand
 161
 162   [chroot]
 163   ; settings for chroot subcommand
 164
 165 In this configuration file, there are four sections: [common] is for general
 166 setting, and [create] [convert] [chroot] sections are for the options of
 167 corresponding mic subcommands: create, convert, and chroot.
 168
 169 In the [create] section, the following values can be specified:
 170
 171 tmpdir
 172   Temporary directory used in the image creation
 173
 174 cachedir
 175   Directory to store cached repos and downloaded rpm files
 176
 177 outdir
 178   Output directory
 179
 180 pkgmgr
 181   Default backend package manager: yum or zypp
 182
 183 Usages
 184 ======
 185 It's recommended to use `--help` or `help <subcmd>` to get the help message, for
 186 the tool is more or less self-documented.
 187
 188 Running 'mic create'
 189 --------------------
 190 Subcommand *create* is used for creating images. To create an image, you should
 191 give the sub-sub commands which presents the image type you want, and also you
 192 should provide an argument which presents the kickstart file for using, such
 193 as: ::
 194
 195   $ sudo mic create fs test.ks
 196
 197 The supported image types can be listed using `mic create --help` ::
 198
 199   fs             create fs image
 200   livecd         create livecd image
 201   liveusb        create liveusb image
 202   loop           create loop image
 203   raw            create raw image
 204
 205 For each image type, you can get their own options by `--help` option, like
 206 `mic cr fs --help`. Meanwhile, there are some common options that can be used
 207 by all image types, as the following ::
 208
 209   -h, --help          show this help message and exit
 210   --logfile=LOGFILE   Path of logfile
 211   -c CONFIG, --config=CONFIG
 212                       Specify config file for mic
 213   -k CACHEDIR, --cachedir=CACHEDIR
 214                       Cache directory to store the downloaded
 215   -o OUTDIR, --outdir=OUTDIR
 216                       Output directory
 217   -A ARCH, --arch=ARCH
 218                       Specify repo architecture
 219   --release=RID       Generate a release of RID with all neccessary
 220                       files,when @BUILD_ID@ is contained in kickstart file,
 221                       it will be replaced by RID
 222   --record-pkgs=RECORD_PKGS
 223                       Record the info of installed packages, multiple values
 224                       can be specified which joined by ",", valid values:
 225                       "name", "content", "license"
 226   --pkgmgr=PKGMGR     Specify backend package manager
 227   --local-pkgs-path=LOCAL_PKGS_PATH
 228                       Path for local pkgs(rpms) to be installed
 229
 230 *Tips*: the common options can be normally put before sub-sub command, but also
 231 can be after them, such as: ::
 232
 233   $ sudo mic cr --outdir output fs test.ks
 234
 235 or ::
 236
 237   $ sudo mic cr fs test.ks --outdir output
 238
 239 *Tips*: if you failed to create armv7* image, the reason may be qemu/qemu-arm on your host is lower than required, please update qemu/qemu-arm higher than 0.13.0.
 240
 241 Running 'mic chroot'
 242 --------------------
 243 Subcommand *chroot* is used to chroot an image file. Given an image file, you
 244 can use `mic chroot` to chroot inside the image, and then you can do some
 245 modification to the image. After you logout, the image file will keep your
 246 changes. It's a convenient way to hack your image file.
 247
 248 Sample command: ::
 249
 250   $ sudo mic chroot test.img
 251
 252 Running 'mic convert'
 253 ---------------------
 254 Subcommand *convert* is used for converting an image to another one with
 255 different image type. Using `convert`, you can get your needed image type
 256 comfortably. So far converting livecd to liveusb and liveusb to livecd is
 257 supported.
 258
 259 Sample command: ::
 260
 261   $ sudo mic convert test.iso liveusb
 262
 263 Debug/Verbose Output
 264 --------------------
 265 When you encounter some errors, and you want to know more about it, please use
 266 debug/verbose output to get more details in the process by adding `-d/-v`. And
 267 it's recommended to add `-d/--debug` or `-v/--verbose` like: ::
 268
 269   $ sudo mic -d cr fs test.ks