Home router

This document details how to turn an old Gentoo machine into a router for connecting a home network to the internet.

Introduction
Building a personal router out of old spare parts has many advantages over buying a pre-made router built by big companies (Linksys, D-Link, Netgear, etc). The biggest advantage by far is control over the connection. The other advantages can be left up to the user's imagination; just about anything can be done in this scenario, it is simply a matter of need.

This guide will provide instructions on how to setup Network Address Translation (NAT) on a custom router (kernel and iptables), add and configure common services (Domain Name System (DNS) via, dhcp via , ADSL via ), and conclude with some elaborate and fun things custom routers are capable of (port forwarding, traffic shaping, proxies/caching, etc...).

Before getting started, please review the list of basic requirements:
 * 1) A computer that has at least 2 Network Interface Cards (NICs) installed.
 * 2) The configuration settings for an internet connection (may include things like IP/DNS/Gateway/username/password).
 * 3) (Optionally) a wifi card that supports master mode. Master mode is recommended to avoid NICs with a bypass feature since some NICs require proprietary drivers. Without access to the proprietary driver the card will remain in bypass mode permanently and will not be usable.
 * 4) A bit of spare time and Gentoo loving in order to successfully follow this guide and implement a well functioning home router.

The conventions used in this guide are:


 * eth0 - NIC connected to the Local Area Network (LAN) or network bridge consisting of multiple NICs
 * eth1 - NIC connected to the Wide Area Network (WAN)
 * LAN utilizes the private 192.168.0.xxx network
 * Router is hardcoded to the standard 192.168.0.1 IP address
 * Router is running Linux 2.4 or 2.6; other versions of the kernel are not supported by this guide).

Kernel setup (know thyself first)
The kernel needs to have the drivers installed for both NICs present on the system. To see if the cards are already setup, run ifconfig. The output may differ slightly from the following example. What matters is that the interface shows up.

If only one (or none) of the two cards show up try running lspci | grep Ethernet. The lspci utility is part of the package and can be installed by running emerge sys-apps/pciutils. Once the make(s)/model(s) of the NIC(s) has been obtained, configure the kernel with support for the correct drivers. For more information on kernel configuration see the Kernel Configuration Guide.

The next thing needed is support for iptables and NAT (and packet shaping if desired). The following list is split up into always required (*), required only for adsl via PPPoE (a), suggested for everyone (x), and only for shaper (s) features. It does not matter whether the features are built into the kernel or as modules as long as when the feature is needed, the correct module(s) are loaded. For more information on loading modules see the

While using a 2.4.x kernel, the following must be enabled for DHCP:

Intro
There are many ways to connect to the internet, however there are generally only a couple of ways that are used by most of the public. ADSL (PPPoE) and cable modems (static/dynamic) are the two most common methods ISP (Internet Service Providers) provide. If there are other methods available, feel free to add them to this wiki article. Skip any of the following sections in this chapter that are not applicable to the needed use case. This chapter addresses getting the router connected to the internet via eth1.

ADSL and PPPoE
All the fancy PPPoE software that used to be provided by rp-pppoe (Roaring Penguin) has been integrated into the standard PPP package. Simply emerge ppp to install PPPoE. Remember how username and password information was a requirement listed above? Load up in a favorite text editor and configure it accordingly.

Replace " " and "" in the following example with the required username with the password:

Cable and/or dynamic/static IP
If a static IP is necessary then additional configuration details will be required. Static users IP users will need to add the IP address, gateway address, and DNS server addresses.

Dynamic IP Users:

Static IP Users:

Dynamic and Static Setup:

After working through the changes above the system should be ready to continue.

Hug the LAN (bring along some friends)
This step is a breeze compared to the previous one. To use more than two devices (more than the one for LAN and the one for WAN), a Network bridge will need to be setup between all NICs using the LAN. This will allow multiple NICs to be reached by the same IP address.

If a network bridge will be necessary, follow the instructions to set up a Network bridge. The name of the bridge (default br0) will then replace eth0 for the LAN device in the steps in this wiki. If a large number of network devices in the home router, consider renaming them via udev to make administration easier. Setting up a bridge and renaming devices is completely optional but recommended for larger home networks.

When creating a wifi access point make sure the wifi card supports master mode and set up Hostapd.

DHCP Server
It would be nice if everyone in the house could plug their computers into the network and things would just work. No need to remember mind-numbing details or make them stare at confusing configuration screens! Life would be grand, eh? Introducing the Dynamic Host Configuration Protocol (DHCP) and why everyone should care.

DHCP is exactly what its name implies: a protocol that allows dynamic configuration of hosts automatically. Run a DHCP server on the router, give it all the information about the network (valid IPs, DNS servers, gateways, etc...), then when the other hosts start up, they can run a DHCP client to automatically configure themselves. No fuss, no muss! For more information about DHCP, visit Wikipedia's DHCP article.

