Gentoo Network Appliance (GNAP)

1.  Introduction to GNAP

What is GNAP ?

The acronym GNAP stands for Gentoo Network APpliance. It's an easy way to build Gentoo-based network appliance systems, ready for use in old PCs or embedded devices without the need for a full installation.

Using GNAP, you can build in a few minutes target systems geared toward network services like routing, firewalling, traffic profiling, VPN and network monitoring, that will run directly from a LiveCD or a disk device (including CompactFlash cards or DiskOnModules).

Specific configuration files are added to the LiveCD or disk to customize its behaviour. Those systems can run stateless, making them easy to restart, and impossible to permanently compromise. They can also save their modified configuration so that they don't need to be rebuilt all the time.

But why GNAP ?

I had a bunch of old PCs with fragile components, and wanted to use them as internal routers and firewalls. I wanted to be able to easily switch PCs in case of failure. Using removable media with a burned-on configuration is the most flexible way I found. When it fails, just put the media on another machine. I started by using LEAF Bering-uClibc floppy-based firewalls but was quickly undermined by problems: media fragility, difficulty to automate creation of floppies and lack of easy extensibility. I switched to LEAF Bering-uClibc CDROM-based configurations, with a web-based automated ISO generation. This solved most of the problems but the extensibility problems remain, and maintaining the web-app was becoming a nightmare.

I finally chose to leverage Gentoo Catalyst power to build custom LiveCDs, solving both the extensibility problem and the non-standard solution maintenance. The idea was to have a generic LiveCD core that I could build once and use everywhere, and burn on the CD a specific configuration overlay to customize the appliance role. This simplifies CD generation as you don't have to go through the whole Catalyst process to customize a specific LiveCD.

Fast to build, easy to maintain up to date

To create a GNAP system, use the provided GNAP Core and create configuration overlays detailing your specific needs. Using the gnap_overlay script, in a few seconds your overlays are combined to the GNAP Core to produce a new LiveCD ISO file. Burn this file to a CD, put it inside an old box (no hard disk or mouse needed), and boot. Alternatively, use the same script to initialize a disk device with a complete bootable filesystem, put the disk in its target environment, and boot.

To completely update a GNAP configuration, just modify your saved overlay and combine it to the latest GNAP Core to produce an updated GNAP system. Reboot the appliance with the new system. You're done.

2.  Documentation

GNAP User Guide

The GNAP User Guide covers everything you need to know to produce and customize GNAP systems. Read it and start using GNAP today !

GNAP Advanced User Guide

The GNAP Advanced User Guide gives information for power users that want to further customize and modify what their GNAP systems can do. You should be familiar with GNAP systems and Gentoo systems in general before reading this guide.

3.  Standard features

• Stripped down system with squashfs compressed filesystem (13Mb)
• hardened-sources 2.6 kernel
• GRsec kernel security patch enabled, including PaX address randomization
• Small footprint executables with PIE/SSP security protection (Gentoo uclibc/x86/hardened profile)
• Features supported as configuration options: Dropbear (SSH server), Shorewall/FireHOL (iptables firewall helpers), traffic control using cbqinit or htbinit, OpenVPN, OpenNTPD (time synchronisation), DNSMasq (DNS relay and DHCP server), RP-PPPOE
• Utilities: Watch network traffic flow using iftop or tcpdump
• Standard Extensions: boa HTTP server, rrdtool graph backend, dash shell

4.  Resources

CVS and Bugs database

GNAP CVS repository can be browsed here.

GNAP uses Gentoo Bugzilla as its bugsystem. Please select the "Gentoo-hosted projects" product and the "GNAP" component when opening a GNAP bug. Alternatively you can click here.

Communication channels

The GNAP project is part of Gentoo Linux's Embedded Project and shares communication channels with it. You can subscribe to the gentoo-embedded@gentoo.org mailing-list or discuss on the #gentoo-embedded official IRC channel.

A GNAP-specific IRC channel has also be created for GNAP users to meet, it is located at #gentoo-gnap on FreeNode.

5.  Changelog

GNAP 2.0 (2006/04/20)

• GNAP now uses Catalyst 2.0 (still at RC phase) for improved results
• gnap_make now supports writing to image files, thanks to hansmi's patch
• Multiple bugfixes and syntax fixes
• Support for scp included
• 3% smaller than the 1.8.2 release thanks to even more fat trimming
• 20060416 portage snapshot compatibility, including multiple security fixes and improvements

GNAP 1.8.2 (2005/10/21)

