Gentoo Network Appliance (GNAP) User Guide

1.  GNAP basics

Goal

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 or DOM):

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.

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 to gnap_overlay.

2.  Your first GNAP LiveCD

Installing GNAP

GNAP is available through Gentoo Portage. Simply emerge it using (as root):

# emerge gnap

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 configuration.

First of all, create a directory that will serve as the root for the overlay directory, and create the etc/, etc/conf.d/ and etc/firehol/ subdirectories:

$ 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 111.222.111.47 (gateway 111.222.111.254) 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:

# Use iproute2-style configuration
modules=( "iproute2" )

# The external interface
ipaddr_eth0=( "111.222.111.47/24" )
iproute_eth0=( "default via 111.222.111.254" )

# 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:

version 5
interface eth0 internet
interface eth1 lan
router lan2internet inface eth1 outface eth0
  masquerade
  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:

# Use two network cards
NBCARDS=2

# Start the 'firehol' firewall script at startup
USE_FW=yes
FW_TYPE=firehol

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 the command:

$ 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:

$ 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.

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.

3.  More customization

Overlay maintenance

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:

$ 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:

$ 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.

Internationalization

Two options in overlay.conf control the timezone (default being UTC) and the keymap (default being 'us' keyboard layout) used on the target system:

• TIMEZONE: If you want to use another timezone than UTC, you should check this page 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.

# Use Central European Time (UTC+1) with usual Summer Time rules
TIMEZONE=CET-1CEST

# Use a french keyboard layout
KEYMAP=fr

Network configuration

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 script.
• 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 resolution information.
• etc/conf.d/hostname: This file can be specified to give a specific hostname to the target. The etc/hosts file should be adapted accordingly.

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 htbinit, 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 in /usr/sbin/htbinit.

GNAP services

GNAP offers several standard services. The first is the Dropbear 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 DnsMasq 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 file:

# Start iptables and boa at startup
START_SERVICES="iptables boa"

iptables 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:

DROPBEAR_OPTS="-s"

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:

RW_SYNC=/dev/fd0

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:

* 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 subsequent backups.

# 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 command:

# rw-sync.sh -w

For more help on rw-sync.sh, just run it without any option to show the help contents.

4.  Disk output

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 risk !

Media preparation

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.

# 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 following command:

# dd if=/usr/lib/gnap/mbr/mbr.bin of=/dev/sdb bs=512 count=1

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 is "hda1".

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:

# gnap_overlay -d /dev/sdb1 -r hda1 -o myoverlay/

Specific options

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.

# 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.

# gnap_overlay -l myimagefile.img -r hda1 -o myoverlay/ -m -s 19200

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:

# gnap_overlay -L newimagefile.img -S 14 -r hda1 -o myoverlay/

5.  Using extensions

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.

# emerge gnap-ext

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 extensions added:

# gnap_remaster -e boa -o mynewcore.tar

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:

$ gnap_overlay -g mynewcore.tar -i myfirewall.iso -o myoverlay/

6.  GNAP Reference

overlay.conf

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:

gnap_overlay and gnap_remaster options

Please refer to the man pages for information on all the options available in these commands:

$ 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.