Home router

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

Introduction
Building your own router out of old spare parts has many advantages over buying a pre-made canned router by say Linksys. The biggest one by far is control over the connection. The other advantages are left up to your imagination; just about anything can be done in this scenario, it's just a matter of needing it.

This guide will show you how to setup Network Address Translation (NAT) on the router (kernel and iptables), add and configure common services (Domain Name System (DNS) via dnsmasq, dhcp via dhcpcd, ADSL via ppp), and conclude with more elaborate and fun things that can be done (port forwarding, traffic shaping, proxies/caching, etc...).

Before getting started, there's a few basic requirements you must meet. First, you'll need a computer that has at least 2 Network Interface Cards (NICs) in it. Next, you'll need the configuration settings for your internet connection (may include things like IP/DNS/Gateway/username/password). You optionally need a wifi card which supports master mode. If you are buying server ethernet parts, I recommend avoiding NICs with a bypass feature as some of them require proprietary drivers. If you don't have access to that driver, the card will remain in bypass mode permanently and will not be usable. Finally, you'll need a bit of spare time and some Gentoo loving.

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
 * router is running Linux 2.4 or 2.6; you're on your own with 2.0/2.2

Kernel setup (know thyself first)
Your kernel needs to have the drivers running for both your NICs. To see if your cards are already setup, just run. Your output may differ slightly from the following, that's fine. What matters is that the interface shows up at all.

If you do not see your two cards showing up and you're not sure what kind of cards you have, try running. You can get that from. Once you have this information, go into your kernel and add support for the correct drivers.

The next thing you'll need is support for iptables and NAT (and packet shaping if you want). 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 you build the features into the kernel or as a module so long as when the feature is needed, the correct module(s) are loaded (module loading is left to the reader as a fun exercise however).

Intro
There are many ways to connect to the internet so I'll just cover the ones I'm familiar with. That leaves us with ADSL (PPPoE) and cable modems (static/dynamic). If there are other methods out there, feel free to write up a little blurb and e-mail me. Feel free to skip any of the following sections in this chapter that don't apply to you. This chapter is just about 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  and you'll be on your way. Remember how I said you'll need username/password information? Well I wasn't lying so I hope you have it now! Load up in your favorite editor and set it up.

Replace 'vla9h924' in the following example with your username and 'boogie' with your password.

Cable and/or dynamic/static IP
If you have a static IP then you will need a few more details than if you have a dynamic IP. For static users, you will need your IP, gateway, and DNS servers.

Dynamic IP Users:

Static IP Users:

Dynamic and Static Setup:

You should be all set to go now.

Hug the LAN (bring along some friends)
This step is a breeze compared to the previous one. However, if you want to use more than two devices (one for LAN and one for WAN), you will have to set up a Network bridge. If you decide to do so, follow instructions to set up Network bridge. The name of your bridge (default br0) will then replace eth0 for the LAN device in the steps in this wiki. If you have a large number of network devices in your router, you may consider renaming them via udev to make administration easier. Setting up a bridge and renaming devices is completely optional.

If you plan on creating a wifi access point, you will need to make sure your wifi card supports master mode and you will have to set up Hostapd.

DHCP Server
I bet it'd be nice if everyone else in your house could just 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 you should care.

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

We'll use a package called dnsmasq which provides both DHCP and DNS services. For now lets just focus on the DHCP aspect. Note that if you want to run a different DHCP server, you can find another example in the Fun Things chapter. Also, if you wish to tinker with the DHCP server settings, just read the comments in. All the defaults should work fine though.

Now your little router is a bona-fide DHCP server! Plugin those computers and watch them work! With Windows systems you should go into the TCP/IP Properties and select the 'Obtain an IP address automatically' and 'Obtain DNS server address automatically' options. Sometimes the changes aren't instantaneous, so you may have to open a command prompt and run  and. But enough about Windows, let's get back to our 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's 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 our computers understand). For more information about DNS, you can always visit Wikipedia.

Since we're using dnsmasq for our DHCP server, and it includes a DNS server, you've got nothing left to do here! Your little router is already providing DNS to its DHCP clients. Bet you wish everything was this easy ;).

You're welcome to choose other DNS servers if you're more comfortable with them, but the reason dnsmasq is great is because it was designed to do exactly what we want and nothing more. It's a little DNS caching/forwarding server for local networks. We're not looking to provide DNS for our own domain here, just offer simple DNS services to everyone else on our LAN.

NAT (a.k.a. IP-masquerading)
At this point, people on your network can talk to each other and they can look up hostnames via DNS, but they still can't actually connect to the internet. While you may think that's great (more bandwidth for you!), I bet they're not too happy just yet.

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 you have a smaller number of public IP addresses available to you. Typically you are given 1 IP by your ISP, but you want to let your whole house connect to the internet. NAT is the magic that makes this possible. For more information about NAT, you can always visit Wikipedia.

First we flush our current rules

Setup default policies to handle unmatched traffic

Copy and paste these examples ...

