jfding/mic

Image Creator for Linux Distributions

mic

image creator for Linux distributions

Copyright

GPLv2

Manual section

1

Overview

The tool mic is used to create and manipulate images for Linux distributions. It's composed of three subcommand: create, convert, chroot. Subcommand create is used to create images with different types, including fs image, loop image, live CD image, live USB image, raw image, etc. For each image type, there is a corresponding subcommand. (Details in the following sections)

It supports native running in many mainstream Linux distributions, including:

• Fedora (14 and above)
• openSUSE (11.3 and above)
• Ubuntu (10.04 and above)
• Debian (5.0 and above)
• MeeGo

Installation

Repositories

So far we support mic binary rpms/debs for many popular Linux distributions, please see the following list. And you can get the corresponding repository on

http://download.meego.com/live/devel:/tools:/building

If there is no the distribution you want in the list, please install it from source code.

• Debian 6.0
• Fedora 14
• Fedora 15
• Fedora 16
• openSUSE 11.3
• openSUSE 11.4
• openSUSE 12.1
• Ubuntu 10.04
• Ubuntu 10.10
• Ubuntu 11.04
• Ubuntu 11.10

Binary Installation

Fedora Installation

1. Add devel:tools:building repo: :

$ sudo cat <<REPO > /etc/yum.repos.d/devel-tools-building.repo
> [devel-tools-building]
> name=Tools for Fedora
> baseurl=http://download.meego.com/live/devel:/tools:/building/Fedora_<VERSION>
> enabled=1
> gpgcheck=0
> REPO

Also you can take the repo file on devel:tools:building as example. For example, Fedora 13 can use: http://download.meego.com/live/devel:/tools:/building/Fedora_13/devel:tools:building.repo.

2. Update repolist: :

$ sudo yum makecache

3. Install mic: :

$ sudo yum install mic

openSUSE Installation

1. Add devel:tools:building repo: :

$ sudo zypper addrepo http:/download.meego.com/live/devel:/tools:/building/openSUSE_<VERSION>/ devel-tools-building

2. Update repolist: :

$ sudo zypper refresh

3. Update libzypp: :

$ sudo zypper update libzypp

4. Install mic: :

$ sudo zypper install mic

Ubuntu/Debian Installation

1. Append repo source: :

$ sudo cat <<REPO >> /etc/apt-sources.list
> deb http://download.meego.com/live/devel:/tools:/building/<Ubuntu/Debian>_<VERSION>/ /
> REPO

Tips: for Ubuntu 10.10, you need to use xUbuntu_10.10 to replace <Ubuntu/Debian>_<VERSIN>.

2. Update repolist: :

$ sudo apt-get update

3. Install mic: :

$ sudo apt-get install mic

Source Installation

First, get the source of mic (TBD). Then unpack the tar ball, and use make to process the installation.

1. Unpack: :

$ tar xzvf mic.tar.gz

2. Build: :

$ cd micng
$ make clean
$ make

3. Install: :

$ sudo make install

Configuration file

The configure file for mic can be provided as /etc/mic/mic.conf, where you can specify the global settings. The blow is the content of one sample file: :

[common]
; general settings

[create]
; settings for create subcommand
tmpdir= /var/tmp/mic
cachedir= /var/tmp/mic/cache
outdir= .
pkgmgr = zypp

; proxy = http://proxy.yourcompany.com:8080/
; no_proxy = localhost,127.0.0.0/8,.yourcompany.com
; ssl_verify = no

[convert]
; settings for convert subcommand

[chroot]
; settings for chroot subcommand

In this configuration file, there are four sections: [common] is for general setting, and [create] [convert] [chroot] sections are for the options of corresponding mic subcommands: create, convert, and chroot.

In the [create] section, the following values can be specified:

tmpdir

Temporary directory used in the image creation

cachedir

Directory to store cached repos and downloaded rpm files

outdir

Output directory

pkgmgr

Default backend package manager: yum or zypp

Usages

It's recommended to use --help or help <subcmd> to get the help message, for the tool is more or less self-documented.

Running 'mic create'

Subcommand create is used for creating images. To create an image, you should give the sub-sub commands which presents the image type you want, and also you should provide an argument which presents the kickstart file for using, such as: :

$ sudo mic create fs test.ks

The supported image types can be listed using mic create --help :

fs             create fs image
livecd         create livecd image
liveusb        create liveusb image
loop           create loop image
raw            create raw image

For each image type, you can get their own options by --help option, like mic cr fs --help. Meanwhile, there are some common options that can be used by all image types, as the following :

-h, --help          show this help message and exit
--logfile=LOGFILE   Path of logfile
-c CONFIG, --config=CONFIG
                    Specify config file for mic
-k CACHEDIR, --cachedir=CACHEDIR
                    Cache directory to store the downloaded
-o OUTDIR, --outdir=OUTDIR
                    Output directory
-A ARCH, --arch=ARCH
                    Specify repo architecture
--release=RID       Generate a release of RID with all necessary
                    files,when @BUILD_ID@ is contained in kickstart file,
                    it will be replaced by RID
--record-pkgs=RECORD_PKGS
                    Record the info of installed packages, multiple values
                    can be specified which joined by ",", valid values:
                    "name", "content", "license"
--pkgmgr=PKGMGR     Specify backend package manager
--local-pkgs-path=LOCAL_PKGS_PATH
                    Path for local pkgs(rpms) to be installed

Tips: the common options can be normally put before sub-sub command, but also can be after them, such as: :

$ sudo mic cr --outdir output fs test.ks

or :

$ sudo mic cr fs test.ks --outdir output

Tips: if you failed to create armv7* image, the reason may be: qemu/qemu-arm on your host is lower than required, please upgrade qemu/qemu-arm higher than version 0.13.0.

Running 'mic chroot'

Subcommand chroot is used to chroot an image file. Given an image file, you can use mic chroot to chroot inside the image, and then you can do some modification to the image. After you logout, the image file will keep your changes. It's a convenient way to hack your image file.

Sample command: :

$ sudo mic chroot test.img

Running 'mic convert'

Subcommand convert is used for converting an image to another one with different image type. Using convert, you can get your needed image type comfortably. So far converting livecd to liveusb and liveusb to livecd is supported.

Sample command: :

$ sudo mic convert test.iso liveusb

Debug/Verbose Output

When you encounter some errors, and you want to know more about it, please use debug/verbose output to get more details in the process by adding -d/-v. And it's recommended to add -d/--debug or -v/--verbose like: :

$ sudo mic -d cr fs test.ks

Advance Features

Proxy support

proxy setting in mic.conf is not enabled, but you can set proxy in repo section of ks file, example as follows: :

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

Multiple running instances support

mic support running multi-instance, but cache dir can't be shared between instances, so you should specify different cachedir for different instance using --cachedir. Also outdir should be specified to a different directory for each instance using --outdir, example as follows: :

mic cr fs netbook1.ks --cachedir=/var/tmp/cache/mic1 --outdir=out1
mic cr fs netbook2.ks --cachedir=/var/tmp/cache/mic2 --outdir=out2

Known Issues

Bug of latest "syslinux" package

In some new Linux distributions, the "syslinux" package in their official software repositories is the version 4.04. It will cause segment fault for a fatal bug, and mic will failed with syslinux installation errors.

The solution is to install the patched "syslinux" package in MeeGo or Tizen's tools repos, until the official released one being fixed.