This HowTo article will use the package which will provide both DHCP and DNS services. For now lets focus on the DHCP aspect. Note: to run a different DHCP server, another example can be found in the Fun Things chapter below. Also, to tinker with the DHCP server settings read the comments in the file.

Setting the interface is very important. Using default dnsmasq settings will open the router to DNS amplification attacks which could create some scary email from the ISP providing the connection. Check to make sure the router is not allowing for DNS amplification attacks by using.

Now the little router is a bona-fide DHCP server! Plugin those computers and watch them work! With Windows systems navigate to the and select the  and  options. Sometimes the changes are not instantaneous, so opening a command prompt and running ipconfig /release and ipconfig /renew might be necessary. But enough about Windows, time to get back to everyone's favorite penguin!

DNS Server
When people want to visit a place on the internet, they remember names, not a string of funky numbers. After all, what is easier to remember, ebay.com or 66.135.192.87? This is where the DNS steps in. DNS servers run all over the internet, and whenever someone wants to visit 'ebay.com', these servers turn 'ebay.com' (what we understand) into '66.135.192.87' (what computers understand). For more information about DNS visit Wikipedia.

Since dnsmasq is being used for the DHCP server, and it includes a DNS server, there is nothing left to do here! The little router is already providing DNS to its DHCP clients. Shouldn't everything be this easy? ;)

It is possible to choose other DNS servers if they are more comfortable to setup. dnsmasq is used in this article because it was designed to do exactly what this guide required. It is a little DNS caching/forwarding server for local networks. The scope of this howto is not to provide DNS for a domain; but it does offer simple DNS services to every user of a home-based LAN.

NAT (a.k.a. IP-masquerading)
At this point, people on the network can talk to each other and look up hostnames via DNS, but they still ca not actually connect to the internet. While the network administrator (the person reading this) may think it is great (more bandwidth for the Admin!), the other users are probably not very happen without an internet connection.

This is where Network Address Translation (NAT) steps in. NAT is a way of connecting multiple computers in a private LAN to the internet when a small number of public IP addresses are available. Typically a home internet user is provided with 1 public IP address by an ISP for the whole house to connect to the internet. NAT is the magic that makes this possible. For more information about NAT, please visit Wikipedia.

After IPtables is installed, flush the current rules:

Setup default policies to handle unmatched traffic:

Copy and paste the following:

The next step locks the services so they only work from the LAN:

(Optional) Allow access to the ssh server from the WAN:

Drop TCP / UDP packets to privileged ports:

Finally add the rules for NAT:

Inform the kernel that IP forwarding is OK:

Instruct the IPtables daemon to save the changes to the rules, then add IPtables to the default runlevel:

For dynamic internet the following setting should be enabled:

Once the above text has been entered the rest of your network should now be able to use the internet as if they were directly connected themselves.

The  option is useful for dial on demand systems or when the ISP gives out dynamic addresses. This works around the problem where a connection is attempted before the internet interface is fully setup. This provides a smoother network experience for users behind the router.

Intro
Believe it or not, it is done! From here on out, some other common topics that may interest will be covered. Everything in the following sections are completely optional.

Port Forwarding
Sometimes users need to be able to host services on a computer behind the router, or need to be able to connect remotely to a computer behind the router. Perhaps a FTP, HTTP, SSH, or VNC server is needed on one or more machines behind the router and outsiders need to connect to them all. The only caveat to Port Forwarding is only one service/machine combo can be established per port. For example, there is no practical way to setup three FTP servers behind the router and connect to them all through port 21; only one system can be on port 21 while the others would need to be on other ports (port 123 and port 567 would be fine options).

All the port forwarding rules are of the form. Unfortunately, iptables does not accept hostnames when port forwarding. When forwarding an external port to the same port on the internal machine, omit the destination port. See the iptables(8) man page for more information.

Forward port 2 to ssh on an internal host:

FTP forwarding to an internal host:

HTTP forwarding to an internal host:

VNC forwarding for internal hosts:

To VNC in to 192.168.0.3, then add ':1' to the router's hostname.

SAMBA forwarding to an internal host (excess ports to cover Windows):

Bittorrent forwarding:

eDonkey/eMule forwarding:

Game Cube Warp Pipe support:

Playstation 2 Online support:

Xbox Live:

Identd (for IRC)
Internet Relay Chat utilizes the ident service pretty heavily. Now that the IRC clients are behind the router, a way to host ident for both the router and the clients is needed. A server has been created for this purpose. It is called.

There are a few other ident servers in the Portage tree. Other viable options are and.

Time Server
Keeping the system time correct is essential to maintaining a healthy system. One of the most common ways of accomplishing this is with the Network Time Protocol (NTP) and the package (which provides implementations for both server and client).