Then we lock our services so they only work from the LAN:

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

Drop TCP / UDP packets to privileged ports:

Finally we add the rules for NAT:

Tell the kernel that ip forwarding is OK:

This is so when we boot we don't have to run the rules by hand.

If you have a dynamic internet address you probably want to enable this:

Once you've typed out all of that, the rest of your network should now be able to use the internet as if they were directly connected themselves.

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

Intro
Believe it or not, you're done :). From here on out, I'll cover a bunch of common topics that may interest you. Everything in this chapter is completely optional.

Port Forwarding
Sometimes you would like to be able to host services on a computer behind the router, or just to make your life easier when connecting remotely. Perhaps you want to run a FTP, HTTP, SSH, or VNC server on one or more machines behind your router and be able to connect to them all. The only caveat is that you can only have one service/machine combo per port. For example, there is no practical way to setup three FTP servers behind your router and then try to connect to them all through port 21; only one can be on port 21 while the others would have to be on say port 123 and port 567.

All the port forwarding rules are of the form. Unfortunately, iptables does not accept hostnames when port forwarding. If you are forwarding an external port to the same port on the internal machine, you can 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:

If you want to VNC in to 192.168.0.3, then just 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, we need a way to host ident for both the router and the clients. One such server has been created called.

There are a few other ident servers in portage. Depending on your needs, I would recommend checking out  and.

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

Many people run ntp clients on their computers. Obviously, the more clients in the world, the larger the load the ntp servers need to shoulder. In environments like home networks though, we can help keep the load down on public servers while still providing the proper time to all our computers. As an added bonus, our private updates will be a lot faster for the clients too! All we have to do is run a ntp server on our router that synchronizes itself with the public internet servers while providing the time to the rest of the computers in the network. To get started, simply  on the router and edit  to your liking.

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

Now, on your clients, have them  also. However, we will just run the ntp client so setup is a lot simpler.

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

Rsync Server
For those who run multiple Gentoo boxes on the same lan, you often want to keep from having every machine running  with remote servers. By setting up a local rsync, you save on both your bandwidth and the Gentoo rsync servers' bandwidth. It's pretty simple to do.

Since every Gentoo machine requires rsync, theres no need to emerge it. Edit the default config file, uncomment the   section, and make sure you 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 your clients to sync against the router.

Mail Server
Sometimes it's nice to run your own 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 also don't allow for mail relaying for accounts that aren't 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:

I'm a huge fan of qmail, but you're free to use a different mta :). When you setup e-mail on the hosts in your network, tell them that their SMTP server is 192.168.0.1 and everything should be peachy. You might want to visit the netqmail homepage for more documentation.

Full DHCP Server
Earlier we used dnsmasq to provide DHCP service to all our clients. For most people with a simple small LAN, this is perfect. But you may need something with more features. Thus we turn to a full-featured DHCP server as provided by the ISC folks.

In set   to "eth0".

This is the minimal setup required to replace the dnsmasq DHCP functionality that we used earlier. Speaking of which, you did remember to disable the DHCP features in dnsmasq didn't you? If not, you should do so now (just comment out the  setting in  and restart the service).

Connect Another LAN (or two or three or ...)
Sometimes you have need of connecting the router to another LAN. Maybe you want to hook up a group of friends temporarily, or you're a neat freak and want to section off different groups of computers, or you're just really really bored. Whatever the reasons, extending the router to other LAN networks should be pretty straightforward. In the following examples, I will assume that this new network is connected via a third ethernet card, namely.

First you need to configure the interface. Just take the instructions in this section and replace  with   and   with.

Then you need to tweak dnsmasq to service the new interface. Just edit the file again and append   to DNSMASQ_OPTS; 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. You may want to create another variable, say, to make things easier.

Useful Tools
If you're having trouble getting your computers to communicate, you may way to try out the following tools (they can all be found in the  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 give you any useful info.

The trick is to know where dhcpd is sending its output. Simply browse to and read the log files. Since the exact log file depends on the package you are using as a syslog, try running  to narrow down the possibilities. Chances are you made a typo in your config file. You could also try running  (short for debug / foreground) and debug the error based upon the output.

Incorrect MTU Value
If you experience odd errors (such as not being able to access some webpages while others load fine), you may be having Path MTU Discovery trouble. The quick way to test is to run this iptables command:

This will affect all new connections, so just refresh the website you're having problems with in order to test. 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, you should read Chapter 15 of the Linux Advanced Routing & Traffic Control HOWTO.

If that command does not work for you, you may want to try putting the rule into the mangle table. Simply add  to the command.

Unable to connect two machines directly
If (for whatever reason) you want to connect two machines directly together without a hub or switch, a regular ethernet cable will likely not work, unless you have an Auto MDI/MDI-X (also known as "autosensing") capable network adapter. You will need a different cable called a crossover cable. This Wikipedia page explains the low level details.

Final Notes
I have 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.

Acknowledgements
We would like to thank the following authors and editors for their contributions to this guide: