Overview

umibuilder is an easy tool to prepare a memory disk or a Live CD based on Mandrake Linux for OpenBrick and other hardware, such as Sumicom barebone machines. Because it installs Mandrake Linux from the internet with security updates on the fly, it is very easy to keep your installation up-to-date and secure.

umibuilder downloads the latest RPM packages from the internet, installing them into a local directory, removing unnecessary packages and files, customizing the installation, making OS images, formatting your memory disk, and making it bootable. These steps are all automatic, so all you need to do is wait for some minutes to finish.

The idea behind umibuilder is to make it quite easy and fast to test new ideas of embedded appliances and share the knowledge base on the Internet. This is made possible by having a simple configuration file for each target in plain text format. For example, you can define a VPN (virtual private network) appliance target with umibuilder. For this target, you will simply have to create one simple text file which specifies what RPM packages to be installed, what files should be removed, which kernel to be used, and some shell commands to modify the contents dynamically as you wish. In addition, you can optionally have files which are merely copied, so you can add new files and overwrite existing files easily. This is very convenient when you want to replace configuration files statically without modifying official RPM packages.

Also, you can add new hardware support into umibuilder. This is done only by a single text file again. For this, all you have to do is define kernel modules included in initrd and boot devices. Thus it is straightforward to support your own hardware and share the information with others using the umibuilder repository.

You are encouraged to contribute to umibuilder. umibuilder is under the term of GNU General Public License (GPL), so we can develop and share knowledge on making good appliances using umibuilder in Open Source way. The CVS repository, which provides everyone the cutting-edge version of umibuilder, is open to all people who are interested in getting the latest version and adding new targets into umibuilder. We are looking forward to seeing your contribution to the CVS repository of umibuilder.

For non-Mandrake systems

umibuilder currently runs only under Mandrake Linux, because it uses some Mandrake-specific features (such as urpmi) to install Mandrake locally. So it would be very convenient if you have a Mandrake machine.

However, even if you don't have Mandrake running systems, you can still play umibuilder using a chroot environment. chroot is a usual way to make another OS environment in a single system by changing the root directory virtually only in a new shell process. Once you make a chroot environment based on Mandrake Linux in your machine, you can use Mandrake Linux as if you installed it to the whole machine.

For your convenince, a tarball file which can be simply extracted is ready. All you need to do is to extract it in your working directory, and configure a few things. It's quite instant and takes only 5 minutes. Please download the tarball from http://www.nexedi.org/static/mdk-9.2.tar.bz2 .

Please follow these steps to make a chroot environment based on Mandrake Linux in your own OS:

    $ su root
    # tar jxpf mdk-9.2.tar.bz2
    # cd mdk-9.2
    # cp -f /etc/resolv.conf etc
    # mount -t devfs none dev
    # mount -t proc none proc
    # mount -t usbfs none proc/bus/usb
    # chroot .

Because this environment already contains Umigumi, you don't need to download Umigumi separately. You can find Umigumi in the directory /root/umigumi.

Getting the latest version of umibuilder

umibuilder is a part of Umigumi, which is Free Software to simplify the installation and the distribution of operating system installers.

You can get Umigumi from our CVS repository using your favorite web browser. Just click Download tarball and save it somewhere. Then, extract it on your Mandrake Linux machine:

    $ tar zxf umigumi.tar.gz
    $ cd umigumi

That's it!

Note that if you want a specific version (eg : umibuilder for Mandrake 9.2), you have to select this specific branch before clicking "Download tarball".

Quick overview : How to build a system in five minutes

1. Insert a compact flash card or usb key into your machine, without mounting it.
2. Modify config/common.py to adapt the device name to your environment, if necessary.
3. Run umibuilder like this as a superuser (root):

       # ./umibuilder -ba vpn
   

This example makes a VPN setup for OpenBrick.

You can check all supported setup targets by running:

    # ./umibuilder --help

Detailed operation of umibuilder

The five steps of building an image are called in this order when invoking umibuilder with the -ba (all steps) option.

Note : the letter between parenthesis refers to the -b? option of umibuilder.

1. Installing Mandrake Linux packages (p)

   This step will simply use urpmi to install packages from Mandrake Linux into a local directory, thus creating our system from void. The list of packages that will be installed is defined in "config/common.py" and "config/target_name.py". The packages listed in "config/common.py" will be installed first, then the kernel package is installed and finally, packages in "config/target_name.py" are too.

2. Removing unnecessary packages and files (r)

   This step will remove every package and file that isn't usefull in an embedded system, like documentation, in order to save space on the device. The list of packages and file that are to be removed is in "config/target_name.py".

3. Customizing the installation (c)

   This step will copy the customized files that are present "custom/target_name" to the local directory, then it will chroot in the directory to execute the shell commands defined in "config/target_name.py".

4. Creating compressed filessytem and initrd (b)

   This step can do two things :

   • if the live-cd option is set, it will build the iso image,
   • else, it will compress the local directory to a squashfs image and build an initrd filled with the necessary kernel modules, as defined in "hardware/hardware_name.py".