Many users run ntp clients on their computers. Obviously, the more clients in the world, the larger the load ntp servers need to shoulder. In environments like home networks an NTP server can be setup locally to help keep the load down on public servers while still providing the proper time to local systems. As an added bonus, private updates will be a lot faster for the local clients! The setup is simple: run a ntp server on the router that synchronizes itself with the public internet servers while, at the same time, providing the time to the rest of the computers in the network. To get started, simply emerge ntp on the router and edit as desired.

These will allow only ntp clients with an IP address in the 192.168.0.xxx range to use your ntp server.

Now, on the clients, run emerge ntp. By running the ntp client setup is a lot simpler.

In, change the 'pool.ntp.org' server in the  variable to '192.168.0.1'.

Rsync Server
For those who run multiple Gentoo boxes on the same LAN, it is wise to prevent every machine running emerge --sync with remote servers. By setting up a local rsync, both personal bandwidth and the Gentoo rsync servers' bandwidth is saved. It is pretty simple to do.

Since every Gentoo machine requires rsync, there is no need to emerge it. Edit the default config file, uncomment the   section, and make sure to add an   option. All the other defaults should be fine.

Then you need to start the service (again, the defaults are OK).

Only thing left is to set tell the clients to sync against the router.

Mail Server
Sometimes it is nice to run a Simple Mail Transfer Protocol (SMTP) server on the router. You may have your own reason for wanting to do so, but I run it so that the users see mail as being sent instantly and the work of retrying/routing is left up to the mail server. Some ISPs do not allow for mail relaying for accounts that are not part of their network (like Verizon). Also, you can easily throttle the delivery of mail so that large attachments won't seriously lag your connection for half an hour.

Make sure the output of `hostname` is correct

Edit and add an entry like so to the allow section:

When e-mail is setup on the hosts in the network, tell them the SMTP server is 192.168.0.1. You might want to visit the netqmail homepage for more documentation.

Full DHCP Server
Earlier dnsmasq was used to provide DHCP service to all DHCP clients. For most people with a simple small LAN, this is perfect, however there may needs something with more features. Thus a full-featured DHCP server is provided by the ISC folks for users who crave the maximum.

In set   to "eth0".

This is the minimal setup required to replace the dnsmasq DHCP functionality used earlier. The DHCP features in dnsmasq should be disabled? If not, comment out the  setting in  and restart the service.

Connect Another LAN (or two or three or ...)
Sometimes the router must be connected to another LAN. This can be done to hook up a group of friends temporarily or to section off different groups of computers. Whatever the reason, extending the router to other LAN networks should is straightforward. In the following examples, This article presumes that the new network is connected via a third ethernet card, namely.

First configure the interface. Take the instructions in this section and replace  with   and   with.

Tweak dnsmasq to service the new interface. Edit the file again and append   to  ; using -i multiple times is OK. Then edit and add another line like the dhcp-range line in this section, replacing   with. Having multiple dhcp-range lines is OK too.

Finally, see the rules in this section and duplicate the rules that have  in them. Another variable may need to be created, say, to make things easier.

Useful Tools
When having trouble getting computers to communicate try out the following tools (they can all be found in the net-analyzer Portage category):

DHCP Fails To Start
When starting the dhcp init.d script for the first time, it may fail to load but neglect to provide any useful infomation.

The trick is used to know where dhcpd is sending its output. Browse to and read the log files. Since the exact log file depends on the package using a syslog, try running grep -Rl dhcpd /var/log to narrow down the possibilities. Chances are a typo was made in the config file. Another command to try running: dhcpd -d -f (short for debug / foreground). This aids in debugging the errors based upon the output.

Incorrect MTU Value
If odd errors are experienced (such as not being able to access some webpages while others load fine), it might be Path MTU Discovery trouble. The quick way to test for this is to run the following iptables command:

This will affect all new connections; refresh the problematic website in order to test the fix. In case it helps, the standard MTU value for 100mbit ethernet connections is ; this value also applies to PPPoA. For PPPoE connections it is. For more info, read Chapter 15 of the Linux Advanced Routing & Traffic Control HOWTO.

If the above command does not work, consider putting the rule into the mangle table. Simply add -t mangle to the command.

Unable to connect two machines directly
If (for whatever reason) connecting two machines directly together without a hub or switch is required, a regular ethernet cable will likely not work, unless an Auto MDI/MDI-X (also known as "autosensing") capable network adapter is available. A different cable called a crossover cable will be needed for direct NIC to NIC connections. This Wikipedia page explains the low level details.

Final Notes
There are no final notes other than if you experience any troubles with the guide, please contact or file a bug with Gentoo's Bugtracking Website. If you have some interesting bits you think would enhance this guide, by all means send it my way for inclusion.