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 need to use xUbuntu_10.10 to replace
 113 <Ubuntu/Debian>_<VERSIN>.
 114
 115 2. Update repolist:
 116 ::
 117
 118   $ sudo apt-get update
 119
 120 3. Install mic:
 121 ::
 122
 123   $ sudo apt-get install mic
 124
 125 Source Installation
 126 -------------------
 127 First, get the source of mic (`<TBD>`_). Then unpack the tar ball, and use make
 128 to process the installation.
 129
 130 1. Unpack:
 131 ::
 132
 133   $ tar xzvf mic.tar.gz
 134
 135 2. Build:
 136 ::
 137
 138   $ cd micng
 139   $ make clean
 140   $ make
 141
 142 3. Install:
 143 ::
 144
 145   $ sudo make install
 146
 147 Configuration file
 148 ==================
 149 The configure file for mic can be provided as `/etc/mic/mic.conf`, where you
 150 can specify the global settings.
 151 The blow is the content of one sample file: ::
 152
 153   [common]
 154   ; general settings
 155
 156   [create]
 157   ; settings for create subcommand
 158   tmpdir= /var/tmp/mic
 159   cachedir= /var/tmp/mic/cache
 160   outdir= .
 161   pkgmgr = zypp
 162
 163   ; proxy = http://proxy.yourcompany.com:8080/
 164   ; no_proxy = localhost,127.0.0.0/8,.yourcompany.com
 165   ; ssl_verify = no
 166
 167   [convert]
 168   ; settings for convert subcommand
 169
 170   [chroot]
 171   ; settings for chroot subcommand
 172
 173 In this configuration file, there are four sections: [common] is for general
 174 setting, and [create] [convert] [chroot] sections are for the options of
 175 corresponding mic subcommands: create, convert, and chroot.
 176
 177 In the [create] section, the following values can be specified:
 178
 179 tmpdir
 180   Temporary directory used in the image creation
 181
 182 cachedir
 183   Directory to store cached repos and downloaded rpm files
 184
 185 outdir
 186   Output directory
 187
 188 pkgmgr
 189   Default backend package manager: yum or zypp
 190
 191 Usages
 192 ======
 193 It's recommended to use `--help` or `help <subcmd>` to get the help message, for
 194 the tool is more or less self-documented.
 195
 196 Running 'mic create'
 197 --------------------
 198 Subcommand *create* is used for creating images. To create an image, you should
 199 give the sub-sub commands which presents the image type you want, and also you
 200 should provide an argument which presents the kickstart file for using, such
 201 as: ::
 202
 203   $ sudo mic create fs test.ks
 204
 205 The supported image types can be listed using `mic create --help` ::
 206
 207   fs             create fs image
 208   livecd         create livecd image
 209   liveusb        create liveusb image
 210   loop           create loop image
 211   raw            create raw image
 212
 213 For each image type, you can get their own options by `--help` option, like
 214 `mic cr fs --help`. Meanwhile, there are some common options that can be used
 215 by all image types, as the following ::
 216
 217   -h, --help          show this help message and exit
 218   --logfile=LOGFILE   Path of logfile
 219   -c CONFIG, --config=CONFIG
 220                       Specify config file for mic
 221   -k CACHEDIR, --cachedir=CACHEDIR
 222                       Cache directory to store the downloaded
 223   -o OUTDIR, --outdir=OUTDIR
 224                       Output directory
 225   -A ARCH, --arch=ARCH
 226                       Specify repo architecture
 227   --release=RID       Generate a release of RID with all necessary
 228                       files,when @BUILD_ID@ is contained in kickstart file,
 229                       it will be replaced by RID
 230   --record-pkgs=RECORD_PKGS
 231                       Record the info of installed packages, multiple values
 232                       can be specified which joined by ",", valid values:
 233                       "name", "content", "license"
 234   --pkgmgr=PKGMGR     Specify backend package manager
 235   --local-pkgs-path=LOCAL_PKGS_PATH
 236                       Path for local pkgs(rpms) to be installed
 237
 238 *Tips*: the common options can be normally put before sub-sub command, but also
 239 can be after them, such as: ::
 240
 241   $ sudo mic cr --outdir output fs test.ks
 242
 243 or ::
 244
 245   $ sudo mic cr fs test.ks --outdir output
 246
 247 *Tips*: if you failed to create armv7* image, the reason may be: qemu/qemu-arm
 248 on your host is lower than required, please upgrade qemu/qemu-arm higher than
 249 version 0.13.0.
 250
 251 Running 'mic chroot'
 252 --------------------
 253 Subcommand *chroot* is used to chroot an image file. Given an image file, you
 254 can use `mic chroot` to chroot inside the image, and then you can do some
 255 modification to the image. After you logout, the image file will keep your
 256 changes. It's a convenient way to hack your image file.
 257
 258 Sample command: ::
 259
 260   $ sudo mic chroot test.img
 261
 262 Running 'mic convert'
 263 ---------------------
 264 Subcommand *convert* is used for converting an image to another one with
 265 different image type. Using `convert`, you can get your needed image type
 266 comfortably. So far converting livecd to liveusb and liveusb to livecd is
 267 supported.
 268
 269 Sample command: ::
 270
 271   $ sudo mic convert test.iso liveusb
 272
 273 Debug/Verbose Output
 274 --------------------
 275 When you encounter some errors, and you want to know more about it, please use
 276 debug/verbose output to get more details in the process by adding `-d/-v`. And
 277 it's recommended to add `-d/--debug` or `-v/--verbose` like: ::
 278
 279   $ sudo mic -d cr fs test.ks
 280
 281 Advance Features
 282 ================
 283
 284 Proxy support
 285 -------------
 286 proxy setting in mic.conf is not enabled, but you can set proxy in repo section
 287 of ks file, example as follows: ::
 288
 289   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
 290
 291 Multiple running instances support
 292 ----------------------------------
 293 mic support running multi-instance, but cache dir can't be shared between
 294 instances, so you should specify different cachedir for different instance
 295 using `--cachedir`. Also outdir should be specified to a different directory
 296 for each instance using `--outdir`, example as follows: ::
 297
 298     mic cr fs netbook1.ks --cachedir=/var/tmp/cache/mic1 --outdir=out1
 299     mic cr fs netbook2.ks --cachedir=/var/tmp/cache/mic2 --outdir=out2
 300
 301 Known Issues
 302 ============
 303
 304 Bug of latest "syslinux" package
 305 --------------------------------
 306 In some new Linux distributions, the "syslinux" package in their official
 307 software repositories is the version 4.04. It will cause segment fault for
 308 a fatal bug, and mic will failed with syslinux installation errors.
 309
 310 The solution is to install the patched "syslinux" package in MeeGo or Tizen's
 311 tools repos, until the official released one being fixed.
 312