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