README.rst

   1 =====
   2  mic
   3 =====
   4 -------------------------------------
   5 image creator for Linux distributions
   6 -------------------------------------
   7 :Copyright: GPLv2
   8 :Manual section: 1
   9
  10 Overview
  11 ========
  12 The tool `mic` is used to create and manipulate images for Linux distributions.
  13 It's composed of three subcommand: create, convert, chroot. Subcommand `create`
  14 is used to create images with different types, including fs image, loop image,
  15 live CD image, live USB image, raw image, etc. For each image type, there is a
  16 corresponding subcommand. (Details in the following sections)
  17
  18 It supports native running in many mainstream Linux distributions, including:
  19
  20 * Fedora (14 and above)
  21 * openSUSE (11.3 and above)
  22 * Ubuntu (10.04 and above)
  23 * Debian (5.0 and above)
  24 * MeeGo
  25
  26 Installation
  27 ============
  28
  29 Repositories
  30 ------------
  31 So far we support `mic` binary rpms/debs for many popular Linux distributions,
  32 please see the following list. And you can get the corresponding repository on
  33
  34  `<http://download.meego.com/live/devel:/tools:/building>`_
  35
  36 If there is no the distribution you want in the list, please install it from
  37 source code.
  38
  39 * Debian 6.0
  40 * Fedora 14
  41 * Fedora 15
  42 * Fedora 16
  43 * openSUSE 11.3
  44 * openSUSE 11.4
  45 * openSUSE 12.1
  46 * Ubuntu 10.04
  47 * Ubuntu 10.10
  48 * Ubuntu 11.04
  49 * Ubuntu 11.10
  50
  51 Binary Installation
  52 -------------------
  53
  54 Fedora Installation
  55 ~~~~~~~~~~~~~~~~~~~
  56 1. Add devel:tools:building repo:
  57 ::
  58
  59   $ sudo cat <<REPO > /etc/yum.repos.d/devel-tools-building.repo
  60   > [devel-tools-building]
  61   > name=Tools for Fedora
  62   > baseurl=http://download.meego.com/live/devel:/tools:/building/Fedora_<VERSION>
  63   > enabled=1
  64   > gpgcheck=0
  65   > REPO
  66
  67 Also you can take the repo file on devel:tools:building as example. For example,
  68 Fedora 13 can use:
  69 `<http://download.meego.com/live/devel:/tools:/building/Fedora_13/devel:tools:building.repo>`_.
  70
  71 2. Update repolist:
  72 ::
  73
  74   $ sudo yum makecache
  75
  76 3. Install mic:
  77 ::
  78
  79   $ sudo yum install mic
  80
  81 openSUSE Installation
  82 ~~~~~~~~~~~~~~~~~~~~~
  83 1. Add devel:tools:building repo:
  84 ::
  85
  86   $ sudo zypper addrepo http:/download.meego.com/live/devel:/tools:/building/openSUSE_<VERSION>/ devel-tools-building
  87
  88 2. Update repolist:
  89 ::
  90
  91   $ sudo zypper refresh
  92
  93 3. Update libzypp:
  94 ::
  95
  96   $ sudo zypper update libzypp
  97
  98 4. Install mic:
  99 ::
 100
 101   $ sudo zypper install mic
 102
 103 Ubuntu/Debian Installation
 104 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 105 1. Append repo source:
 106 ::
 107
 108   $ sudo cat <<REPO >> /etc/apt-sources.list
 109   > deb http://download.meego.com/live/devel:/tools:/building/<Ubuntu/Debian>_<VERSION>/ /
 110   > REPO
 111
 112 *Tips*: for Ubuntu 10.10, you should use xUbuntu_10.10 to replace <Ubuntu/Debian>_<VERSIN>.
 113
 114 2. Update repolist:
 115 ::
 116
 117   $ sudo apt-get update
 118
 119 3. Install mic:
 120 ::
 121
 122   $ sudo apt-get install mic
 123
 124 Source Installation
 125 -------------------
 126 First, get the source of mic (`<TBD>`_). Then unpack the tar ball, and use make
 127 to process the installation.
 128
 129 1. Unpack:
 130 ::
 131
 132   $ tar xzvf mic.tar.gz
 133
 134 2. Build:
 135 ::
 136
 137   $ cd micng
 138   $ make clean
 139   $ make
 140
 141 3. Install:
 142 ::
 143
 144   $ sudo make install
 145
 146 Configuration file
 147 ==================
 148 The configure file for mic can be provided as `/etc/mic/mic.conf`, where you
 149 can specify the global settings.
 150 The blow is the content of one sample file: ::
 151
 152   [common]
 153   ; general settings
 154
 155   [create]
 156   ; settings for create subcommand
 157   tmpdir= /var/tmp/mic
 158   cachedir= /var/tmp/mic/cache
 159   outdir= .
 160   pkgmgr = zypp
 161
 162   ; proxy = http://proxy.yourcompany.com:8080/
 163   ; no_proxy = localhost,127.0.0.0/8,.yourcompany.com
 164   ; ssl_verify = no
 165
 166   [convert]
 167   ; settings for convert subcommand
 168
 169   [chroot]
 170   ; settings for chroot subcommand
 171
 172 In this configuration file, there are four sections: [common] is for general
 173 setting, and [create] [convert] [chroot] sections are for the options of
 174 corresponding mic subcommands: create, convert, and chroot.
 175
 176 In the [create] section, the following values can be specified:
 177
 178 tmpdir
 179   Temporary directory used in the image creation
 180
 181 cachedir
 182   Directory to store cached repos and downloaded rpm files
 183
 184 outdir
 185   Output directory
 186
 187 pkgmgr
 188   Default backend package manager: yum or zypp
 189
 190 Usages
 191 ======
 192 It's recommended to use `--help` or `help <subcmd>` to get the help message, for
 193 the tool is more or less self-documented.
 194
 195 Running 'mic create'
 196 --------------------
 197 Subcommand *create* is used for creating images. To create an image, you should
 198 give the sub-sub commands which presents the image type you want, and also you
 199 should provide an argument which presents the kickstart file for using, such
 200 as: ::
 201
 202   $ sudo mic create fs test.ks
 203
 204 The supported image types can be listed using `mic create --help` ::
 205
 206   fs             create fs image
 207   livecd         create livecd image
 208   liveusb        create liveusb image
 209   loop           create loop image
 210   raw            create raw image
 211
 212 For each image type, you can get their own options by `--help` option, like
 213 `mic cr fs --help`. Meanwhile, there are some common options that can be used
 214 by all image types, as the following ::
 215
 216   -h, --help          show this help message and exit
 217   --logfile=LOGFILE   Path of logfile
 218   -c CONFIG, --config=CONFIG
 219                       Specify config file for mic
 220   -k CACHEDIR, --cachedir=CACHEDIR
 221                       Cache directory to store the downloaded
 222   -o OUTDIR, --outdir=OUTDIR
 223                       Output directory
 224   -A ARCH, --arch=ARCH
 225                       Specify repo architecture
 226   --release=RID       Generate a release of RID with all necessary
 227                       files,when @BUILD_ID@ is contained in kickstart file,
 228                       it will be replaced by RID
 229   --record-pkgs=RECORD_PKGS
 230                       Record the info of installed packages, multiple values
 231                       can be specified which joined by ",", valid values:
 232                       "name", "content", "license"
 233   --pkgmgr=PKGMGR     Specify backend package manager
 234   --local-pkgs-path=LOCAL_PKGS_PATH
 235                       Path for local pkgs(rpms) to be installed
 236
 237 *Tips*: the common options can be normally put before sub-sub command, but also
 238 can be after them, such as: ::
 239
 240   $ sudo mic cr --outdir output fs test.ks
 241
 242 or ::
 243
 244   $ sudo mic cr fs test.ks --outdir output
 245
 246 *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.
 247
 248 Running 'mic chroot'
 249 --------------------
 250 Subcommand *chroot* is used to chroot an image file. Given an image file, you
 251 can use `mic chroot` to chroot inside the image, and then you can do some
 252 modification to the image. After you logout, the image file will keep your
 253 changes. It's a convenient way to hack your image file.
 254
 255 Sample command: ::
 256
 257   $ sudo mic chroot test.img
 258
 259 Running 'mic convert'
 260 ---------------------
 261 Subcommand *convert* is used for converting an image to another one with
 262 different image type. Using `convert`, you can get your needed image type
 263 comfortably. So far converting livecd to liveusb and liveusb to livecd is
 264 supported.
 265
 266 Sample command: ::
 267
 268   $ sudo mic convert test.iso liveusb
 269
 270 Debug/Verbose Output
 271 --------------------
 272 When you encounter some errors, and you want to know more about it, please use
 273 debug/verbose output to get more details in the process by adding `-d/-v`. And
 274 it's recommended to add `-d/--debug` or `-v/--verbose` like: ::
 275
 276   $ sudo mic -d cr fs test.ks
 277
 278 Advance Features
 279 ================
 280
 281 Proxy support
 282 -------------
 283 proxy setting in mic.conf is not enabled, but you can set proxy in repo section
 284 of ks file, example as follows: ::
 285
 286   repo --name=1.2-oss --baseurl=http://repo.meego.com/MeeGo/releases/1.2.0/repos/oss/ia32/packages/ --proxy=http://host:port --save --debuginfo --source --gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-meego
 287
 288 Multiple running instances support
 289 ----------------------------------
 290 mic support running multi-instance, but cache dir can't be shared between instances,
 291 so you should specify different cachedir for different instance using `--cachedir`.
 292 Also outdir should be specified to a different directory for each  instance  using
 293 `--outdir`, example as follows: ::
 294
 295     mic cr fs netbook1.ks --cachedir=/var/tmp/cache/mic1 --outdir=out1
 296     mic cr fs netbook2.ks --cachedir=/var/tmp/cache/mic2 --outdir=out2