5. Install image files into a disk device and make it bootable for ready to use. (i)

   As the previous one, this step does two things :

   • if the live-cd option is set, it will burn the iso image, using the provided device name. The device name can be a scsi device, or a ide device (if you're using a 2.6 kernel),
   • else, it will clear the compact flash or usb key, create a FAT filesystem onto it, then copy the kernel, initrd, and squashfs image, and finally, it will make the device bootable.

Important options

the commandline format is "umibuilder OPTIONS TARGET".

General options and parameters

• -h, --help : This displays the help message, and lists the available targets and hardwares.
• -n, --dry-run : this option does prevent umibuilder from doing any sensible task, it's usefull for testing purpose.
• -w, --hardware : this option set the hardware on which the system will run, allowing some specific parameters, like necessary kernel modules.
• -b{aprcbi} : this option is required to tell umibuilder what to do, it can be one out of : all stages, prepare local installation, remove packages and files, customize local installation, build compressed image, install image onto device.
• TARGET : Basically this specifies a list of packages that we want to install into the system, but the target also defines the aim of the system (which can be a router or server, a multimedia player, a thin client...)

Live-cd Options

These options are only used if you are building an iso image.

• -l, --live-cd=FILE : this options tells umibuilder that we want to build an iso image, and it also sets the filename of the iso image.
• -d, --burner=DEV : this option specifies what drive to use to burn the image. You must have a writable disk inserted in the burner. DEV can either be a SCSI burner (like "0,1,0") or an ATAPI burner (-like "/dev/hdb"), but ATAPI mode is only supported in 2.6 kernel and recent cdrecord. More about this option can be found in cdrecord manpage.
• -f, --noburnfree : this option allows to disable cdrecord to use the burnfree technology, as it may cause problems with old drives.

How to extend umibuilder

One can easily add new targets and hardwares to umibuilder. In each case, there is only one file to add, unless you want custom files to be copied into the directory before creating the image (eg : files that aren't in packages, or that need to be modified).

The easiest way to create a new target or hardware file is simply to copy an existing one and modify it :

    # cp -a config/vpn.py config/newtarget.py    (use an existing target as a template)
    # vim config/newtarget.py                    (modify the newtarget.py file)
    # ./umibuilder -ba newtarget                 (build an image for the target)

The same can be done to create a new hardware file, in the hardware directory.

Adding a target

To add a new target, you need to add two things : the "config/target_name.py" file that describes your target, and (optionally) the "custom/target_name" tree that allows you to modify files or add new ones to the image.

The "config/target_name.py" file

This file contains eight elements. They mainly list the data that will be processed during the five steps of umibuilder. Here is an example of such a file :

        # The canonical name of this image.
        canonical_name = 'VPN'

        # The directory where the image will be built.
        build_dir = 'mdk-vpn'

        # The kernel package used in the image.
        kernel = '2.6.3.8mdk'

        # The list of packages to be installed.
        package_list = ('basesystem',
                        'devfsd',
                            (...)
                        'ipsec-tools')

        # The list of packages to be removed after installation.
        package_remove_list = ('eject',
                               'urpmi',
                                   (...)
                               'harddrake')

        # The list of files to be removed from the directory (regular expressions).
        file_remove_list = ('^/usr/share/man/.',
                            '^/usr/share/info/.',
                                (...)
                            '^/sbin/lilo$',)

        # The directory which holds custom files to be copied.
        # If this is set to '', nothing will be done.
        custom_dir = 'custom/vpn'

        # The list of shell commands executed to customize the image (launched from a chroot).
        shell_command_list = ('/sbin/chkconfig alsa off',
                              '/sbin/chkconfig sound off',
                                  (...)
                              '/usr/sbin/msec 3')

The custom_dir tree (generally "custom/target_name")

This tree reproduces the structure of the install directory. For example, if you want to overwrite the default /etc/fstab, you'll just have to put your modified file in "custom/target_name/etc/fstab". Else, if you want a script to be present in "/usr/local/bin/", just add it to "custom/target_name/usr/local/bin/" and it will be copied into the image.

Adding a hardware

To support a new hardware, you just need to add a file named "hardware/hardware_name.py". This file contains very few things, the important one is the list "initrd_module_list" which contains every module that need to be loaded by the initrd.

Generally, you WANT to add your hard disk controller driver and partition type modules in here, unless they are statically compiled into the kernel.

If the hardware has multiple hard disks or uses SCSI, you may also need to modify the boot_partition and boot_device parameters accordingly.

Finally, in order to build an image for your new target that will run on your new hardware, just run :

      # ./umibuilder -w newhardware -ba newtarget

After installation notes

For details about the boot process, please have a look at the linuxrc script contained in the initrd.img archive. Basically, what it does is quite simple :

• it loads the modules needed to access the filesystem containing the system images,
• if compression is enabled :
  • if a file named base.new is present, it replaces base.sqh with it (usefull for remote system upgrade),
  • it loads a tmpfs as a new root,
  • it mounts the image in it,
  • it copies files from /etc, /var, /root, /home to the tmpfs, so that they are accessible in read and write mode,
  • it links from /bin, /sbin, /usr, /lib to the tmpfs, so that they are in read-only mode and use very few system memory,
  • if a config.tgz file is present, it is extracted in the tmpfs.

Usefull Note

if you want to overwrite some of the files, without having to rebuild an image, add them to the config.tgz file. Do not forget to run the sync command before rebooting, so that the files are actually written on the medium.

Resources

1. Umigumi homepage http://umigumi.org/
2. Umigumi CVS http://openbrick.org/cgi-bin/viewcvs.cgi/umigumi/
3. Umigumi tarball (including umibuilder) http://openbrick.org/cgi-bin/viewcvs.cgi/umigumi/umigumi.tar.gz?tarball=1
4. Mandrake Linux tarball for chroot environment (including Umigumi) http://www.nexedi.org/static/mdk-9.2.tar.bz2