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   ; ssl_verify = no
 164
 165   [convert]
 166   ; settings for convert subcommand
 167
 168   [chroot]
 169   ; settings for chroot subcommand
 170
 171 In this configuration file, there are four sections: [common] is for general
 172 setting, and [create] [convert] [chroot] sections are for the options of
 173 corresponding mic subcommands: create, convert, and chroot.
 174
 175 In the [create] section, the following values can be specified:
 176
 177 tmpdir
 178   Temporary directory used in the image creation
 179
 180 cachedir
 181   Directory to store cached repos and downloaded rpm files
 182
 183 outdir
 184   Output directory
 185
 186 pkgmgr
 187   Default backend package manager: yum or zypp
 188
 189 Usages
 190 ======
 191 It's recommended to use `--help` or `help <subcmd>` to get the help message, for
 192 the tool is more or less self-documented.
 193
 194 Running 'mic create'
 195 --------------------
 196 Subcommand *create* is used for creating images. To create an image, you should
 197 give the sub-sub commands which presents the image type you want, and also you
 198 should provide an argument which presents the kickstart file for using, such
 199 as: ::
 200
 201   $ sudo mic create fs test.ks
 202
 203 The supported image types can be listed using `mic create --help` ::
 204
 205   fs             create fs image
 206   livecd         create livecd image
 207   liveusb        create liveusb image
 208   loop           create loop image
 209   raw            create raw image
 210
 211 For each image type, you can get their own options by `--help` option, like
 212 `mic cr fs --help`. Meanwhile, there are some common options that can be used
 213 by all image types, as the following ::
 214
 215   -h, --help          show this help message and exit
 216   --logfile=LOGFILE   Path of logfile
 217   -c CONFIG, --config=CONFIG
 218                       Specify config file for mic
 219   -k CACHEDIR, --cachedir=CACHEDIR
 220                       Cache directory to store the downloaded
 221   -o OUTDIR, --outdir=OUTDIR
 222                       Output directory
 223   -A ARCH, --arch=ARCH
 224                       Specify repo architecture
 225   --release=RID       Generate a release of RID with all necessary
 226                       files,when @BUILD_ID@ is contained in kickstart file,
 227                       it will be replaced by RID
 228   --record-pkgs=RECORD_PKGS
 229                       Record the info of installed packages, multiple values
 230                       can be specified which joined by ",", valid values:
 231                       "name", "content", "license"
 232   --pkgmgr=PKGMGR     Specify backend package manager
 233   --local-pkgs-path=LOCAL_PKGS_PATH
 234                       Path for local pkgs(rpms) to be installed
 235
 236 *Tips*: the common options can be normally put before sub-sub command, but also
 237 can be after them, such as: ::
 238
 239   $ sudo mic cr --outdir output fs test.ks
 240
 241 or ::
 242
 243   $ sudo mic cr fs test.ks --outdir output
 244
 245 *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.
 246
 247 Running 'mic chroot'
 248 --------------------
 249 Subcommand *chroot* is used to chroot an image file. Given an image file, you
 250 can use `mic chroot` to chroot inside the image, and then you can do some
 251 modification to the image. After you logout, the image file will keep your
 252 changes. It's a convenient way to hack your image file.
 253
 254 Sample command: ::
 255
 256   $ sudo mic chroot test.img
 257
 258 Running 'mic convert'
 259 ---------------------
 260 Subcommand *convert* is used for converting an image to another one with
 261 different image type. Using `convert`, you can get your needed image type
 262 comfortably. So far converting livecd to liveusb and liveusb to livecd is
 263 supported.
 264
 265 Sample command: ::
 266
 267   $ sudo mic convert test.iso liveusb
 268
 269 Debug/Verbose Output
 270 --------------------
 271 When you encounter some errors, and you want to know more about it, please use
 272 debug/verbose output to get more details in the process by adding `-d/-v`. And
 273 it's recommended to add `-d/--debug` or `-v/--verbose` like: ::
 274
 275   $ sudo mic -d cr fs test.ks