LDP/LDP/howto/docbook/Linksys-Blue-Box-Router-HOWTO.xml

<?xml version="1.0"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" 
    "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
<!ENTITY howto         "http://www.tldp.org/HOWTO/">
<!ENTITY mini-howto    "http://www.tldp.org/HOWTO/mini/">
<!ENTITY home          "http://www.catb.org/~esr/">
]>

<article id="index">
<articleinfo>
<title>Linksys Blue Box Router HOWTO</title>

<author>
  <firstname>Eric</firstname>
  <othername>Steven</othername>
  <surname>Raymond</surname>
  <affiliation>
    <orgname><ulink url="&home;">Thyrsus Enterprises</ulink></orgname> 
  </affiliation>
</author>

<revhistory>
   <revision>
      <revnumber>1.2</revnumber>
      <date>2003-04-29</date>
      <authorinitials>esr</authorinitials>
       <revremark>
	 Typo corrections.
       </revremark>
   </revision>
   <revision>
      <revnumber>1.1</revnumber>
      <date>2003-04-25</date>
      <authorinitials>esr</authorinitials>
       <revremark>
	 Added link to the linksysmon project.  More configuration tips.
       </revremark>
   </revision>
   <revision>
      <revnumber>1.0</revnumber>
      <date>2003-04-09</date>
      <authorinitials>esr</authorinitials>
       <revremark>
	 Initial release, reviewed by LDP.
       </revremark>
   </revision>
</revhistory>

<abstract>

<para>Linksys makes a line of cheap, ubiquitous router/firewall boxes
(models BEFSR41 and up) well-suited for use on a home DSL connection and
popular among Linux hackers.  This HOWTO gives hints and tips for managing
Linksys routers from a Linux system, including the firmware upgrade
procedure.</para>

</abstract>
</articleinfo>

<sect1 id="introduction"><title>Introduction</title>

<sect2 id="purpose"><title>Why this document?</title>

<para>Linksys makes a line of cheap, ubiquitous router/firewall boxes
well-suited for use on a home DSL connection and popular among Linux
hackers.  This HOWTO gives hints and tips for managing Linksys routers
from a Linux system.</para>

<para>The specific recipes described here are derived from long experience
with a BEFSR41, the 4-port router/firewall box.  I have also configured a
BEFW11S4v2, the 4-port router with 80211b wireless, and it behaves so
similarly to the BEFSR41 that I suspect they're using the firmware images
mostly generated from common source code &mdash; in fact, it wouldn't
surprise me if it were the same firmware, doing port tests to figure out
what pieces of the user interface it should enable.  The firmware and web
interfaces on all these blue boxes are very similar, and most of the advice
should generalize.</para>
</sect2>

<sect2 id="newversions"><title>New versions of this document</title>

<para>You can also view the latest version of this HOWTO on the World Wide Web
via the URL <ulink url="&howto;Linksys-Blue-Box-Router-HOWTO.html">
&howto;Linksys-Blue-Box-HOWTO.html</ulink>.</para>
</sect2>
    
<sect2 id="license"><title>License and Copyright</title>

<para>Copyright (c) 2003, Eric S. Raymond.</para>

<para>Permission is granted to copy, distribute and/or modify this document
      under the terms of the GNU Free Documentation License, Version 1.2
      or any later version published by the Free Software Foundation;
      with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
      A copy of the license is located at <ulink url="http://www.gnu.org/copyleft/fdl.html">www.gnu.org/copyleft/fdl.html</ulink>.</para>

<para>Feel free to mail any questions or comments about this HOWTO to Eric
S. Raymond, <email>esr@snark.thyrsus.com</email>. But please don't ask me
to troubleshoot your general networking problems; if you do, I'll just
ignore you.</para>

</sect2>
</sect1>

<sect1 id="howandwhen"><title>How and where to deploy</title>

<para>The Linksys BEFSR41 and its higher-end siblings are designed to
be used as gateway boxes on a home Ethernet.  Typically, you'll hook
one up to a DSL or cable modem, which will automatically switch into
bridge mode and simply pass packets between your ISP's router and the
Linksys box.</para>