• Wrong permissions on /var/empty were preventing OpenNTPD to start correctly (bug #105563)
• Even less fat: the dash shell (potentially used to speed up Shorewall parsing) is now an extension, dropbear is built as a multicall binary, and pgawk was removed
• 20051019 portage snapshot compatibility, including openSSL protocol rollback fixes

GNAP 1.8.1 (2005/08/30)

• GNAP 1.8 was suffering from network start problems (bug #102247)
• Wrong permissions on the GNAP system root directory were preventing users other than root from doing anything (bug #103463)
• An error in the GNAP 1.8 ebuild was installing the root_overlay specs subdirectory contents without preserving permissions (bug #102985)
• Extensions were not preserving file ownership and permissions, resulting in failure to operate in some cases (bug #103004)
• GNAP now supports using a .tar.bz2 specs directory, and the -e option now accepts relative paths
• 20050829 portage snapshot compatibility, including openVPN DoS fixes

GNAP 1.8 (2005/08/10)

• New feature to automate configuration changes backup (bug #86241). See the RW_SYNC option in overlay.conf, which replaces the RW_OVERLAY option (deprecated)
• GNAP kernel now supports n_hdlc line discipline to use with synchronous PPP (bug #99115), and vfat filesystems as r/w overlays
• Support to specify account password initialization (chpasswd) and services to start (services_start) as files on the target filesystem
• Support for customizable baudrate on the serial console
• Possibility to use genkernel-built packages (minkernpackage, modulespackage) as GNAP extensions
• gnap_make now starts from Portage snapshot files rather than requiring a Catalyst snapshot stage. A reduced Portage snapshot is now shipped in the gnap-dev package to facilitate GNAP rebuild
• Easier filesystem customization using root_overlay/ in gnap_make
• Support for distcc building, in case you have uclibc-powered systems to use as build partners...
• The rrdtool backend, which was a standard core feature, has been moved to a standard extension. Use gnap_remaster -e rrdtool to rebuild the core with that extension included
• 20050808 portage snapshot compatibility, including zlib security fixes
• GNAP now uses udev as its device manager, anticipating devfs removal in future kernels

GNAP 1.7.1 (2005/06/23)

• Bug #96050: Building extensions with multiple packages was resulting in a failure (patch from BaSS)
• gnap_overlay option -s (use serial console) was not properly supported
• 20050621 portage snapshot compatibility

GNAP 1.7 (2005/05/31)

• Bug #92239: It was impossible to use multiple overlays (-o option) in gnap_overlay (patch from Paul Smith)
• GNAP now supports overlays from a r/w partition at boot time, allowing to save configuration changes back to a floppy or a CF partition. See the RW_OVERLAY option in overlay.conf
• GNAP now supports the concept of "extensions", making it easier to extand GNAP functionality. The gnap-ext package contains standard prebuilt extensions and the new gnap_remaster tool you can use to add extensions to a core. gnap_make has been extended to allow building your own extensions (-t extensions option), without requiring a complete core rebuild
• The boa HTTP server, which was a standard core feature, has been moved to a standard extension. Use gnap_remaster -e boa to rebuild the core with that extension included
• More features, but always slimmer: GNAP 1.7 is 9% smaller than GNAP 1.5
• 20050529 portage snapshot compatibility, including OpenVPN 2.0

GNAP 1.6 (2005/05/17)

• DHCP was in fact not working since a few versions. It's back, and it's automatically used when no /etc/conf.d/net file is overlaid
• In Disk mode, console was only appearing on the serial port. It now appears by default on the default console and can be swicthed to use serial using the new -s option
• gnap_make has a new -o option to specify a portage overlay to use in your snapshots (patch from Nick Lemberger)
• 20050515 portage snapshot compatibility

GNAP 1.5.1 (2005/04/20)

• GNAP is now available in Portage directly
• gnap_overlay disk-mode was not working in 1.5
• gnap_overlay was warning about ISO overwrite even if there wasn't a file with the same name
• 20050419 portage snapshot compatibility

GNAP 1.5 (2005/04/06)

• gnap_make and gnap_overlay have been extensively rewritten for prettier output, better warnings and handling of errors and position-independant parameters support
• Now includes man pages and support for installation from Portage
• Support for multiple overlay directories and using tar.bz2 files (conflets) as overlay sources
• No more "/etc/init.d/serial missing" warnings during boot
• 20050404 portage snapshot, including a dnsmasq security update
• 6.5 % smaller than version 1.2 core file !

GNAP 1.2.1 (2005/03/21)

• hardened-dev-sources-2.6.11-r1 with recent GRSEC security fixes
• gnap_make now creates the necessary temporary directories under /var/tmp/catalyst at first run.

GNAP 1.2 (2005/02/15)

• hardened-dev-sources-2.6.10
• RP-PPPOE is now supported (see USE_PPPOE option in overlay.conf)
• Support for the FireHOL iptables script, in addition to Shorewall (see FW_TYPE option in overlay.conf)
• A minimal firewall is started before the network and the shorewall/firehol script, allowing full protection while still enabling any Shorewall configuration options
• Support for the htbinit traffic control script, in addition to cbqinit (see the USE_TC and TC_TYPE options in overlay.conf)
• iputils (ping, tracepath...), which was unavailable in 1.1, is back !
• gnap_overlay now ignores CVS/ subdirectories, allowing you to use CVS to control versions on your overlay files without bringing unnecessary fat into your GNAP system
• More features, less fat: GNAP 1.2 core is 5% smaller than GNAP 1.1

GNAP 1.1 (2005/01/06)

• Boa (HTTP server) is now supported (see USE_HTTP option in overlay.conf)
• rrdtool can be used to store and graph statistics
• Boot speedups (new baselayout scripts, possibility to use "dash" as the SHOREWALL_SHELL)
• OpenNTPD now support "-s" option in /etc/conf.d/ntpd to set time at startup
• Shorewall is now started before the network for full protection
• OpenSSH has been replaced by Dropbear to make GNAP even smaller despite all those new features
• A README.upgrading file has been added to the gnap-tools to help in upgrading existing configurations

GNAP 1.0 (2004/12/03)

• DNSMasq (DNS relay and DHCP server) is now supported (see USE_DNSDHCP option in overlay.conf)
• GNAP uses recent (~x86) baselayout (supports iproute2-style network configuration)
• Speedups in overlaying (one single pass to add all services)
• 14% smaller (now fits a 16Mb CF card)
• No more "CONFIG_HOTPLUG not enabled" error
• Replaced buggy ntpd by smaller and nicer OpenNTPD

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.