Gentoo Network Appliance (GNAP) Advanced User Guide

1.  Audience

This guide is for GNAP users that want to go deeper and customize what GNAP does even more. If you want other software available than what is in the standard GNAP core and extensions, or if you want to make GNAP use another kernel or even another Gentoo profile, this guide is for you.

GNAP is very easy to use. But changing GNAP to match your specific needs is more complicated. You need to be familiar with Gentoo systems, packages and profiles, as well as understand the basic concepts of Gentoo Catalyst, the tool used to create GNAP elements. Building complete system images from scratch also takes a lot of time and computing power. You've been warned :)

2.  Kernel extensions

Replacing the kernel (and modules) used in GNAP is the simplest of the advanced tasks. The idea is to use genkernel to create a minkernpackage (which contains the kernel and initramfs) and a modulespackage (which contains the modules) for specific kernel sources and configuration. Then you can use gnap_remaster to create a new GNAP core file with the new kernel and modules in.

Build kernel extensions

First you should emerge the kernel sources you want to use:

# emerge --oneshot =gentoo-sources-2.6.11-r11

You'll also need to create a temporary directory to hold the modules installation:

# mkdir /home/foo/modules_tmp

Then run genkernel with the right options (kernel source location, modules temporary directory) to produce a minkernpackage and modulespackage:

# genkernel --kerneldir=/usr/src/linux-2.6.11-gentoo-r11 --menuconfig \
  --minkernpackage=/home/foo/kernel.tar.bz2 --modulespackage=modules.tar.bz2 \
  --no-install --module-prefix=/home/foo/modules_tmp all

Finally you can safely remove the modules temporary directory:

# rm -rf /home/foo/modules_tmp

Remastering a GNAP core with a kernel extension

Once you have a minkernpackage and/or a modulespackage, you can easily use gnap_remaster to create a GNAP core file where the kernel and/or modules you built replace the original ones. This is done through the use of the -k (for minkernpackages) and -m (for modulespackages) options:

# gnap_remaster -k kernel.tar.bz2 -m modules.tar.bz2 -o mynewcore.tar

3.  Introduction to gnap_make

How it works

Creating new GNAP elements is done through the use of the gnap_make script, which is a high-level wrapper for catalyst calls. Catalyst is the powerful tool used to automate the building of installation tarballs (the stage files) and LiveCDs constituting a Gentoo release. Being familiar with how Catalyst works will help you understand how gnap_make works.

The gnap_make script takes a GNAP seed stage tarball and a specs directory or .tar.bz2 file (containing build directives), and can produce new GNAP core files, GNAP basefs files and extensions:

Figure 3.1: How gnap_make works

The gnap_make stages and the stage seed

The gnap_make script goes through several steps in order to complete building elements. Some of those steps correspond to Catalyst stages, but others are purely GNAP-specific stages.

seed stage file -> stage3 -> livecd-stage1 -> livecd-stage2 -> tarball -> GNAP Core and basefs files
stage3 stage file -> extensions -> extension files

If stage3 completed but livecd-stage1 failed, you can restart at livecd-stage1 and just execute the remaining stages.

In all cases you need a seed stage file. You can download an official uclibc-hardened stage2 tarball from the latest Gentoo release. Alternatively, GNAP provides a stage3 stage file that can be used for building GNAP Core and basefs files, but also extensions. If you run both the stage3 and the extensions steps in the same gnap_make run, GNAP will use your stage3 build results to serve as a seed stage for the extensions step.

Prerequisites

You'll need root rights to run gnap_make, but also specific features enabled in your host system kernel, so that gnap_make can play with virtual filesystems. Your host kernel will need (builtin or as modules):

• Support for loopback devices (CONFIG_BLK_DEV_LOOP)
• Support for ISO9660 filesystems (CONFIG_ISO9660_FS)

Installing the GNAP development package

The GNAP development package is now available through Portage:

# emerge gnap-dev

The specs directory

The specs directory is a directory or .tar.bz2 file containing several files describing how GNAP should be built. After installation of gnap-dev, the reference specs directory used to build the current GNAP core is available at /usr/lib/gnap/gnap-specs.tar.bz2.

The specs directory contains some files that will be used as part of Catalyst specfiles (packages.conf will be injected in livecd-stage1 specfile, livecd.conf in livecd-stage2 specfile), but also GNAP-specific files and directories.

You should unpack the reference specs directory to make your changes:

$ mkdir myspecs
$ tar jxvf /usr/lib/gnap/gnap-specs.tar.bz2 -C myspecs

The portage snapshot

The portage snapshot is the .tar.bz2 file containing the Portage tree to use to build the GNAP core packages and/or extensions.

Since changes to the Portage tree can result in GNAP incompabilities, the GNAP development package provides a reduced Portage snapshot file containing everything needed to rebuild the current GNAP core (but not more !). It can serve as a safe base upon which to build your own Portage tree snapshot (by adding new files). You will find it installed as /usr/lib/gnap/gnap-portagesnapshot.tar.bz2.

Alternatively, if you're brave and don't fear compilation failures and unexpected side-effects, you can build your own snapshot file from your Portage tree, or download a complete one from one of the Gentoo mirrors (look for the snapshots subdirectory).

4.  Building your own extensions

How extension building works

An extension is a compressed tarball, containing one or more packages, bringing extra functionality to a GNAP system. You must tell gnap_make what those packages are, and with which USE flags to build them. gnap_make will then pull all required dependencies, build everything and make a single tarball out of them all.

One of GNAP challenges is to stay the smallest possible, and packages usually bring in lots of unnecessary doc or example files, and you might not need all the binary files... One of your jobs as extension designer is to determine what can be safely removed from the extension tarball after build and tell it to gnap_make, which will do the cleanup automatically at the end of the build.

You will need to provide a Portage snapshot containing all necessary packages, or specify a Portage overlay directory that contains everything needed to build your extensions. It may not be easy to determine what are the packages you need to add to your snapshot, and therefore it might be easier to go with a complete Portage snapshot. Just remember that using a Portage snapshot different from the one used to build the GNAP core and seed stage3 file might bring its own problems (pull extra dependencies for example).

The extensions.conf specfile

The extensions.conf file in your specs directory is the place where you configure what extensions must be built during the extensions stage, and what must be done for each separate extension to build. The following extensions.conf file, for example, specifies to build two extensions, one called vi with the elvis vi-clone, and one called squid with everything needed to use squid and squidguard:

extensions: vi squid

vi/packlist: elvis
vi/cleanup: /usr/share /usr/bin/elvfmt

squid/packlist: squid squidguard
squid/useflags: zero-penalty-hit
squid/cleanup: /usr/share

Build extensions using gnap_make

Once the extensions.conf file and portage snapshot to use are ready, you should use gnap_make to call the extensions build stage on your modified specs directory (as root):

# gnap_make -t extensions -p myportage.tar.bz2 -e myspecs

When you run the command, you'll get the following message:

 * The extensions target was selected without the stage3 target.
 * Should I use the seed stage as stage3 result ? [N]:

In complete builds, gnap_make uses the results of the stage3 step as a seed stage for the extensions step. If you run the extensions step alone, gnap_make proposes to use the GNAP seed stage3 file instead. You should answer "Y" to that question.

By default, this will timestamp your build with the current date. To use another timestamp, use the -v option:

# gnap_make -t extensions -p myportage.tar.bz2 -e myspecs -v 2005A

If you don't specify the -p option, gnap_make will use the reduced Portage snapshot provided in the gnap-dev package. In all cases, you can use the -o option to specify a Portage overlay directory to use:

# gnap_make -t extensions -o myportageoverlay/ -e myspecs

Both commands should build two files: a gnapext_vi-YYYYMMDD.tbz2 file containing the vi extension and a gnapext_squid-YYYYMMDD.tbz2 file for the squid one.

Use your own extensions with gnap_remaster

To use home-made extensions with gnap_remaster, you will need to tell it in which directory the extensions files can be found (by default it will look into the /usr/lib/gnap/extensions directory), and the names of the extensions to use. For example, if the extensions can be found in the ./extensions directory:

# gnap_remaster -d ./extensions -e vi -e squid -o gnapcore.tar

5.  Using gnap_make to produce GNAP elements

Rebuilding the current GNAP release

You can easily use gnap_make to run all stages, using the reference specs directory and the provided reduced Portage snapshot:

# gnap_make -t all

This will take a very long time to complete, and should produce nice new GNAP elements (core file, basefs file and extension files) with a version stamp based on current date.

In case of failure: debugging tips

When the build fails, you should read your build logfiles. The .out log contains standard output from the catalyst commands, while the file .err log contains their standard error. By looking at the last hundred lines, you should be able to tell what's wrong.

Usually the build fails because a package fails to compile. It's quite easy to introduce changes into an ebuild that will break existing uclibc compatibility, so that's something that frequently happens when working on a Portage snapshot different than the reduced Portage snapshot provided with GNAP.

The Catalyst temporary directories (usually in /var/tmp/catalyst) contain the builds results and work directories that can be useful in determining what happened. You can for example chroot into the work directory corresponding to the stage that failed and try to see why a specific compilation failed by running the emerge command in it:

# chroot /var/tmp/catalyst/tmp/gnap/stage3-x86-20050802 /bin/bash
# emerge -a packagefailing

If you just want to re-run some final stages, you might want to specify which stages gnap_make should call. You can do this by providing the GNAP version timestamp to reuse (-v) and the stage names you want to run (stage3, livecd-stage1, livecd-stage2, tarball and extensions) as -t parameters:

# gnap_make -v 20041012 -t livecd-stage2 -t tarball

6.  To infinity, and beyond: Changing your GNAP core

Rebuilding the already-provided GNAP core with the reference specs directory and reduced portage snapshot file is not very useful, since you should end up with the exact same GNAP elements as the official release ones. Here is how you can change things to go further.

Changing Portage snapshot and configuration

You can change the Portage tree contents and the Portage configuration files. This is useful to include new or masked versions of packages.

We saw in the previous chapters how to specify alternate Portage snapshot files and Portage overlay directories, by using the -p and -o options in gnap_make. In the portage_confdir/ subdirectory of your specs directory you can change the Portage configuration files usually found in /etc/portage, including package.keywords (to enable ~x86 masked packages) and package.mask (to mask specific versions of packages).

Adding Kernel-depending packages

Some packages in the Gentoo tree rely on sources corresponding to the target kernel to compile, for example the pcmcia-cs package. Such packages will fail if you try to build them as extensions with errors like "/usr/src/linux directory not found". The only way to workaround this is to specify those packages in the livecd.conf specs file and run the livecd-stage2 step in order to build them in the GNAP core directly.

To build pcmcia-cs, you should add the following line to the livecd.conf file:

boot/kernel/gentoo/packages: pcmcia-cs

During the livecd-stage2 step, once the kernel is compiled, catalyst will emerge these kernel-depending packages.

Changing the Kernel

Rather than using kernel extensions, you can build the kernel you want directly in. To that effect, you should modify the KERNEL_SOURCES option in the common.conf specs file to point to the right sources name and fill the kernel.config specs file with the kernel configuration to use.

Changing installed packages and startup services

Rather than using the extensions system, you can also build the packages you want installed on the GNAP system directly in. To achieve that result, you should edit packages.conf specs file and add names to the livecd/packages: directive.

You can set the (common) USE flags you want to use while building the packages by setting the appropriate livecd/use: value in packages.conf.

You may want to change the services started by default, this is done by modifying the livecd/rcadd: and livecd/rcdel: directives in the livecd.conf specs file.

When emerge installs a package, it pulls all the packages required as build dependencies. You may not need them on the resulting system. The livecd.conf specs file contains a livecd/unmerge: directive listing the packages that should be removed before the filesystem is finalized. Remember to keep GNAP small, so make use of those features.

Changing filesystem contents

It is possible to add or remove arbitrary files on the GNAP filesystem, bypassing the ebuild system for a more precise control of what's present on the GNAP target system.

The contents of the root_overlay/ specs subdirectory are copied to the resulting filesystem, without any restriction on directories you can write to. This is useful to add arbitrary files to the system.

The livecd.conf specs file contains filesystem cleanup rules that you can use to get rid of slack installed on your system. The livecd/empty: directive lists directories that should be emptied, while the livecd/rm: directive lists elements to remove.

If you have to do more precise changes to the filesystem, you can modify the fsscript script located in your specs directory. This script is executed on the resulting filesystem and can update its contents.

Changing build profile

The compilation flags used to build GNAP can be changed by editing the CFLAGS and CXXFLAGS options in the common.conf specs file.

If you feel even more brave, you can try to change the Gentoo profile used to build the GNAP elements (by default, an x86 subarch with uclibc/x86/hardened profile). This is done by editing the the SUBARCH, PROFILE and CHOST options in common.conf.

I want more !

If you've gone that far in changing GNAP and want more, you should probably use directly Catalyst, which is much more generic and powerful than GNAP is. gnap_make is just a shell wrapper around catalyst to make the basic tasks a little easier, and simplification comes with a price you pay in flexibility.

7.  Specs directory reference

common.conf

This file contains global directives for the GNAP build. This file is sourced by the gnap_make bash script to initialize environment variables.

packages.conf

This file contains directives that will be included in the livecd-stage1 Catalyst specfile. It is used in GNAP to list the packages to add to the minimal stage3 system, and the USE flags to use while building them.

livecd.conf

This file contains directives that will be included in the livecd-stage2 Catalyst specfile. It is used in GNAP to list kernel-depending packages, packages to unmerge, cleanup rules and services to start by default.

root_overlay directory

This directory contains files that will be copied on the resulting filesystem during livecd-stage2. It is used as the value for the livecd/root_overlay: directive in the livecd-stage2 Catalyst specfile.

fsscript

This file is an executable bash script that will be run in livecd-stage2 to update the resulting filesystem. It is used as the value for the livecd/fsscript: directive in the livecd-stage2 Catalyst specfile.

isolinux directory

The isolinux directory contains files that will be used as parameters in the syslinux and isolinux calls used to make GNAP bootable:

extensions.conf

This file contains the list of extensions to build, with directives on how to build and package each of them. It will be used to build specfiles for Catalyst grp stages.

The contents of this document are licensed under the Creative Commons - Attribution / Share Alike license.