<para>If you want to use a general-purpose PC running Linux as a
firewall, have fun &mdash; but these little boxes are more efficient.
The nicest thing about Linksys boxes is that they run out of
firmware and are too stupid to be cracked.  Also, they don't generate
fan noise or heat.  Finally, they have no moving parts, so you can
expect a good long mean time between failures.</para>

<para>At minimum, your Linksys box will do the following things for you:</para>

<orderedlist>
<listitem>
<para><emphasis>Act as an Ethernet router.</emphasis>  You can plug all
your lines and hubs and hosts into it to exchange packets even when
your outside link is down.</para>
</listitem>
<listitem>
<para><emphasis>Act as a smart gateway.</emphasis>  When you configure
the Linksys with a public static IP address (or tell it to grab a
dynamic IP address from your ISP at startup time), it will gateway
between hosts on your private network and the Internet, performing all
the IP masquerading and address translation required to route your
traffic.</para>
</listitem>
<listitem>
<para><emphasis>Firewall your connection.</emphasis>  You can tell it to
block out all but the minimum sevice channels you need.  You can
specify separately, for each service, to which of your internal machines 
the traffic should be routed.</para>
</listitem>
</orderedlist>

<para>Some of the higher-end versions will do extras like
virtual private networking and wireless.</para>

<para>I give my Linksys box the standard private-network gateway
address, 192.168.1.1.  I then give all my boxes 192.168.1.x addresses
and tell them the Linksys is their gateway.  Everything works.</para>

<para>But these boxes are cheap, low-end devices.  They have some
limitations.  It has been reported that some key features, including
DMZ and port forwarding, are disabled if you have a dynamic address
rather than a static (at least, this was true of the BEFSR41 in 2000;
later firmware upgrades might be more capable).</para>

</sect1>
<sect1 id="lostmanual"><title>Lost the manual?</title>

<para>If you've lost the manual, or acquired a secondhand unit that doesn't
have one with it, never fear.  Under the Help tab there are links to the
PDF and to the Linksys corporate website.</para>

</sect1>
<sect1 id="confighints"><title>Configuration hints</title>

<para>For security and performance, do these things:</para>

<para>First, make sure <guibutton>AOL Parental Controls</guibutton>
(under <menuchoice><guimenu>Security</guimenu></menuchoice>) is turned off
(off is the default); otherwise the Linksys won't pass packets for your
Unix box at all.</para>

<para>For security, make sure the DMZ host feature is disabled (under
<menuchoice><guimenu>Advanced</guimenu><guimenuitem>DMZ
Host</guimenuitem></menuchoice>).  Port forward specific services instead,
and as few of those as you can get away with.  A good minimum set is 22
(ssh), and 80 (http).  If you want to receive mail add 25.  If you need to
serve DNS queries, add 53.</para>
    
<para>Disable Universal Plug and Play (under
<menuchoice><guimenu>Password</guimenu></menuchoice>).  There is a radio
button for this under the <quote>Password</quote>
tab. <acronym>UPnP</acronym> is a notorious security hole in Windows, and
up to at least firmware version 1.44 there was a lot of Web scuttlebutt
that the Linksys implementation is flaky.  While this won't affect
operating systems written by <emphasis>competent</emphasis> people, there
is no point in having traffic from a bunch of script-kiddie probes even
reach your network.</para>

<para>If you want to run a server, you also need to make sure stateful
packet inspection is off &mdash; this feature restricts incoming packets to
those associated with an outbound connection and is intended for heightened
security on client-only systems.  On the
<menuchoice><guimenu>Filters</guimenu></menuchoice> page, make sure
<guilabel>SPI</guilabel> is off.  If you don't see a radiobutton for SPI,
relax &mdash; the feature isn't present in all versions of the
firmware, and in fact was removed in 1.43 for stability reasons.</para>

<para>To speed up sending of outbound mail, go to
<menuchoice><guimenu>Advanced</guimenu><guimenuitem>Forwarding</guimenuitem></menuchoice>
and click the <guibutton>Port Triggering</guibutton> button.  Specify 25,25
a the trigger port range and 113,113 as its incoming-port range.  What this
will do is punch a temporary hole through the firewall during each outbound
SMTP session that will allow the receiving system to get to port 113, which
is identd service.  This will enable the receiving SMTP to do an identd
check on your connection rather than timing out.</para>

