Gentoo Network Appliance (GNAP) Advanced User Guide
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 :)
Replacing the kernel (and modules) used in GNAP is the simplest of the
advanced tasks. The idea is to use
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:
Code Listing 2.1: Emerge the kernel sources of your choice
# emerge --oneshot =gentoo-sources-2.6.11-r11
You'll also need to create a temporary directory to hold the modules
Code Listing 2.2: Create a temporary directory for modules
# mkdir /home/foo/modules_tmp
Then run genkernel with the right options (kernel source location,
modules temporary directory) to produce a minkernpackage
Code Listing 2.3: Generate a minkernpackage and modulespackage using genkernel
# genkernel --kerneldir=/usr/src/linux-2.6.11-gentoo-r11 --menuconfig \
--minkernpackage=/home/foo/kernel.tar.bz2 --modulespackage=/home/foo/modules.tar.bz2 \
--no-install --module-prefix=/home/foo/modules_tmp all
Alternatively to using --menuconfig, you can specify an existing kernel
configuration file using the --kernel-config option.
Finally you can safely remove the modules temporary directory:
Code Listing 2.4: 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:
Code Listing 2.5: Create a GNAP core with new kernel and modules
# gnap_remaster -k kernel.tar.bz2 -m modules.tar.bz2 -o mynewcore.tar
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
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.
Code Listing 3.1: The gnap_make 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
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:
Code Listing 3.2: GNAP development package installation
# emerge gnap-dev
gnap-dev might only be available in "~x86". Adjust your
/etc/portage/package.keywords file if needed.
This will fetch a reduced portage snapshot and the GNAP seed stage3 file
(which is ~41Mb large). You can set the "minimal" USE flag if you don't want
to download those files, but only install the GNAP development utilities.
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
You should unpack the reference specs directory to make your changes:
Code Listing 3.3: Creating your own specs directory from the reference specs
$ 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
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
(look for the snapshots subdirectory).
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
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).
Tip: Do a first build with a complete snapshot and look in the log files (or
Catalyst temporary directories) to find the list of packages needed in the
build. Then create a new Portage snapshot (or a Portage overlay directory)
containing the extra required ebuilds. Finally, rebuild your extension with
that new Portage.
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:
Code Listing 4.1: Example extensions.conf file
extensions: vi squid
vi/cleanup: /usr/share /usr/bin/elvfmt
squid/packlist: squid squidguard
An extensions stage run is in fact several grp Catalyst stages,
one for each extension you specify.
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):
Code Listing 4.2: Building specified GNAP extensions
# gnap_make -t extensions -p myportage.tar.bz2 -e myspecs
When you run the command, you'll get the following message:
Code Listing 4.3: Warning message when you run the extensions stage only
* 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:
Code Listing 4.4: Forcing a '2005A' timestamp
# 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:
Code Listing 4.5: Using the reduced Portage snapshot and an overlay directory
# 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:
Code Listing 4.6: Make a gnapcore.tar including the two home-made extensions
# gnap_remaster -d ./extensions -e vi -e squid -o gnapcore.tar
Multiple extensions may conflict with each other (especially if built with
different Portage snapshots). Testing of the resulting
GNAP Core file is necessary to ensure everything is working properly.
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:
Code Listing 5.1: Rebuilding the GNAP Release
# gnap_make -t all
By default, it will use the seed stage at
/usr/lib/gnap/gnap-stage3seed.tar.bz2, as installed by the ebuild.
You can use the -s option to change that default location.
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.
You should read the gnap_make man page for information on all the
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
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:
Code Listing 5.2: Debugging by chrooting into Catalyst tmp directories
# 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:
Code Listing 5.3: Calling only two stages of a 20041012 GNAP build
# gnap_make -v 20041012 -t livecd-stage2 -t tarball
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).
You can't use a package.use file in portage_confdir/ to
change the USE flags used when building packages. The system packages (built
during the stage3 step) use the default USE flags from the profile.
The livecd-stage1 packages use directives from packages.conf.
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.
These packages will most likely fail if you remaster the resulting GNAP core
file with a kernel extension containing a different kernel version than the one
used to build the kernel-depending package.
To build pcmcia-cs, you should add the following line to the livecd.conf
Code Listing 6.1: Adding kernel-source depending packages
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
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.
System packages built during stage3 use the default USE flags from the
profile. If you want them to use other USE flags, a simple solution is to
rebuild them during the livecd-stage1 step by readding them to
packages.conf, and set the appropriate USE flags in livecd/use:.
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.
Specs directory reference
This file contains global directives for the GNAP build. This file is
sourced by the gnap_make bash script to initialize environment
||The sub-architecture for the build. It will be used as the value for
the subarch: directive in all Catalyst calls.
||Location of the cascaded Gentoo profile to use in the build. It will be
used as the value for the profile: directive in all Catalyst
||CHOST environment variable setting used during the build.
||CFLAGS environment variable setting used during the build.
||CXXFLAGS environment variable setting used during the build.
||Specification of the kernel sources to use in the GNAP build. It will be
used to set the boot/kernel/gentoo/sources: directive in the
Catalyst livecd-stage2 call. It can define a specific source version,
||List of IP addresses that can be used as distcc build slaves. Those
slaves must run uclibc-powered instances of gcc so you probably can't use
your regular build hosts for this task. You can download LiveCDs to use as
uclibc-compatible build hosts
To enable this, you need to set the "distcc" option in your
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.
||USE flags to set while building the packages.
||List of the Gentoo packages to build. This will also pull any needed
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.
||List of kernel-dependent packages to emerge after kernel build.
||List of packages to remove from the system.
||List of directories to empty (but keep) in the resulting filesystem.
||List of elements to remove in the resulting filesystem.
||List of services that should be started systematically at boot.
||List of services that baselayout and LiveCDs run by default but you
don't want to run.
||File to use as the Catalyst cdtar file. When you upgrade Catalyst
versions, the version number of the cdtar file can change. You must edit the
value of the cdtar directive to match.
There are other parameters which you should probably not change. See the
Catalyst docs for more information about them.
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.
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.
The isolinux directory contains files that will be used as parameters in the
syslinux and isolinux calls used to make GNAP bootable:
||ASCII boot splash to use.
||ISOLINUX configuration file, used when making an ISO file bootable.
||SYSLINUX configuration file, used when making a target disk bootable.
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.
||List of the extensions names to build.
||extensions: boa myext
||List of the Gentoo packages to build in the extension. This will also
pull any needed dependency.
||Specific USE flags to enable while building the extension. This is an
||List of the directories or files to remove from built extension. Keep
GNAP small, remove all unnecessary stuff !
The contents of this document, unless otherwise expressly stated, are licensed under the CC-BY-SA-2.5 license. The Gentoo Name and Logo Usage Guidelines apply.