diff options
Diffstat (limited to 'README.rst')
-rw-r--r-- | README.rst | 251 |
1 files changed, 251 insertions, 0 deletions
diff --git a/README.rst b/README.rst new file mode 100644 index 0000000..1037cd0 --- /dev/null +++ b/README.rst @@ -0,0 +1,251 @@ +====================== + User Guide of **mic** +====================== + +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 (13 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 +your distribution in the list, please install the tool `mic` from source. + + * Debian 5.0 + * Fedora 13 + * Fedora 14 + * Fedora 15 + * openSUSE 11.3 + * openSUSE 11.4 + * Ubuntu 10.04 + * Ubuntu 10.10 + +*Tips*: Debian 6.0 can use the repository of Debian 5.0. + +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 =1 +>>> gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-meego +>>> 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 update + +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 + +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 +================== +A global configure file for mic is provided as `/etc/mic/mic.conf`, where you +can specify the program options statically. +Below is a sample file which is presented in the source: + +>>> cat /etc/mic/mic.conf +>>> [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 +>>> +>>> [convert] +>>> ; settings for convert subcommand +>>> +>>> [chroot] +>>> ; settings for chroot subcommand + +For the further development, there are four sections on mic.conf, and [common] +is for general setting, [create], [convert], and [chroot] are prepared for the +options of mic subcommands: create, convert, and chroot. + +While you only need set [create] section properly for practice, since other +section would be not effective currently. + ++---------+-------------------------------------------------------------------+ +| Option | Usage | ++=========+===================================================================+ +| tmpdir | temporary directory used to put _instroot and others | ++---------+-------------------------------------------------------------------+ +| cachedir| directory where cached repos will reside also downloaded packages | ++---------+-------------------------------------------------------------------+ +| outdir | where your images will reside once they are created | ++---------+-------------------------------------------------------------------+ +| pkgmgr | default backend package manager, including yum/zypp | ++---------+-------------------------------------------------------------------+ +| arch | default repo architecture, like i586, armv7l | ++---------+-------------------------------------------------------------------+ + +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, see following table: + ++------------------+----------------------------------------------------------+ +| Option | Usage | ++==================+==========================================================+ +| -o/--outdir | specify directory where the images reside | ++------------------+----------------------------------------------------------+ +| -a/--arch | specify repo architecture, like i586, armv7l, etc | ++------------------+----------------------------------------------------------+ +| -c/--config | specify the custom configure file for mic | ++------------------+----------------------------------------------------------+ +| --release | generate release package: image, ks, pkg-list, MANIFEST | ++------------------+----------------------------------------------------------+ +| --logfile | specify log file to record the output | ++------------------+----------------------------------------------------------+ +| --local-pkgs-path| directory where local packages can be used when creating | ++------------------+----------------------------------------------------------+ +| --pkgmgr | specify backend package manager | ++------------------+----------------------------------------------------------+ + +*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 + +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 could be like this: + +>>> 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 is given as following: + +>>> 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 as following: + +>>> sudo mic -d cr fs test.ks |