<para>Some bug was introduced in firmware revision 1.42.3 that broke
traceroute.  This was fixed in 1.42.6; just upgrade to the latest
version.</para>

</sect1>
<sect1 id="Software"><title>Software</title>

<para>There is a Unix utility called <application>linksysmon</application> that
talks with these boxes via SNMP.  There is a <ulink
url="http://woogie.net/linksysmon/">Linksysmon project site</ulink>.</para>

<para>Linksysmon is a tool for monitoring Linksys BEFSR41 and BEFSR11
firewalls under Linux and other Unix-like operating systems.  It accepts
log messages from the Linksys, and logs the messages to
<filename>/var/log/linksys.log</filename>. It handles the standard activity
logs, as well as the <quote>secret</quote> extended logging, and can handle
logs from multiple firewalls. When using extended logging, it can detect
external IP address changes (if you are using either DHCP or PPPOE) and can
call an external program to process the change.</para>

</sect1>
<sect1 id="ts-tips"><title>Troubleshooting tips</title>

<sect2 id="catatonia"><title>Occasional catatonia and epilepsy</title>

<para>Linksys boxes freeze up occasionally (once every few months) and
have to be power-cycled.  Suspect this is happening if your outside
Web access suddenly stops working; ping the Linksys box to check.</para>

<para>These catatonic episodes may be related to dirty power; at least,
they seems to happen more frequently in association with electrical storms
and brownouts.  If you think this has happened, just pull the power
connector out of the back and plug it back in.  The Linksys should reboot
itself within 30 seconds or so.</para>

<para>There is a more severe failure mode that I've only seen once; it's
more like an epileptic seizure than catatonia, and involves strange blink
patterns on the Link, Collision, and 100Mbit diagnostic lights (the 100Mbit
light should not normally ever blink).</para>

<para>If this happens, power-cycling the Linksys won't suffice; you'll have
to hard-reset the thing.  Some versions (like the BEFSR41) have a reset pin
that you poke with a paperclip end through a small hole in the front panel
labeled Reset.  Some versions (like the BEFW11S4) have a reset button on
the back.  You have to hold these down for about thirty seconds to
hard-reset the nonvolatile RAM.  This will lose your configuration
settings.</para>

</sect2>
<sect2 id="mozillaquirks"><title>Mozilla interface quirks under 1.38 and earlier firmware</title>

<para>Linksys blue boxes have a webserver embedded in their firmware.
The normal way to administer one is to point a browser at its IP
address on your network.  You program the box by filling out HTML
forms.</para>

<para>This is a nice bit of design that neatly avoids having OS-specific
client software.  But some older versions of the webserver firmware have a
quirk that interacts with a bug in Mozilla (at least at release 1.0.1) to
make the interface almost unusable.  Fortunately, the recovery procedure is
trivial.  This bug was known to be present as late as 1.40, and also
interfered with Netscape; it is absent in 1.44 and a good reason to
upgrade.</para>

<para>The symptom you're likely to see is a broken-image icon at the
upper left hand corner of each page.  The broken image is a series of
file-folder tabs for an image map.  That image map is how you get to
the other web pages.</para>

<para>You can recover by right-clicking on the broken-image icon.
Select <quote>View Image</quote>, then back out. This will build the
image map correctly.</para>

<para>You will almost always have to do this on the first page,
but it often won't trigger on later page loads.</para>

<para>Here's what's going on.  Mozilla tries to stream multiple
concurrent requests at the webservers it talks to in order to speed up
page loading.  The dimwitted little firmware webserver in the Linksys is
only single-threaded and doesn't handle concurrent requests.  So there's
a race condition.  When you hit the window just right, you get an 
aborted request and a broken graphic.</para>

<para>Most other browsers are immune to this problem.  Konqueror
doesn't trigger it.  Neither does Internet Explorer.</para>
</sect2>

</sect1>
<sect1 id="upgradingfirmware"><title>Upgrading the firmware</title>

