ELBE Overview

From Wiki-DB
Jump to navigation Jump to search

Changing the subset that is extracted as the root filesystem

Elbe has several methods to select the subset that is packaged as the root-filesystem.

  • The finetuning section allows to remove, copy or move files before the archive or image is generated.
  • The norecommend tag.
  • The initial copy has several modes, which allow to extract very small subsets.
  • The embedded archive.

Finetuning

The finetuning section allows to copy, move and delete files in the target root-filesystem. Additionally it is possible to run commands. Here is an example finetuning section:

  <finetuning>
    <rm>/usr/share/doc</rm>
    <mv path="/var">/var_ro</mv>
    <cp path=/copy/me>/my/name/on/target</mv>
  </finetuning>
Note

The copy, mv, and rm commands operate on full directories.

Advanced Copy

To copy files from the buildimage into the target image, the <command> tag can be used. The current directory is the target.

For example to copy /etc/passwd from the buildenvironment into the target, the following command can be used:

<command>cp /etc/passwd etc/ </command>

Useful directories to trim with finetuning

This section provides some useful directories that can safely be removed, and which generate big space savings:

<finetuning>
        <rm>/usr/share/doc</rm>                         (1)
        <rm>var/cache/apt/archives/*</rm>               (2)
        <rm>var/cache/apt/pkgcache.bin</rm>
        <rm>var/cache/apt/srcpkgcache.bin</rm>
        <rm>var/lib/apt/lists/*_Release</rm>
        <rm>var/lib/apt/lists/*_Packages</rm>
        <rm>var/lib/apt/lists/*_Sources</rm>

        <rm>boot</rm>                                   (3)

        <rm>lib/modules/2.6.32-5-versatile/</rm>        (4)
        <rm>var/cache/man/*</rm>                        (5)
        <rm>opt/elbe</rm>                               (6)
        <rm>var/cache/debconf/*</rm>                    (7)
</finetuning>

(1)

The doc file are not necessary.

(2)

The apt cache can be downloaded, when necessary.

(3)

The boot directory contains the kernel used for the VM. On embedded targets this is generally loaded through u-boot.

(4)

The kernel modules for the standard debian kernel.

(5)

The man page cache

(6)

The full copy mode, will also copy elbe onto the root-filesystem.

(7)

debconf cache is also not necessary

Archive

It’s also possible to include an archive into the xml file, that is unpacked into the target root-filesystem after the finetuning step. This archive must be a bzip2 compressed tar (.tar.bz2) and the following command can be used to embed the archive into the xml file:

elbe chg_archive <xmlfile> archive.tar.bz2

This feature is useful to place custom configuration-files into the final image.

Slimming the root filesystem with the different modes

The copying process has several modes. The mode is configured in the target tag. It needs to be the tag before finetuning.

The following commented example illustrates where the mode is configured.

  <target>
    <hostname>example</hostname>
    <domain>example.com</domain>
    <passwd>foo</passwd>
    <package>
            <tar>nfsroot.tar.gz</tar>
    </package>

    <diet />        (1)

    <norecommend /> (2)

    <finetuning \>
    <pkg-list>
            <pkg>bash</pkg>
    </pkg-list>

  </target>

(1)

The mode is configured at this place, leaving it out, enables the default mode.

(2)

norecommend should be placed here.

norecommend

norecommend disables installation of recommended packages. This is a frequent cause for big root-filesystems. Installed programs will still work, but some functionality requiring external programs might be disabled.

Note

This is not strictly a mode as described in the following paragraphs. It can be combined with any of them, and the following modes are mutually exclusive.

default

The default mode generates a full copy of the build image. This mode is the easiest to use, but its not possible to generate images which have the debian package management removed.

setsel

The setsel mode can be used to generate images which only contain dpkg, and offers a more fine-grained control on which packages are installed.

The recommended usage is as follows:

  • Generate an image in the default mode.
  • Run the image and use aptitude to purge unwanted packages.
  • Maybe even use dpkg to remove apt and aptitude.
  • Then generate the list of selected Packages using dpkg --get-selections > selections.list
  • Transfer this file to the host System.
  • Use elbe setsel <xmlfile> selections.list to import the pkg-list into the xml file.
  • Rebuild using setsel mode.
How it works

The setsel mode works by feeding the pkg list to dpkg --set-selections in the target image copy. It has the advantage that we do not have to cope with some unregistered configuration files.

diet

Diet Mode only copies the files that are referenced in the Package management. It resolves the dependencies so that one does not need to reference library packages.

But

Some packages rely on files generated in the post-inst scripts, which are not tracked by the package management. Work is in progress to execute the post-inst scripts in the target copy, but we are still facing some problems with corner-cases, when dependencies of these scripts get removed in the finetuning.

This also holds for the tighten mode.

tighten

Tighten mode only extracts the files referenced by the packages in pkg-list. No dependencies are resolved. This mode is intended for compatibility with old xml files, do not use in new elbe projects.

XML Reference

This section is a step by step rundown of the arm example.

The xml file starts with the following header, which should always be the same:

<ns0:RootFileSystem xmlns:ns0="https://www.linutronix.de/projects/Elbe"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     created="2009-05-20T08:50:56" revision="4"
     xsi:schemaLocation="https://www.linutronix.de/projects/Elbe dbsfed.xsd">

After this Header follows the project description.

        <project>
                <name>ARMexample</name>
                <version>08.15</version>
                <mirror>
                        <primary_host>debian.tu-bs.de</primary_host>    (1)
                        <primary_path>/debian</primary_path>
                        <primary_proto>http</primary_proto>
                        <url-list>                                      (2)
                                <url>
                                        <binary>http://192.168.1.2/custom/pkgs ./</binary>
                                </url>
                        </url-list>

                </mirror>
                <noauth />                                              (3)
                <suite>squeeze</suite>                                  (4)

(1)

The mirror tag contains primary_host, primary_path and primary_proto. It describes the debian mirror used.

(2)

The url-list can contain additional binary package sources.

(3)

The noauth tag can be used to disable authentication, when custom unsigned packages, are supposed to be installed.

(4)

The suite also controls which kernel and initrd is downloaded with the elbe dl_kernel` command. It also selects the distribution codename used from the primary mirror.
Note

We did not close the project tag yet.

The following section describes the virtual machine in which the debian installer will run, and where we want to build our custom packages in.

                <buildimage>
                        <arch>armel</arch>                              (1)
                        <size>20G</size>                                (2)
                        <mem>256</mem>                                  (3)
                        <interpreter>qemu-system-arm</interpreter>      (4)
                        <console>ttyAMA0,115200n1</console>             (5)
                        <machine>versatilepb</machine>                  (6)
                        <NIC>
                                <model>smc91c111</model>
                                <MAC>de:ad:be:ef:be:05</MAC>
                        </NIC>
                        <portforwarding>                                (7)
                                <forward>
                                        <proto>tcp</proto>
                                        <buildenv>22</buildenv>
                                        <host>5022</host>
                                </forward>
                        </portforwarding>
                        <pkg-list>                                      (8)
                        </pkg-list>
                </buildimage>
        </project>

(1)

arch is the debian architecture of the target.

(2)

size is the size of the hard-disk image.

(3)

mem controls the amount of RAM that is allocated to the virtual machine.

(4)

The interpreter is either qemu-system-<arch> or qemu-kvm. Usage of kvm is usually only possible, when the target is x86.

(5)

The console line needs special attention, because it is different on different emulation targets.

(6)

The machine tag contains the -machine parameter, that is provided to qemu.

(7)

portforwarding of network server ports from the virtual machine to the host. This example forwards the ssh port to port 5022 on the host.

(8)

This is the package list of buildimage.
Note

Our advice is to only change the sizes of hard-disk and RAM, if thats necessary. The other values come correctly configured in the example files.

We provide examples for arm, powerpc and x86.

        <target>
                <hostname>myARM</hostname>                      (1)
                <domain>tec.linutronix.de</domain>              (2)
                <passwd>foo</passwd>                            (3)
                <console>ttyS0,115200</console>
                <package>
                        <tar>
                                <name>nfsroot.tar.gz</name>     (4)
                        </tar>
                </package>
                <finetuning>                                    (5)
                </finetuning>
                <pkg-list>                                      (6)
                        <pkg>build-essential</pkg>
                        <pkg>bash</pkg>
                        <pkg>less</pkg>
                        <pkg>git</pkg>
                        <pkg>debhelper</pkg>
                        <pkg>nfs-common</pkg>
                        <pkg>openssh-server</pkg>
                </pkg-list>
        </target>

(1)

The hostname

(2)

and domainname

(3)

This is the root password of the machine.

(4)

This describes, that the resulting rootfilesystem, shall be generated as nfsroot.tar.gz

(5)

Empty finetuning section. Format of this section was already explained above.

(6)

The Packages list resides here.

Building ubi images

Elbe also has the ability to generate ubi images, including different partitions and mountpoints. Lets look at an example target section.

<target>
        <hostname>myARM</hostname>
        <domain>tec.linutronix.de</domain>
        <passwd>foo</passwd>
        <console>ttyS0,115200</console>

        <images>
                <mtd>
                        <name>linux.img</name>                  (1)
                        <nr>0</nr>
                        <size>60MB</size>
                        <ubivg>
                                <label>nand</label>
                                <miniosize>2048</miniosize>     (2)
                                <maxlogicaleraseblockcount>1533</maxlogicaleraseblockcount>
                                <logicaleraseblocksize>126976</logicaleraseblocksize>
                                <physicaleraseblocksize>128KiB</physicaleraseblocksize>
                                <ubi>                           (3)
                                        <type>static</type>
                                        <label>kernel</label>
                                        <id>0</id>
                                        <size>4MiB</size>
                                        <binary>/boot/vmlinuz-2.6.33.9-rt31</binary>
                                </ubi>
                                <ubi>
                                        <type>dynamic</type>
                                        <label>rfs</label>
                                        <id>1</id>
                                        <size>26MiB</size>
                                </ubi>
                                <ubi>
                                        <type>dynamic</type>
                                        <label>data</label>
                                        <id>2</id>
                                        <size>30MiB</size>
                                </ubi>
                        </ubivg>
                </mtd>
        </images>

        <fstab>                                                 (4)
                <bylabel>                                       (5)
                        <label>data</label>
                        <mountpoint>/opt</mountpoint>
                        <fs>
                                <type>ubifs</type>
                                <mkfs>-x lzo</mkfs>
                        </fs>
                        <options>rw</options>
                </bylabel>
                <bylabel>
                        <label>rfs</label>
                        <mountpoint>/</mountpoint>
                        <fs>
                                <type>ubifs</type>
                                <mkfs>-x lzo</mkfs>
                        </fs>
                        <options>ro</options>
                </bylabel>
                <bydev>                                         (6)
</font>'''proc'''<font color="#0000FF">
                        <mountpoint>/proc</mountpoint>
                        <fs>
                                <type>proc</type>
                        </fs>
                </bydev>
                <bydev>
</font>'''sysfs'''<font color="#0000FF">
                        <mountpoint>/sys</mountpoint>
                        <fs>
                                <type>sysfs</type>
                        </fs>
                </bydev>
                <bydev>
</font>'''tmpfs'''<font color="#0000FF">
                        <mountpoint>/tmp</mountpoint>
                        <fs>
                                <type>tmpfs</type>
                        </fs>
                        <options>size=2M</options>
                </bydev>
                <bydev>
</font>'''tmpfs'''<font color="#0000FF">
                        <mountpoint>/var/log</mountpoint>
                        <fs>
                                <type>tmpfs</type>
                        </fs>
                        <options>size=4M</options>
                </bydev>
                <bydev>
</font>'''tmpfs'''<font color="#0000FF">
                        <mountpoint>/var/run</mountpoint>
                        <fs>
                                <type>tmpfs</type>
                        </fs>
                        <options>size=2M</options>
                </bydev>
        </fstab>

        <finetuning>
        </finetuning>
        <pkg-list>
                <pkg>dash</pkg>
        </pkg-list>
</target>

(1)

This specifies an mtd image with 60MB size whose filename is linux.img

(2)

Parameters for the ubi tools, describing the NAND geometry.

(3)

Specification of ubi volumes.

(4)

Because we are dealing with a root-filesystem split into more than one partition, we need to specify the fstab, so that everything can be copied into the right place.

(5)

Normal partition entries are by label.

(6)

Since we now create the target fstab ourselves, we also need to include the entries for /proc, /sys etc. These can be generated with bydev nodes.