Gentoo Network Appliance (GNAP) User Guide
The goal is to use your current Gentoo system (called the host)
to build a LiveCD or a disk with a bootable Network Appliance system, complete
with customized configuration files, that you can use to boot another system
(called the target).
GNAP provides a prebuilt system image, called the GNAP core. You can
modify the default configuration of this image by providing new configuration
files that will be overlaid over the system image during the target boot.
The gnap_overlay script takes a GNAP core tarball and one or more
overlay sources and either produces a bootable LiveCD .iso file, or
writes a bootable filesystem to a disk device (typically a CompactFlash card
Figure 1.1: How gnap_overlay works
The overlay sources
There are two types of overlay sources you can use with
gnap_overlay: directories and conflet files.
Overlay directories are just directories containing files that will be copied
over the root filesystem during the target boot. The root of the directory
corresponds to the root of the target filesystem, so it typically contains
an etc/ subdirectory containing files that will be copied over
the /etc target directory.
Conflet files are just .tar.bz2 compressed tarballs containing an
overlay directory. They usually contain typical reusable configuration changes,
making it easier to maintain several configurations.
At the moment only the /etc, /var, /tmp,
/home, /root and /mnt target directories
are writable on the target at boot time, meaning your overlay sources cannot
specify files outside these directories.
The overlay.conf file
The overlay.conf file controls general target customization options,
like localization options and which features should be enabled on your GNAP
target. It must be present either in an overlay source (as
etc/overlay.conf) or directly specified as a -c parameter
Your first GNAP LiveCD
GNAP is available through Gentoo Portage. Simply emerge it using (as root):
Code Listing 2.1: GNAP installation
# emerge gnap
GNAP might only be available in "~x86". Adjust your
/etc/portage/package.keywords file if needed.
This will fetch the GNAP core file, which is usually quite large (~14Mb). You
can set the "minimal" USE flag if you don't want to download the GNAP core,
but only install the GNAP tools.
Users of other flavors of Linux should refer to the
Using GNAP on non-Gentoo hosts guide.
Preparing your overlays and overlay.conf
For this tutorial, we'll use GNAP to produce a bootable Firewall LiveCD that
will filter traffic and do NAT for a small LAN. We'll need to activate these
features in overlay.conf and overlay files for the network and firewall
You don't need root rights to produce a GNAP LiveCD.
First of all, create a directory that will serve as the root for the overlay
directory, and create the etc/, etc/conf.d/ and
Code Listing 2.2: Preparing overlay directories
$ mkdir myoverlay
$ mkdir myoverlay/etc
$ mkdir myoverlay/etc/conf.d
$ mkdir myoverlay/etc/firehol
Then we create the network configuration file (etc/conf.d/net),
for an external address of 184.108.40.206 (gateway 220.127.116.11) and a LAN
on 192.168.1.*. This file follows the Gentoo syntax described in the
/etc/conf.d/net.example file on your host system:
Code Listing 2.3: myoverlay/etc/conf.d/net contents
# Use iproute2-style configuration
modules=( "iproute2" )
# The external interface
ipaddr_eth0=( "18.104.22.168/24" )
iproute_eth0=( "default via 22.214.171.124" )
# The internal interface
ipaddr_eth1=( "192.168.1.254/24" )
Then we create the firehol configuration file that we'll use as a firewall,
allowing all traffic out of the LAN but no traffic in:
Code Listing 2.4: myoverlay/etc/firehol/firehol.conf contents
interface eth0 internet
interface eth1 lan
router lan2internet inface eth1 outface eth0
route all accept
Finally, we need to write an overlay.conf file to tell GNAP that it
will use two network cards, and start a firehol firewall script at startup:
Code Listing 2.5: myoverlay/etc/overlay.conf contents
# Use two network cards
# Start the 'firehol' firewall script at startup
Generating the .iso file, burning it to CD-R
The next step is to use gnap_overlay to combine the
myoverlay overlay directory and the GNAP core to produce a
myfirewall.iso file containing the target LiveCD image. This is done using
Code Listing 2.6: Creating the .iso file
$ gnap_overlay -i myfirewall.iso -o myoverlay/
You should burn the resulting myfirewall.iso image onto a CD-R (or better, a
CD-RW) using your favorite CD burning tool, for example:
Code Listing 2.7: Burning the .iso file, YMMV
$ cdrecord -v -eject speed=4 dev=/dev/hdc myfirewall.iso
Testing the resulting GNAP system
Once the CD-R is ready, take it to the target system and use it to boot.
Low-end systems are OK, GNAP should boot successfully on 486 systems with as
low as 32 Mb RAM.
The BIOS of the target system should of course be configured to boot on CD-ROM.
During boot, you can see the GNAP-specific messages, while the GNAP initscript
(found as /etc/init.d/overlay on the target system) takes care of
overlaying files and processing the overlay.conf options.
If the configuration is not OK, you can change the contents of your
myoverlay/ directory, rebuild an .iso image, burn it again, and
restart the target system with the new LiveCD.
In the previous section, we used a single overlay source (the
myoverlay/ directory), making it difficult to manage multiple
system configurations which share common features. gnap_overlay accepts
multiple -o options, so you can use multiple directories and
conflet files to form a single configuration:
Code Listing 3.1: Using multiple overlay sources
$ gnap_overlay -i myfirewall.iso -o common/ -o specific/ -o mypublickey.tbz2
Rather than including an etc/overlay.conf file in one of your
overlay sources, it is possible to specify the name of a file to use as
overlay.conf in your GNAP system, using the -c option:
Code Listing 3.2: Using a separate overlay.conf file
$ gnap_overlay -i myfirewall.iso -c firewall.conf -o overlay2/
To keep track of configuration changes, it is possible to use CVS directly
on the overlay directories. gnap_overlay will automatically ignore
the CVS control directories and not copy them onto the target system.
Two options in overlay.conf control the timezone (default being
UTC) and the keymap (default being 'us' keyboard layout) used on the target
- TIMEZONE: If you want to use another timezone than UTC, you should check
to determine the appropriate uclibc-compliant timezone code.
- KEYMAP: If you want to log on locally, you might need to change the default
keyboard layout ('us') to something more appropriate. There is a complete
tree of keymaps in /usr/share/keymaps to choose from.
Code Listing 3.3: overlay.conf internationalization options example
# Use Central European Time (UTC+1) with usual Summer Time rules
# Use a french keyboard layout
We already know about the NBCARDS option in overlay.conf, which
specifies how many network cards should be started, and that we need to provide
an etc/conf.d/net file in our overlays to give the static network
configuration details. Here are the other options and typical overlay files
that you can use in further detailing the network configuration:
- IP_RELAY: Should be set to yes if you want to relay IP between your network
interfaces. Useful if you want to run a gateway without a firewall
- NTPSERVER: Allows to specify the name of an NTP server to use as a time
source to maintain correct time on the target system.
- USE_PPPOE: Indicates that the rp-pppoe should be started during boot.
etc/resolv.conf: This file should contain the DNS
configuration for the system.
etc/hosts: Complementary or alternatively to
etc/resolv.conf, this file will contain static hostnames
etc/conf.d/hostname: This file can be specified to give a
specific hostname to the target. The etc/hosts file should be
If you don't specify an etc/conf.d/net configuration, the system
will use DHCP to get the network configuration for the missing interfaces.
Firewall, traffic control
Enabling a firewall script is controlled by the USE_FW=yes option. By default,
GNAP will use Shorewall, an
excellent and very complete iptables helper. You can set the FW_TYPE=firehol
option to switch to Firehol,
a simpler yet efficient script.
If you use Shorewall, you should overlay files in the etc/shorewall
directory to customize its behavior, in particular you should have to change
the interfaces, zones, policy and
shorewall.conf files. If you decide to use Firehol, you'll have
to customize the etc/firehol/firehol.conf file.
You can enable a traffic control script using the USE_TC=yes option. By default,
GNAP will use cbqinit,
a simple but sometimes inefficient traffic control helper. You can set the
TC_TYPE=htbinit option to switch to
a more complex but more efficient script.
If you use cbqinit, you should overlay files in the etc/cbqinit
directory to customize its behavior, following the instructions given in
/usr/sbin/cbqinit. If you decide to use htbinit, you'll have
to create files in etc/htbinit following the instructions given
GNAP offers several standard services. The first is the
SSH server, which allows remote control of the GNAP system.
You enable it using the USE_SSH=yes option. Dropbear behaviour is
controlled using the etc/conf.d/dropbear file. You might
want to overlay prebuilt RSA/DSS keys for the server in
etc/dropbear (so that they are not rebuilt after each boot).
Another service is the
DNS cache / DHCP server, which provides DNS resolution and DHCP
capabilities to a LAN. You enable it using the USE_DNSDHCP=yes option, and
you configure it through the etc/dnsmasq.conf file.
Another service that GNAP provides by default is the
OpenVPN VPN solution. This is a simple
but full-featured VPN solution that will help you securely bridge LANs over
insecure networks. You enable it using the USE_VPN=yes option, in which case
you should overlay files in the etc/openvpn directory
with the desired OpenVPN configuration.
Finally, you can specify extra services to start when GNAP is booted.
There are two ways to do this: using the START_SERVICES option in
overlay.conf or using the etc/gnap/start_services
Code Listing 3.4: Specifying the iptables and boa services using overlay.conf
# Start iptables and boa at startup
Code Listing 3.5: etc/gnap/start_services contents, will start iptables and boa
Accounts and passwords
GNAP runs happily as a blackbox appliance by default. However, you might want
to be able to log onto it. By default, it doesn't define user accounts, and the
root account has an impossible password, making it impossible to log in. There
are several ways to change this behaviour:
You can set an empty root password, useful in test configurations for example,
using the EMPTY_ROOTPASS=yes option.
The most secure way to access the GNAP box is to run the Dropbear SSH server
in public key mode. You will need to configure Dropbear to disable password
logins (in etc/conf.d/dropbear) and put your own public key
to the root/.ssh/authorized_keys file:
Code Listing 3.6: etc/conf.d/dropbear contents to disable password auth
The /usr/lib/gnap/examples/conflets/dropbear_nopasswd.tbz2 file,
installed during the GNAP installation, is a conflet file containing
the necessary etc/conf.d/dropbear overlay file.
If you still want to change passwords for system users, you can do it by
overlaying a etc/gnap/chpasswd file containing
username:cryptedpassword lines that will be fed to chpasswd -e during
boot. See man chpasswd for details on the format of that file.
Support for saving live configuration changes
One problem you will have with GNAP systems using evolving configurations
(like firewalls) is that all live config changes will be lost at the next
reboot. One solution is to report all changes to the host system overlay
directories and be sure to burn a new CD-R with the new configuration before
the next reboot, but it's not very practical. Another solution is to use a
read/write partition and use the RW_SYNC system to backup the changes and
have them taken into account at next reboot automatically.
To enable this system, you should add the RW_SYNC option to your
overlay.conf file, pointing to the r/w partition you want to use.
GNAP supports FAT and ext2 partitions:
Code Listing 3.7: RW_SYNC value to backup to floppy disk
During the first boot, when the option is activated but no backup file is
present on the RW_SYNC partition yet, you'll get the following error during
the target system boot, which you can safely ignore:
Code Listing 3.8: First-time RW_SYNC safe errors
* Sync rw-sync changes to /dev/fd0 ...
* Missing gnap_sav.tgz or gnap_md5.sum file : aborting [ !! ]
Once the RW_SYNC option is enabled, you can use the rw-sync.sh utility
on the GNAP target system to specify which files to save. You only need to
specify the files once so that they are added to the rw-sync.cfg file for
Don't forget to add the /etc/rw-sync.cfg file to the backup list
so that it is restored at next reboot !
Code Listing 3.9: Specifying files and directories to backup
# rw-sync.sh -a /etc/rw-sync.cfg
# rw-sync.sh -a /etc/shorewall/
Then you can backup the files anytime after a change using the following
Code Listing 3.10: Backup to the r/w partition
# rw-sync.sh -w
For more help on rw-sync.sh, just run it without any option to show
the help contents.
Objectives and requirements
In the previous chapters, we used GNAP to produce a bootable LiveCD with
a customized network appliance system on it. We can also use GNAP to
initialize a disk device with a customized network appliance filesystem,
ready to be plugged in a target system and booted.
This mode of operation can be used to initialize hard disks that can be
plugged in low-end systems, but is especially useful for small device
targets like Soekris boxes
which can boot from a CompactFlash card, or other embedded systems
that will boot from an IDE bus (Disk-On-Module, Disk-On-Chip...).
For this mode of operation, you'll need to run gnap_overlay with
root rights to be able to manipulate the disk device at low-level. It is
also slightly more complicated and dangerous to run, so use at your own
Before you run gnap_overlay for the first time on a device, you need
to prepare the target media. You should plug the hard disk, CF card or other
medium you want to use on the host system and determine what is the plugged
device's name (system log might be useful here). You don't need to mount it !
For the remaining examples we'll suppose the target disk is available on
the host system as /dev/sdb.
If not already done, you need to partition the device. The partition where
GNAP will install the filesystem should be marked "active" and be large
enough to handle GNAP. In doubt, create a single partition of 16Mb,
and activate it.
Code Listing 4.1: Partitioning the /dev/sdb target disk
# fdisk /dev/sdb
The disk should also have a Master Boot Record installed, which will allow the
system to boot on it. If you're unsure, you can install an MBR using the
Code Listing 4.2: Installing MBR on /dev/sdb target disk
# dd if=/usr/lib/gnap/mbr/mbr.bin of=/dev/sdb bs=512 count=1
You only need to prepare the media once, you can run multiple
gnap_overlay commands on it once it has been prepared.
Using gnap_overlay to write to disk
In disk mode, you need to pass two options to gnap_overlay. One is
the complete name of the target disk partition as seen on the host
system (option -d), the other is the short name of the
target disk partition as seen on the target system at boot (option
-r). The distinction being quite important, here is an example.
Let's say you want to install a GNAP system on a CF card, to use to boot a
Soekris box. You plug it in the host system (the one you will run
gnap_overlay on), it is recognized as /dev/sdb.
You create a single partition on it, /dev/sdb1. So in this
example, the complete name of the target disk partition as seen on the
host system is /dev/sdb1.
On the other hand, you know, from testing or specs, that the Soekris box will
recognize a CF card plugged in it as /dev/hda. So the short name
of the target disk partition as seen on the target system at boot
To initialize a disk with a GNAP configuration, you just have to replace the
-i option (used to build a LiveCD iso file) by the correct -d
and -r options:
Code Listing 4.3: Initializing the /dev/sdb1 partition
# gnap_overlay -d /dev/sdb1 -r hda1 -o myoverlay/
The target disk partition (-d option) should not be mounted.
gnap_overlay will mount it when it needs it.
Two options might be useful in an embedded target situation. One is the
-m optional parameter you can use to tell GNAP to cache in memory the
filesystem once at startup to avoid multiple read access that can wear the
device (or be too slow).
The other is the -s parameter you can use
to tell GNAP to send the console to the serial port, at the specified baudrate.
This is especially useful for serial-port only devices like the Soekris boxes.
Code Listing 4.4: Reduce read access and use a 19200 baud serial console
# gnap_overlay -d /dev/sdb1 -r hda1 -o myoverlay/ -m -s 19200
Writing to disk image files
You might want to write to a disk image file rather than writing directly
a disk. This is made possible by the -l option: it allows to specify
the name of the disk image file to write to. Options from disk mode (except
the -d option) apply to image mode.
Code Listing 4.5: Write to the preexisting myimagefile.img disk image file
# gnap_overlay -l myimagefile.img -r hda1 -o myoverlay/ -m -s 19200
Only one partition is supported on the disk image file !
Alternatively you can ask GNAP to create the disk image file using the
-L option. The image file is by default 15 Mb long, you can specify an
alternative size using the -S option:
Code Listing 4.6: Write to a new disk image file named newimagefile.img
# gnap_overlay -L newimagefile.img -S 14 -r hda1 -o myoverlay/
Extensions and remastering
You might want to add features to your GNAP network appliance system. The
simplest way to do it is to use extensions, which are small software
packages adding functionality to a GNAP system.
Extensions are .tar.bz2 compressed files with standardized names.
They are installed in standard in /usr/lib/gnap/extensions and
are named gnapext_[name].tbz2.
The boa extension, for example, is in fact
the /usr/lib/gnap/extensions/gnapext_boa.tbz2 file.
The gnap_remaster tool combines a GNAP base filesystem file, an
existing GNAP core file and extensions to create a new GNAP core file which
will contain the extensions you choose. Then, you can use this extended GNAP
core file with gnap_overlay to create specific systems making use of
the extra functionality.
Figure 5.1: How gnap_remaster works
Installing the GNAP extension package
The GNAP extension package, which installs the gnap_remaster tool,
the GNAP basefs file and standard extensions (everything needed to play with
extensions), is available through Portage. You should install the version
corresponding to your GNAP package version.
Code Listing 5.1: GNAP extension package installation
# emerge gnap-ext
gnap-ext might only be available in "~x86". Adjust your
/etc/portage/package.keywords file if needed.
This will fetch a GNAP basefs file, which is usually quite large (~9Mb). You
can set the "minimal" USE flag if you don't want to download the basefs and
the standard extension pack, but only install the gnap_remaster tool.
Remastering a GNAP core with extensions
You should call gnap_remaster with the needed extensions names, as root.
This will build a mynewcore.tar remastered core file with the requested
Code Listing 5.2: Remastering the current GNAP core, adding the boa extension
# gnap_remaster -e boa -o mynewcore.tar
You must use the extensions name, not the filename. You can use multiple
-e options at the same time.
Using gnap_overlay on a specific GNAP core
It's easy to make gnap_overlay use your remastered core file instead
of the standard one. Just use the -g option:
Code Listing 5.3: Make gnap_overlay use the remastered core file
$ gnap_overlay -g mynewcore.tar -i myfirewall.iso -o myoverlay/
gnap_remaster can also be used on modules you build yourself:
extensions, minkernpackages and modulespackages. Please see the
GNAP Advanced User Guide
for more information about these features.
||If set to yes, the root password will be empty and everyone with
console access will be able to log as root. This should be used
mainly for testing purposes.
||Set to shorewall or firehol depending on the firewall
system you want to use.
||Should IP relaying be active at startup ?
||Console keymap value.
||Number of connected network cards you want to start.
||The name of the NTP server to use as a time synchronisation source.
||empty (do not synchronise time using NTP)
||Location of a read/write partition to use to save the modified
configuration files using rw_sync.sh
||empty (do not use the RW_SYNC backup system)
||List of the extra services you want to run as startup. This is
useful to start services from extensions (like boa).
||empty (no extra service)
||Set to cbqinit or htbinit depending on the traffic
control system you want to use.
||The uclibc-compliant timezone code.
||Set to yes to have the DNSMasq daemon run at startup.
no (do not run)
||Set to yes to have a firewall script run at startup.
See FW_TYPE option.
no (do not run)
||Set to yes to have the rp-pppoe daemon run at startup.
no (do not run)
||Set to yes to have the Dropbear daemon run at startup.
no (do not run)
||Set to yes to have a traffic control script run at startup.
See the TC_TYPE option.
no (do not run)
||Set to yes to have the OpenVPN daemon run at startup.
no (do not run)
GNAP-specific files to overlay on target system
Other than etc/overlay.conf, GNAP uses several additional files
on the target system, here is their list:
||This is the rw_sync.sh control file, listing the files and directories
that should be backed up. You should probably use rw_sync.sh to edit
||Contains a list of (whitespace-separated) service names that the target
system should additionally start at boot. Those services must exist as
/etc/init.d scripts on the target system !
||Contains a file that will be fed to chpasswd -e at boot to
initialize passwords on the system. It should contain a list of
gnap_overlay and gnap_remaster options
Please refer to the man pages for information on all the options available
in these commands:
Code Listing 6.1: getting more information about gnap_overlay or gnap_remaster
$ man gnap_overlay
$ man gnap_remaster
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.