<para>Before you upgrade, here is a tip the documentation does not mention:
disconnect all the patch cables except the one from the machine you are
using to upgrade the box.  Handling a lot of other network traffic while
the firmware load is gong on can corrupt the firmware.</para>

<para>There are three ways you can upgrade your Linksys firmware.</para>

<para>One is to click the <quote>Upgrade firmware</quote> link on the
help page.  Unfortunately, this required Java in the browser under
the 1.38 firmware.  That has changed under 1.44.  It looks as though 
you can now fill in the field that says <quote> Please select a file
to upgrade:</quote>, click the Upgrade button, and have the right
thing happen.</para> 

<para>Another way is to use one of Linkys's firmware-upgrade floppy images
from their website.  This requires that you boot Windows or use
WINE.</para>

<para>The third way is to use <application>tftp</application>.  This is how
I did it.  There is a tftp client included with Red Hat Linux.  To upgrade
your firmware this way, do the following steps:</para>

<procedure>
<step>
<para><emphasis>Capture a copy of your settings.</emphasis> The 
firmware upgrade may wipe some of them.  Older versions nuked 
everything back to factory defaults; newer versions preserve
your basic settings but clear some advanced ones.</para>
</step>
<step>
<para><emphasis>Download a copy of the new firmware.</emphasis> You should
find it at <ulink
url="http://www.linksys.com/download/firmware.asp?dlid=1"> Firmware
Upgrades for your Linksys Products</ulink> on the Linksys site.  Note that
what you get may well be marked <quote>For Windows Users</quote> and be a
zip archive.  Open it in a scratch directory, because it will rudely create
several Windows files wherever you unpack it.  The file you need will be
called <filename>CODE.BIN</filename>.</para>
</step>
<step>
<para><emphasis>Disable the router password</emphasis> Note that every
attempt I made to do this with Mozilla failed (both under 1.38 and
1.44).  Konqueror worked fine.  Go to the Password tab, backspace over
both sets of asterisks until both the Password and Confirm fields are
blank, and click Apply.</para>
</step>
<step>
<para><emphasis>Cross your fingers and load the firmware</emphasis>
The command session you want will to see will look something like
this, with your router's IP address substituted for
192.168.1.1:</para>

<screen>
tftp 192.168.1.1
tftp&gt; binary
tftp&gt; put code.bin
Sent 386048 bytes in 10.3 seconds
tftp&gt;
</screen>

<para>Don't panic if the client hangs for a bit before returning and
<emphasis>do not abort the transfer</emphasis>.  The command is 
writing to firmware, and the Linksys hasn't got much of a brain.
Wait for it to finish.</para>
</step>
<step>
<para><emphasis>Re-enable your router password and other
settings.</emphasis> You'll be able to tell the upgrade worked because
the firmware version number has changed.</para>
</step>
</procedure>

<para>You're done.</para>

</sect1>
<sect1 id="resources"><title>Related Resources</title>

<para>There is a site called <ulink
url="http://www.hansenonline.net/Networking/linksysFW.html">HansenOnline.net</ulink>
that seems to be mainly devoted to tracking and critiquing the Linksys
firmware releases.  Alas, the monitoring software it offers is for
Windows.</para>

<para>There is a Linksys tips and tricks <ulink
url="http://www.dslreports.com/faq/linksys">FAQ</ulink>; it's mostly
Windows stuff, but a few of the war stories may be useful.</para>

<para>There is a good article on configuring the BEFSR41, and its
limitations, at <ulink
url="http://www.arstechnica.com/reviews/3q00/linksys/befsr41-2.html">
Linksys EtherFast Cable/DSL Router, Model BEFSR41</ulink>. It dates
from August of 2000.</para>

</sect1>
</article>

<!--
The following sets edit modes for GNU EMACS
Local Variables:
fill-column:75
compile-command: "mail -s \"Linksys Blue Box Router HOWTO update\" submit@en.tldp.org <Linksys-Blue-Box-Router-HOWTO.xml"
End:
End:
-->
  

---------------------------------------------------------------------
To unsubscribe, e-mail: submit-unsubscribe@en.tldp.org
For additional commands, e-mail: submit-help@en.tldp.org